ThinkPHP数据库迁移需三步缺一不可：安装topthink/think-migration扩展（TP6.0.8+用^3.0）、在config/console.php中注册'\think\migration\Command::class'、运行php think migrate:install初始化状态表；迁移文件须置于database/migrations/且以14位时间戳命名。
ThinkPHP 的数据库迁移不是开箱即用的功能，必须手动安装扩展、注册命令、初始化状态表，三者缺一不可；否则 php think migrate:run 会静默失败或报 “Command not defined”。
迁移命令不存在？检查 think-migration 是否装对了
TP6 默认不带迁移命令，topthink/think-migration 是独立扩展包，且版本和安装方式极易出错。
- TP6.0.8 及以上或 TP6.1+ 必须用
composer require topthink/think-migration:^3.0；旧版 TP6.0.0–6.0.7 只能用^2.0 - 上线部署时若用了
composer install --no-dev，而该包被写在require-dev里，命令会直接消失——生产环境也得留着它，它只在命令行生效，不参与运行时 - 装完后必须执行
php think list，确认输出里有migrate:install、migrate:run等条目；没有就说明类没注册或自动加载失败
php think migrate:install 报 Class 'PhinxConsoleCommandInit' not found
这不是 Phinx 配置问题，而是 topthink/think-migration 根本没被 Composer 正确加载。
- 检查
composer.json的require或require-dev里是否真有"topthink/think-migration": "^3.0"，而不是拼错成think-migrations（少个-）或topthink/think-phinx - 执行
composer dump-autoload -o强制刷新自动加载映射 - 某些定制化项目会禁用 Composer 的 autoload，需确认
vendor/autoload.php在入口文件中被引入
No migrations to run 却明明有文件？路径和命名必须严丝合缝
ThinkPHP 迁移扫描器极其严格：只认 database/migrations/ 目录下、以 14 位时间戳开头的 PHP 文件，其余一律忽略。
立即学习“PHP免费学习笔记（深入）”；
- 路径必须是
database/migrations/（注意是migrations，不是migrate或migration） - 文件名格式必须为
YYYYMMDDHHIISS_*.php，例如20260426200000_add_status_to_order.php；Windows 下复制粘贴可能带不可见空格或 BOM 头，导致解析失败 - 类名必须与文件名主干一致（如
20260426200000_add_status_to_order.php对应AddStatusToOrder），且继承think\migration\Migrator - 如果改过
config/migration.php中的path配置，记得清掉runtime/cache/，否则旧缓存路径仍生效
rollback 报 SQLSTATE[42000]：down() 逻辑不能想当然
回滚失败往往不是命令问题，而是 down() 方法写的 SQL 在目标数据库上根本不合法。
- MySQL 5.7.6 以下不支持
DROP COLUMN，但你在up()里加了字段、down()里写了$table->dropColumn('xxx')，就会炸 - SQLite 不允许删主键字段，
down()里删id字段会静默失败或报错 -
down()不是可选的，也不是“尽量写”，它必须和up()操作一一逆向；增字段就要删字段，建索引就要删索引，改类型就得改回去 - 数据填充（如
Db::insert()）不该塞进up()，那是seed的事；rollback不处理数据，只管结构
最常被跳过的环节是 php think migrate:status —— 它不光看哪些 migration 已执行，更关键的是比对 batch 值和 version 时间戳，跨环境同步前不查这个，等于蒙眼上线。
