升级到 Prisma ORM 7

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

何时应用

在以下情况参考此 skill：

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

按优先级划分的规则类别

| 优先级 | 类别 | 影响 | 前缀 | |----------|----------|--------|--------| | 1 | Schema 迁移 | 严重 | 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 provider 必需的适配器安装、连接池差异，以及 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" 的项目 — 请查看 prisma-mongodb-upgrade skill 以了解实际决策 （刻意留在 v6 与迁移到 Prisma Next）。

重要说明

• MongoDB 项目应留在 Prisma 6.x 或迁移到 Prisma Next - 不要将 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. 更新 schema generator 块
5. 创建 prisma.config.ts
6. 为 SQL provider 安装并配置驱动适配器
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" | | 生成器 provider | prisma-client-js | 默认为 prisma-client，同时 prisma-client-js 仍用于旧版设置 | | 输出路径 | 自动 (node_modules) | 必须显式设置 | | 驱动适配器 | 可选 | SQL provider 必需 | | 配置文件 | .env + schema | prisma.config.ts | | 环境加载 | 自动 | 手动 (dotenv) | | 生成的入口点 | 单一包导出 | client、browser、models、enums 入口点 | | 类型安全查询片段 | Prisma.validator() | TypeScript satisfies | | 中间件 | $use() | Client Extensions | | 指标 | 预览功能 | 已移除 |

规则文件

针对每项破坏性变更的详细迁移指南：

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，并在 generator 块中设置 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 provider）

# 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. 用 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” 错误

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

SSL 证书错误

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

连接超时问题

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

资源

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

如何使用

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