php ≥ 8.0 且启用 ext-curl、ext-json 才满足 flysystem v3 的 league/flysystem-aws-s3-v3 最低要求；php 7.4 及以下需退至已停止维护的 v2 版本，不推荐新项目使用。
确认 PHP 和 Composer 环境是否满足最低要求
Flysystem v3（当前主流版本）的 league/flysystem-aws-s3-v3 要求 PHP ≥ 8.0，且必须启用 ext-curl 和 ext-json。运行 php -v 和 php -m | grep -E "curl|json" 快速验证。若用 PHP 7.4 或更低版本，只能退回到 Flysystem v2 的 league/flysystem-aws-s3-v2，但该包已停止维护，不建议新项目使用。
安装正确的包并避免版本冲突
直接执行 composer require league/flysystem-aws-s3-v3 即可。注意：不要同时安装 aws/aws-sdk-php —— flysystem-aws-s3-v3 已将它设为 require，Composer 会自动拉取兼容版本；手动再装可能引发 SDK 版本错位，导致 Aws\S3\S3Client 初始化失败或签名异常。
常见错误现象：Class 'Aws\S3\S3Client' not found，通常是因为未安装该包，或 Composer 自动加载失效（可试 composer dump-autoload）。
初始化 S3 客户端与 Flysystem 适配器时的关键参数
构造 S3Client 时，region 和 version 必须显式指定（如 'us-east-1'、'2006-03-01'），否则部分区域（如 cn-north-1）会报 Invalid region 或签名过期错误。Bucket 名称不能带协议前缀（如去掉 s3://），也不能含斜杠。
-
credentials推荐用数组传入key和secret，避免环境变量未生效导致认证失败 - 若使用 IAM 角色（如 EC2 实例），可省略
credentials，但需确保实例有对应权限策略 -
endpoint参数仅在对接兼容 S3 的私有存储（如 MinIO、腾讯云 COS）时才需要填，填错会导致连接超时
写入文件后无法立即访问的缓存问题
调用 $filesystem->write('path/file.txt', 'content') 成功不代表文件立刻可公开访问。S3 默认 ACL 是 private，且对象 URL 需要显式生成。若需直链，要么上传时加 'ACL' => 'public-read'（仅限公有桶），要么用 $s3Client->getObjectUrl() 构造临时预签名 URL。
另一个隐蔽坑：Flysystem 的 listContents() 默认不递归，且不返回子目录（prefix 模式下只列一层）。要模拟“目录浏览”，得手动拼接路径 + 过滤 type === 'dir'，或者改用 getAdapter()->getClient()->listObjectsV2() 原生调用。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
