CodeIgniter 4 中如何精准执行单个迁移文件（含模块化批量调用方案）_技术教程

codeigniter 4 原生不支持直接运行单个迁移文件，但可通过自定义 cli 命令（基于 `migrationrunner::force()`）实现精确控制；结合数组分组策略，还可轻松扩展为按模块（如 blog、sales）批量执行指定迁移。

在 CodeIgniter 4 的数据库迁移体系中，php spark migrate 默认按时间戳顺序执行所有待迁移文件，而 php spark migrate -f 仅支持指定类名（需完整命名空间），无法直接通过文件路径或模块标识触发单个或一组迁移。面对模块化项目（如 blog、storage、sales 各自独立维护迁移脚本），这种限制会显著降低开发与部署灵活性。幸运的是，CI4 提供了高度可扩展的 CLI 命令机制和底层迁移 API，让我们能自主构建精准迁移能力。

✅ 核心方案：自定义 migrate:file 命令

我们通过创建一个专用 CLI 命令，封装 MigrationRunner::force() 方法，实现「按文件路径一键执行」：

步骤 1：生成命令骨架

php spark make:command MigrateFile --command migrate:file --group Database --suffix Command

该命令将在 app/Commands/ 下生成 MigrateFileCommand.php。

步骤 2：实现核心逻辑（精简关键部分）

 'Migration file path relative to ROOTPATH. E.g.: "app/Database/Migrations/2025-02-16-101819_AddBlogMigration.php"'
    ];
    protected $options     = [
        '--namespace' => 'Set migration namespace. Default: "App".',
        '--dbgroup'   => 'Set database group. Default: "default".',
    ];

    public function run(array $params)
    {
        CLI::write('Running migration...', 'yellow');

        if (count($params) !== 1) {
            CLI::error('Invalid arguments: exactly one file path is required.', 'red');
            $this->showHelp();
            return;
        }

        $runner    = Services::migrations();
        $namespace = CLI::getOption('namespace') ?: 'App';
        $dbgroup   = CLI::getOption('dbgroup') ?: 'default';
        $filePath  = ROOTPATH . $params[0];

        try {
            if (!$runner->force($filePath, $namespace, $dbgroup)) {
                CLI::error(lang('Migrations.generalFault'), 'red');
                return;
            }

            foreach ($runner->getCliMessages() as $msg) {
                CLI::write($msg);
            }
            CLI::write('Done migration.', 'green');
        } catch (\Throwable $e) {
            $this->showError($e);
        }
    }
}

? 关键点：$runner->force($filePath, $namespace, $dbgroup) 是底层核心——它绕过版本检查，强制加载并执行指定 PHP 文件中的迁移类，完全跳过时间戳排序逻辑。

步骤 3：使用示例

# 执行 App 命名空间下的单个迁移
php spark migrate:file "app/Database/Migrations/2025-02-16-101819_AddBlogMigration.php"

# 指定非默认命名空间与数据库组（如模块化销售系统）
php spark migrate:file "Modules/Sales/Database/Migrations/2025-05-01-090000_CreateOrdersTable.php" \
  --namespace "Modules\Sales" \
  --dbgroup "sales_db"

? 进阶：按模块批量执行迁移（runAll($files['sales'])）

虽然 CI4 不内置模块分组执行，但借助上述命令，你可在控制器、服务类或脚本中程序化调用：

// 在任意业务逻辑中（如模块安装钩子）
public function runModuleMigrations(string $module): void
{
    $migrations = [
        'blog'    => ['app/Database/Migrations/2025-02-16-101819_AddBlogMigration.php'],
        'sales'   => [
            'Modules/Sales/Database/Migrations/2025-05-01-090000_CreateOrdersTable.php',
            'Modules/Sales/Database/Migrations/2025-05-02-103000_AddOrderStatus.php'
        ],
        'storage' => ['app/Database/Migrations/2025-11-10-142000_CreateStorageBuckets.php']
    ];

    if (!isset($migrations[$module])) {
        throw new \InvalidArgumentException("Unknown module: {$module}");
    }

    foreach ($migrations[$module] as $file) {
        $output = command("migrate:file \"{$file}\" --namespace \"App\" --dbgroup \"default\"");
        if (strpos($output, 'Done migration.') === false) {
            log_message('error', "Migration failed: {$file}");
            throw new \RuntimeException("Failed to migrate {$file}");
        }
    }

    log_message('info', "Successfully migrated module: {$module}");
}

⚠️ 注意事项：

command() 函数会捕获 CLI 输出，适合后台调度；若需实时日志，建议改用 exec() 或重定向输出流。

确保迁移文件路径从 ROOTPATH 开始书写，且使用正斜杠 /（Windows 兼容）。

force() 不校验已执行状态，重复执行可能导致数据异常，请确保幂等性或手动管理 migrations 表记录。