CodeIgniter 4 迁移需启用 $enabled=true、路径正确、命名规范、根目录执行；up/down 应用 Schema Builder；依赖顺序、环境同步和时间戳严格匹配是关键。
CodeIgniter 迁移命令不生效，php spark migrate 报错或无反应
多数情况是没启用 Migrations 类或配置未生效。CodeIgniter 4 的迁移功能默认关闭，必须手动开启。app/Config/Migrations.php 中的 $enabled 必须设为 true，否则所有 spark migrate 命令都静默跳过。
常见错误现象：Nothing to migrate. 却实际有新迁移文件；或执行后 spark migrate:list 显示空列表。
-
app/Config/Migrations.php的$path要指向真实迁移目录（默认是APPPATH . 'database/Migrations/'），路径错会导致文件根本读不到 - 迁移文件名必须严格遵循
YYYYMMDDHHIISS_描述.php格式（如20231015142230_create_users_table.php），时间戳错位、字母大小写混用、下划线缺失都会被忽略 - CLI 必须在项目根目录运行（即含
spark文件的那层），不在根目录时命令会成功但操作的是错误路径下的数据库
迁移文件里 up() 和 down() 写什么才安全
这两个方法不是“随便写 sql”，而是要适配 CodeIgniter 的 Schema Builder，否则跨数据库（mysql/postgresql/sqlite）会出问题，回滚也容易失败。
使用场景：建表、加字段、改字段类型、删索引——这些都该用 $this->forge，而不是手写 DB::query() 或原生 SQL。
-
up()中避免写DROP TABLE if EXISTS，应先用$this->forge->tableExists('xxx')判断再操作 -
down()不是up()的反向拼接，比如addcolumn对应dropColumn，但modifyColumn回滚时得按原始定义重建，不能只删 - 如果迁移中调用了模型或服务（如更新某条记录），
down()必须能逆向还原数据状态，否则下次migrate:rollback会报错或留脏数据
执行 php spark migrate:status 显示 pending 却无法运行
这说明迁移文件已识别，但未被执行，原因通常卡在依赖或顺序上。
CodeIgniter 4 的迁移是严格按时间戳顺序执行的，且支持 $depends 属性声明前置依赖。一旦某个迁移文件依赖另一个尚未执行的迁移，它就会一直 pending。
- 检查迁移类里的
public $depends = ['20231015142230_create_users_table'];—— 依赖值必须是其他迁移文件的时间戳前缀，拼错一个字符就卡住 - 若手动删过数据库中的
migrations表，或清空过它，Spark 不会自动重算状态，需用php spark migrate:refresh（慎用，会重跑全部）或php spark migrate:to 20231015142230指定目标版本 - SQLite 用户注意：
ALTER TABLE ... RENAME COLUMN在旧版 SQLite 不支持，modifyColumn可能静默失败，建议用dropColumn + addColumn组合代替
本地开发迁移到测试环境，php spark migrate 报主键冲突或字段已存在
这不是代码问题，是环境间 migrations 表不同步导致的。每个环境的 migrations 表记录了已执行的迁移时间戳，本地多跑了一次，测试环境却没同步，就会重复执行同一迁移。
性能影响不大，但结构错乱风险极高——比如两次 addColumn 同名字段会直接报错。
- 上线前务必确认测试/生产环境的
migrations表和本地一致，可用php spark migrate:status对比输出 - 不要在生产环境直接
php spark migrate:refresh，它会删库重来；应只用migrate或migrate:latest - 团队协作时，迁移文件提交后，必须同步更新
migrations表快照（例如导出 SQL），否则 A 提交迁移、B 拉取后直接跑，可能跳过中间某几条
迁移不是“写完就能跑”，真正麻烦的是时间戳顺序、依赖链、环境状态三者的咬合。漏掉任意一环，后面查起来都是绕着数据库日志打转。