Symfony返回二进制响应的核心是流式或文件句柄输出，正确设置Content-Type、Content-Disposition等响应头；推荐BinaryFileResponse（本地文件）、StreamedResponse（动态大文件）和Response（小文件），并注意中文文件名RFC 5987编码。
Symfony 返回二进制响应（如图片、PDF、Excel、ZIP 等文件）的核心是避免将整个文件加载进内存，而是通过流式或直接文件句柄方式输出，同时正确设置响应头。关键不在于“压缩”或“编码”，而在于精准控制 Content-Type、Content-Disposition 和传输机制。
用 BinaryFileResponse 直接输出本地文件
这是最常用、最高效的方式，适用于已存在的磁盘文件（如上传后保存的 PDF、生成的报表）：
- 自动设置 Content-Length、Content-Type（基于文件扩展名）、Accept-Ranges（支持断点续传）
- 内部使用
readfile()+fastcgi_finish_request()（PHP-FPM 下），零内存拷贝 - 文件路径必须绝对且可读；相对路径会出错
示例：
use Symfony\Component\HttpFoundation\BinaryFileResponse;
use Symfony\Component\HttpFoundation\ResponseHeaderBag;
public function downloadReport(): BinaryFileResponse
{
$file = '/var/www/project/public/reports/2026-05-report.pdf';
$response = new BinaryFileResponse($file);
$response->setContentDisposition(
ResponseHeaderBag::DISPOSITION_ATTACHMENT,
'monthly-report-2026-05.pdf'
);
return $response;
}
用 StreamedResponse 流式生成并输出
适合动态生成大文件（如导出万条数据为 CSV、打包多个文件为 ZIP、实时渲染 PDF），不落盘、不占内存：
- 响应体由闭包函数按需写入，框架接管底层 flush 和 header 发送
- 必须手动设置 Content-Type 和 Content-Disposition
- 禁用输出缓冲（
ob_end_clean()）和默认缓存头，防止截断
示例（导出 CSV）：
use Symfony\Component\HttpFoundation\StreamedResponse;
public function exportUsersCsv(): StreamedResponse
{
$response = new StreamedResponse(function () {
$handle = fopen('php://output', 'wb');
// 写入 CSV 头
fputcsv($handle, ['ID', 'Name', 'Email']);
// 查询并逐行写入（非全量加载）
$users = $this->userRepository->findActiveUsersForExport();
foreach ($users as $user) {
fputcsv($handle, [$user->getId(), $user->getName(), $user->getEmail()]);
}
fclose($handle);
});
$response->headers->set('Content-Type', 'text/csv; charset=utf-8');
$response->headers->set('Content-Disposition', 'attachment; filename="users-export.csv"');
$response->headers->set('Cache-Control', 'no-cache');
return $response;
}
用 Response 返回原始二进制字符串
仅适用于小文件（
- 直接传入
string或resource，但注意内存占用 - 必须显式指定 Content-Type 和 Content-Length（推荐）
- 对 PNG/JPEG 等常见类型，可用
mime_content_type()或扩展名推断
示例（返回 GD 图像）：
use Symfony\Component\HttpFoundation\Response;
public function avatarImage(int $userId): Response
{
$image = imagecreatefrompng('/path/to/avatar.png');
ob_start();
imagepng($image);
imagedestroy($image);
$content = ob_get_clean();
$response = new Response($content, 200, [
'Content-Type' => 'image/png',
'Content-Length' => strlen($content),
]);
return $response;
}
文件名与中文兼容处理
浏览器对中文文件名支持不一，建议采用 RFC 5987 标准编码：
- 不要拼接
filename="中文.pdf"—— 在 Safari/旧版 IE 中会乱码或截断 - 改用
filename*=UTF-8''%E4%B8%AD%E6%96%87.pdf形式 - Symfony 的
ResponseHeaderBag已内置支持：$response->setContentDisposition(..., '用户列表.xlsx')会自动编码
手动设置时可复用：
$filename = '用户导出.xlsx';
$encoded = rawurlencode($filename);
$response->headers->set('Content-Disposition', "attachment; filename*=UTF-8''{$encoded}"); 
