ThinkPHP的Migration需通过第三方扩展topthink/think-migration实现，TP6用^3.0、TP8用^4.0；须用php think migrate:create生成文件，php think migrate:run执行，注意数据库配置、SQL兼容性及up/down逻辑可逆性。

ThinkPHP 的 Migration 功能不是内置的，得靠第三方扩展 topthink/think-migration，官方没提供原生支持。

怎么装 think-migration 扩展

它不是 ThinkPHP 自带组件，必须手动引入 Composer 包。注意版本对齐：TP6 用 topthink/think-migration:^3.0，TP8（即 ThinkPHP 8.x）对应 ^4.0。装错版本会报 Class not found 或命令不识别。

• 执行 composer require topthink/think-migration（TP6）或 composer require topthink/think-migration:^4.0（TP8）
• 装完检查 vendor/topthink/think-migration/src/Command 是否存在，避免因 autoload 未生效导致 php think migrate 命令找不到
• TP8 项目若启用了命令自动发现，一般无需额外注册；TP6 需确认 app/command.php 中是否已包含迁移命令类

创建和运行 migration 文件

迁移文件本质是 PHP 类，继承 think\migration\Migrate，含 up() 和 down() 方法。别手写类名或路径——必须用命令生成，否则框架无法识别。

• 建迁移：运行 php think migrate:create CreateUserTable，会在 database/migrate/ 下生成带时间戳前缀的文件，如 20240510123456_create_user_table.php
• 执行迁移：用 php think migrate:run，不是 php think migrate（后者无响应，是常见误输）
• up() 里写建表/改字段逻辑，down() 必须可逆；比如 dropTable('user') 对应 createTable('user')，漏写 down() 或逻辑不匹配会导致回滚失败

常见报错和兼容性坑

迁移失败多数卡在数据库连接或 SQL 兼容性上，而不是语法错误。

ThinkPHP6.0.0

ThinkPHP 6.0.0 是国产轻量级 PHP 框架的里程碑式版本，于 2019 年正式发布。该版本基于“精简核心”与“统一用法”原则，对底层架构进行了彻底重构。它强制要求 PHP 7.1+ 环境，全面启用强类型声明，深度支持 PSR 规范，并引入了独立的多应用模式、改进的中间件机制及全新的事件系统，标志着 ThinkPHP 正式迈入现代化、标准化与企业级开发的新阶段。

下载

立即学习“PHP免费学习笔记（深入）”；

• SQLSTATE[HY000] [1045] Access denied：检查 config/database.php 中的 username、password 是否正确，迁移命令走的是应用配置，不是单独的 .env 数据库配置（TP6 默认不读 .env 的 DB 配置）
• Base table or view not found：执行 down() 时表已被删，但代码里又去删一次；建议在 down() 开头加 if ($this->hasTable('xxx')) { ... }
• MySQL 8+ 的 utf8mb4_0900_as_cs 排序规则可能被迁移命令忽略，导致建表后中文排序异常；可在 createTable() 的 options 参数里显式传 'charset=utf8mb4 COLLATE=utf8mb4_0900_as_cs'

迁移状态和回滚控制

php think migrate:status 能看哪些迁移已执行、哪些待执行，但不会告诉你具体哪条 SQL 出了问题。回滚操作要格外小心。

• php think migrate:rollback 只回退最后一条，不是全部；想退多条得加 --step=3
• 回滚依赖 migration 表里的 version 字段顺序，如果手动改过该表数据，后续迁移可能混乱
• 生产环境禁用 migrate:refresh（清空再重跑），它会删所有表，且不校验外键依赖，极易丢数据

迁移不是“写完就跑”，关键在 up/down 的幂等性和数据库状态一致性。哪怕只是加个字段，也要先在测试库跑通 rollback 再上线。