开发工作流：migrate dev 与团队协作

migrate dev 一次做了什么

npx prisma migrate dev 是开发环境的日常命令，完整流程如下：

1. 在影子数据库里重放现有迁移历史，检测漂移
2. 把还没应用的迁移（比如同事刚提交的）应用到影子数据库
3. 对比 Schema 与迁移历史的终点，生成新的迁移 SQL
4. 把所有未应用的迁移应用到开发数据库，更新 _prisma_migrations 表

第 3 步是关键：只有 Schema 变了，它才会生成新迁移；没变化时，它只负责把别人欠的「迁移债」补上。

第一次运行（项目里还没有任何迁移）时，它会从空库生成初始迁移，把整个 Schema 一次性建出来。

命名与预览：—name 和 —create-only

--name 给迁移起个可读的名字，文件夹名变成 20260811120000_add_job_title：

npx prisma migrate dev --name add_job_title

不带 --name 也能跑，只是文件夹名没有语义，排查时很痛苦。

--create-only 只生成 SQL，不应用：

npx prisma migrate dev --name rename_field --create-only

生成的文件躺在 prisma/migrations/<时间戳>_rename_field/migration.sql，你可以先检查、修改，再跑一次 migrate dev 应用它。这是自定义迁移的入口，第 32 章细讲。

开发日常循环

改 Schema、跑迁移、生成客户端，三件事按固定顺序转：

1. 修改 schema.prisma
2. npx prisma migrate dev --name 改动描述
3. npx prisma generate

第 2 步管数据库，第 3 步管代码。v7 里两步分离，少了哪一步都会出问题：只迁移不生成，编辑器里类型是旧的；只生成不迁移，查询时报表不存在。

给迁移起名用「动词 + 对象」的短句，比如 add_job_title、remove_legacy_column，别用 fix、update 这种没信息的名字。

什么时候会被提示重置

migrate dev 在两种情况下会要求重置数据库（删库重建，再重放全部历史）：

• 迁移历史冲突：已应用的迁移文件被改过或删了
• 漂移：开发库结构被人手动改过，和迁移历史的终点不一致

重置是开发环境的正常操作——开发数据可以丢。比如同事手动在开发库执行了 ALTER TABLE，或者你实验过 db push，这些改动都不在迁移历史里。migrate dev 检测到后不会自动覆盖，而是停下来问你：重置数据库，还是先处理？

但同样的行为在生产环境就是灾难：

团队协作：拉取、合并、再迁移

多人协作的典型场景：同事 A 给 User 加了 favoriteColor 字段，同事 B 新增了 Tag 模型，两人各自在分支上跑了 migrate dev --name ...，提交了 Schema 和迁移文件。你 git pull 之后，本地会多出两份迁移和一份改过的 Schema。

此时跑一次：

npx prisma migrate dev
npx prisma generate

migrate dev 会自动把同事的迁移应用到你的开发库，再为你的本地 Schema 差异生成新迁移。注意三个习惯：

1. 先 pull，再迁移，顺序不能反
2. 迁移文件冲突时，先解决 Git 冲突，确保 prisma/migrations/ 目录完整
3. 提交时把 Schema 和新迁移一起提交，缺一不可

多人同时改不同的模型，迁移会各自生成，按时间戳排序应用，互不干扰。合并后的应用顺序由时间戳决定，先创建的先应用，与提交先后无关。只要每个人的迁移文件都还在，历史就是一条直线，不会出现「谁的改动覆盖谁」的问题。

拉取时如果本地还有未提交的迁移文件，先提交或暂存再 pull，避免 Git 把别人的迁移和你的草稿混在一起。合并完成后跑 migrate status 确认历史没有缺口，再继续开发。

真正危险的是多人改同一个已应用的迁移文件——所以第 29 章的「已应用迁移不可编辑」是团队铁律。

重置开发库

想从头再来，比如实验了 db push 或手动改坏了库：

npx prisma migrate reset

它删除数据库、重建、重放全部迁移历史。v7 里重置不再自动跑种子脚本，需要数据就手动补一句 npx prisma db seed。

参考来源

• Prisma 官方文档：migrate dev
• Prisma 官方文档：Schema changes
• Prisma 官方文档：Development and production workflows
• Mapagam：Creating and running migrations
• DevSheets：Database migrations