Prisma 命令速查

Prisma Schema 迁移、Client 生成、Studio 调试、缓存清理的完整命令速查。

#tech / ops / database #type / howto #status / evergreen

[!info] related notes

Dbeaver

Navicat

Neon（PostgreSql云部署）

Redis

Ti DB Cloud

Prisma 命令速查

核心概念

schema.prisma      数据模型定义（表结构、关系、枚举）
prisma/migrations/  迁移文件（SQL 变更历史）
node_modules/.prisma/  生成的 Client 代码

工作流：修改 schema → 生成迁移 → 应用到数据库 → 生成 Client → 代码中使用。

Schema 管理

命令	说明	常用示例
`pnpm exec prisma init`	初始化 Prisma（生成 schema 模板）	`pnpm exec prisma init`
`pnpm exec prisma validate`	验证 schema 语法有效性	`pnpm exec prisma validate`
`pnpm exec prisma format`	格式化 schema 文件	`pnpm exec prisma format`
`pnpm exec prisma generate`	根据 schema 生成 Prisma Client	修改 schema 后必须执行
`pnpm exec prisma generate --no-engine`	生成无引擎 Client（更小体积）	适用于 Edge Runtime

数据库迁移

命令	说明	常用示例
`pnpm exec prisma migrate dev`	创建并应用迁移（开发环境）	`pnpm exec prisma migrate dev --name init`
`pnpm exec prisma migrate dev --name <name>`	命名迁移	`pnpm exec prisma migrate dev --name add-user-table`
`pnpm exec prisma migrate deploy`	应用迁移（生产环境）	CI/CD 中使用，不创建新迁移
`pnpm exec prisma migrate status`	查看迁移状态	检查哪些迁移已应用/待应用
`pnpm exec prisma migrate reset`	重置数据库（删除所有数据并重新迁移）	开发环境重建
`pnpm exec prisma migrate resolve --applied <name>`	手动标记迁移为已应用	修复迁移状态
`pnpm exec prisma migrate resolve --rolled-back <name>`	手动标记迁移为已回滚	修复迁移状态
`pnpm exec prisma db push`	直接同步 schema 到数据库（不生成迁移文件）	快速原型开发
`pnpm exec prisma db push --force-reset`	强制重置并同步	重建表结构
`pnpm exec prisma db push --accept-data-loss`	接受数据丢失并同步	允许删除列/表
`pnpm exec prisma db pull`	从数据库反向同步到 schema	拉取现有数据库结构

Prisma Studio（可视化）

命令	说明
`pnpm exec prisma studio`	打开 Prisma Studio Web UI（默认端口 5555）
`pnpm exec prisma studio --port 3000`	指定端口打开

Docker 环境中的 Prisma

命令	说明	常用示例
`docker exec <container> pnpm prisma db push`	在容器中同步 schema	`docker exec my-api pnpm prisma db push --skip-generate`
`docker exec <container> pnpm prisma migrate deploy`	在容器中应用迁移	`docker exec my-api pnpm prisma migrate deploy`
`docker exec <container> pnpm prisma generate`	在容器中生成 Client	`docker exec my-api pnpm prisma generate`

缓存清理

当 Prisma Client 出现类型不一致或奇怪的错误时：

方法	命令	说明
删除生成的 Client（推荐）	`rm -rf node_modules/.prisma && rm -rf node_modules/@prisma/client && pnpm prisma generate`	彻底清理并重新生成
内置清理	`pnpm prisma generate --no-engine && pnpm prisma generate`	先生成无引擎版本再重新生成
重启 Node.js	`Ctrl+C` 停止服务 → 重新启动	最简单，Node.js 重新加载模块
环境变量强制重新生成	`PRISMA_SKIP_POSTINSTALL_GENERATE=false pnpm prisma generate`	强制触发重新生成

Schema 配置速查

数据源 (datasource)

datasource db {
  provider = "postgresql"  // postgresql | mysql | sqlite | sqlserver | mongodb
  url      = env("DATABASE_URL")
}

生成器 (generator)

generator client {
  provider = "prisma-client-js"
  // previewFeatures = ["multiSchema"]  // 可选：启用预览特性
}

模型定义示例

model User {
  id        Int      @id @default(autoincrement())
  email     String   @unique
  name      String?
  posts     Post[]
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt

  @@map("users")  // 映射到数据库表名
}

model Post {
  id       Int    @id @default(autoincrement())
  title    String
  content  String?
  author   User   @relation(fields: [authorId], references: [id])
  authorId Int

  @@index([authorId])  // 添加索引
}

常见问题速查

问题	原因	解决方案
`PrismaClientKnownRequestError`	Client 与 schema 不匹配	重新 `prisma generate`
类型不一致	缓存了旧的 Client	删除 `node_modules/.prisma` 后重新生成
`Environment variable not found: DATABASE_URL`	.env 文件缺失或路径不对	检查 `.env` 文件位置和变量名
`P1001: Can't reach database server`	数据库连接失败	检查 `DATABASE_URL`、网络、数据库服务状态
`P3006: Migration ... failed to apply`	迁移 SQL 执行失败	检查数据库权限、手动修复后 `migrate resolve`
`db push` 与 `migrate` 混用导致状态混乱	不要混用	开发用 `migrate dev`，原型用 `db push`，生产用 `migrate deploy`
容器中 schema 变更不生效	需要重新构建或 exec	`docker exec` 执行 `prisma generate`