直接执行 composer require league/flysystem 即可安装 Flysystem v3 最新版（如 3.29.0），无需指定 ^3.0 或 v3；适配器需单独安装，如 S3 用 league/flysystem-aws-s3-v3，本地开发推荐 league/flysystem-local。
直接装 league/flysystem 就够了，v3 不是单独版本
Flysystem 当前（2026 年）的主干就是 v3，league/flysystem 这个包本身已是 v3.x 系列，不存在“安装 v3”的额外操作。所谓“v3”是相对于早已废弃的 v1（2014 年停更）和已 EOL 的 v2（2022 年终止维护）而言的命名延续，并非一个需特殊指定的分支或标签。
常见错误现象：composer require league/flysystem:^3.0 或 composer require league/flysystem:v3 —— 这些写法要么报错，要么装不上，因为 Packagist 上没有 v3 这个版本别名，也没有 ^3.0 这种过时的约束（当前稳定版是 ^3.29 左右）。
- 正确命令就一条：
composer require league/flysystem - 它会自动拉取最新兼容 PHP 8.1+ 的 v3.x 版本（如
3.29.0），无需手动锁版本 - 如果你项目还跑在 PHP 7.4，得加约束：
composer require league/flysystem:^3.20（v3.20 是最后一个支持 PHP 7.4 的小版本）
适配器必须单独装，不能只靠 flysystem 核心
league/flysystem 本身不带任何存储驱动——它只是接口和抽象层。你要用 S3、本地磁盘、FTP 或内存测试，都得额外装对应适配器包，否则运行时会抛出 Class not found 或 Adapter not provided 错误。
常见错误现象：代码里写了 new AwsS3V3Adapter(...)，但没装 league/flysystem-aws-s3-v3，结果报 Class 'League\Flysystem\AwsS3V3\AwsS3V3Adapter' not found。
- S3 必装：
composer require league/flysystem-aws-s3-v3（注意不是flysystem-aws-s3，那是旧 v2 适配器） - 本地开发常用：
composer require league/flysystem-local（v3 专用本地适配器，比原生LocalFilesystemAdapter更健壮） - 如果只装核心不装适配器，
Filesystem实例能创建，但所有读写操作都会失败
PHP 版本和依赖冲突是静默失败主因
Flysystem v3 要求 PHP ≥ 8.0（部分功能需 8.1），而它的适配器还有各自依赖链。比如 flysystem-aws-s3-v3 依赖 aws/aws-sdk-php ^3.250，若你项目里已有老版本 SDK（如 3.209.31），Composer 会直接拒绝安装，且错误提示模糊——可能只显示 “Your requirements could not be resolved”，不指明冲突点。
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
常见错误现象：执行 composer require league/flysystem-aws-s3-v3 卡住或报错，但没看到具体哪个包冲突。
- 先查冲突：
composer why aws/aws-sdk-php或composer prohibits aws/aws-sdk-php:3.250 - 注意 Flysystem 官方
conflict声明中明确排除了aws/aws-sdk-php:3.209.31 || 3.210.0，这类版本必须升级或降级绕过 - 本地开发建议用
league/flysystem-local先跑通逻辑，再切 S3；避免一上来就被 AWS 凭据、区域、桶权限等外围问题干扰
实例化时路径/桶名传错会导致“文件存在却读不到”
本地适配器的构造参数是绝对路径（如 /var/www/storage），S3 适配器的第一个参数是 S3Client 实例，第二个才是桶名（my-bucket-name）。很多人把桶名当成路径传给本地适配器，或把本地路径当桶名传给 S3 适配器，结果 fileExists() 返回 true，但 read() 报 No such key 或空内容。
常见错误现象：$adapter = new LocalFilesystemAdapter('my-bucket-name') —— 这会在当前目录下建一个叫 my-bucket-name 的子目录，而非连到 S3。
- 本地适配器必须用真实路径：
new LocalFilesystemAdapter(__DIR__.'/storage') - S3 适配器第二参数是桶名字符串，不是 URL：
new AwsS3V3Adapter($client, 'my-bucket-name')（不是s3://my-bucket-name） - 路径分隔符统一用正斜杠
/，即使在 Windows 上也别用\，Flysystem 内部不处理反斜杠转义
最容易被忽略的是：Flysystem 的 write() 和 read() 默认不校验 MIME 类型或编码，上传二进制文件（如图片、PDF）时若用 writeStream() 却忘了 fopen(..., 'rb')，Windows 下可能损坏文件——这个坑不会报错，只会让你调试半天发现文件打不开。
