Nginx 的二进制兼容性确保了在不同版本之间可以平滑升级，而无需重新编译模块或重新配置。
示例：
1.24.0 → 1.24.1：完全兼容1.24.0 → 1.25.0：通常兼容1.24.0 → 2.0.0：可能不兼容动态模块必须与 Nginx 核心版本完全兼容：
# 检查模块兼容性
nginx -V
# 查看模块信息
nginx -V 2>&1 | grep build
平滑升级允许在不中断服务的情况下升级 Nginx：
# 1. 下载新版本
cd /usr/local/src
wget http://nginx.org/download/nginx-1.24.1.tar.gz
tar -xzvf nginx-1.24.1.tar.gz
cd nginx-1.24.1
# 2. 配置（使用与之前相同的选项）
./configure --prefix=/etc/nginx \
--sbin-path=/usr/sbin/nginx \
--modules-path=/usr/lib/nginx/modules \
--with-compat \
--with-http_ssl_module \
--with-http_v2_module
# 3. 编译
make
# 4. 备份旧版本
sudo cp /usr/sbin/nginx /usr/sbin/nginx.old
# 5. 替换新版本
sudo cp objs/nginx /usr/sbin/nginx
# 6. 测试新版本
sudo /usr/sbin/nginx -t
# 7. 升级
sudo make upgrade
# 8. 验证
nginx -v
如果升级出现问题，可以快速回滚：
# 1. 停止新版本
sudo kill -TERM `cat /var/run/nginx.pid.oldbin`
# 2. 恢复旧版本
sudo cp /usr/sbin/nginx.old /usr/sbin/nginx
# 3. 启动旧版本
sudo systemctl start nginx
# 4. 验证
nginx -v
# 查看模块版本
strings /usr/lib/nginx/modules/ngx_http_ssl_module.so | grep build
# 或使用 objdump
objdump -p /usr/lib/nginx/modules/ngx_http_ssl_module.so | grep NEEDED
如果 Nginx 版本升级，需要重新编译动态模块：
# 1. 下载模块源码
cd /usr/local/src
git clone https://github.com/openresty/headers-more-nginx-module.git
# 2. 配置 Nginx
cd nginx-1.24.1
./configure --with-compat \
--add-dynamic-module=../headers-more-nginx-module
# 3. 编译模块
make modules
# 4. 安装模块
sudo cp objs/ngx_http_headers_more_filter_module.so /usr/lib/nginx/modules/
# 5. 测试
sudo nginx -t
不同版本的 Nginx 可能有配置语法变化：
# 测试配置文件兼容性
sudo nginx -t
# 查看详细错误
sudo nginx -T
新版本可能新增指令，旧版本会报错：
# HTTP/3 配置（需要 Nginx 1.25.1+）
listen 443 quic;
listen 443 ssl;
某些指令在新版本中可能被废弃：
# 旧版本
server_name_in_redirect off;
# 新版本
server_name_in_redirect on; # 默认值已更改
# 查看构建信息
nginx -V 2>&1 | grep build
# 输出示例
# built by gcc 9.4.0 (Ubuntu 9.4.0-1ubuntu1~20.04.1)
# built with OpenSSL 1.1.1f 31 Mar 2020
# TLS SNI support enabled
# configure arguments: --prefix=/etc/nginx ...
# 检查 OpenSSL 版本
openssl version
# 检查 PCRE 版本
pcretest -C
# 检查 zlib 版本
zlib-flate -h
# 备份配置文件
sudo cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bak
sudo cp -r /etc/nginx/conf.d /etc/nginx/conf.d.bak
# 在测试环境先验证
./configure --prefix=/tmp/nginx-test
make
sudo make install
# 测试配置
/tmp/nginx-test/sbin/nginx -t -c /etc/nginx/nginx.conf
# 监控错误日志
sudo tail -f /var/log/nginx/error.log
# 监控访问日志
sudo tail -f /var/log/nginx/access.log
# 1. 先升级到次版本
1.24.0 → 1.24.1
# 2. 验证稳定后再升级
1.24.1 → 1.25.0
# 错误信息
nginx: [emerg] dlopen() "/usr/lib/nginx/modules/ngx_http_xslt_filter_module.so" failed (libexslt.so.0: cannot open shared object file: No such file or directory)
# 解决方案
sudo apt install libxslt1.1
# 错误信息
nginx: [emerg] BIO_new_file("/etc/nginx/ssl/cert.pem") failed (SSL: error:0200100D:system library:fopen:Permission denied)
# 解决方案
sudo chmod 644 /etc/nginx/ssl/cert.pem
sudo chmod 600 /etc/nginx/ssl/key.pem
# 错误信息
nginx: [emerg] invalid parameter "quic" in /etc/nginx/conf.d/default.conf:5
# 解决方案
# 检查 Nginx 版本是否支持该指令
nginx -v
| Nginx 版本 | OpenSSL 最低版本 | PCRE 最低版本 | zlib 最低版本 |
|---|---|---|---|
| 1.24.x | 1.0.1 | 4.4 | 1.1.2 |
| 1.25.x | 1.1.1 | 7.0 | 1.2.0.4 |
| 1.26.x | 1.1.1 | 8.0 | 1.2.11 |