symfony 7.3 大文件下载应优先使用 binaryfileresponse（静态文件）或 streamedresponse（动态内容），二者均支持流式传输且不占内存；binaryfileresponse 适用于 public/ 下已存在文件，自动设头并由 web 服务器直接发送；streamedresponse 需手动清缓冲、设响应头、flush 输出，适合 zip 打包等运行时生成场景。
在 Symfony 7.3 中实现大文件下载，核心是避免把整个文件加载进内存。推荐用 StreamedResponse（动态生成或大体积文件）或 BinaryFileResponse（已存在的磁盘文件）。两者都支持流式传输，但适用场景不同。
用 BinaryFileResponse 下载已存在的本地文件
这是最简单、最高效的方式，适合文件已保存在 public/ 目录下（如上传后移动过的 PDF、图片、ZIP 包）：
确保路径绝对、可读，且 Web 服务器有权限访问
- 文件必须位于 Web 根目录（如
public/uploads/report.pdf），不能在var/或src/等私有路径 - 响应自动设置
Content-Length、Content-Type和断点续传头（Accept-Ranges） - 不占 PHP 内存，由 Web 服务器直接发送文件内容
示例代码：
use Symfony\Component\HttpFoundation\BinaryFileResponse;
use Symfony\Component\HttpFoundation\ResponseHeaderBag;
public function downloadFile(): BinaryFileResponse
{
$filePath = $this->getParameter('kernel.project_dir').'/public/uploads/report.pdf';
$response = new BinaryFileResponse($filePath);
$response->setContentDisposition(
ResponseHeaderBag::DISPOSITION_ATTACHMENT,
'monthly-report-2026-10.pdf'
);
return $response;
}
用 StreamedResponse 流式输出动态内容（如打包 ZIP）
适用于需要运行时构建 ZIP、导出超大数据 CSV、或实时生成 JSON 流等场景——不落盘、不爆内存。
关键：清缓冲、设对头、手动 flush、禁止异常中断
- 开头必须调用
ob_end_clean()清掉已有输出缓冲 - 必须手动设置
Content-Type和Content-Disposition，框架不会自动推断 - 每次
echo后紧跟flush()，确保数据立即推给客户端 - 回调函数内不能抛异常、不能重定向、不能
exit
ZIP 打包下载示例（使用原生 ZipArchive + 内存流）：
use Symfony\Component\HttpFoundation\StreamedResponse;
public function downloadBatchZip(): StreamedResponse
{
$filePaths = [
'/var/www/project/public/uploads/photo1.jpg',
'/var/www/project/public/uploads/data.json',
];
// 路径校验（防遍历）
$safePaths = [];
$rootDir = $this->getParameter('kernel.project_dir').'/public/';
foreach ($filePaths as $path) {
$realPath = realpath($path);
if ($realPath && str_starts_with($realPath, $rootDir) && is_file($realPath) && is_readable($realPath)) {
$safePaths[] = $realPath;
}
}
return new StreamedResponse(function () use ($safePaths) {
ob_end_clean();
$zip = new \ZipArchive();
if ($zip->open('php://memory', \ZipArchive::CREATE) !== true) {
throw new \RuntimeException('Cannot create ZIP in memory');
}
foreach ($safePaths as $path) {
$archiveName = basename($path); // 避免解压出现完整绝对路径
$zip->addFile($path, $archiveName);
}
$zip->close();
// 从内存流读取并输出
$stream = fopen('php://memory', 'r');
fpassthru($stream);
fclose($stream);
}, 200, [
'Content-Type' => 'application/zip',
'Content-Disposition' => 'attachment; filename="batch-20261014.zip"',
'Content-Transfer-Encoding' => 'binary',
'Cache-Control' => 'private, must-revalidate, max-age=0',
]);
}
注意事项与避坑点
实际部署中容易忽略但影响极大的细节：
-
中文文件名不要直接写入
Content-Disposition：浏览器兼容性差，应转为 RFC 5987 编码（如%E6%8A%A5%E8%A1%A8.pdf） -
Nginx/Apache 需关闭
fastcgi_buffering或proxy_buffering，否则会缓存整个流再返回，失去“边生成边下载”意义 -
PHP-FPM 建议调大
request_terminate_timeout，防止大文件传输中途被强制杀进程 - 若用
maennchen/zipstream-php替代原生 ZipArchive，它默认写到php://output，需同样配合ob_end_clean()和flush()
