doctrine/doctrine-bundle 与 doctrine/migrations 版本必须主版本对齐：v2.x 对应 v3.x，v3.x 对应 v3.5+/v4.x（推荐 v4.3+）；错配会导致命令缺失或 Class not found 错误，需同时升级两者并处理命名空间变更、方法签名及 $connection 访问方式。
composer update doctrine/doctrine-bundle 报版本不匹配
Doctrine Migrations 的行为严重依赖 doctrine/doctrine-bundle 和 doctrine/migrations 之间的主版本对齐。常见现象是执行 php bin/console doctrine:migrations:diff 时抛出 Class "Doctrine\Migrations\Version" not found 或命令根本不存在——这往往不是 Migrations 本身没装，而是 Bundle 版本太旧，没注册对应命令。
检查当前组合是否匹配：
-
doctrine/doctrine-bundlev2.x → 必须配doctrine/migrationsv3.x（PHP 7.4+） -
doctrine/doctrine-bundlev3.x（Symfony 6.2+ 默认）→ 必须配doctrine/migrationsv3.5+ 或 v4.x（推荐 v4.3+）
若发现错配，直接运行：
composer require doctrine/doctrine-bundle:^3.0 doctrine/migrations:^4.3
不要只升级其中一个。v4.x 的 Migrations 引入了 SqlSyncCommand 和更严格的事务包裹，默认启用 --if-not-exists 行为，老项目需检查 up() 中的 CREATE TABLE IF NOT EXISTS 是否冗余。
多个迁移文件生成相同版本号（如 Version20251002062800）
这是团队协作中最容易被忽略的冲突点：不同开发者本地执行 php bin/console make:migration 时，若未先 git pull，可能基于旧 Schema 生成完全相同的版本前缀（时间戳精确到秒），导致 Git 合并失败、doctrine:migrations:migrate 执行报错 Migration class ... was not found。
预防和修复方法：
- 强制所有成员在生成迁移前运行
git pull && php bin/console doctrine:schema:update --dump-sql，确认本地 DB 结构与远程一致 - 若已产生重复版本号，不要手动改类名——先删掉冲突的本地迁移文件，再运行
php bin/console doctrine:migrations:sync-metadata-storage重置元数据表 - 然后用
php bin/console make:migration --no-interaction重新生成（该参数避免交互式命名，减少人为误差）
注意：sync-metadata-storage 只修正 migrations 表的记录，不回滚已执行的变更，生产环境慎用。
执行 migrate 时提示 “Migration already executed” 但数据库实际没变
典型诱因是 Doctrine 的迁移元数据表（默认 doctrine_migration_versions）和实际数据库结构脱节。比如手动执行过 SQL、或用 --write-sql 导出后人工执行却忘了标记完成。
验证方式：
- 查表：
SELECT * FROM doctrine_migration_versions ORDER BY version DESC LIMIT 5; - 对比
migrations/目录下最新文件名（如Version20260415123456.php）是否已在表中记录
若缺失，可安全补录：
php bin/console doctrine:migrations:version "20260415123456" --add
若存在但结构不对，说明迁移逻辑本身有 bug（例如 up() 里漏写 $schema->createTable()），此时应进文件检查 PHP 代码，而不是跳过或强制标记。
自定义迁移类里 use 语句报错 Class not found
从 Doctrine Migrations v3 升级到 v4 后，核心命名空间已变更：Doctrine\DBAL\Migrations\AbstractMigration 彻底废弃，全部移至 Doctrine\Migrations\AbstractMigration。但旧迁移文件仍保留原 use，运行时会 fatal error。
必须统一处理：
- 全局替换：在
migrations/目录下执行grep -rl "DBAL.Migrations" . | xargs sed -i '' 's/DBAL.Migrations/Migrations/g'（macOS）或sed -i 's/DBAL.Migrations/Migrations/g' $(grep -rl "DBAL.Migrations" .)（Linux） - 同时检查
up()和down()方法签名：v4 要求参数类型为Schema（来自Doctrine\DBAL\Schema\Schema），而非旧版的Schema别名或AbstractSchemaManager - v4 不再自动注入
$connection，如需原生 SQL，改用$this->connection->executeStatement(...)
这个改动不报 deprecation warning，直接 crash，上线前务必在 CI 中跑一遍 php -l 检查所有迁移文件语法。
