PHP 無法上傳大檔案？php.ini 與 Nginx 完整調教指南

上傳大檔案失敗通常是「多層限制疊加」：PHP 設定、Nginx 設定、表單屬性、瀏覽器行為。本文提供從 php.ini 到 Nginx、再到前端表單的完整檢查清單與設定範例，一次解決所有瓶頸。

第一層：php.ini 核心參數（必改）

修改後必須重啟 php-fpm：systemctl reload php8.2-fpm。

第二層：Nginx 客戶端請求體積限制

# nginx.conf / http {} 或 server {} 或 location {}
client_max_body_size 200m;        # 預設 1m，超過回 413 Request Entity Too Large
client_body_buffer_size 10m;      # 緩衝區，太小會頻繁落磁碟拖慢速度
client_body_temp_path /var/lib/nginx/body 1 2; # 臨時檔目錄需可寫

修改後 nginx -t && systemctl reload nginx。

第三層：前端表單必備屬性

<form action="upload.php" method="post" enctype="multipart/form-data">
    <!-- 僅為瀏覽器端提示，不可信，後端仍需驗證 -->
    <input type="hidden" name="MAX_FILE_SIZE" value="209715200">
    <input type="file" name="file" id="file">
    <button type="submit">上傳</button>
</form>

第四層：PHP 接收端範例（含分塊/斷點續傳預留）

<?php
// upload.php
$targetDir = '/var/www/uploads/';
$maxSize   = 200 * 1024 * 1024; // 200MB
$allowed   = ['image/jpeg','image/png','application/pdf'];

if ($_SERVER['REQUEST_METHOD'] !== 'POST') exit('Method not allowed');
if (!isset($_FILES['file']) || $_FILES['file']['error'] !== UPLOAD_ERR_OK) {
    exit('上傳錯誤代碼: ' . ($_FILES['file']['error'] ?? '未知'));
}
if ($_FILES['file']['size'] > $maxSize) exit('檔案過大');
if (!in_array($_FILES['file']['type'], $allowed)) exit('類型不允許');

// 安全檔名：UUID + 原始副檔名
$ext = pathinfo($_FILES['file']['name'], PATHINFO_EXTENSION);
$newName = bin2hex(random_bytes(16)) . '.' . $ext;
$dest = $targetDir . $newName;

if (!move_uploaded_file($_FILES['file']['tmp_name'], $dest)) {
    exit('移動檔案失敗，請檢查權限');
}
// 後續：記錄資料庫、觸發佇列處理、回傳 JSON
echo json_encode(['ok'=>true, 'path'=>'/uploads/'.$newName]);

常見錯誤碼速查

進階：超大檔（>2GB）與斷點續傳

• PHP 32 位元整數溢位，需 64 位元 PHP + post_max_size = 0（無限制）。
• 前端採用 Resumable.js / Uppy 分片上傳，後端合併分片。
• Nginx proxy_request_buffering off; 避免代理緩衝大檔案導致記憶體暴增。

照著清單逐項核對，99% 的「上傳大檔失敗」都能在 10 分鐘內解決。