Nginx 配置生效机制与 405 错误排查复盘

1. 现象描述

在解决图片上传大小限制问题时，我们修改了 Nginx 配置文件并尝试让其生效。在此过程中遇到了两个主要问题：

1. 配置未生效：修改了 client_max_body_size 后，上传大文件依然失败（413 错误）。
2. 接口瘫痪：在排查过程中，发现登录接口 (/api/auth/login) 和小文件上传接口突然报错，返回 HTTP 405 Method Not Allowed。

2. 原因分析

2.1 配置未生效的原因

• 重载机制：Nginx 的 reload 命令虽然能平滑重启，但在某些系统环境下（或进程异常时），可能无法彻底清除旧的配置缓存或旧进程。
• 验证缺失：修改文件后，如果没有通过 nginx -T 查看最终加载的配置，很难确认修改是否真的被 Nginx 读取到了。

2.2 接口报 405 (Method Not Allowed) 的原因

这是本次故障的核心原因。

• 请求域名：小程序客户端发起的请求域名是 api.zhangxiaoxi.cn。
• 配置缺失：我们的 Nginx 配置文件 used-car-api.conf 中，server_name 只配置了 zhangxiaoxi.cn 和 www.zhangxiaoxi.cn，漏掉了 api.zhangxiaoxi.cn。
• 默认服务器回退 (Fallback)：
  • 当 Nginx 接收到 api.zhangxiaoxi.cn 的请求时，由于找不到匹配的 server_name，它会将请求转发给 默认服务器 (Default Server)。
  • 在服务器上，按字母顺序，admin.zhangxiaoxi.cn.conf（后台管理静态资源站点）排在 used-car-api.conf 之前，或者被显式设为了默认站点。
• 静态站点不支持 POST：默认站点是一个静态文件服务（托管前端 HTML/CSS/JS）。静态服务器通常只支持 GET 请求，收到 POST 请求（如登录、上传）时，就会拒绝并返回 405 Method Not Allowed。

3. 解决方法

3.1 修复 405 错误

在 Nginx 配置文件的 server_name 指令中，显式添加 api.zhangxiaoxi.cn。

server {
    listen 443 ssl;
    # 补全所有使用的子域名
    server_name zhangxiaoxi.cn www.zhangxiaoxi.cn api.zhangxiaoxi.cn;
    
    # ...
}

3.2 确保配置生效

1. 强制重启：当 nginx -s reload 看起来没生效时，使用 service nginx restart 进行完全重启。
2. 进程管理：同时重启后端应用（如 PM2 中的 Node.js 进程），确保业务代码也是最新的。

4. 小结与避坑指南

为了避免日后再次遇到类似问题，建议遵循以下最佳实践：

1. 域名清单检查：在配置 Nginx 时，务必核对客户端使用的所有域名和子域名，确保它们都出现在 server_name 中。
2. 理解 405 错误：看到 Nginx 返回 405，第一反应应该是“请求是不是打错地方了？”——通常是打到了不支持 POST 的静态服务或默认站点上。
3. 配置验证习惯：
   • 修改前备份。
   • 修改后用 nginx -t 检查语法。
   • 用 nginx -T 查看运行时的完整配置快照，确认修改已包含。
4. 显式定义默认站点：建议配置一个明确的 default_server，返回清晰的错误信息（如 404 或 403），防止请求“以此充好”落入错误的站点处理逻辑中，增加排查难度。