不用赘述干这行的都懂Demo阶段一切完美交互流畅、样式精致、数据齐全可真到了上线那一刻各种奇怪问题像约好了一样排队出现。白屏、接口超时、样式错乱、首屏加载慢到让人怀疑人生。这不是你技术不行而是Demo和线上本来就不是同一个物种。作为FDEFrontend 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.htmlAPI跨域问题立刻崩盘。打包后的文件名是带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响应立刻能发现。首屏性能监控记录FCPFirst Contentful Paint、LCPLargest Contentful Paint、TTITime 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-age31536000, immutable; }这段配置是基础但很多小团队压根没配过。Demo阶段看不到这个问题因为浏览器缓存总是清着的可真实用户不会天天清缓存。4.2 跨域和鉴权在Demo里被绕过的问题本地开发时webpack/vite的proxy帮你把/api代理到了后端地址跨域问题在DevServer里不存在。上线后前端资源和API通常部署在不同域名就必须处理跨域和鉴权。最容易翻车的点有三个第一是CORS配置只开放了某个域名线上用户域名不一样请求直接被浏览器拦截。解决方法是让后端把允许的域名写成配置别写死。第二是Cookie的SameSite属性跨域请求如果带Cookie必须设置SameSiteNone; 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数据做对比。时间久了这份对比就是非常宝贵的经验库哪类数据、哪种结构最容易出问题一目了然。希望这份经验能帮你在下一次上线前少踩几个坑。