多模块项目迁移顺序错乱的根本原因是doctrine仅按时间戳排序且不识别模块边界，解决需统一迁移目录、显式声明依赖、分离生成与合入流程，并通过status命令验证状态。
多模块项目里迁移顺序错乱，本质是 Doctrine 没法自动识别“哪个模块的变更该先执行”，它只按时间戳排序迁移文件，不感知模块边界。解决关键不是强行改顺序，而是统一入口、隔离路径、显式控制依赖关系。
确保所有模块迁移都归入同一 migrations 目录
Doctrine 默认只扫描 migrations/ 目录下的 PHP 文件，且严格按文件名中的时间戳（如 Version20260715103000.php）排序执行。如果各模块各自维护 migrations/ 子目录（比如 module_a/migrations/），Doctrine 根本不会加载它们——导致部分迁移缺失、顺序失控。
- 把所有模块的迁移文件统一放在项目根目录的
migrations/下 - 生成时用
php bin/console doctrine:migrations:diff --filter=App\ModuleA\Entity等方式限定范围，避免混入无关变更 - 不要手动重命名迁移文件来“调整顺序”，时间戳一旦写死就不可逆，改名会导致哈希校验失败
用依赖声明明确执行先后
当模块间存在结构依赖（例如 ModuleB 的表要外键引用 ModuleA 的主表），仅靠时间戳不够可靠。Doctrine 支持在迁移类中声明 $dependsOn 属性，强制前置依赖。
- 在 ModuleB 的迁移类顶部添加：
public $dependsOn = ['DoctrineMigrations\Version20260710120000']; - 目标版本类必须已存在且已被 Doctrine 记录（即出现在
doctrine_migration_versions表中） - 执行
doctrine:migrations:migrate时，Doctrine 会自动检查依赖并按需提前执行被依赖项
拆分迁移生成与执行流程
开发阶段多人协作时，不同模块开发者可能同时生成迁移，时间戳冲突或覆盖容易引发错乱。建议分离“生成”和“合入”两个环节。
- 每个模块开发者本地运行
doctrine:migrations:diff，生成临时迁移文件但不提交 - 由专人（如 Tech Lead）统一审查、合并逻辑、重排时间戳（通过复制内容到新文件 + 手动修改时间戳字符串实现）
- 合并后的迁移文件才提交到主干，确保每次发布的迁移序列是确定、可复现的
验证状态比盲目执行更重要
执行前务必运行 doctrine:migrations:status，重点看三栏：
- Available migrations：列出所有未执行但已发现的迁移（含时间戳）
- Executed migrations：已执行的迁移及其执行时间
- Latest version：当前数据库所处的最新版本号
如果发现 “Available” 中有跳号、或 “Executed” 里版本号不连续，说明已有迁移被跳过或状态表脱节——此时不能直接 migrate，应先用 doctrine:migrations:sync-metadata-storage 或人工修复 doctrine_migration_versions 表。
