yii2项目需通过flysystem统一管理本地磁盘、s3、ftp等存储，避免硬编码；安装creocoder/yii2-flysystem及对应适配器（如league/flysystem-aws-s3-v3），配置components中fs组件，按需定义local、s3或inmemoryadapter，控制器中通过yii::$app->组件名调用write/readstream/delete等标准接口操作文件。
在Yii2项目中需要统一调用本地磁盘、S3、FTP等不同存储服务，且不希望每次切换存储后端都重写业务逻辑，就必须绕过硬编码的file_put_contents或curl上传，直接使用抽象层提供的标准接口。
安装与基础配置
执行命令安装核心扩展：composer require creocoder/yii2-flysystem。
若需对接AWS S3，额外安装适配器：composer require league/flysystem-aws-s3-v3。注意：S3适配器版本必须与Flysystem v2兼容，【v1适配器会导致getAdapter()方法不存在而报错】。
在config/web.php的components中注册fs组件，配置结构必须包含class和adapter两个键，其余参数依适配器要求动态补充。
定义多个存储后端
方法一：本地磁盘
在components中添加如下配置，路径必须以@webroot或@app开头，否则LocalAdapter会因无法解析相对路径而抛出InvalidArgumentException：
'local' => [ 'class' => 'creocoder\flysystem\Bootstrap', 'adapterOptions' => ['@webroot/uploads'] ]
方法二：AWS S3
确保已配置AWS_ACCESS_KEY_ID和AWS_SECRET_ACCESS_KEY环境变量，否则S3Client初始化失败；bucket和region为必填项，endpoint仅私有S3才需显式指定：
's3' => [ 'class' => 'creocoder\flysystem\Bootstrap', 'adapterOptions' => [ 'key' => getenv('AWS_ACCESS_KEY_ID'), 'secret' => getenv('AWS_SECRET_ACCESS_KEY'), 'region' => 'us-east-1', 'version' => 'latest', 'bucket' => 'my-bucket-name' ] ]
方法三：内存模拟（仅开发测试）
用InMemoryAdapter替代真实存储，避免反复清空测试目录。该适配器不持久化数据，应用重启即丢失，【切勿在生产环境启用】。
在控制器中调用存储门面
第一步：在控制器顶部引入命名空间：use yii\helpers\FileHelper;和use creocoder\flysystem\FilesystemComponent;。
第二步：获取已注册的文件系统实例，例如调用S3后端：$fs = Yii::$app->s3;。注意组件名必须与配置中定义的键名完全一致，大小写敏感。
第三步：执行标准操作。上传文件：$fs->write('avatars/user1.jpg', file_get_contents('/tmp/upload.jpg'));。这一步会自动触发适配器的write()实现，无需关心底层是S3的putObject还是本地的file_put_contents。
第四步：读取并返回流：$stream = $fs->readStream('avatars/user1.jpg');。返回的是PHP资源句柄，可直接传给yii\web\Response::sendStreamAsFile()，无需先保存到临时文件。
第五步：删除文件：$fs->delete('avatars/user1.jpg');。该操作不可逆，Flysystem不提供回收站机制，误删无恢复途径。
