编译器 Pass 是 Symfony 容器编译阶段执行的钩子，用于修改已加载但未生成类的服务定义；它不是运行时拦截器，也不是配置文件替代品，不支持动态改参数值。
编译器 Pass 是什么，不是什么
编译器 Pass（CompilerPassInterface）是 Symfony 容器在编译阶段执行的“钩子”，它让你能在服务定义全部加载完毕、但容器类尚未生成前，对服务定义进行修改。它不是运行时拦截器，不参与请求处理；也不是配置文件的替代品，不能用来动态改参数值——它只作用于 ContainerBuilder 中的 Definition 对象。
什么时候必须用 Compiler Pass，而不是 YAML 配置
当你需要基于某种规则批量修改服务定义，且这些规则无法通过静态配置表达时，就该用 Compiler Pass。典型场景包括：
- 为所有打上
legacy_service标签的服务自动注入工厂方法和 FQCN 参数 - 根据环境变量或类存在性，有条件地移除某组服务（比如开发专用工具类）
- 将多个私有服务内联到同一个父服务中，而该父服务本身未在 YAML 中显式声明依赖关系
- 把一组服务注册为事件监听器，但监听器类名需从反射中动态提取（如注解驱动）
写一个安全可用的 Compiler Pass 的关键点
新手常因忽略生命周期或引用错误导致容器编译失败。以下几点直接影响能否通过 php bin/console cache:clear：
- 必须在
process()方法里先检查目标服务是否存在：if (!$container->hasDefinition('some.service')) { return; } - 不要在 Pass 中调用
$container->get()—— 此时容器还未构建完成，会抛出ServiceNotFoundException - 修改服务定义时，优先用
$definition->replaceArgument()或$definition->setFactory()，避免直接覆盖整个arguments数组导致丢失原始参数 - 若需添加新服务，应使用
$container->register()并设为public(false)，否则可能破坏内联优化 - Pass 类必须在
config/bootstrap.php或Kernel::build()中显式添加：$container->addCompilerPass(new MyCompilerPass());
调试 Compiler Pass 的最简方法
别等部署失败才排查。本地验证只需两步：
- 在 Pass 的
process()开头加dump($container->getDefinitions());，然后运行php bin/console debug:container --env=prod --show-private—— 注意：这个命令会触发完整编译流程，你的 Pass 就会执行 - 检查生成的缓存容器类：
var/cache/prod/srcApp_KernelProdContainer.php，搜索你修改的服务 ID，确认getXXXService()方法是否按预期生成了工厂调用或代理逻辑 - 若 Pass 依赖标签（如
routing.loader），用php bin/console debug:container --tag=routing.loader验证标签是否已正确附加
真正难的不是写 Pass，而是判断某个优化是否值得引入——多数性能问题其实靠 lazy: true 和 public: false 就能解决，过早抽象反而增加维护负担。
