在 Symfony 6.4 中用 Flysystem 安全流式传输 S3 私有文件，需配置正确 adapter（client、bucket、visibility、credentials），优先用 readStream() 获取流，配合 StreamedResponse 设置 Content-Type、inline Content-Disposition 和 private Cache-Control 头。
在 Symfony 6.4 中用 Flysystem 读取 S3 私有存储桶中的文件并返回 HTTP 响应，核心不是“下载”，而是安全流式传输：不落地、不暴露原始 URL、不绕过权限控制。关键在于用 Flysystem 获取流或内容后，构造合适的 Response，并设置正确头信息。
确认 Flysystem 配置支持私有读取
私有文件能读出来，前提是 Flysystem adapter 已正确配置为允许读操作且凭证有效：
-
client 必须是容器中已注册的
Aws\S3\S3Client服务 ID（如s3_client），不能写字符串类名 -
bucket 名必须完全匹配（大小写敏感），不能带
s3://前缀 -
visibility 应设为
private，对应 bucket 策略禁止 public-read；若配成public却策略限制，read()会直接抛AccessDenied - 使用 IAM role 时，
credentials必须显式设为null，否则 Flysystem 可能静默 fallback 到环境变量而失败
获取文件流而非全量内容
对大文件或节省内存，优先用 readStream() 而非 read()，避免把整个文件加载进 PHP 内存：
Kadence Theme Design System
下载
使用 Kadence 主题作为 WordPress 项目的设计系统，涵盖设计令牌、布局系统、页头/页脚/导航设置以及页面/归档/单篇文章模板。
$stream = $filesystem->readStream('private/reports/q3.pdf');- 检查流是否有效：
is_resource($stream) && get_resource_type($stream) === 'stream' - 若返回
false，说明文件不存在或无读权限，应抛出FileNotFoundException或返回 404
构造响应并设置关键头信息
流式响应需明确告知浏览器内容类型、长度（可选）、不缓存（尤其私有内容）：
- 用
Symfony\Component\HttpFoundation\BinaryFileResponse不适用（它要求本地路径）；改用StreamedResponse - 先调用
$filesystem->mimeType('path')获取 MIME 类型，fallback 到application/octet-stream（S3 adapter 支持此方法） - 设置
Content-Type、Content-Disposition: inline（让浏览器尝试内嵌显示 PDF/图片等） - 添加
Cache-Control: private, no-store, no-cache防止 CDN 或代理缓存私有文件
示例代码片段：
$mimeType = $filesystem->mimeType('private/doc.pdf') ?: 'application/octet-stream';
$response = new StreamedResponse(function () use ($filesystem) {
$stream = $filesystem->readStream('private/doc.pdf');
if (!$stream) {
throw new FileNotFoundException();
}
fpassthru($stream);
fclose($stream);
});
$response->headers->set('Content-Type', $mimeType);
$response->headers->set('Content-Disposition', 'inline; filename="doc.pdf"');
$response->headers->set('Cache-Control', 'private, no-store, no-cache');
return $response;
处理常见失败点
很多“返回空白”或 500 实际是链路前端中断：
- 前端请求未通过认证中间件？私有文件访问必须确保控制器方法受防火墙保护（如
is_granted('ROLE_USER')） - 调用
readStream()前未验证文件存在：$filesystem->has('path')可提前拦截 404 - PHP 或 Nginx 限制了响应超时或缓冲区，大文件流式传输失败——检查
max_execution_time和fastcgi_buffer_size - S3 返回 403 时，Flysystem 默认转为
RuntimeException，建议 try/catch 并记录原始错误码（如$e->getAwsErrorCode()）
