Laravel 团队协作数据库迁移规范：从命名到版本控制的完整避坑指南

在多人协作的 Laravel 项目中，数据库迁移文件冲突、字段类型不一致、回滚失败是高频问题。本文系统梳理 Laravel 数据库迁移的团队协作规范，涵盖迁移文件命名、结构组织、字段修改原则、冲突解决流程及版本控制策略，帮助团队建立标准化的数据库变更流程，降低协作成本，提升开发效率。

引言

Laravel 迁移（Migration）作为“数据库的版本控制工具”，允许团队通过代码管理数据库结构变更。但在多人并行开发场景下，常出现以下问题：

迁移文件命名随意，无法追溯功能来源；
并行开发时迁移时间戳冲突，导致 php artisan migrate 执行失败；
直接修改已提交的生产环境迁移文件，引发数据不一致；
缺乏回滚机制，错误变更后无法快速恢复。

建立统一的迁移协作规范，是解决上述问题的核心手段。

一、迁移文件命名规范

迁移文件名需具备“自解释性”，通过命名即可定位功能模块与变更类型。遵循以下格式：

[时间戳]_[模块名]_[操作类型]_[字段/表描述].php

时间戳：Laravel 自动生成，不可手动修改（确保执行顺序）；
模块名：对应业务模块（如 user、order、product）；
操作类型：create_table（新建表）、add_column（新增字段）、modify_column（修改字段）、drop_column（删除字段）、create_index（创建索引）等；
字段/表描述：简明说明变更对象（如 add_column_age_to_users、create_table_orders）。

示例：

20240520123000_user_create_table_users.php
20240520124500_user_add_column_age_to_users.php
20240520130000_order_create_index_order_no_on_orders.php

禁止行为：

使用模糊命名（如 update_users.php、fix_bug.php）；
合并多个不相关操作为单个迁移（如同时修改用户表和订单表）。

二、迁移文件结构组织

按“功能模块”拆分迁移目录，避免根目录文件堆积。在 database/migrations 下创建子目录：

database/migrations/
├── user/                # 用户模块迁移
│   ├── 20240520123000_user_create_table_users.php
│   └── 20240520124500_user_add_column_age_to_users.php
├── order/               # 订单模块迁移
│   └── 20240520130000_order_create_index_order_no_on_orders.php
└── common/              # 公共模块迁移（如权限、配置表）

加载子目录迁移：在 config/database.php 中配置迁移路径：

'migrations' => [
    'paths' => [
        database_path('migrations/user'),
        database_path('migrations/order'),
        database_path('migrations/common'),
    ],
],

三、字段修改与表结构规范

1. 字段类型统一

团队需提前约定常用字段类型，避免同一字段在不同迁移中类型不一致：

主键：id()（默认 bigIncrements，禁止手动指定 integer）；
时间戳：timestamps()（自动维护 created_at/updated_at）；
软删除：softDeletes()（使用 deleted_at 字段）；
枚举类型：优先使用 tinyInteger + 注释（如 comment('1:启用,2:禁用')），避免 enum（跨数据库兼容性问题）；
字符串：string('column', 255)（默认长度，超长需显式声明）。

2. 索引规范

外键索引：必须显式命名，格式 fk_主表名_外键字段_关联表名，如 $table->foreign('user_id')->references('id')->on('users')->name('fk_orders_user_id_users')；
普通索引：命名格式 idx_表名_字段名，如 $table->index('order_no', 'idx_orders_order_no')；
唯一索引：命名格式 uk_表名_字段名，如 $table->unique('email', 'uk_users_email')。

3. 禁止操作

禁止在已提交到版本库的迁移文件中修改字段类型/删除字段（如需修改，新建迁移文件）；
禁止在生产环境迁移中使用 DB::statement() 执行原生 SQL（特殊情况需团队评审）；
禁止使用 dropColumn 删除生产环境核心业务字段（需先标记废弃，观察周期后删除）。

四、团队协作流程规范

1. 迁移文件创建流程

开发前从主分支拉取最新代码，确保本地迁移时间戳无冲突；
使用 php artisan make:migration 生成迁移文件，按命名规范重命名；
编写迁移逻辑后，执行 php artisan migrate:test（自定义命令，测试迁移回滚）验证；
提交代码前，通过 git pull --rebase 拉取最新迁移文件，解决冲突（冲突时优先保留对方迁移，调整自身时间戳）。

2. 代码评审重点

迁移文件命名是否符合规范；
字段类型、索引命名是否符合约定；
是否存在禁止操作（如修改已提交迁移、删除生产字段）；
down() 方法是否可安全回滚（如 dropTable 需确认无数据依赖）。

3. 环境同步策略

开发环境：每次拉取代码后执行 php artisan migrate --force；
测试环境：通过 CI/CD 自动执行迁移，失败则阻断部署；
生产环境：发布前执行 php artisan migrate --dry-run 验证 SQL，发布时手动执行 php artisan migrate。

五、冲突解决与回滚机制

1. 迁移时间戳冲突

当两人同时生成迁移文件导致时间戳重复时：

修改冲突文件的 timestamp（前14位），确保全局唯一；
执行 php artisan migrate:refresh --path=database/migrations/冲突文件目录（仅刷新冲突文件）。

2. 回滚规范

开发环境：允许使用 php artisan migrate:rollback --step=1 回滚单步迁移；
测试/生产环境：禁止直接回滚，需新建“反向迁移”（如删除字段的迁移对应新增字段的迁移）；
回滚后需验证数据完整性（如通过 php artisan db:seed --class=RollbackTestSeeder 填充测试数据）。

六、版本控制与文档同步

迁移文件必须提交到版本库，禁止 .gitignore 忽略；
重大表结构变更（如新增模块表、核心字段修改）需同步更新 docs/database/表结构说明.md；
生产环境迁移执行后，需记录变更日志（包含迁移文件名、执行时间、影响范围）。

引言