Nginx 文件上傳大小限制及 client_max_body_size最大值問題記錄

更新時間：2025年05月17日 14:34:55 作者：Hello.Reader

這篇文章主要介紹了Nginx 文件上傳大小限制及 client_max_body_size最大值問題,本文給大家介紹的非常詳細,對大家的學習或工作具有一定的參考借鑒價值,需要的朋友可以參考下

一、默認值與錯誤提示

默認值：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（不區(qū)分大小寫），如 10K、2m、1G。

三、client_max_body_size 的最大上限

Nginx 在內部將該值存儲為 C 語言類型 off_t，其位寬決定了上限：

64 位可執(zhí)行文件

off_t 為 64 位有符號整數(shù)，理論最大值為 2?³ − 1 字節(jié)（約 9.22×10¹? 字節(jié)，≈ 8 EiB），故可將 client_max_body_size 設置至 2^63 而不報錯。

32 位可執(zhí)行文件（未啟用大文件支持）

off_t 為 32 位有符號整數(shù)，其最大值約為 2³¹ − 1（約 2 GiB），即 2147483647 字節(jié)。若需突破此限制，可在編譯時定義 _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 不再在自身層面攔截任何大小的請求體。

五、實戰(zhàn)示例

按需放寬單接口限制

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 或前端上傳大文件，確認是否仍出現(xiàn) 413 錯誤，并查看 /var/log/nginx/error.log 以排查問題。

七、小結

核心指令：client_max_body_size 決定 Nginx 層面的請求體大小上限。
默認值：1 MiB（1m）。
最大上限：由 off_t 位寬決定，64 位環(huán)境支持至 2?³ − 1 字節(jié)，32 位環(huán)境（未啟用大文件支持）限約 2 GiB。
取消限制：設置為 0 即可禁用檢查，允許無限制上傳。

通過上述配置與示例，您可以靈活地調整或取消 Nginx 的上傳大小限制，滿足從小型表單到超大文件傳輸?shù)母鞣N業(yè)務需求。

到此這篇關于Nginx 文件上傳大小限制及 client_max_body_size最大值問題記錄的文章就介紹到這了,更多相關nginx 文件上傳大小限制內容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關文章希望大家以后多多支持腳本之家！

您可能感興趣的文章: