前端应用部署前的配置核对

前端应用部署前的配置核对前端应用在本地能打开不代表部署配置已经正确。构建时变量、静态资源路径、反向代理、缓存和服务端渲染会在发布链路的不同位置生效。任何一层仍沿用开发默认值都可能表现为白屏、接口跨域、资源 404或服务端与客户端水合不一致。部署前的核对不应只翻一遍.env。更可靠的做法是列出配置的来源、最终使用位置和验证方式再从运行中的实例确认实际值。配置文件写了什么与浏览器最终拿到什么中间还隔着构建、镜像、CDN 和代理。先区分构建时配置与运行时配置多数前端构建工具会把公开环境变量写进产物。变量一旦进入 JavaScript 包就可以被浏览器用户读取不能放令牌、数据库密码或内部凭据。字段名前缀只是暴露标记不是保密机制。API 基础地址、资源公共路径和功能开关若在构建时注入切换环境通常需要重新构建。若团队希望一份镜像用于多个环境可以在启动时生成一份只含公开字段的配置文件由页面加载。无论采用哪种方式都要防止两套入口同时存在导致旧值覆盖新值。配置启动后应输出一份非敏感摘要例如应用版本、接口目标类别、资源前缀和已启用功能。摘要不显示密钥或完整内部地址但能帮助确认当前实例加载的是哪份配置。缺少必要字段时应在发布阶段失败不要让页面运行到用户操作时才报错。静态资源路径和缓存需要成对检查HTML 通常更新频繁带内容哈希的 JavaScript、CSS 和图片则适合长期缓存。两类资源的缓存策略不同。若 HTML 被长期缓存它可能继续引用已经清理的旧文件若静态文件没有哈希却设置不可变缓存修复发布后浏览器仍可能使用旧内容。核对时从部署后的 HTML 中取出真实资源地址再确认 CDN 或源站能够访问而不是只检查构建目录里文件存在。应用部署在子路径时还要验证路由基址、动态导入和图片地址都使用同一前缀。回滚前保留上一版哈希资源避免旧 HTML 恢复后找不到对应脚本。Service Worker 会增加另一层缓存。更新策略、旧缓存清理和多标签页切换都要单独验证。发布完成后页面仍旧不一定是 CDN 问题也可能是旧 Worker 仍在控制客户端。不要用“让用户清缓存”代替更新机制。流式 SSR 要核对整条响应链React 的renderToPipeableStream能在全部内容完成前先发送页面骨架但流式效果取决于 Node 服务、反向代理和客户端三端配置。代理缓冲可能让分块响应最后一次性到达过宽的读取超时则会让异常连接长期占用资源。服务端应为一次渲染设置可配置的时限并在响应正常结束、客户端断开时清理定时器和流。下面是简化示例重点是关闭路径不是可以直接复制的完整服务器实现。import { renderToPipeableStream } from react-dom/server; import type { Request, Response } from express; const SSR_TIMEOUT_MS Number(process.env.SSR_TIMEOUT_MS ?? 10_000); export function render(req: Request, res: Response) { let shellSent false; let didError false; const stream renderToPipeableStream(App url{req.url} /, { bootstrapScripts: [/static/client.bundle.js], onShellReady() { shellSent true; res.statusCode didError ? 500 : 200; res.setHeader(Content-Type, text/html; charsetutf-8); res.setHeader(Cache-Control, no-cache, no-transform); res.setHeader(X-Accel-Buffering, no); stream.pipe(res); }, onShellError(error) { console.error(SSR shell failed, error); if (!res.headersSent) res.status(500).send(SSR unavailable); }, onError(error) { didError true; console.error(SSR render failed, error); }, }); const timer setTimeout(() stream.abort(), SSR_TIMEOUT_MS); timer.unref(); const cleanup () { clearTimeout(timer); if (!shellSent || !res.writableEnded) stream.abort(); }; res.once(finish, () clearTimeout(timer)); res.once(close, cleanup); }反向代理最好把普通 SSR 和真正的 SSE 接口分开配置。SSR 需要关闭响应缓冲并设置与应用超时相匹配的读取窗口SSE 可以有更长连接但也要有心跳、客户端断开处理和连接上限。把整个站点的代理超时统一调得很长会掩盖未关闭的请求。location / { proxy_pass http://node_ssr_backend; proxy_http_version 1.1; proxy_set_header Connection ; proxy_set_header Host $host; proxy_set_header X-Forwarded-Proto $scheme; proxy_buffering off; proxy_read_timeout 30s; } location /events/ { proxy_pass http://node_event_backend; proxy_http_version 1.1; proxy_set_header Connection ; proxy_buffering off; proxy_read_timeout 5m; }这些时间只是示例实际值应根据接口行为和上游预算确定并让应用超时早于代理强制断开。用curl -N可以观察响应是否逐步到达同时查看服务端在客户端取消后是否释放连接。水合差异要从输入找原因服务端和浏览器首次渲染必须使用一致的数据。当前时间、随机数、浏览器专有对象和地区格式都可能造成差异。不要把所有警告用suppressHydrationWarning压掉先确认哪些内容应该由客户端加载哪些内容需要由服务端固定后随页面传递。useId可以生成在服务端与客户端之间稳定的组件标识但不能替代对任意随机值的处理。需要客户端环境的信息可以在挂载后更新同时为首次渲染提供稳定占位。部署验证应保留浏览器控制台警告并覆盖直接访问、刷新、登录状态和不同语言设置。发布前按运行结果验收上线前至少检查公开配置摘要、静态资源地址、接口代理、缓存头、水合警告和客户端断开。再模拟一个旧版本回滚确认旧 HTML 对应资源仍在配置格式仍兼容。验证请求带上发布版本方便把浏览器错误、代理日志和 Node 日志串起来。配置核对的结果应是一份可复查清单字段来自哪里在哪一层生效用什么请求验证失败后如何回退。这样出现白屏或流式响应停住时团队可以沿部署链路定位而不是在前端、CDN 和服务端之间来回猜测。