ThinkPHP 8.0 数据库迁移工具建表详解

ThinkPHP 8.0 默认移除了内置的数据库迁移（Migrations）支持，如果现在要给新项目初始化表结构，必须手动集成 Phinx 并严格遵循它的路径、命名和方法规范——稍有不慎，迁移命令就会“不认识”你的文件，或者静默跳过，整个操作形同虚设。

安装并初始化 think-phinx

先执行 composer require topthink/think-phinx 安装官方兼容扩展。注意，这里使用的是 topthink/think-phinx，而不是 topthink/think-migration，后者在 TP8 中已完全失效，强行使用会报 Class not found 错误。

安装完成后，运行 php think phinx:init，它会自动生成 phinx.php 配置文件，并将 config/database.php 中的数据库连接参数读入其中。

打开 phinx.php，确认 'paths' => ['migrations' => 'database/migrations'] 这一行存在且路径未被修改。TP8 强制要求迁移文件只能放置在 database/migrations/ 目录下，位置错误时控制台只会提示“No migrations to run”。

创建迁移文件并定义建表逻辑

接着使用 php think phinx:create CreateUsersTable 创建迁移文件，系统会在 database/migrations/ 目录下生成类似 20260707120000_create_users_table.php 的文件。

打开该文件，将默认的 up() 和 down() 方法全部删除，仅保留 change() 方法。示例如下：

public function change(): void {
    $this->table('users')
        ->addColumn('id', 'biginteger', ['identity' => true, 'primary_key' => true])
        ->addColumn('name', 'string', ['limit' => 50])
        ->addColumn('email', 'string', ['limit' => 100, 'null' => false])
        ->addColumn('created_at', 'datetime')
        ->addColumn('updated_at', 'datetime', ['null' => true])
        ->create();
}

这里必须注意不能编写 up() 或 down()——TP8 的 think-phinx 集成默认只识别 change()，若写错则迁移不会执行，而且控制台既不报错也不建表，排查起来非常困难。

注册命令并执行迁移

如果执行 php think list 后看不到 phinx:migrate 命令，说明命令类尚未注册。需要到 config/console.php 的 'commands' 数组中添加：

'thinkphingCommand::class'

然后确保数据库服务连通，执行：

php think phinx:migrate

若提示 Command "phinx:migrate" is not defined，请先检查类名是否拼写正确——应为 thinkphingCommand，而非 thinkphinxCommand。这一拼写错误非常常见。

迁移成功后，think_migration 表中会新增一条记录，对应文件名前缀（如 20260707120000），数据库中也会生成 users 表。