“Transition ‘xxx’ does not exist”报错主因是当前状态不在该transition的from列表中，需检查workflow.yaml的from配置、state值准确性、多workflow上下文、marking_store一致性、guard静默拦截及事件监听器异常。
Workflow::apply() 报错 “Transition ‘xxx’ does not exist”
这是最常遇到的报错，不是代码写错了，而是当前状态根本不能触发该 transition。Symfony 状态机严格校验「当前状态 → 目标状态」是否在定义的 transition 列表中存在对应路径。
- 检查
workflow.yaml里该 transition 的from是否包含当前对象的state值（注意大小写和空格） - 确认对象 state 属性已正确加载 —— 如果用 Doctrine，确保
$order->getState()返回的是字符串（如'created'），而不是 null 或未初始化对象 - transition 名本身不参与状态判断，
apply('pay')能否执行，只取决于当前 state 是否在pay的from列表中
多个 workflow 共存时，getMarking() 返回空或意外状态
一个实体可能被多个 workflow 管理（比如订单有主流程 + 退款子流程），但 WorkflowRegistry::get($subject) 默认只返回第一个匹配的 workflow，容易拿错上下文。
- 显式指定 workflow name：
$registry->get($order, 'order_main_workflow')，别依赖自动推断 - 确保
marking_store配置一致：如果用single_state，state 字段名必须和 workflow 定义里的place名完全对应；若用multiple_state，字段需是数组，且 key 必须是 place 名 - Doctrine 实体里不要手动改 state 字段值 —— 必须走
apply()+save()，否则 marking store 和数据库会脱节
自定义 guard 导致 transition 永远不生效
guard 是 PHP 回调函数，返回 false 就直接拦截 transition，但它不抛异常、也不打日志，默认静默失败，非常难排查。
- 在 guard 函数开头加
error_log("guard triggered for {$subject->getId()}")，确认它确实被执行了 - guard 接收的
$subject是原始对象，不是代理对象 —— 如果用了 Doctrine Proxy，小心$subject->getXXX()触发额外查询甚至 N+1 - 避免在 guard 里做耗时操作（如 API 调用、复杂计算），它运行在 apply() 同步流程中，会阻塞整个状态变更
- 测试时临时注释 guard，确认 transition 路径本身没问题，再逐步加回逻辑
Workflow::can() 返回 true，但 apply() 仍失败
can() 只校验 transition 存在性和 guard 返回值，而 apply() 还要处理 marking 更新、事件分发、持久化等后续动作，任一环节出问题都会中断。
- 常见陷阱：监听
workflow.entered事件时，回调里抛了未捕获异常 —— Symfony 会吞掉它，只留下 “Unable to apply transition” 这种模糊提示 - 检查
marking_store类型是否匹配：比如配置成multiple_state，但数据库字段是 varchar，就会在序列化 marking 时失败 - 使用
Workflow::buildMarking()手动构造 marking 测试，确认你的 state 字段格式能被正确解析（例如['confirmed' => true]vs['confirmed']）
状态机真正麻烦的从来不是定义几个状态，而是 guard 的边界、事件监听器的副作用、以及 marking 和数据库字段之间那层隐式映射 —— 这三处不画图、不写单元测试，迟早要花两小时 debug 一行 return true。
