codeigniter 4 原生不支持直接运行单个迁移文件，但可通过自定义 cli 命令（基于 `migrationrunner::force()`）实现精确控制；结合数组分组策略，还可轻松扩展为按模块（如 blog、sales）批量执行指定迁移。
在 CodeIgniter 4 的数据库迁移体系中，php spark migrate 默认按时间戳顺序执行所有待迁移文件，而 php spark migrate -f
✅ 核心方案：自定义 migrate:file 命令
我们通过创建一个专用 CLI 命令，封装 MigrationRunner::force() 方法，实现「按文件路径一键执行」：
步骤 1：生成命令骨架
php spark make:command MigrateFile --command migrate:file --group Database --suffix Command
该命令将在 app/Commands/ 下生成 MigrateFileCommand.php。
步骤 2：实现核心逻辑（精简关键部分）
<?php
namespace App\Commands;
use CodeIgniter\CLI\BaseCommand;
use CodeIgniter\CLI\CLI;
use Config\Services;
class MigrateFileCommand extends BaseCommand
{
protected $name = 'migrate:file';
protected $description = 'Migrates a single migration file.';
protected $arguments = [
'name' => '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 "Modules\Sales" \ --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 项目既能享受迁移框架的稳定性，又不失模块化开发所需的精准控制力。
