nginx不支持内置模块版本管理，需通过路径隔离、命名规范和配置控制实现多版本共存与切换；模块按版本分目录存放并用load_module精准引用，配合变量、符号链接或include实现运行时选择，升级须原子化操作并确保版本兼容。
Nginx 本身不支持“模块版本管理”，它只负责加载指定路径下的 .so 动态模块文件。所谓“多个版本的动态模块”，实际是指同一功能模块的不同编译版本（如 v1.0、v1.2、v2.0）共存并可按需切换。关键在于路径隔离、命名规范和配置控制，而非 Nginx 内置的版本机制。
模块文件按版本命名并分目录存放
避免覆盖或混淆，把不同版本的模块文件放在独立子目录中，用清晰后缀标识：
-
/usr/lib/nginx/modules/ngx_http_brotli_filter_v1.0.3.so -
/usr/lib/nginx/modules/ngx_http_brotli_filter_v1.2.0.so -
/usr/lib/nginx/modules/ngx_http_geoip2_v4.1.0.so -
/usr/lib/nginx/modules/ngx_http_geoip2_v4.2.1.so
配合 load_module 指令精准引用：
load_module modules/ngx_http_brotli_filter_v1.2.0.so; load_module modules/ngx_http_geoip2_v4.1.0.so;
通过配置变量或 include 实现运行时模块选择
不硬编码模块名，改用变量或条件 include，便于批量切换：
- 在主配置顶部定义版本变量（需配合
--with-compat编译）：env BROTLI_MODULE_VERSION=v1.2.0;
- 或使用
include+ 符号链接实现软切换：# 创建指向当前生效版本的链接 ln -sf ngx_http_brotli_filter_v1.2.0.so /usr/lib/nginx/modules/ngx_http_brotli_filter_current.so
配置中写：
load_module modules/ngx_http_brotli_filter_current.so;
配合 systemd 或脚本做原子化升级
更新模块时，应确保：
- 新模块文件先写入临时路径，校验
md5sum或file类型无误 - 原子替换符号链接（
mv -T）或更新变量配置 - 执行
nginx -t && nginx -s reload，验证成功后再清理旧版本文件
例如灰度发布一个新 geoip2 模块：
- 把
v4.2.1.so放入模块目录 - 临时修改
include /etc/nginx/conf.d/modules-geoip2-staging.conf指向新版本 - 测试流量命中后，再将
modules-geoip2.conf切换为正式引用
避免常见陷阱
- 不同 Nginx 主版本（如 1.20 vs 1.24）编译的动态模块不可混用，必须匹配源码版本和编译参数（尤其
--with-compat） -
load_module必须出现在events或http块外部，且每个模块只能load_module一次 - 模块加载失败会导致
nginx -t报错，但不会影响已加载模块；建议每次只增/换一个模块，降低排障复杂度
本质上，这是运维层面的文件与配置协同管理，不是 Nginx 自身的模块版本系统。核心就三点：路径分隔、引用明确、切换可控。
