nginx实现前端灰度发布的核心是服务端根据请求特征（如cookie、ip、header等）动态返回不同版本html，而非前端控制；其主流方法包括基于权重的流量分配、基于cookie/请求头的精准分流，并需配合map指令、正确透传请求头及缓存策略以保障全链路一致性。
灰度发布不是前端写HTML能控制的事
HTML 文件本身没有逻辑、无法判断用户身份、也不能动态决定返回哪版内容。所谓“HTML灰度”，本质是服务端在 index.html 被请求的那一刻，根据请求特征（如 Cookie、X-Canary-Version header、IP段）返回不同版本的 HTML 文本——前端只负责渲染，不参与分流决策。
常见错误现象包括：改了 index-v2.html 但老用户仍加载旧版 JS，导致按钮点击报 ReferenceError: handleV2Submit is not defined；或 CDN 缓存了旧 HTML，强制刷新也拿不到新结构。
- 浏览器首次请求 HTML 时，JS 尚未执行，
localStorage、sessionStorage、navigator.userAgent都不可用，无法靠前端代码做初始分流 - 静态资源（
.js、.css、图片）的请求发生在 HTML 解析阶段，同样依赖服务端提前注入正确路径，不能靠 JS 动态加载补救 - 若用
document.write或eval拼接脚本加载逻辑，现代浏览器会拦截或引发 FOUC/白屏，且无法绕过 CDN 缓存
Nginx 是最常用也最可控的灰度入口
大型门户通常用 Nginx 做统一入口，它支持基于请求属性做轻量级路由，无需改业务代码，适合 HTML 全链路灰度。
关键点在于：用 map 提取分流标识 → 映射到不同 upstream → proxy_pass 转发时携带原始请求头，确保后端能复用同一套策略。
-
map $cookie_canary $backend比if ($cookie_canary = "1")更安全，避免 Nginx 的if指令嵌套陷阱 - 务必设置
proxy_set_header Cookie $http_cookie，否则下游服务收不到灰度标识 - CDN 或反向代理层若缓存 HTML，必须按灰度维度生成
cache_key，例如cache_key $scheme$request_method$host$request_uri$cookie_canary - 禁止对
*.html设置Cache-Control: public, max-age=3600；应设为no-cache, must-revalidate或max-age=0
前端代码必须“无感适配”多版本HTML
一旦服务端完成分流，前端要保证所有资源加载、API 请求、埋点行为与当前 HTML 版本严格对齐，否则跨版本混用就会出问题。
- API base URL 必须由服务端注入，例如在 HTML 中写
<script>window.API_BASE = "/api/v2"</script>，而非 JS 里硬编码"https://api.example.com/v2" - CSS/JS 文件名必须带构建哈希，如
app.a1b2c3.js，禁用app.js这类无区分路径，否则浏览器可能复用旧缓存 - 避免在 HTML 里写相对路径如
<script src="js/main.js"></script>；应使用绝对路径或<base href="/v2/">，且href值需由服务端动态输出 - 埋点上报需主动带灰度标识，例如调用
fetch("/log/canary?group=v2")，而不是等 JS 执行后读localStorage再拼参数
最容易被忽略的坑：base 标签和相对路径失效
当你通过 Nginx 返回 /v2/index.html，但页面里写的是 <script src="js/app.js"></script>，浏览器会按当前 URL 路径解析，实际请求的是 /v2/js/app.js —— 如果你没把 v2 版本资源部署到该目录下，就 404 了。
更隐蔽的问题是：某些构建工具（如 Webpack）默认用 publicPath: "/"，导致所有资源都从根目录加载，结果 v2 HTML 加载了 v1 的 JS，功能错乱却难以定位。
- 解决方案一：服务端渲染时动态写入
<base href="/v2/">，并确保所有src/href使用相对路径 - 解决方案二：构建时按版本生成不同
publicPath，例如 v2 构建产物设为publicPath: "/v2/"，且 Nginx upstream 精确指向该子目录 - 验证方式：打开浏览器开发者工具 → Network 标签页 → 刷新页面 → 查看每个 JS/CSS 请求的真实 URL 是否匹配当前 HTML 版本路径
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
