Web 服务器与网关 / 系统课时
nginx -t 能检查哪些问题
nginx -t 能检查哪些问题
配置检查可以在加载前发现语法和文件引用问题,却不会替你访问页面或调用后端。理解检查范围,才能把它放在正确的发布步骤。本篇对一个已知配置做正例,再用非法 Worker 值做负例,区分检查失败与业务验证失败。
学习目标
- 使用与运行实例一致的二进制、前缀和配置路径。
- 根据退出状态判断检查是否通过。
- 为检查覆盖不到的业务行为准备独立请求验证。
语法与引用文件是基础门槛
nginx -t 检查配置语法,并尝试打开配置引用的文件;证书或私钥不可读、不匹配,必需 include 缺失,以及某些上下文错误都可能导致失败。它不会自动连接每个上游完成业务请求。官方检查参数说明
通配 include 未匹配任何文件未必失败,所以“原本应该存在的站点文件是否遗漏”还要核对清单。检查运行身份与服务启动身份不同,文件权限结果也可能不同。
先检查已知实验配置
沿用前章 /tmp/nginx-worker-lab/nginx.conf,它包含完整独立配置与临时目录。需要已安装的 Nginx 1.28;使用该实例对应的二进制执行:
nginx -p /tmp/nginx-worker-lab/ -c nginx.conf -t预期结果:退出码为 0,终端提示语法正确且检查成功;消息中的路径和时间依版本不同。这里没有启动或重载服务。
更换 -c 指向另一份文件时,检查的就是另一份配置,不代表当前运行实例已加载它。存在多套安装时,应核对可执行文件完整路径、版本和服务启动参数。
用非法值观察失败状态
以下完整 Linux shell 命令只写入独立的 bad.conf,不修改可用配置:
set -eu
base=/tmp/nginx-worker-lab
printf 'worker_processes two;\n' > "$base/bad.conf"
if nginx -p "$base/" -c bad.conf -t; then
printf 'unexpected-pass\n'
exit 1
else
printf 'rejected\n'
fi预期结果:Nginx 报告 worker_processes 的值非法,检查退出状态非零,最后输出 rejected。具体错误前缀、路径和行号动态;只需保留首个导致失败的原因及文件位置。不要为了让发布脚本继续而忽略非零状态。
通过检查仍需要业务请求
| 可能通过语法检查的问题 | 后续验证 |
|---|---|
| server_name 写成别的域名 | 用正确 Host 与实际入口测试 |
| proxy_pass 指向未启动后端 | 调用 API 并查上游日志 |
| location 优先级或 URI 改写错误 | 验证真实路径、方法与参数 |
| 静态目录空或首页版本错误 | 比对状态、类型与正文标记 |
| 证书名称不符合用户域名 | 做完整 TLS 名称验证 |
nginx -T 还会输出配置内容,适合核对 include 展开,但不等于请求链路测试。输出涉及内部地址、凭据或其他敏感配置时,要按配置文件相同权限保存。
放在加载之前并检查加载之后
正确流程是生成候选配置、检查、受控重载、观察运行日志,再验证实际响应。检查通过到加载之间还可能发生文件变化、权限变化或监听资源竞争,最终加载结果必须再次确认。
保留失败的候选版本供定位,恢复或修正后重新检查。不能因为旧 Worker 仍能服务,就把失败检查记为发布成功;配置可接受和新版本已对外服务是两份不同证据。