文件下載看似簡單,實則暗藏坑點:大文件內存溢出、中文文件名亂碼、瀏覽器兼容性、斷點續傳、防盜鏈、權限控制。本文提供一個生產級 FileDownloader 類,涵蓋所有核心場景,代碼可直接投入使用。
<?php
/**
* 生產級文件下載器
* 特性:
* - 支持大文件(流式輸出,不佔內存)
* - 支持斷點續傳(HTTP Range / HTTP 206)
* - 中文文件名 RFC 5987 編碼兼容所有瀏覽器
* - 安全路徑驗證(防目錄遍歷)
* - 速度限制、並發控制擴展點
*/
class FileDownloader
{
private $filePath;
private $downloadName;
private $mimeType;
private $speedLimit = 0; // bytes/s, 0 = 無限制
private $bufferSize = 8192;
public function __construct(string $filePath, string $downloadName = '', string $mimeType = '')
{
$this->filePath = $this->normalizePath($filePath);
$this->downloadName = $downloadName ?: basename($this->filePath);
$this->mimeType = $mimeType ?: $this->guessMimeType();
}
/** 設置下載速度限制 (KB/s) */
public function setSpeedLimit(int $kbPerSecond): self
{
$this->speedLimit = $kbPerSecond * 1024;
return $this;
}
/** 執行下載 */
public function download(): void
{
$this->validateFile();
$this->sendHeaders();
$this->outputFile();
exit; // 確保腳本結束
}
/** 路徑標準化與安全驗證 */
private function normalizePath(string $path): string
{
$realBase = realpath('/data/uploads'); // 你的文件存儲根目錄
$realPath = realpath($path);
if ($realPath === false || strpos($realPath, $realBase) !== 0) {
throw new RuntimeException('Invalid file path');
}
return $realPath;
}
private function validateFile(): void
{
if (!is_file($this->filePath) || !is_readable($this->filePath)) {
http_response_code(404);
exit('File not found or not readable');
}
}
/** 發送 HTTP 頭:Content-Type, Content-Disposition, Content-Length, Accept-Ranges, Cache-Control */
private function sendHeaders(): void
{
$fileSize = filesize($this->filePath);
$lastModified = gmdate('D, d M Y H:i:s', filemtime($this->filePath)) . ' GMT';
$etag = md5($this->filePath . $fileSize . $lastModified);
// 緩存控制
header('Cache-Control: public, must-revalidate');
header('Pragma: public');
header('Last-Modified: ' . $lastModified);
header('ETag: ' . $etag);
// 文件類型
header('Content-Type: ' . $this->mimeType);
header('Content-Length: ' . $fileSize);
header('Accept-Ranges: bytes');
// 文件名編碼:RFC 5987 (UTF-8'') + fallback
$encodedName = rawurlencode($this->downloadName);
header("Content-Disposition: attachment; filename=\"{$encodedName}\"; filename*=UTF-8''{$encodedName}");
// 處理範圍請求(斷點續傳核心)
$rangeStart = 0;
$rangeEnd = $fileSize - 1;
$statusCode = 200;
if (isset($_SERVER['HTTP_RANGE'])) {
$range = $_SERVER['HTTP_RANGE'];
if (preg_match('/bytes=(\d+)-(\d*)/', $range, $matches)) {
$rangeStart = (int)$matches[1];
$rangeEnd = $matches[2] !== '' ? (int)$matches[2] : $fileSize - 1;
if ($rangeStart < $fileSize && $rangeEnd < $fileSize && $rangeStart <= $rangeEnd) {
$statusCode = 206; // Partial Content
header('Content-Range: bytes ' . $rangeStart . '-' . $rangeEnd . '/' . $fileSize);
header('Content-Length: ' . ($rangeEnd - $rangeStart + 1));
} else {
header('Content-Range: bytes */' . $fileSize);
http_response_code(416); // Range Not Satisfiable
exit;
}
}
}
http_response_code($statusCode);
}
/** 流式輸出文件內容,支持速度限制 */
private function outputFile(): void
{
$fp = fopen($this->filePath, 'rb');
if (!$fp) {
http_response_code(500);
exit('Cannot open file');
}
// 定位到範圍起始位置
if (isset($_SERVER['HTTP_RANGE'])) {
fseek($fp, $rangeStart ?? 0);
}
$bytesSent = 0;
$chunkSize = $this->bufferSize;
$startTime = microtime(true);
while (!feof($fp) && connection_status() === CONNECTION_NORMAL) {
$chunk = fread($fp, $chunkSize);
echo $chunk;
$bytesSent += strlen($chunk);
// 速度限制
if ($this->speedLimit > 0) {
$elapsed = microtime(true) - $startTime;
$expectedTime = $bytesSent / $this->speedLimit;
if ($expectedTime > $elapsed) {
usleep(($expectedTime - $elapsed) * 1000000);
}
}
// 定期 flush 避免緩衝區過大
if ($bytesSent % (1024 * 1024) === 0) { // 每 1MB flush
@ob_flush();
@flush();
}
}
fclose($fp);
}
/** 猜測 MIME 類型 */
private function guessMimeType(): string
{
$finfo = finfo_open(FILEINFO_MIME_TYPE);
$mime = finfo_file($finfo, $this->filePath);
finfo_close($finfo);
return $mime ?: 'application/octet-stream';
}
}
<?php
// 下載控制器
public function download(string $id): void
{
// 1. 權限校驗、記錄日志、獲取文件信息
$fileRecord = FileModel::find($id);
if (!$fileRecord || !$this->checkPermission($fileRecord)) {
abort(403);
}
// 2. 實例化下載器
$downloader = new FileDownloader(
$fileRecord->storage_path,
$fileRecord->original_name, // 用戶看到的文件名
$fileRecord->mime_type
);
// 可選:限速 500 KB/s
// $downloader->setSpeedLimit(500);
// 3. 執行下載(內部會 exit)
$downloader->download();
}
將文件傳輸卸載給 Nginx,PHP 僅負責權限校驗,極大降低 PHP 進程佔用。
// Nginx 配置
location /protected-files/ {
internal; # 只允許內部重定向
alias /data/uploads/; # 文件真實存儲路徑
add_header Content-Disposition "attachment; filename=$arg_filename; filename*=UTF-8''$arg_filename";
}
// PHP 控制器
public function downloadXAccel(string $id): void
{
$fileRecord = FileModel::find($id);
// ... 權限校驗 ...
// 發送 X-Accel-Redirect 頭,Nginx 接管傳輸
header('X-Accel-Redirect: /protected-files/' . $fileRecord->storage_relative_path);
header('Content-Type: ' . $fileRecord->mime_type);
header('Content-Disposition: attachment; filename="' . rawurlencode($fileRecord->original_name) . '"; filename*=UTF-8\'\'' . rawurlencode($fileRecord->original_name));
header('Content-Length: ' . $fileRecord->file_size);
exit;
}
| 問題 | 解決方案 |
|---|---|
| 大文件內存溢出 | 流式讀取 fread() + echo,不將整個文件載入內存 |
| 中文文件名亂碼 | Content-Disposition: attachment; filename="urlencoded"; filename*=UTF-8''urlencoded (RFC 5987) |
| 斷點續傳/多線程下載 | 支持 HTTP Range 請求,返回 206 Partial Content + Content-Range |
| 防盜鏈/權限控制 | PHP 層校驗權限後再發送文件,或使用 Nginx secure_link 模塊 |
| 目錄遍歷攻擊 | realpath() 驗證路徑在允許的根目錄下 |
| 瀏覽器直接打開而非下載 | 設置 Content-Type: application/octet-stream 或具體 MIME + Content-Disposition: attachment |
@ob_end_clean() 清理輸出緩衝,避免輸出混入文件內容導致文件損壞。Content-Length 否則瀏覽器無法顯示進度條。set_time_limit(0) 防止腳本超時。connection_status() 檢測客戶端斷開,及時停止傳輸釋放資源。這套方案已在千萬級下載量系統穩定運行,覆蓋了從基礎到高級的所有常見需求。根據項目規模選擇純 PHP 或 Nginx 協作模式即可。