Nginx 文件上传大小限制及 `client_max_body_size` 最大值详解

lwb_0118

于 2025-07-29 21:20:15 发布

阅读量280

点赞数 5

CC 4.0 BY-SA版权

分类专栏：面试学习路线阿里巴巴文章标签： nginx 运维

本文链接：https://blog.csdn.net/lwb_0118/article/details/149756176

面试同时被 3 个专栏收录

51 篇文章

订阅专栏

阿里巴巴

51 篇文章

订阅专栏

学习路线

47 篇文章

订阅专栏

一、默认值与错误提示

默认值：client_max_body_size 1m;
Nginx 默认允许的请求体最大为 1 MiB，超过该值会返回 413 Request Entity Too Large 错误。

错误提示示例：

HTTP/1.1 413 Request Entity Too Large
Content-Type: text/html

二、如何配置 `client_max_body_size`

该指令可放置在 http、server 或 location 块中，后者会覆盖前者的配置：

http {
    # 全局设置，作用于所有 server
    client_max_body_size 50m;

    server {
        listen 80;
        server_name example.com;

        # 针对某个虚拟主机单独设置
        client_max_body_size 100m;

        location /upload {
            # 针对特定路径再度覆盖
            client_max_body_size 200m;
            proxy_pass http://backend;
        }
    }
}

说明：在嵌套块中声明的 client_max_body_size 会覆盖祖先块中的同名指令citeturn1search1。
单位：支持 k、m、g（不区分大小写），如 10K、2m、1G。

三、`client_max_body_size` 的最大上限

Nginx 在内部将该值存储为 C 语言类型 off_t，其位宽决定了上限：

64 位可执行文件
- off_t 为 64 位有符号整数，理论最大值为 23 1 字节（约 9.22×101 字节，≈ 8 EiB），故可将 client_max_body_size 设置至 2^63 而不报错。
32 位可执行文件（未启用大文件支持）
- off_t 为 32 位有符号整数，其最大值约为 231 1（约 2 GiB），即 2147483647 字节。若需突破此限制，可在编译时定义 _FILE_OFFSET_BITS=64 启用大文件支持，使 off_t 拓展至 64 位。

四、取消大小检查（无限制上传）

将 client_max_body_size 设置为 0，可禁用对请求体大小的检查，允许无限制上传或 POST 请求：

server {
    listen 80;
    server_name unlimited.example.com;

    # 取消大小限制
    client_max_body_size 0;

    location / {
        proxy_pass http://backend;
    }
}

说明：设置为 0 时，Nginx 不再在自身层面拦截任何大小的请求体。

五、实战示例

按需放宽单接口限制

server {
    listen 80;
    server_name upload.example.com;

    # 默认允许 10MiB
    client_max_body_size 10m;

    location /api/v1/upload {
        # 单接口放宽至 500MiB
        client_max_body_size 500m;
        proxy_pass http://backend_upload;
    }
}

开启无限制上传

server {
    listen 80;
    server_name files.example.com;

    # 完全取消 Nginx 层面的大小限制
    client_max_body_size 0;

    location /files {
        proxy_pass http://backend_files;
    }
}

六、配置验证

# 检查配置语法
nginx -t

# 重载 Nginx（应用新配置）
nginx -s reload

随后可使用 curl 或前端上传大文件，确认是否仍出现 413 错误，并查看 /var/log/nginx/error.log 以排查问题。

七、小结

核心指令：client_max_body_size 决定 Nginx 层面的请求体大小上限。
默认值：1 MiB（1m）。
最大上限：由 off_t 位宽决定，64 位环境支持至 23 1 字节，32 位环境（未启用大文件支持）限约 2 GiB。
取消限制：设置为 0 即可禁用检查，允许无限制上传。

通过上述配置与示例，您可以灵活地调整或取消 Nginx 的上传大小限制，满足从小型表单到超大文件传输的各种业务需求。

Nginx 文件上传大小限制及 `client_max_body_size` 最大值详解

一、默认值与错误提示

二、如何配置 client_max_body_size

三、client_max_body_size 的最大上限

四、取消大小检查（无限制上传）

五、实战示例

六、配置验证

七、小结

二、如何配置 `client_max_body_size`

三、`client_max_body_size` 的最大上限