composer install 不会自动安装迁移工具，需显式添加 doctrine/migrations 或 laravel/framework 依赖；Doctrine 首次运行前须执行 migrations:sync-metadata-storage 初始化元数据表；Laravel 要求 database/migrations 目录存在且 DB 连接有效；迁移状态与实际结构不一致时应查 doctrine_migration_versions 表并谨慎回退。
composer install 时找不到 migrations 工具包
Composer 本身不自带数据库迁移功能，所谓“数据迁移工具”是第三方包，最常用的是 doctrine/migrations 或 Laravel 自带的 laravel/framework（含 php artisan migrate）。直接运行 composer install 不会自动装迁移工具，必须显式声明依赖。
- 检查
composer.json是否已包含"doctrine/migrations": "^3.5"（推荐 v3+，PHP 8 兼容性好）或"laravel/framework" - 没加就补上，然后运行
composer require doctrine/migrations（v3 默认带 CLI 命令vendor/bin/doctrine-migrations） - 如果项目用 Laravel，别单独装
doctrine/migrations—— 它和php artisan migrate冲突，优先走框架原生流程 - 装完确认二进制文件存在：
ls vendor/bin/doctrine-migrations（Linux/macOS）或dir vendor\bin\doctrine-migrations.bat（Windows）
配置 migrations 的 YAML 文件报错：“No metadata storage table”
Doctrine Migrations 第一次运行前必须初始化元数据表（默认叫 doctrine_migration_versions），否则所有命令（如 doctrine-migrations status）都会报这个错。这不是数据库连接问题，而是迁移系统自身没“登记册”。
- 先确保
doctrine/dbal和 PDO 驱动已安装：composer require doctrine/dbal - 运行初始化命令：
vendor/bin/doctrine-migrations migrations:sync-metadata-storage（v3+ 必须这步） - 该命令会在你配置的数据库里建表，**不操作业务表**，但要求当前 DB 用户有建表权限
- 如果用 MySQL 且报
Specified key was too long，需在doctrine.dbal.platform_options中加{"version": "5.7"}或升级 MySQL
php artisan migrate 找不到 migrations 目录或驱动异常
Laravel 的迁移命令依赖两个硬性前提：config/database.php 中的默认连接可用，且 database/migrations/ 目录存在且可写。任何一项缺失都会让命令静默失败或抛出模糊异常（比如 Class 'CreateUsersTable' not found）。
- 运行前先验证 DB 连接：
php artisan tinker -n --execute="DB::connection()->getPdo();"，不报错才算通 - 确认
database/migrations/下至少有一个以时间戳开头的 PHP 文件（如2014_10_12_000000_create_users_table.php），Laravel 只扫这个目录 - 如果改过
config/database.php里的'default'值，但没配对应连接项（比如设成'pgsql'却没定义'connections.pgsql'），migrate会直接崩 - Windows 下路径大小写不敏感，但 Docker 或 Linux 环境中，
Database/Migrations（首字母大写）会被忽略 —— 必须小写database/migrations
迁移执行一半失败，再次 run 提示 “Already up to date” 却没生效
这是 Doctrine 和 Laravel 共有的元数据状态与实际 DB 不一致导致的。迁移工具只看元数据表记录，不校验表结构是否真匹配。常见于手动删了表、改了字段又没回滚，或者并发执行 migration。
- Doctrine：用
doctrine-migrations migrations:list查哪些已标记为 executed；用doctrine-migrations migrations:execute --down [version]回退单个版本（慎用） - Laravel：
php artisan migrate:status看状态；若想强制重跑，先php artisan migrate:rollback --step=1，再migrate；不要直接删元数据表行 - 最稳妥方式：导出现有表结构，生成新 migration，用
doctrine-migrations migrations:generate或php artisan make:migration sync_users_table补丁 - 永远别在生产环境直接
php artisan migrate:fresh—— 它会 DROP 所有表，连元数据表都清掉
迁移不是“执行 SQL”，而是维护一个版本状态机。一旦元数据和物理结构脱节，靠猜不如查 doctrine_migration_versions 表内容，再比对 schema.yml 或当前 migration 文件里的 up() 逻辑。
