Symfony 7 默认不提供文件系统操作能力，必须通过 FlysystemBundle 显式集成；服务名按驼峰规则生成（如 default_storage → $defaultStorage），配置在 config/packages/flysystem.yaml，路径须为绝对路径（如 '%kernel.project_dir%/public/uploads'），Windows 下用正斜杠，读写须用 FilesystemOperator 的 has()/read() 等方法。
Symfony 7 默认不提供文件系统操作能力，必须通过 FlysystemBundle 显式集成，否则 FilesystemOperator 无法自动注入，write()、read() 等调用会直接失败或返回空。
FlysystemBundle 安装与服务注册是否生效
确认你用的是 FlysystemBundle（Symfony Flex 官方支持），不是已废弃的 OneupFlysystemBundle。两者配置结构、服务名、自动注入规则完全不兼容：
-
FlysystemBundle：安装后自动注册服务，配置在config/packages/flysystem.yaml，服务名按驼峰规则生成，例如default_storage→ 自动绑定为类型提示$defaultStorage: FilesystemOperator -
OneupFlysystemBundle：服务名固定为oneup_flysystem.<mapping_name>_filesystem，需手动声明类型，且 Symfony 7.2+ 已不再维护 - 混用会导致
ServiceNotFoundException或Cannot autowire argument—— 尤其常见于迁移项目中忘了删干净旧 Bundle 和config/packages/oneup_flysystem.yaml或config.yml中残留配置
本地适配器路径配置必须是绝对路径
Flysystem 不解析相对路径，directory: 'data' 实际指向 PHP 当前工作目录（通常是 public/），而非项目根目录：
- 正确写法（使用容器参数）：
directory: '%kernel.project_dir%/public/uploads'或'%kernel.project_dir%/var/storage' - 错误写法：
directory: 'data'、directory: './data'、directory: '../var/data' - Windows 下必须用正斜杠
/，不要用反斜杠\—— Flysystem 内部不处理转义，C:\project\var\storage会被当作无效路径 - 确保目标目录存在且 Web 服务器用户有读写权限，否则
createDirectory()或write()会静默失败或抛出UnableToWriteFile
读写操作必须走 FilesystemOperator，不能混用 PHP 原生函数
直接调用 file_exists()、file_get_contents() 无法感知 Flysystem 的路径映射和适配器逻辑，极易误判：
- 判断文件是否存在，必须用
$filesystem->has('path/to/file.txt')，别信file_exists() -
$filesystem->read()返回字符串内容，不是响应对象；直接return $filesystem->read(...)会触发Fatal error: Object of class League\Flysystem\File could not be converted to string - 下载文件应构造响应：
return new BinaryFileResponse($filesystem->readStream('report.pdf'), 200, ['Content-Type' => 'application/pdf']) - 写入时注意
Config参数影响：$filesystem->write('log.txt', 'msg', new Config(['visibility' => 'private']))可控可见性，但本地适配器下该设置无实际效果
最常被忽略的是路径解析逻辑 —— Flysystem 的 has() 和 read() 对路径敏感，/uploads/file.txt 和 uploads/file.txt 在同一适配器下可能一个存在、一个不存在，而错误往往只在生产环境暴露，因为开发机权限宽松掩盖了问题。
