symfony 6.4+集成s3最稳方式是league/flysystem-aws-s3-v3 + oneup_flysystem-bundle，避免手动new s3client；需正确配置client、bucket、visibility等关键项，并检查表单编码、php上传限制及元数据大小写规范。
直接用 league/flysystem-aws-s3-v3 + oneup_flysystem-bundle 是当前 Symfony（6.4+）集成 S3 最稳、最轻量、也最符合框架习惯的方式。硬套 AWS SDK 原生客户端或自己封装上传逻辑，反而容易绕进权限、临时凭证、流式上传失败等坑里。
为什么不用直接 new Aws\S3\S3Client？
Symfony 项目里手动 new Aws\S3\S3Client 看似自由，实际会快速暴露三个问题：
- 无法被容器自动管理生命周期，
credentials和region难以按环境隔离（比如本地用 minio，生产用 real S3） - 缺少统一的抽象层，后续想切到 GCS 或本地磁盘时，所有业务代码都要重写
putObject()、getObject()调用 - 不处理文件元数据（如
Cache-Control、Content-Type）的自动推导，上传图片却返回binary/octet-stream是常态
而 flysystem 抽象掉这些细节，你只管 $filesystem->write('avatars/123.jpg', $content)，MIME 类型、ETag、ACL 都能通过配置或 adapter 参数控制。
oneup_flysystem.yaml 中必须配对的 key
关键不是“怎么写 YAML”，而是哪几项配错会导致静默失败或 403：
-
client必须指向一个已定义的Aws\S3\S3Client服务（不能是字符串名），且该服务的credentials必须是数组结构，key/secret不能为 null —— 即使用了 IAM role，也要显式设为null，否则 Flysystem 会 fallback 到 env 变量，但不报错 -
bucket值必须和真实 bucket 名完全一致（含大小写），S3 对 bucket 名是严格区分的；若填了带s3://前缀的字符串，flysystem不会报错，但所有操作都返回 false -
options下的visibility默认是public，但如果你的 bucket 策略禁止 public-read，就得显式设为private，否则write()成功，read()却抛AccessDenied
典型安全配置片段：
oneup_flysystem:
adapters:
s3_adapter:
awss3v3:
client: 'Aws\S3\S3Client'
bucket: '%env(AWS_S3_BUCKET)%'
options:
visibility: private
acl: private
上传前必须检查的三件事
很多“上传没反应”“文件 0 字节”问题，其实跟 S3 无关，而是本地环节断了：
- 前端表单是否带
enctype="multipart/form-data"？漏了这行，$request->files就是空的，UploadedFile::move()会报 “file not found in temporary directory” -
php.ini的upload_max_filesize和post_max_size是否足够？上传 5MB 文件却只设了 2MB，$file->getError()会返回UPLOAD_ERR_INI_SIZE，但默认不显示 - 是否在 move 之后才读取
$file->getClientOriginalName()？别在move()前就用它生成路径，因为临时文件可能已被清理（尤其 Nginx + php-fpm fastcgi_finish_request 场景）
如何让上传的图片带 Cache-Control 和自定义 metadata
Flysystem 默认不传额外 header，但 S3 adapter 支持通过 writeStream() 或 write() 的第三个参数注入：
$stream = fopen($tmpPath, 'r');
$filesystem->writeStream(
'images/photo.jpg',
$stream,
[
'ContentType' => 'image/jpeg',
'CacheControl' => 'public, max-age=31536000',
'Metadata' => ['uploaded_by' => 'admin'],
'ACL' => 'private',
]
);
注意：ContentType 必须全大写，CacheControl 不能写成 cache-control，否则 S3 会忽略；Metadata 键名会自动转为小写并加 x-amz-meta- 前缀，读取时需用 getMetadata() 方法获取，不能靠 HTTP header 直接读。
真正麻烦的从来不是“怎么连上 S3”，而是当 write() 返回 true 却在浏览器打不开链接时，得一层层确认：CloudFront 是否缓存了 403、bucket policy 是否限制了 referer、CORS 配置是否允许你的域名、甚至 PHP 进程有没有权限读取临时文件——这些点散落在不同层级，不列清楚就容易反复抓瞎。
