Symfony 5.4 Finder组件通过链式调用实现灵活文件筛选，需显式调用files()或directories()，支持多条件组合、递归扫描及高效迭代，且注意contains()、date()、size()等方法的语法细节。
Symfony 5.4 的 Finder 组件专为灵活、可读性强的文件筛选而设计，链式调用是它的核心使用方式。多条件组合不是“叠加多个 if”，而是通过连续调用方法，在同一个 Finder 实例上逐层添加约束，最终一次性执行高效迭代。
基础结构：从创建到遍历
所有链式操作都始于 Finder::create()，并以 in() 指定根目录收尾。中间的方法顺序不影响逻辑结果（如 name() 和 date() 谁先谁后都行），但建议按“类型→名称→内容→时间→大小→权限”等常见逻辑组织，提升可读性。
- 必须显式调用
files()或directories()，否则默认包含两者 -
in()支持字符串或数组路径，自动递归扫描子目录 - 遍历时直接用
foreach，Finder 返回的是Iterator，不加载全部路径到内存
常用多条件组合示例
以下写法均合法且高效，适用于 Symfony 5.4：
- 找最近 2 天内修改、大于 10KB、扩展名为
.log或.txt的文件：$finder = Finder::create()->files()->name(['*.log', '*.txt'])->size('> 10K')->date('since 2 days ago')->in('/var/log'); - 排除临时文件和隐藏文件，只保留 PHP 源码（不含测试文件）：
$finder = Finder::create()->files()->name('*.php')->notName('*Test.php')->notName('*.blade.php')->depth('exclude(['tests', 'vendor', 'node_modules'])->in(__DIR__); - 查找包含特定文本、且修改时间在某区间内的配置文件：
$finder = Finder::create()->files()->name('*.yml')->contains('database')->date('after 2026-09-01')->date('before 2026-09-30')->in('config/');
注意边界与兼容细节
Symfony 5.4 的 Finder 对部分语法有明确要求，稍不注意会静默失败或行为异常：
-
contains()默认按行匹配，若需全文本模糊匹配，应配合正则：->contains('/debug.*true/i') -
date()字符串支持since、after、before，但不支持between；需两段date()组合实现区间 -
size()单位必须大写：K、M、G，小写（如k）会被忽略 - Windows 下路径分隔符自动转换，但
exclude()中仍建议用正斜杠或DirectorySeparator常量保持一致性
调试与验证技巧
链式调用不易打断点，推荐两种轻量验证方式：
- 用
count($finder)快速获知匹配数量（不触发完整迭代） - 加一句
->depth(' 临时限制搜索深度，缩小范围快速确认规则是否生效 - 在循环中加入
echo $file->getRelativePathname() . "\n";输出路径，比getRealPath()更易看出是否命中预期目录结构
