DockerでPHPのファイルアップロード設定をする方法｜php.ini・Nginx・docker-compose

Dockerで構築した環境では「ローカルで設定したはずなのにコンテナで反映されない」「Nginxコンテナを直したが PHP-FPMコンテナの設定が残っている」といった問題が起きやすいです。これは、Dockerコンテナが独立した環境を持つため、設定ファイルがホストとコンテナで分離されているためです。本記事では、NginxコンテナとPHP-FPMコンテナの組み合わせで、ファイルアップロード設定を正しく行う方法を体系的に解説します。

DockerでのPHPカスタム設定方法

PHP コンテナに独自の php.ini 設定を反映させる方法は主に2つあります。Dockerfile でイメージビルド時にファイルをコピーする方法と、docker-compose でボリュームマウントを使う方法です。

方法1: Dockerfile でphp.iniをコピー

# Dockerfile（PHP-FPM コンテナ）
FROM php:8.3-fpm-alpine

# 必要な拡張をインストール
RUN docker-php-ext-install pdo_mysql opcache

# カスタム php.ini をコンテナにコピー
# php.ini-development または php.ini-production をベースにする
COPY ./docker/php/php.ini /usr/local/etc/php/php.ini

# または conf.d ディレクトリに追加設定ファイルとして置く（推奨）
# 既存設定を上書きせず、変更したい値だけ記述できる
COPY ./docker/php/custom.ini /usr/local/etc/php/conf.d/99-custom.ini

WORKDIR /var/www/html

方法2: docker-compose でボリュームマウント

# docker-compose.yml
services:
  php:
    build:
      context: .
      dockerfile: ./docker/php/Dockerfile
    volumes:
      # アプリのソースコード
      - ./src:/var/www/html
      # php.ini をマウント（ファイル変更が即反映される）
      - ./docker/php/custom.ini:/usr/local/etc/php/conf.d/99-custom.ini:ro

ボリュームマウント方式は開発環境に向いており、設定ファイルを変更してコンテナを再起動するだけで反映できます。本番環境はイメージにコピーする Dockerfile 方式が推奨されます（イメージの再現性が保たれるため）。

必要な設定値と php.ini の書き方

ファイルアップロードに関連する設定値は4つあります。これらをまとめて設定した custom.ini ファイルを用意します。

; docker/php/custom.ini
; ============================================
; ファイルアップロード関連の設定
; ============================================

; ファイルアップロードを有効化（デフォルトOnだが明示する）
file_uploads = On

; 1ファイルあたりのアップロード上限
; Nginx の client_max_body_size と合わせること
upload_max_filesize = 100M

; POSTリクエスト全体の上限
; upload_max_filesize より大きくすること（フォームフィールドのオーバーヘッド分）
post_max_size = 110M

; ============================================
; メモリ・実行時間の設定
; ============================================

; PHPスクリプトが使用できる最大メモリ
; post_max_size より大きくすること
memory_limit = 256M

; スクリプトの最大実行時間（秒）
; 大きなファイルのアップロードや処理に対応
max_execution_time = 300

; リクエストデータ（POSTやファイル）の読み込み最大時間（秒）
; -1 で max_execution_time に従う
max_input_time = 300

php.ini の設定ファイルの場所を確認する方法

コンテナ内でどの php.ini が読み込まれているか確認するには、以下のコマンドを使います。

# コンテナ内で実行（docker exec 経由）
docker exec -it <コンテナ名> php -i | grep "php.ini"

# 出力例:
# Configuration File (php.ini) Path => /usr/local/etc/php
# Loaded Configuration File         => /usr/local/etc/php/php.ini

# Additional .ini files parsed（conf.d の追加設定）
docker exec -it <コンテナ名> php -i | grep "additional"
# Additional .ini files parsed => /usr/local/etc/php/conf.d/docker-php-ext-opcache.ini,
#   /usr/local/etc/php/conf.d/99-custom.ini

# 特定の設定値を確認
docker exec -it <コンテナ名> php -i | grep -E "upload_max|post_max|memory_limit"
# upload_max_filesize => 100M
# post_max_size       => 110M
# memory_limit        => 256M

Web 経由で確認する場合は phpinfo() を使います。

<?php
// /var/www/html/public/info.php （一時的なデバッグ用）
phpinfo();
// ※ 本番環境では削除すること（サーバー情報が丸見えになる）

NginxコンテナとPHP-FPMコンテナ間の設定の関係

Docker の典型的な PHP 構成は Nginx コンテナと PHP-FPM コンテナを分離する2コンテナ構成です。それぞれが独立した制限を持つため、両方の設定が適切でないとアップロードは失敗します。

クライアント
    │
    ▼（HTTP リクエスト）
┌──────────────────────────────┐
│  Nginx コンテナ              │  ← client_max_body_size で制限
│  client_max_body_size 100m;  │     ここを超えると 413 エラー
└──────────────────────────────┘
    │
    ▼（FastCGI プロトコル）
┌──────────────────────────────┐
│  PHP-FPM コンテナ            │  ← upload_max_filesize / post_max_size で制限
│  upload_max_filesize = 100M  │     ここを超えると UPLOAD_ERR_INI_SIZE
│  post_max_size = 110M        │
└──────────────────────────────┘

# docker/nginx/conf.d/default.conf
server {
    listen 80;
    server_name localhost;
    root /var/www/html/public;
    index index.php;

    # Nginx レベルのアップロード上限
    # PHP の upload_max_filesize / post_max_size 以上にする
    client_max_body_size 110m;

    # タイムアウト設定（大容量ファイル処理用）
    proxy_read_timeout 300s;
    proxy_send_timeout 300s;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass php:9000;   # PHP-FPMコンテナのサービス名:ポート
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;

        # FastCGI のタイムアウト設定
        fastcgi_read_timeout 300s;
        fastcgi_send_timeout 300s;
    }
}

docker-compose.yml の完全な設定例

Nginx + PHP-FPM + ボリュームマウントを含む完全な docker-compose.yml の例を示します。

version: '3.8'

services:
  # Nginx コンテナ
  nginx:
    image: nginx:1.27-alpine
    ports:
      - "8080:80"
    volumes:
      # アプリのソースコード（Nginx から静的ファイルを配信）
      - ./src:/var/www/html/public:ro
      # Nginx 設定ファイル
      - ./docker/nginx/conf.d:/etc/nginx/conf.d:ro
    depends_on:
      - php
    networks:
      - app-network

  # PHP-FPM コンテナ
  php:
    build:
      context: .
      dockerfile: ./docker/php/Dockerfile
    volumes:
      # アプリのソースコード
      - ./src:/var/www/html
      # PHP カスタム設定（開発時はマウントで即反映）
      - ./docker/php/custom.ini:/usr/local/etc/php/conf.d/99-custom.ini:ro
      # アップロードファイルの一時保存先（権限に注意）
      - upload_tmp:/tmp/php-uploads
    environment:
      PHP_UPLOAD_TMP_DIR: /tmp/php-uploads
    networks:
      - app-network

networks:
  app-network:
    driver: bridge

volumes:
  upload_tmp:
    driver: local

# docker/php/Dockerfile
FROM php:8.3-fpm-alpine

# 必要なシステムパッケージ
RUN apk add --no-cache \
    libpng-dev \
    libjpeg-turbo-dev \
    libwebp-dev \
    freetype-dev

# PHP 拡張のインストール
RUN docker-php-ext-configure gd \
        --with-freetype \
        --with-jpeg \
        --with-webp && \
    docker-php-ext-install \
        gd \
        pdo_mysql \
        opcache \
        exif

# アプリユーザーを作成（www-data と権限を合わせる）
RUN addgroup -g 1000 appuser && \
    adduser -u 1000 -G appuser -s /bin/sh -D appuser

USER appuser
WORKDIR /var/www/html

設定が反映されているか確認する方法

設定変更後は必ずコンテナを再起動し、設定が正しく読み込まれているか確認します。

# コンテナの再起動（設定ファイル変更を反映）
docker compose restart php

# または特定の設定値だけ確認
docker compose exec php php -r "echo ini_get('upload_max_filesize'), PHP_EOL;"
docker compose exec php php -r "echo ini_get('post_max_size'), PHP_EOL;"
docker compose exec php php -r "echo ini_get('memory_limit'), PHP_EOL;"

# 複数の値をまとめて確認
docker compose exec php php -r "
foreach (['upload_max_filesize', 'post_max_size', 'memory_limit', 'max_execution_time'] as \$key) {
    echo \$key . ' = ' . ini_get(\$key) . PHP_EOL;
}"

# Nginx の設定確認
docker compose exec nginx nginx -T | grep -E "client_max_body|server_name"

# Nginx の設定をリロード（コンテナ再起動なし）
docker compose exec nginx nginx -s reload

よくあるトラブルと解決法

本番環境向けの補足

本番環境では以下の点も考慮してください。

• php.ini はイメージビルド時に COPY で組み込み、ボリュームマウントしない（再現性のため）
• display_errors = Off・log_errors = On を必ず設定する
• アップロード先を S3 などのクラウドストレージにする場合、コンテナローカルへの一時保存はリクエスト処理中のみに留める
• 複数レプリカ（水平スケール）構成では、ローカルのアップロード先は使えない。S3や共有ストレージ（EFS・NFS）を使う
• PHP-FPM のプロセス数（pm.max_children）も大容量アップロードが同時多数発生するとメモリを圧迫する