prisma-upgrade-v7

升级到 Prisma ORM 7

从 Prisma ORM v6 迁移到 v7 的完整指南。此次升级引入了多项重大不兼容变更，涉及新的 prisma-client 生成器、驱动适配器、prisma.config.ts、显式加载环境变量以及生成的客户端入口点。

适用场景

在以下情况下参考此技能：

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

按优先级划分的规则类别

优先级	类别	影响	前缀
1	架构迁移	严重	schema-changes
2	数据库连接	严重	driver-adapters
3	模块系统	严重	esm-support
4	配置和环境变量	高	prisma-config、env-variables
5	已移除的功能	高	removed-features
6	Accelerate	高	accelerate-users

快速参考

• schema-changes - 生成器迁移、必需的输出路径、生成的入口点，以及替代 Prisma.validator 的方案
• driver-adapters - SQL 提供程序必须安装适配器、连接池差异，以及 Prisma Postgres 适配器选项
• esm-support - 以 ESM 为先的设置，以及通过 moduleFormat = "cjs" 回退到 CommonJS
• prisma-config - 创建和使用 prisma.config.ts
• env-variables - 显式加载环境变量
• removed-features - 已移除的中间件、指标和旧版 CLI 行为
• accelerate-users - 面向 Accelerate 用户的迁移说明

使用 MongoDB？本指南不适用

Prisma 7 没有 MongoDB 连接器。请勿对使用 provider = "mongodb" 的项目应用本指南中的任何步骤——有关实际决策（有意保留在 v6，还是迁移到 Prisma 8），请参阅 prisma-mongodb-upgrade 技能。

重要说明

• MongoDB 项目应继续使用 Prisma 6.x，或迁移到 Prisma 8 - 请勿将 MongoDB 应用迁移到 Prisma 7 的 SQL 客户端路径（参阅 prisma-mongodb-upgrade）
• 需要 Node.js 20.19.0+
• 需要 TypeScript 5.4.0+
• Prisma ORM 最新稳定版本：7.6.0

升级步骤概览

1. 将软件包更新到 v7
2. 选择模块格式（默认使用 esm，必要时可使用 cjs）
3. 更新 TypeScript 配置
4. 更新架构生成器代码块
5. 创建 prisma.config.ts
6. 为 SQL 提供程序安装并配置驱动适配器
7. 更新 Prisma Client 导入
8. 更新客户端实例化方式
9. 替换 Prisma.validator 等已弃用的辅助模式
10. 运行 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"
生成器提供程序	prisma-client-js	默认使用 prisma-client，旧版设置仍可使用 prisma-client-js
输出路径	自动（node_modules）	必须显式指定
驱动适配器	可选	SQL 提供程序必须使用
配置文件	.env + 架构	prisma.config.ts
环境变量加载	自动	手动（dotenv）
生成的入口点	单一软件包导出	client、browser、models、enums 入口点
类型安全的查询片段	Prisma.validator()	TypeScript satisfies
中间件	$use()	客户端扩展
指标	预览功能	已移除

规则文件

各项不兼容变更的详细迁移指南：

references/esm-support.md        - ESM and CommonJS configuration
references/schema-changes.md     - Generator, output, imports, and generated entrypoints
references/driver-adapters.md    - Required driver adapter setup
references/prisma-config.md      - New configuration file
references/env-variables.md      - Environment variable loading
references/removed-features.md   - Middleware, metrics, and CLI flags
references/accelerate-users.md   - Special handling for 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

已发布的 Prisma 7.6.0 软件包中没有适用于 MongoDB 的 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. 将 Prisma.validator 替换为 satisfies

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”错误

• 检查生成器的 output 路径是否与你的导入路径匹配
• 确保 prisma generate 成功运行

SSL 证书错误

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

连接超时问题

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

资源

• 官方 v7 升级指南
• 驱动适配器文档
• Prisma 配置参考

使用方法

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