配置陷阱

Location 匹配

• location /api 匹配 /api、/api/、/api-v2、/apiary — 比预期更宽
• location /api/（有斜杠）不匹配 /api（无斜杠）
• location = /api 精确匹配但不匹配 /api/
• 正则 location ~ 优先于最长前缀 — 书写顺序重要

root vs alias

• root /var/www; location /img/ → 查找 /var/www/img/
• alias /var/www/; location /img/ → 查找 /var/www/（替换 location 路径）
• alias 无尾部斜杠 + location 有斜杠 = 路径错误
• alias 搭配正则需要捕获组：alias /var/www$1

try_files

• try_files $uri /index.html 缺少 $uri/ — 找不到目录
• 最后一个参数是内部重定向，不是文件检查 — 行为不同
• try_files + proxy_pass 在同一个 location = try_files 总是优先
• =404 作为 fallback 是状态码，不是文件 — /404 才是文件

if 语句

• if 创建新的上下文 — 继承的指令可能不生效
• if ($request_uri ~* \.php) 在已处理的 location 中 = 无意义的重复检查
• if 中的 return 和 rewrite 正常工作 — 其他指令有问题
• 多个 if 不会用 AND 组合 — 每个 if 独立

变量

• $uri 是解码后的规范化路径 — $request_uri 是原始值
• 未定义变量 = 空字符串，不报错
• if 块内的 set 总是执行 — 只有块内其他指令是条件性的
• map 比多个 if 更高效，适合 switch/case 场景

include

• include /etc/nginx/conf.d/*.conf — 按字母顺序排列，可能有影响
• 包含不存在的文件 = nginx 无法启动
• 相对路径是相对于 nginx.conf，不是当前文件
• 循环 include = nginx 启动报错但提示不清晰