Symfony 4.4 升级至 5.4 时，Finder 排序需改用 sortBy() 配合 DateComparator，date() 过滤器须显式传 DateComparator 实例；exclude() 仅接受数组；in() 路径校验更严；Flysystem rename() 不覆盖目标且路径不带前导斜杠。
从 Symfony 4.4 迁移到 5.4 时，文件操作相关代码最容易出问题的集中在 Finder 和 Flysystem 两大组件。改动不是语法微调，而是设计逻辑升级——更强调类型安全、显式声明和可组合性。关键不在“怎么写”，而在“为什么这么改”。
Finder 排序与时间过滤必须显式传 Comparator
sortByModifiedTime()、sortByAccessedTime() 等快捷方法在 5.4 中已废弃，不能再用。它们被统一收口到 sortBy()，必须配合 DateComparator 实例。
- 替换前：
$finder->sortByModifiedTime(); - 替换后：
use Symfony\Component\Finder\Comparator\DateComparator;$finder->sortBy(new DateComparator('mtime', false)); // false 表示降序（最新在前） -
'mtime'可换为'atime'（访问时间）或'ctime'（inode 修改时间） -
date()过滤器也一样：不再接受date('since 2 days ago')这类模糊字符串，必须用new DateComparator('>=', '-2 days')
Finder 路径与排除逻辑更严格
路径校验变硬，容错性降低，很多原来能跑通的写法会在 5.4 启动时直接报错或运行时报异常。
-
exclude('vendor')不再合法 —— 必须传数组：exclude(['vendor', 'node_modules']) -
in()方法对空路径、相对路径、不存在路径更敏感，建议先用is_dir()或file_exists()做前置判断 - 所有路径参数都不再自动补全或忽略尾部斜杠，务必确保传入的是真实存在的绝对路径或规范相对路径
Flysystem 重命名/移动必须检查目标是否存在
rename() 在 Flysystem v2（Symfony 5.4 默认）中是原子操作，但默认不覆盖。这点和旧版行为不同，容易导致静默失败。
- 源路径和目标路径都不能带前导斜杠，例如
photos/img.jpg✅，/photos/img.jpg❌ - 目标路径若已存在，会抛
FileExistsException；如需覆盖，得先delete()再rename() - 上传后移动文件时，务必用
$filesystem->fileExists('source/path')显式验证源文件，别依赖表单临时路径的“看起来存在” - S3 场景下，注意
visibility配置冲突：private 源 + public 目录策略可能导致 rename 失败且无明确报错
VichUploaderBundle 配置路径必须落在 public/ 下
如果你用 VichUploaderBundle 管理附件，5.4 对路径合法性检查更严，尤其 upload_destination 必须是 public/ 的子目录，且 uri_prefix 必须与之严格对应。
- 错误配置：
upload_destination: '%kernel.project_dir%/var/uploads'→ 无法通过 Web 访问，Twig 中asset()会 404 - 正确写法：
upload_destination: '%kernel.project_dir%/public/uploads/documents'，同时uri_prefix: /uploads/documents - 实体注解中的
@Vich\UploadableField(mapping="document", fileNameProperty="fileName")中的 mapping 名，必须和vich_uploader.yaml里定义的 key 一致
