记一次 Nginx 上传文件大小限制引发的 413 错误排查

1. 背景

在开发二手车小程序的“发布车辆”功能时，包含了一个图片上传模块。 在测试过程中发现：

• 上传几百 KB 的小图片一切正常。
• 当尝试上传一张 1.7MB 的图片时，接口请求直接失败，甚至没有进入后端业务逻辑。

2. 问题现象

查看开发者工具的 Network 面板，发现上传请求返回了 HTTP 状态码 413 Request Entity Too Large。

Status Code: 413 Request Entity Too Large
Server: nginx/1.18.0 (Ubuntu)

3. 原因分析

HTTP 413 错误明确表示请求体（Body）过大，超过了服务器允许的限制。

由于我们的架构是 Uni-app 前端 -> Nginx 反向代理 -> Node.js 后端，这个限制可能出现在两个地方：

1. Nginx 层：Nginx 作为网关，会最先接收请求。
2. Node.js 层：Express/Multer 中间件也有文件大小限制。

经过检查：

• Node.js 代码中 multer 配置了 limits: { fileSize: 5 * 1024 * 1024 }（5MB），理论上允许 1.7MB 的文件。
• 关键点：Nginx 的默认配置中，client_max_body_size 指令的默认值仅为 1MB。

因此，当请求体超过 1MB 时，Nginx 直接拦截了请求，导致请求根本没有到达 Node.js 后端。

4. 解决方法

步骤一：修改 Nginx 配置

在 Nginx 的配置文件（通常在 /etc/nginx/nginx.conf 或 /etc/nginx/conf.d/xxx.conf）的 server 块或 http 块中，增加或修改 client_max_body_size 指令。

server {
    listen 443 ssl;
    server_name zhangxiaoxi.cn www.zhangxiaoxi.cn api.zhangxiaoxi.cn;

    # --- 新增/修改配置 ---
    # 将上传限制调整为 20MB（根据实际需求调整）
    client_max_body_size 20M; 
    # -------------------

    # 其他配置...
    location / {
        proxy_pass http://127.0.0.1:3000;
        # ...
    }
}

步骤二：重载 Nginx 配置

修改配置文件后，必须重载或重启 Nginx 服务才能生效。

# 检查配置语法是否正确
nginx -t

# 重载配置（推荐，不中断服务）
nginx -s reload

# 或者完全重启服务（如果 reload 不生效）
service nginx restart

5. 小结

1. 413 错误通常是服务器限制了请求体大小。
2. 在涉及文件上传的项目中，务必检查 Nginx 和 后端应用（如 Node.js/Java/PHP） 两端的限制配置。
3. Nginx 默认限制非常小（1MB），这在现代应用中通常是不够用的，部署时需要作为标准检查项之一。
4. 修改 Nginx 配置后，不要忘记 nginx -s reload。