LaravelEloquent迁移使用教程

本文深入剖析 Laravel Eloquent 迁移中高频踩坑场景与实战解法，从“表已存在却强行 create 导致迁移失败”“回滚时报类不存在”“多人协作下重复字段冲突”，到“JSON 字段索引兼容性难题”，逐一揭示错误根源并给出精准、可落地的解决方案；核心强调迁移的本质是**结构演化的可信契约**——必须严守不修改已提交文件、不共享本地迁移、每次变更仅限单文件这三条铁律，否则看似便捷的命令终将引发数据库状态失控的连锁危机。

迁移文件生成后，php artisan migrate 报错“Base table or view not found”

这是最常见的误操作：Laravel 默认迁移会先执行 create_users_table，但如果你的数据库里已有 users 表（比如手动建过、或之前迁移失败残留），而当前迁移又没做存在性判断，就会因重复建表失败；更隐蔽的情况是，down() 方法里写了 Schema::dropIfExists('users')，但 up() 里却用 Schema::create('users', ...) —— 这本身没问题，但一旦表已存在，create() 就直接报错，不会跳过。

• 始终优先用 Schema::create() 配合 if (!Schema::hasTable('users')) { ... } 做兜底（仅调试/开发环境临时用，生产环境应严格依赖迁移顺序）
• 真正可靠的解法是：删掉手动创建的表，再清空 migrations 表中对应记录，然后重跑 php artisan migrate
• 别在迁移里写业务逻辑（比如插入默认用户），那属于 php artisan db:seed 的职责

php artisan migrate:rollback 回滚失败，提示“Class XXX does not exist”

说明 Laravel 找不到对应迁移类——不是文件丢了，而是自动加载没刷新。Laravel 从 vendor/composer/autoload_classmap.php 读取迁移类路径，而 artisan 命令不自动触发 composer dump-autoload，尤其当你手动改过迁移文件名、或用 IDE 重命名后没更新命名空间时，类名和文件路径对不上，就报这个错。

• 执行 composer dump-autoload 再试回滚
• 检查迁移文件顶部 class CreatePostsTable extends Migration 是否与文件名一致（如 2014_10_12_000000_create_posts_table.php）
• 确认类定义在全局命名空间，不要加 namespace（Laravel 迁移约定就是无命名空间）

多个开发者协作时，php artisan migrate 在 A 机器成功、B 机器报“Duplicate column name”

根本原因是迁移文件时间戳（如 2023_05_10_142300）被手动修改过，或 Git 合并时产生冲突未解决，导致同一张表在不同人本地生成了两个不同时间戳的迁移文件（比如一个叫 2023_05_10_142300_add_status_to_posts.php，另一个叫 2023_05_10_142500_add_status_to_posts.php），而两者都试图加 status 字段。Laravel 按时间戳顺序执行，但不会校验 SQL 语义是否重复。

• 严禁手动改迁移文件名中的时间戳；新增字段必须复用已有迁移（用 php artisan make:migration add_status_to_posts --table=posts）
• 团队统一用 php artisan migrate --step=1 逐条执行，配合 php artisan migrate:status 查看每条状态，快速定位哪条卡住
• 上线前用 php artisan migrate --pretend 预览将执行的 SQL，确认无重复 DDL

想在迁移里加索引但不确定字段类型兼容性，比如给 JSON 字段建普通索引

MySQL 5.7+ 支持 JSON 类型，但直接对 JSON 列建 index 会失败，必须用生成列（generated column）+ 普通索引组合。PostgreSQL 则原生支持 jsonb 的 GIN 索引。Eloquent 迁移不自动适配这些细节，全靠你手写 DB::unprepared() 或用方言特定语法。

• MySQL 示例：

  DB::unprepared("ALTER TABLE users ADD COLUMN email_hash VARCHAR(32) AS (MD5(email)) STORED");
  Schema::table('users', function (Blueprint $table) {
      $table->index('email_hash');
  });

• Laravel 9+ 开始支持 $table->jsonb('metadata')->index()（仅 PostgreSQL），但底层仍是 jsonb_path_ops 索引，查 @> 时才生效
• 别在迁移里用 DB::table()->insert() 插测试数据——它绕过模型事件和访问器，且事务不保证回滚一致性

实际用迁移控制结构版本，最难的从来不是写命令，而是让所有人遵守「不改已提交迁移」「不跨环境共享本地迁移文件」「每次变更只动一个迁移」这三条铁律。一旦破例，migrations 表和物理表结构就会出现隐性偏差，后面所有 rollback、fresh 都可能变成定时炸弹。

到这里，我们也就讲完了《LaravelEloquent迁移使用教程》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！