唯一推荐路径是用php spark make:migration生成迁移类并在up()中调用$this->forge->createTable(),禁止手写SQL或直接操作DB;文件名、类名、命名空间须严格匹配,且down()必须与up()严格对称。

直接用 php spark make:migration 生成迁移类,再在 up() 方法里调用 $this->forge->createTable() —— 这是唯一推荐路径,手写 SQL 或直接操作 DB 是反模式。
迁移文件必须用 Spark 命令创建
CI4 不接受手动新建 PHP 文件或随意命名。执行命令时名称要体现意图,比如:
php spark make:migration CreateUsersTable
框架会自动生成带时间戳前缀的文件(如 20260902141500_create_users_table.php),并确保命名空间、类名、文件路径三者严格匹配。常见错误包括:
- 手动创建文件但类名写成
create_users_table(小写)或Create_user_table(下划线),导致Class not found - 改了文件名里的时间戳部分,破坏执行顺序,后续
spark migrate可能跳过或重复运行 - 没运行
composer dump-autoload,尤其在新增/重命名后,Autoloader 找不到类
$this->forge->createTable() 的参数和陷阱
createTable() 接收两个参数:表名(字符串)和可选的 $ifNotExists 布尔值。它不接受原始 SQL 字符串 —— 所有字段和索引必须通过 addField() 和 addKey() 显式定义。
-
$this->forge->addField()必须传关联数组,每个字段键名是字段名,值是描述数组('type'、'constraint'、'unsigned'等) - 主键必须显式调用
$this->forge->addKey('id', true)(第二个参数true表示是主键) - 唯一约束不能只靠
'unique' => true,还得配addUniqueKey();普通索引要用addKey('field_name') - 字符集和排序规则由数据库组配置决定,默认不写进迁移,如需强制指定,得在
app/Config/Database.php中设置'charset'和'DBCollat'
为什么不能在 up() 里写原生 SQL?
CI4 的 Forge 层目标是跨数据库兼容(MySQL、PostgreSQL、SQLite),而原生 SQL 会立刻打破这一前提。例如:
- MySQL 的
ENGINE=InnoDB在 PostgreSQL 里不存在 - SQL Server 的
[column]方括号语法在其他驱动中报错 -
COMMENT字段支持程度不一,Forge 会自动忽略不支持的平台
如果你硬要在 up() 里执行 SQL,得先判断当前数据库类型:$this->db->DBDriver,再拼接对应方言 —— 但这等于放弃迁移的可协作性和可回滚性,也违背 CI4 设计初衷。
down() 必须与 up() 严格对称
down() 不是“删掉所有相关表”,而是仅撤回本迁移引入的变更。常见疏漏:
- 在
up()里建了users表又加了user_profiles表,down()却只删users—— 下次migrate:rollback会失败 - 用
addUniqueKey()添加了唯一索引,down()却没调用dropKey(),导致后续迁移因索引冲突报错 - 没包装事务:
$this->db->transStart()/transComplete()—— 某个dropTable()失败时,其余已执行的删除无法回滚
真正容易被忽略的是:迁移状态只记录“是否执行过”,不校验实际结构。一旦 down() 漏删字段或索引,migrations 表里仍显示成功,但 DB 已处于不一致状态 —— 这种问题在线上环境极难排查。











