不用赘述，干这行的都懂：Demo阶段一切完美，交互流畅、样式精致、数据齐全，可真到了上线那一刻，各种奇怪问题像约好了一样排队出现。白屏、接口超时、样式错乱、首屏加载慢到让人怀疑人生。这不是你技术不行，而是Demo和线上本来就不是同一个物种。作为FDE（Frontend Developer Experience，前端开发工程师），我在多次经历“演示时风光、上线后翻车”之后，总结出一套自己的排查和改进方法，这篇就聊聊到底差在哪，以及怎么提前堵住这些坑。
先给个结论：Demo演示的是“最理想状态下的可能性”，线上运行的是“最复杂环境下的稳定性”。两者的差距如果不在开发阶段提前抹平，上线那天就是在赌运气。这篇文章适合正在做前端开发、即将把功能从演示推向生产的同学，尤其是FDE岗位或者负责前端工程化的朋友。你会看到我踩过的坑、排查思路、以及一套可以抄走的防翻车清单。
1. 为什么Demo和线上是两个世界？
1.1 最容易被忽视的“环境洁癖”差异
我见过太多团队，Demo跑得挺好，问题就出在环境上。本地开发时，你的电脑是一个完全可控的封闭环境：固定的Node版本、固定的依赖锁定、特定的API服务还开着热更新。可线上不是这样。线上意味着你面对的是未知的服务器环境、混合的浏览器版本、随时可能变化的网络状况，以及无法预料的运营商缓存策略。
举个最典型的例子：本地开发时，前端静态资源往往走的是webpack-dev-server或vite的dev server，资源都是即时编译、本地读取，延迟几乎为零。但上线后，资源文件放在CDN上，浏览器要发起真实的HTTP请求，要经过DNS解析、TCP握手、TLS协商，还有可能遇到CDN节点没缓存需要回源的情况。这一步就可能让首屏时间从Demo时的毫秒级变成几秒。所以FDE在开发时就应该有意识地把“本地环境”和“生产环境”当成两套不同的系统来对待，而不是默认“我本地能跑，线上肯定也能跑”。
1.2 演示数据和生产数据的“物种隔离”
Demo好看的另一大原因是数据太“干净”。Mock数据通常字段齐全、长度适中、没有异常值。而生产数据千奇百怪：超长用户名、几十MB的富文本内容、空白字符、特殊字符、缺失字段、非法日期，这些在Demo里永远不会出现，但真实用户的数据就是这么不讲道理。
我在一个实际的商城项目中遇到过：Demo里展示的商品标题都是十几个字，排版完美。上线后，有商家传了一个300多个字的标题，直接撑破了卡片布局，导致整个列表页错位。这个问题在Demo阶段不可能发现，因为mock数据根本不会设计这种极端场景。后来我们把所有线上的长文本数据导出一份脱敏副本，专门放到一个“极限数据测试环境”，每次上线前都会拿这组数据回归一遍页面。这个做法强烈建议FDE们安排上。数据层面的“物种隔离”不打破，Demo再好看也是空中楼阁。
1.3 接口调用量：Demo阶段根本压不出来的瓶颈
Demo阶段的接口请求量少，一个页面可能就几个请求，完全感觉不到压力。但真实用户一上来，情况完全不同。以我做过的一个中后台系统为例，Demo时首页只有我自己在点，一次最多10个并发请求。上线半小时后，几十个人同时打开首页，每个请求都要经过网关鉴权、权限校验、数据聚合，数据库连接池直接被打满，接口响应时间从80ms飙升到8秒。
这不是后端单方面的问题，FDE在前端也要提前做好应对：本地缓存策略、请求合并、防抖节流、骨架屏这些优化手段，在Demo阶段容易被忽略，因为“响应都快到不需要优化了”。但一上线，性能瓶颈全部暴露。所以我现在的习惯是，每次功能开发完成后，自己先用浏览器的网络面板模拟弱网和慢速，再拉上后端同事做一次简单的并发冒烟，提前把性能债还掉。
2. 用真实生产数据“养”出来的Demo才算数
2.1 mock数据和真实接口的比例怎么定
我踩过最狠的一次坑：本地完全用mock数据联调，页面开发完干干净净，结果换到测试环境联调真实接口，字段名对不上、嵌套层级不一样、有的接口直接返回null，前后端扯皮半天。后来我给自己定了一条规矩：mock数据只用于“开发阶段”，联调阶段必须切到真实接口，且禁止后端在你本地起服务帮你伪装数据。联调过了，再把真实接口的返回结果保存为fixture，用来以后做回归测试。
具体比例上，我建议这样控制：页面静态展示部分可以用mock，涉及到交互逻辑、数据流转、权限判断的，必须接真实接口。比如一个用户列表页，列表展示可以用mock填UI，但“删除用户”“修改角色”这类操作必须走真实接口，因为这些环节的鉴权、参数校验、异常处理，mock永远模拟不出来。
2.2 网络环境下限：真机弱网和DevTools降速是两码事
很多FDE会用DevTools的网络面板模拟Slow 3G，但说实话，它和真实弱网差距很大。DevTools模拟的是固定的带宽和延迟，真实弱网的特点是抖动、丢包、断线重连，这些在DevTools里模拟不出来。尤其是移动端H5项目，真机在电梯、地铁、地下车库这些场景下的网络表现，和你在电脑上模拟完全是两回事。
我现在的做法是：每个迭代上线前，至少留半天时间做真机弱网测试。准备一台Android一台iOS，打开设置里的弱网模式（Android可以装一个NetLimiter类工具，iOS用系统自带的开发者模式里的Network Link Conditioner），重点测这几种场景：
- 页面首次加载，网络缓慢时白屏多久
- 网络中断后恢复，接口是否能自动重试
- 图片懒加载在慢速网络下，是否有占位符
- 接口超时后，前端有没有可理解的错误提示而不是直接卡死
这些在Demo阶段全部看不到，因为演示用的网络永远是满格Wi-Fi。如果你们公司没有条件准备真机弱网测试，也至少要保证在预发环境用Charles或Whistle做一次限速测试，这比只在Chrome DevTools里点几下要可靠得多。
2.3 容器/部署层面提前对齐生产配置
前端部署到线上的方式多种多样，常见的有纯静态托管到Nginx/CDN、打包成容器镜像跑在Kubernetes里，还有鸿蒙原生应用这种打包成hap、hsp、har再分发的。不管哪一种，FDE都应该在开发阶段就搞清楚生产环境的部署方式和配置差异，而不是等到上线前一刻才临时去调。
举几个我遇到过的真实情况：
- 本地起的是
npm run dev，线上是nginx托管静态文件，路由模式必须改成history或hash，否则刷新就404。 - 本地接口代理用的是webpack的proxy，线上需要通过Nginx的
location /api做反向代理，如果上线时忘了配Nginx，所有请求都会打到前端服务器上返回index.html，API跨域问题立刻崩盘。 - 打包后的文件名是带hash的，但如果CDN缓存配置错误，用户会一直拿到旧版本的JS文件，等于你发布了个寂寞。
所以我现在负责项目后的第一件事，就是找运维同事要一份生产环境的Nginx配置示例，照着本地部署一套一模一样的Nginx环境来模拟线上。有些问题只有在真实部署结构下才能暴露，单纯在本地dev server里跑得再顺，都不算数。
3. 上线前必须过的“一道坎”：分批灰度与可观测性
3.1 灰度策略怎么设计
不要一次性把所有流量切到新版本。我之前吃过一次亏，新版本功能彻底重写了前端路由，结果上线当天因为某个低版本浏览器不兼容新语法，页面白屏，用户全量崩溃。从那以后，我做任何上线都坚持灰度发布。
灰度的核心思路是把用户按一定比例或条件分批次切换到新版本。常见的做法有：
- 按用户ID取模：比如hash(id) % 100小于10的流量走新版本，然后逐步调大占比。
- 按内部白名单：先让公司内部员工和内测用户看新版本，验证没问题再放量。
- 按IP或地域：先放开某一个区域，观察监控无异常后再扩大。
前端灰度可以通过网关层做，也可以在前端代码里通过读取配置中心的值来控制加载哪套静态资源。我比较推荐后者，因为前端静态资源是独立的，用打包时的环境变量或运行时拉取一个灰度配置，灵活度更高。核心原则是：灰度不是可选项，而是上线流程的标配。只要是涉及前端核心链路的改动，都建议走灰度。
3.2 监控埋点：Demo里根本不会想到的细节
Demo阶段，你关注的是功能对不对，画面美不美。上线阶段，你需要关注的是“用户到底有没有用起来”“哪里卡了”“哪里报错了”。如果没有监控埋点，出了问题只能等用户反馈，反馈链条又长又被动。
前端监控至少要覆盖这几层：
- JavaScript错误监控：捕获全局未处理的异常，包括异步错误、Promise未捕获的rejection，记录错误堆栈、发生页面、浏览器信息。
- 接口请求监控：记录每个请求的URL、耗时、状态码，一旦出现大面积的非2xx响应，立刻能发现。
- 首屏性能监控：记录FCP（First Contentful Paint）、LCP（Largest Contentful Paint）、TTI（Time to Interactive）等核心指标，设置告警阈值。
- 用户行为链路：至少要做到能圈定“用户走到哪一步就不往下走了”，这在转化类页面上特别重要。
我常用的方案是接入Sentry做错误监控，用自研的轻量级性能上报模块把性能指标抛到后端，再配合Grafana做看板。这里给个最小可用的前端性能上报示代码：
// performance-report.js function reportPerformance() { if (!window.performance || !window.performance.timing) return; const timing = window.performance.timing; const reportData = { url: window.location.href, ua: navigator.userAgent, dnsTime: timing.domainLookupEnd - timing.domainLookupStart, tcpTime: timing.connectEnd - timing.connectStart, ttfbTime: timing.responseStart - timing.requestStart, domReadyTime: timing.domContentLoadedEventEnd - timing.navigationStart, loadTime: timing.loadEventEnd - timing.navigationStart, }; navigator.sendBeacon('/api/performanceReport', JSON.stringify(reportData)); } window.addEventListener('load', () => { setTimeout(reportPerformance, 1000); });注意，上报时机不要在load事件里立刻发，因为此时很多资源还在加载中，会有误差。可以延迟1秒再发。这种细节就是Demo阶段不会想到、上线后却很关键的。
3.3 前端上报和报警如何打通
光有上报数据不够，必须能在指标异常时主动通知到人。我的经验是：报警阈值不要设置得太宽松，否则天天报警你就麻木了；也不要太紧，否则误报太多同样会让人麻木。建议从这两个维度开始：
- 错误率：页面JS错误率超过1%，或接口错误率超过2%，触发告警。
- 耗时异常：首屏时间超过3秒（移动端）/2秒（桌面端）的比例超过10%，触发告警。
报警渠道用钉钉、飞书或企业微信机器人Webhook都可以，关键是要把告警信息写得足够详细：影响范围（哪些页面或接口）、错误类型、对应代码位置、开始时间、样本数量，这样值班同学拿到告警才能快速定位，而不是反过来还要去查一堆日志。
4. 上线当天最容易翻车的几个场景实录
4.1 缓存策略导致的“新功能不生效”
前端发布后，用户拿到的还是旧版本的JS/CSS文件，这是最常见的上线问题。通常原因是：静态资源没有带hash命名，或CDN缓存时间配置过长，或者Nginx没有对HTML文件设置no-cache。结果就是用户浏览器还在用缓存的旧资源。
排查思路：先确认在无痕模式或强制刷新下新功能是否正常。如果正常，说明资源本身没坏，问题出在缓存策略上。然后看Nginx配置，对HTML文件要设置Cache-Control: no-cache，保证每次请求都回源校验；对带hash的JS/CSS，则可以设置一年以上的长缓存，因为文件名变了，浏览器自然去拿新文件。
location /index.html { add_header Cache-Control "no-cache, no-store, must-revalidate"; expires 0; } location /static { add_header Cache-Control "public, max-age=31536000, immutable"; }这段配置是基础，但很多小团队压根没配过。Demo阶段看不到这个问题，因为浏览器缓存总是清着的，可真实用户不会天天清缓存。
4.2 跨域和鉴权在Demo里被绕过的问题
本地开发时，webpack/vite的proxy帮你把/api代理到了后端地址，跨域问题在DevServer里不存在。上线后，前端资源和API通常部署在不同域名，就必须处理跨域和鉴权。最容易翻车的点有三个：
第一是CORS配置只开放了某个域名，线上用户域名不一样，请求直接被浏览器拦截。解决方法是让后端把允许的域名写成配置，别写死。第二是Cookie的SameSite属性，跨域请求如果带Cookie，必须设置SameSite=None; Secure，否则浏览器不带会话信息，接口返回401。第三是Token存放在localStorage遇跨域导致的泄漏或丢失，很多项目为了简单，把Token放localStorage，但没有处理跨域域名之间的共享逻辑，用户从主站跳到子站，Token就没了，页面看起来像没登录。
这些在Demo阶段大概率不会出现，因为本地和服务器的域名关系太简单了。FDE要想不被上线搞得焦头烂额，建议提前在代码里就把鉴权逻辑封装成统一的request模块，集中处理请求头、超时、401跳转、Token刷新，而不是每个页面自己fetch。
4.3 资源加载“首屏优化”在预发环境才暴雷
有一种很常见的情况：本地和Demo都很快，一上预发环境，首屏时间就飙到4秒以上。原因是：预发环境的静态资源可能没有部署在CDN节点上，或者预发带宽受限，而Demo环境通常只加载了少量数据，图片都是压过的。真正上线后，真实图片动辄几MB，首屏直接崩掉。
我的建议是：在Demo阶段就使用线上同比例的真实素材，至少是真实尺寸的图片、视频。同时做好首屏的妥协方案：
- 图片全部用CDN链接，并开启WebP格式和压缩。
- 首屏之外的模块用懒加载。
- 大的第三方库用动态import拆包，避免主bundle过大。
- 关键样式内联到HTML中，避免首屏等待CSS文件加载。
坦白讲，首屏优化是个长期工程，但至少在上线前要把最明显的几个大文件优化掉，不然上线那天首屏加载时间长会让用户产生“网站打不开”的印象，这比功能性的Bug还致命。
5. 我怎么在项目里落地一套“防上线翻车”清单
5.1 从Demo到提测的强制自检项
基于前面这些教训，我现在给自己做了一个固定的上线前自检清单，每次发布前逐项确认。这些项看起来基础，但每一条都是我付出过代价换来的：
环境与构建
- [ ] 代码从主干拉的新分支，基于最新依赖锁定文件安装依赖后能正常构建
- [ ]
npm run build无报错，产物体积没有异常暴增 - [ ] 静态资源路径全部使用相对路径或CDN绝对路径，没有硬编码本机地址
- [ ] 接口请求的baseURL区分环境，没有把本地proxy地址打进生产包
接口与数据
- [ ] 每个页面都接真实接口验证过，不是用mock数据自嗨
- [ ] 接口异常时有全局错误提示，不会静默失败或白屏
- [ ] 用脱敏的生产环境数据回归过一次页面
- [ ] 弱网和断网状态下有合理的用户引导
部署与发布
- [ ] Nginx或容器配置和预发环境一致
- [ ] HTML设置no-cache，静态资源设置了长缓存
- [ ] 有灰度发布方案，且带可回滚的发布记录
- [ ] 监控埋点和报警已生效，测试账号能触发告警
兼容性
- [ ] 项目支持的浏览器最低版本都实测过，没有只在高版本Chrome里自测
- [ ] 移动端在真机上，至少测过iOS Safari和主流Android浏览器
5.2 上线时要养成的发布习惯
上线不是“点一下发布按钮”就完事。我建议FDE把发布当成一次有状态变更的变更管理来处理，养成几个习惯：
一是发布窗口期内不做其他无关变更。很多人喜欢顺手修个小Bug一起发，这会让问题定位变得很困难：到底是你代码的问题，还是你顺手改的那行配置的问题？
二是发布后至少观察30分钟再离开。重点看错误率、核心接口异常率、首屏耗时的曲线，如果异常就立刻回滚。回滚操作要提前演练，别等到真出问题时才去翻文档。
三是每次发布前记录当前线上可回滚的版本号。回滚要干脆，不要试图在线上修补。先回滚恢复服务，再留时间排查问题，这才是理性的顺序。我给自己定的规矩：发布后发现问题，前5分钟可以尝试判断是不是配置错误，5分钟定位不到的直接回滚，绝不在线上现场debug。
5.3 复盘机制：翻车不可怕，问题是别翻两次
上线出问题，复盘最重要。我每次遇到线上事故，都会在恢复后48小时内做一次复盘，并记录到一个专门的文档里。复盘不是为了追责，而是把问题变成团队的资产。
复盘文档包含：
- 问题现象和时间段
- 影响范围（用户量、功能点）
- 根因分析，不允许只写“粗心”这种不负责任的结论，要写具体的技术原因
- 改进措施，而且每一条改进都要有对应的完成时间和负责人
- 这个坑如何写进自动化测试或自检清单
这套机制跑下来，团队的线上事故数量会稳定下降。因为你每次的教训都被结构化了，下次上线前检查清单里就会多一条。
6. 聊聊心态：FDE别把Demo当终点
这个系列到第三期，我也见过不少刚转FDE的同事，对做Demo热情很高，但一提到上线就压力大。我想说的是：Demo只是验证方案的起点，不是交付的终点。上线那一刻，才是用户真正用上你劳动成果的开始。好的FDE应该对线上有一种敬畏感，这种敬畏不是让你害怕发布，而是驱动你把该做的事做扎实：环境对齐、数据回归、监控报警、灰度回滚，每一步都踏踏实实。
我个人体会最深的一点是：把上线当“第一次运行”而不是“最后一次演示”。Demo的目标是展示功能，上线要处理的是系统在各种不确定条件下的表现。你提前替用户想得多了，上线后的意外就少了。
最后再分享一个小技巧：每次上线后，我都会把线上真实的接口返回样式截图保存一份，和新版本开发前的mock数据做对比。时间久了，这份对比就是非常宝贵的经验库，哪类数据、哪种结构最容易出问题，一目了然。希望这份经验能帮你在下一次上线前少踩几个坑。
