Cómo configurar correctamente client_max_body_size en Nginx | Solución de problemas de límites de carga

Al implementar carga de archivos en Nginx, el problema de "los archivos pequeños se cargan bien pero los archivos grandes resultan en error 413" es muy frecuente. La causa es casi siempre la configuración insuficiente de <code>client_max_body_size</code>. Sin embargo, simplemente corregir la configuración de Nginx a menudo no resuelve el problema, y se necesita una comprensión integral que incluya <code>upload_max_filesize</code> y <code>post_max_size</code> de PHP, así como la configuración de tiempo de espera. Este artículo explica sistemáticamente todos los elementos de configuración relacionados con los límites de carga.

Valor predeterminado y función de client_max_body_size

Nginx tiene una directiva <code>client_max_body_size</code> que limita el tamaño máximo del cuerpo de solicitudes de clientes. El valor predeterminado es <code>1m</code> (1 MiB). Las solicitudes que superan este límite se rechazan inmediatamente con un error <code>413 Request Entity Too Large</code>.

Como el valor predeterminado es tan pequeño como 1m, rápidamente alcanzarás el límite incluso al cargar una sola imagen o PDF. En entornos de producción reales, necesitas aumentar este valor apropiadamente según tu caso de uso.

Ubicación de configuración: diferencias entre http / server / location

<code>client_max_body_size</code> se puede configurar en cualquier nivel de configuración de Nginx (http / server / location). La configuración de alcance más específico tiene prioridad.

# http ブロック（全サーバー共通）
http {
    client_max_body_size 10m;

    server {
        listen 80;
        server_name example.com;

        # server ブロック（このバーチャルホスト全体）
        client_max_body_size 50m;

        location /upload {
            # location ブロック（このパスのみ）
            # より大きなファイルを許可したい場合
            client_max_body_size 200m;

            proxy_pass http://app;
        }

        location /api {
            # APIエンドポイントはデフォルト（1m）のままにする例
            client_max_body_size 1m;
        }
    }
}

Establecer un valor más grande solo para puntos finales específicos de carga mientras se mantienen otros pequeños es la mejor práctica de seguridad. Puede especificar <code>0</code> para ilimitado, pero esto aumenta el riesgo de ataque DoS y no se recomienda.

Error 413 Request Entity Too Large: causas y soluciones

Organizaremos las causas y contramedidas para los errores 413.

Después de cambiar la configuración de Nginx, debe recargar siempre.

# 設定の文法チェック
nginx -t

# 設定のリロード（サービス停止なし）
nginx -s reload

# または systemd 経由
systemctl reload nginx

Relación con upload_max_filesize / post_max_size de PHP

Simplemente aumentar <code>client_max_body_size</code> de Nginx no es suficiente. Si el backend es PHP, también hay límites independientes a nivel de PHP. La carga tiene éxito solo cuando los tres de estos parámetros se establecen en valores apropiados.

; php.ini の設定
; 1ファイルあたりの上限
upload_max_filesize = 100M

; POSTリクエスト全体の上限（upload_max_filesize より大きくする）
; multipart/form-data のオーバーヘッド分を見込んで多めに設定
post_max_size = 110M

; メモリ上限（post_max_size より大きくする）
memory_limit = 256M

; アップロード処理の実行時間（大容量ファイル用に延ばす）
max_execution_time = 300
max_input_time = 300

Las relaciones entre valores de configuración importantes son las siguientes.

• client_max_body_size（Nginx） ≥ post_max_size（PHP） ≥ upload_max_filesize（PHP）
• Si Nginx rechaza una solicitud, el procesamiento nunca llega a PHP
• <code>post_max_size</code> es el límite de tamaño para todo el cuerpo POST, incluyendo cargas de archivos múltiples y campos de formulario sin archivos

Importancia de proxy_read_timeout / proxy_send_timeout

Al cargar archivos grandes, la configuración de tiempo de espera también es importante. El <code>proxy_read_timeout</code> predeterminado es de 60 segundos, y si la carga toma tiempo, el proceso se interrumpirá.

location /upload {
    client_max_body_size 500m;

    proxy_pass http://app_backend;

    # バックエンドからのレスポンス待機時間
    # 大容量ファイルの処理には長めに設定
    proxy_read_timeout 600s;

    # クライアントへのデータ送信待機時間
    proxy_send_timeout 600s;

    # バックエンドへの接続タイムアウト
    proxy_connect_timeout 60s;

    # クライアントのリクエストボディ受信タイムアウト
    # 2回の連続した読み取り操作の間の時間
    client_body_timeout 120s;
}

Se recomienda establecer valores de tiempo de espera diferentes para puntos finales de carga y puntos finales de API regulares.

Configuración en Docker (Montaje de nginx.conf)

En entornos Docker, los archivos nginx.conf o conf.d personalizados se montan en contenedores para aplicar la configuración.

# Dockerfile でのカスタム設定追加
FROM nginx:alpine

# カスタム設定ファイルをコピー
COPY ./nginx/conf.d/upload.conf /etc/nginx/conf.d/upload.conf

# デフォルト設定を完全に置き換える場合
# COPY ./nginx/nginx.conf /etc/nginx/nginx.conf

# docker-compose.yml でのボリュームマウント
version: '3.8'
services:
  nginx:
    image: nginx:alpine
    volumes:
      # ディレクトリごとマウント（変更が即反映される）
      - ./nginx/conf.d:/etc/nginx/conf.d
      # または特定ファイルだけマウント
      # - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
    ports:
      - "80:80"

# nginx/conf.d/upload.conf
server {
    listen 80;
    server_name localhost;

    # グローバルのアップロード上限
    client_max_body_size 100m;

    location / {
        proxy_pass http://app:9000;
        proxy_read_timeout 300s;
        proxy_send_timeout 300s;
    }

    location /upload {
        client_max_body_size 500m;
        proxy_pass http://app:9000;
        proxy_read_timeout 600s;
        proxy_send_timeout 600s;
    }
}

Comando de verificación de configuración

Para verificar qué valor tiene <code>client_max_body_size</code> en tu configuración actual de Nginx, es conveniente expandir todas las configuraciones con <code>nginx -T</code> y luego hacer grep en el resultado.

# 全設定を展開して client_max_body_size を検索
nginx -T | grep -i body_size

# 出力例:
#   client_max_body_size 1m;   ← デフォルト（http ブロック）
#   client_max_body_size 100m; ← カスタム設定（server ブロック）

# 設定ファイルのパスも確認
nginx -T | grep "# configuration"

# 特定の設定ファイルだけチェック
nginx -t -c /etc/nginx/nginx.conf

# 現在読み込まれている設定のダンプ
nginx -T 2>/dev/null | grep -A1 "client_max"

Errores de configuración comunes y cómo solucionarlos

• <strong>Error de unidad</strong>: <code>client_max_body_size 100</code> especifica bytes de forma predeterminada. Siempre especifica una unidad como <code>100m</code>
• <strong>Descuido jerárquico</strong>: Crees que estás sobrescribiendo dentro de un bloque location, pero un bloque server o http de nivel superior está en vigor
• <strong>Olvido de recarga</strong>: Los cambios de configuración no tendrán efecto a menos que ejecutes <code>nginx -s reload</code>
• <strong>Múltiples bloques de servidor</strong>: Otro archivo conf.d cargado mediante include está en conflicto
• <strong>Desajuste con PHP</strong>: Aunque aumente los límites de Nginx, si <code>upload_max_filesize</code> de PHP sigue siendo bajo, pueden ocurrir errores distintos de 413