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/2022-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/2022-02-16-101819_AddBlogMigration.php"  # 指定非默认命名空间与数据库组（如模块化销售系统） php spark migrate:file "Modules/Sales/Database/Migrations/2023-05-01-090000_CreateOrdersTable.php"    --namespace "ModulesSales"    --dbgroup "sales_db"

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

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

// 在任意业务逻辑中（如模块安装钩子） public function runModuleMigrations(string $module): void {     $migrations = [         'blog'    => ['app/Database/Migrations/2022-02-16-101819_AddBlogMigration.php'],         'sales'   => [             'Modules/Sales/Database/Migrations/2023-05-01-090000_CreateOrdersTable.php',             'Modules/Sales/Database/Migrations/2023-05-02-103000_AddOrderStatus.php'         ],         'storage' => ['app/Database/Migrations/2022-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 表记录。

✅ 总结

• ✅ 原生无解 → 自定义命令破局：CI4 官方未提供单文件迁移指令，但 MigrationRunner::force() 为开发者留出了强大扩展入口。
• ✅ 灵活可控：支持任意命名空间、数据库组、绝对/相对路径，完美适配模块化架构。
• ✅ 可编程集成：通过 command() 在代码中驱动，轻松实现模块级迁移编排（如 runAll($files[‘sales’])）。
• ⚠️ 安全提醒：force() 跳过版本锁，务必确保迁移类逻辑幂等，或配合自定义状态表做二次校验。

从此，你的 CI4 项目既能享受迁移框架的稳定性，又不失模块化开发所需的精准控制力。