CodeIgniter 4 中如何精确执行单个迁移文件（Migration）

在 CodeIgniter 4 项目里，迁移（Migration）用来以版本化的方式变更数据库结构。当项目积累了很多迁移文件后，有时我们只需要把其中某一个迁移应用到数据库，而不希望执行其余未运行的迁移。下面介绍具体的做法。

迁移文件的基本约定

CodeIgniter 4 的迁移文件通常放在 app/Database/Migrations/ 目录下，文件名格式为 YYYY-MM-DD-HHIISS_名称.php，类需要实现 Migration 接口并提供 up() 与 down() 方法。例如：

<?php

namespace AppDatabaseMigrations;

use CodeIgniterDatabaseMigration;

class AddUserScore extends Migration
{
    public function up()
    {
        // 新增用户积分字段
        $this->forge->addColumn('users', [
            'score' => [
                'type'       => 'INT',
                'constraint' => 11,
                'default'    => 0,
                'null'       => false,
            ],
        ]);
    }

    public function down()
    {
        // 回滚时删除字段
        $this->forge->dropColumn('users', 'score');
    }
}

使用命令行精确执行单个迁移

CodeIgniter 4 自带 spark 命令行工具，可以通过 migrate:latest 配合 --batch 或者指定版本的方式来限制范围。若想只执行某一个迁移文件，可以借助 migrate:status 查看状态，然后用 migrate 指定步骤。

查看迁移状态

php spark migrate:status

该命令会列出所有迁移以及是否已执行。假设我们只想执行上面创建的 AddUserScore 迁移，而它之前没有运行过，可以用以下步骤方式：

php spark migrate --step=1

当有多个未执行迁移时，--step=1 只运行最近一个未执行的迁移文件。如果你想确保运行的是特定文件，可以临时调整文件名时间戳，使其排在最前，再执行 step=1。

按批次回滚单个迁移

如果执行错了，可以用 migrate:rollback 配合 --batch=1 回退最近一批：

php spark migrate:rollback --batch=1

通过代码调用单个迁移

除了命令行，也可以在控制器或脚本里用 foreach 精确调用某个迁移类的 up() 方法：

<?php

use AppDatabaseMigrationsAddUserScore;

$ migration = new AddUserScore();
$migration->up();

不过这种方式绕过了框架的迁移记录表，不建议在生产环境频繁使用。

常见问题与处理

• 执行后提示类找不到：检查文件命名空间与 app/Database/Migrations 目录是否一致。
• 字段已存在报错：先确认 migrate:status 中该迁移是否已被标记完成。
• 只想执行某个文件却跑了全部：检查是否漏写 --step 参数。

掌握这些方式之后，你就能在 CodeIgniter 4 中精确控制单个迁移文件的执行，避免不必要的数据库变动。

CodeIgniter4migration命令行修改时间：2026-07-28 09:03:24