Nginx的split_clients模块是官方内置HTTP模块，自1.1.0起默认包含但需编译时显式启用--with-http-split-clients-module，否则配置会报“unknown directive”错误。
Nginx 的 split_clients 模块是官方 HTTP 模块，自 Nginx 1.1.0 起默认内置，无需额外下载第三方模块，但必须在编译时显式启用（部分精简版发行包可能禁用）。如果你用的是源码编译安装，关键在于 ./configure 阶段确认该模块已包含。
✅ 确认 split_clients 模块是否可用
该模块对应编译选项为：--with-http-split-clients-module
它属于 HTTP 核心功能模块，不是可选扩展，但某些定制化编译脚本会跳过它。主流发行版（如 Ubuntu/Debian 的 apt 包、CentOS 的 EPEL）通常已启用；而自己从源码编译时，不加这个参数就等于禁用。
? 源码编译启用步骤（关键命令）
# 1. 下载并解压最新稳定版（例如 1.24.0） wget https://nginx.org/download/nginx-1.24.0.tar.gz tar -zxvf nginx-1.24.0.tar.gz cd nginx-1.24.0 # 2. 安装基础依赖（确保 pcre、openssl、zlib 开发头文件存在） yum -y install pcre-devel openssl-devel zlib-devel gcc make # 或 Ubuntu/Debian： # apt-get update && apt-get install -y libpcre3-dev libssl-dev zlib1g-dev build-essential # 3. configure 时显式启用 split_clients 模块（必加！） ./configure \ --prefix=/usr/local/nginx \ --with-http_ssl_module \ --with-http_realip_module \ --with-http_gzip_static_module \ --with-http_split_clients_module \ # ← 就是这一行 --with-stream \ --with-stream_ssl_module # 4. 编译并安装 make -j$(nproc) sudo make install
⚠️ 注意：如果跳过
--with-http-split-clients-module，即使配置中写了split_clients指令，Nginx 启动时会报错：unknown directive "split_clients"。
? 验证是否成功启用
编译安装后，运行：
/usr/local/nginx/sbin/nginx -V 2>&1 | grep -o with-http-split-clients-module
若输出 with-http-split-clients-module，说明已启用。
再检查配置语法是否识别该指令：
echo 'http { split_clients "" $test {} }' | /usr/local/nginx/sbin/nginx -t -f -不报错即表示模块加载正常。
? 补充说明
- 该模块不需要额外安装数据库或外部服务，纯内存哈希计算，开销极低；
- 它仅在
http { }块中生效，不能放在server或location内； - 若你使用 OpenResty，它默认已集成该模块，无需额外配置；
- 旧版本 Nginx（
配置写法示例（验证用）：
http {
split_clients "$remote_addr" $ab_group {
5% "v2";
* "v1";
}
upstream backend_v1 { server 127.0.0.1:8080; }
upstream backend_v2 { server 127.0.0.1:8081; }
server {
location / {
proxy_pass http://backend_$ab_group;
}
}
} 
