Nginx的split_clients模块通过客户端标识（如IP）一致性哈希实现静态资源灰度，按预设百分比分组并重写路径或注入响应头，零后端侵入、结果稳定、纯Nginx层完成。
使用 Nginx 的 split_clients 模块实现静态资源灰度加载，核心是**基于客户端标识（如 IP、User-Agent、Cookie）做一致性哈希分组，再通过变量控制资源路径或响应头，使不同用户群体加载不同版本的 JS/CSS/图片等静态文件**。它不依赖后端，纯 Nginx 层完成分流，轻量且高效。
一、理解 split_clients 的作用与限制
split_clients 是 Nginx 内置模块（无需编译启用），用于将客户端按指定键（如 $remote_addr 或 $cookie_uid）进行确定性哈希，并均匀分配到预设的百分比桶中。它的关键特性包括：
- 结果稳定：同一客户端每次请求都落入相同桶（适合灰度长期生效）
- 仅支持整数百分比划分（如 1%, 5%, 10%），不支持动态权重或条件嵌套
- 不能直接返回内容，需配合
map、rewrite或add_header等指令使用 - 不感知请求路径或方法，只做“分组”，后续逻辑由你定义
二、配置灰度资源路径（推荐方式）
让不同分组用户访问不同目录下的静态资源（如 /static/v1/ 和 /static/v2/），最简单可靠。
示例配置：
split_clients "$remote_addr" $resource_version {
0.5% "v2";
* "v1";
}
<p>server {
location ^~ /static/ {</p><h1>重写路径：/static/main.js → /static/v2/main.js（若命中 v2 桶）</h1><pre class="brush:php;toolbar:false;"> rewrite ^/static/(.*)$ /static/$resource_version/$1 break;
root /var/www/html;
expires 1y;
add_header X-Resource-Version $resource_version;
}}
说明：
-
$remote_addr作为分桶依据，适合快速验证；生产中建议改用$cookie_abtest_id或$http_x_forwarded_for（需确保可信） -
0.5%用户走 v2，其余走 v1；百分比总和不必为 100%，未匹配项由*捕获 -
rewrite ... break在 location 内部生效，避免循环；root路径需包含v1/和v2/子目录
三、通过响应头控制前端加载逻辑
不改变 URL，而是注入自定义 Header（如 X-Abtest: v2），由前端 JS 读取并动态加载对应版本资源。
配置片段：
split_clients "$cookie_uid" $abtest_group {
2% "v2";
* "v1";
}
<p>server {
location ~* .(js|css|png|jpg|gif)$ {
add_header X-Abtest $abtest_group;</p><h1>静态文件正常服务</h1><pre class="brush:php;toolbar:false;"> root /var/www/static;
expires 1y;
}}
前端配合示例（JS）：
// 发起 HEAD 请求读取 header（或服务端模板注入）
fetch('/main.js', { method: 'HEAD' })
.then(r => {
const version = r.headers.get('X-Abtest') || 'v1';
const src = `/static/${version}/app.js`;
const s = document.createElement('script');
s.src = src;
document.head.appendChild(s);
});优点：URL 不变，CDN 缓存不受影响；缺点：需前端主动适配，增加少量请求开销。
四、进阶技巧与注意事项
提升灰度精度与稳定性：
-
组合客户端特征：用
map构造复合 key，例如"$remote_addr:$http_user_agent"降低哈希碰撞率 -
支持 Cookie 主动切换：添加
if ($cookie_force_version) { set $abtest_group $cookie_force_version; }，便于测试人员强制进入某组 -
避免缓存污染：在
location中加add_header Cache-Control "no-cache";（仅对带灰度 header 的资源），防止 CDN 缓存错乱 -
监控分组效果：用
log_format记录$abtest_group，通过日志分析实际流量分布是否符合预期
不复杂但容易忽略：确保 Nginx 版本 ≥ 1.8.0（split_clients 引入版本），且没有其他 rewrite 规则干扰路径匹配顺序。
