灰度发布必须在服务端或边缘层实现，HTML本身无灰度能力；Nginx可通过cookie/header映射后端服务实现全链路版本分流，前端需避免硬编码、由服务端注入API地址与资源路径以保证版本一致性。
灰度发布不是前端能独立实现的功能
HTML 本身没有“灰度发布”能力，它只是静态标记语言。所谓“HTML 灰度页面”，本质是服务端或网关根据请求特征（如 cookie、header、IP）动态返回不同版本的 HTML，前端只负责渲染。强行用纯 HTML + JS 做客户端分流（比如读 localStorage 决定加载哪个 JS 包），会暴露策略、不可控、不安全，且无法绕过 CDN 缓存——真实灰度必须在服务端或边缘层（如 Nginx、Cloudflare Workers、K8s Ingress）完成。
如何让服务端返回不同 HTML 版本（Nginx 示例）
Nginx 是最常用的轻量级灰度入口。核心思路是用 map 指令提取分流依据，再通过 proxy_pass 转发到不同 upstream。
常见做法：
- 从请求 header（如
X-Canary-Version: v2）或 cookie（如canary=1）提取标识 - 用
map将标识映射为后端服务名（如v1_backend/v2_backend） - 在
location中使用该变量做反向代理，确保 HTML、CSS、JS 全链路走同一版本 - 务必关闭
proxy_cache或按灰度维度缓存（如cache_key $scheme$request_method$host$request_uri$cookie_canary），否则缓存会污染分流
示例片段：
立即学习“前端免费学习笔记（深入）”；
map $cookie_canary $backend {
"1" "v2_backend";
default "v1_backend";
}
upstream v1_backend { server 10.0.1.10:8080; }
upstream v2_backend { server 10.0.1.11:8080; }
location / {
proxy_pass http://$backend;
proxy_set_header Host $host;
}
前端如何配合灰度（避免硬编码、适配多版本）
前端代码要“无感”支持灰度，关键不是切换 HTML，而是让资源加载、API 请求、埋点行为自动对齐当前灰度版本。
- 所有 API 请求 base URL 应由服务端注入（如通过
window.API_BASE = "/api/v2"），而不是写死在 JS 里 - CSS/JS 文件名带版本哈希（
app.a1b2c3.js），并由服务端决定返回哪套构建产物，避免浏览器缓存混用 - 不要用 JS 判断
navigator.userAgent或随机数做灰度逻辑——这属于作弊，且无法与后端状态同步 - 若需前端主动上报灰度分组，应调用统一埋点接口（如
/log/canary?group=v2），由后端记录并用于后续分析
为什么直接改 HTML 文件名（如 index-v1.html / index-v2.html）行不通
这种静态文件双版本方案看似简单，实际会引发一系列问题：
- 用户首次访问可能命中 CDN 缓存的任意一个版本，导致后续请求（如 AJAX、图片）跨版本失败
- 无法保证单次会话内前后端版本一致（比如 HTML 是 v2，但 API 还在调 v1 的 endpoint）
- SEO 友好性崩塌：两个 URL 被当成不同页面，权重分散，且无 canonical 指引时 Google 可能判为重复内容
- 无法做流量比例控制（比如 5% 用户切 v2），只能靠 DNS 或负载均衡器做粗粒度分流，精度差、难回滚
真正的灰度依赖的是请求上下文的一致性传递——从入口网关开始，把灰度标签透传到下游每个服务（包括静态资源服务器），而不是靠前端拼 URL 或改文件名。
