prisma-upgrade-v7

用途

本技能是一份从 Prisma ORM v6 升级到 v7 的完整迁移指南，覆盖 v7 引入的所有破坏性变更。当需要升级 Prisma 版本、遇到 v7 相关错误、或进行版本迁移时，可参考本技能。

主要能力

技能按优先级将规则分为若干类别：

Schema 迁移（CRITICAL，前缀 schema-changes）：生成器迁移、必需的输出路径、生成的入口点，以及 Prisma.validator 的替代方案。
数据库连接（CRITICAL，前缀 driver-adapters）：SQL 提供程序必需的适配器安装、连接池差异，以及 Prisma Postgres 适配器选择。
模块系统（CRITICAL，前缀 esm-support）：ESM 优先的设置，以及通过 moduleFormat = "cjs" 的 CommonJS 回退方案。
配置与环境（HIGH，前缀 prisma-config、env-variables）：创建和使用 prisma.config.ts，以及显式环境变量加载。
已移除功能（HIGH，前缀 removed-features）：移除的中间件、指标和旧版 CLI 行为。
Accelerate（HIGH，前缀 accelerate-users）：Accelerate 用户的迁移说明。

使用方式

升级步骤概览：

将包更新到 v7
选择模块格式（默认 esm，如需可 cjs）
更新 TypeScript 配置
更新 schema 生成器块
创建 prisma.config.ts
为 SQL 提供程序安装并配置驱动适配器
更新 Prisma Client 导入
更新客户端实例化
替换 Prisma.validator 等已弃用的辅助模式
运行 prisma generate 并测试

快速升级命令：

# Update packages
npm install @prisma/client@7
npm install -D prisma@7

# Install a driver adapter (PostgreSQL or Prisma Postgres via direct TCP)
npm install @prisma/adapter-pg pg

# Install dotenv for env loading
npm install dotenv

# Regenerate client
npx prisma generate

破坏性变更摘要

变更	v6	v7
模块格式	隐式/混合	ESM 优先，支持 moduleFormat = "cjs"
生成器 provider	prisma-client-js	prisma-client 为默认，prisma-client-js 仍为旧版设置保留
输出路径	自动（node_modules）	必须显式指定
驱动适配器	可选	SQL 提供程序必需
配置文件	.env + schema	prisma.config.ts
环境加载	自动	手动（dotenv）
生成的入口点	单一包导出	client、browser、models、enums 入口点
类型安全查询片段	Prisma.validator()	TypeScript satisfies
中间件	$use()	Client Extensions
指标	预览功能	已移除

规则文件

每个破坏性变更的详细迁移指南：

references/esm-support.md - ESM 与 CommonJS 配置
references/schema-changes.md - 生成器、输出、导入和生成的入口点
references/driver-adapters.md - 必需的驱动适配器设置
references/prisma-config.md - 新配置文件
references/env-variables.md - 环境变量加载
references/removed-features.md - 中间件、指标和 CLI 标志
references/accelerate-users.md - Accelerate 的特殊处理

分步迁移

1. 为 ESM 优先项目更新 package.json

{
  "type": "module"
}

如果需要继续使用 CommonJS，保持应用为 CJS，并在生成器块中设置 moduleFormat = "cjs"，而不是强制使用 ESM。

2. 更新 tsconfig.json

{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "bundler",
    "target": "ES2023",
    "strict": true,
    "esModuleInterop": true
  }
}

3. 更新 schema.prisma

// Before (v6)
generator client {
  provider = "prisma-client-js"
}

// After (v7)
generator client {
  provider = "prisma-client"
  output   = "../generated/prisma"
  // Optional if you need CommonJS:
  // moduleFormat = "cjs"
}

4. 创建 prisma.config.ts

import 'dotenv/config'
import { defineConfig, env } from 'prisma/config'

export default defineConfig({
  schema: 'prisma/schema.prisma',
  migrations: {
    path: 'prisma/migrations',
  },
  datasource: {
    url: env('DATABASE_URL'),
  },
})

5. 安装驱动适配器（仅 SQL 提供程序）

# PostgreSQL
npm install @prisma/adapter-pg pg

# MySQL
npm install @prisma/adapter-mariadb mariadb

# SQLite
npm install @prisma/adapter-better-sqlite3 better-sqlite3

# Prisma Postgres in standard Node.js apps (recommended)
npm install @prisma/adapter-pg pg

# Prisma Postgres serverless driver (edge/serverless)
npm install @prisma/adapter-ppg @prisma/ppg

# Neon
npm install @prisma/adapter-neon

MongoDB 在已发布的 Prisma 7.6.0 包中没有 SQL @prisma/adapter-* 包。如果正在升级 MongoDB 项目，请停止并让该项目继续使用最新的 Prisma 6.x 版本，而不要遵循标准的 Prisma 7 迁移路径。

6. 更新客户端实例化

// Before (v6)
import { PrismaClient } from '@prisma/client'
const prisma = new PrismaClient()

// After (v7)
import { PrismaClient } from '../generated/prisma/client'
import { PrismaPg } from '@prisma/adapter-pg'

const adapter = new PrismaPg({
  connectionString: process.env.DATABASE_URL
})

const prisma = new PrismaClient({ adapter })

7. 用 satisfies 替换 Prisma.validator

import { Prisma } from '../generated/prisma/client'

const userSelect = {
  id: true,
  email: true,
  name: true,
} satisfies Prisma.UserSelect

8. 运行迁移并生成

npx prisma generate
npx prisma migrate dev  # if needed

故障排查

"Cannot find module" 错误

检查生成器输出路径是否与导入路径匹配
确保 prisma generate 已成功运行

SSL 证书错误

如需保留旧行为，在适配器配置中添加 ssl: { rejectUnauthorized: false }
或通过 NODE_EXTRA_CA_CERTS / OpenSSL CA 设置正确配置证书

连接超时问题

驱动适配器使用底层驱动的默认值，与 v6 不同
如有需要，在适配器上显式配置连接池设置

适用场景

从 Prisma v6 升级到 v7
更新到 prisma-client 生成器
设置驱动适配器
配置 prisma.config.ts
修复升级后的导入错误

限制与注意事项

MongoDB 项目应继续使用 Prisma 6.x，不要迁移到 Prisma 7 的 SQL 客户端路径
需要 Node.js 20.19.0+
需要 TypeScript 5.4.0+
最新稳定版 Prisma ORM 版本为 7.6.0

使用建议

先遵循 references/schema-changes.md 和 references/driver-adapters.md，然后根据项目设置应用其余参考文件。