使用 Flysystem 是 Symfony 5.4 切换 S3 存储最稳妥方式；需安装 league/flysystem:^2.5 和 league/flysystem-aws-s3-v3:^2.0，配置 oneup_flysystem，注意 client、bucket、visibility 设置，并检查表单 enctype、PHP 上传限制及元数据 header 大小写。
Symfony 5.4 切换到 S3 对象存储，用 Flysystem 是最稳妥、可维护性最强的方式。不建议手动 new S3Client 或直连 AWS SDK，那样会绕开容器管理、环境隔离和元数据自动处理，后续换存储或调优都容易出问题。
安装适配器与核心包
执行以下命令安装 Flysystem v2（5.4 兼容性最佳）及 S3 适配器：
composer require league/flysystem:^2.5composer require league/flysystem-aws-s3-v3:^2.0- 确保
aws/aws-sdk-php已加载（它会被自动引入）
配置 oneup_flysystem（推荐）
在 config/packages/oneup_flysystem.yaml 中定义 adapter 和 filesystem：
Kadence Theme Design System
下载
使用 Kadence 主题作为 WordPress 项目的设计系统，涵盖设计令牌、布局系统、页头/页脚/导航设置以及页面/归档/单篇文章模板。
-
client 必须指向一个已注册的
Aws\S3\S3Client服务（不能是字符串名），且 credentials 要显式设为数组或null（如用 IAM role） -
bucket 值必须与真实 bucket 名完全一致（大小写敏感），不要加
s3://前缀 -
visibility 根据 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
在控制器或服务中使用
通过容器获取预配置的 Filesystem 实例即可操作：
- 注入
League\Flysystem\FilesystemInterface并绑定到你的 adapter 别名（如s3_adapter） - 上传：
$filesystem->write('uploads/photo.jpg', $content)— MIME 类型、ETag、ACL 由配置自动控制 - 读取：
$filesystem->read('uploads/photo.jpg')或流式读取避免内存溢出 - 生成公开 URL 需额外处理（Flysystem 不内置 URL 生成功能），可用
Aws\S3\S3Client::getObjectUrl()或前端拼接（仅限 public bucket）
切换前必查三项
很多“上传失败”“空文件”问题其实和 S3 无关：
- 表单是否带
enctype="multipart/form-data"？漏了就拿不到上传文件 - PHP 配置是否允许足够大的上传：
upload_max_filesize、post_max_size、max_execution_time - 上传时传入的元数据 key 是否全小写？S3 对 header 名称大小写敏感，
Content-Type写成content-type可能被忽略
