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 遷移	嚴重	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" 的專案 — 請參閱 prisma-mongodb-upgrade 技能以做出實際決策（刻意停留在 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 提供者安裝並設定驅動程式轉接器
7. 更新 Prisma Client 的匯入
8. 更新客戶端實例化
9. 取代已棄用的輔助模式，例如 Prisma.validator
10. 執行 prisma generate 並測試

快速升級指令

# 更新套件
npm install @prisma/client@7
npm install -D prisma@7

# 安裝驅動程式轉接器（PostgreSQL 或透過直接 TCP 的 Prisma Postgres）
npm install @prisma/adapter-pg pg

# 安裝 dotenv 以載入環境變數
npm install dotenv

# 重新產生客戶端
npx prisma generate

重大變更摘要

變更	v6	v7
模組格式	隱含/混合	ESM 優先，支援 moduleFormat = "cjs"
產生器提供者	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. 更新 package.json 以支援 ESM 優先專案

{
  "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

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

// 之後 (v7)
generator client {
  provider = "prisma-client"
  output   = "../generated/prisma"
  // 如果您需要 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

# 標準 Node.js 應用程式中的 Prisma Postgres（建議）
npm install @prisma/adapter-pg pg

# Prisma Postgres serverless 驅動程式（邊緣/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. 更新客戶端實例化

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

// 之後 (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  # 如果需要

疑難排解

「找不到模組」錯誤

• 檢查 generator 的 output 路徑是否與您的匯入路徑相符
• 確保 prisma generate 成功執行

SSL 憑證錯誤

• 如果您需要保留舊行為，請在轉接器設定中加入 ssl: { rejectUnauthorized: false }
• 或者使用 NODE_EXTRA_CA_CERTS / OpenSSL CA 設定正確配置您的憑證

連線逾時問題

• 驅動程式轉接器使用底層驅動程式的預設值，這與 v6 不同
• 如有需要，請在轉接器上明確設定連線池設定

資源

• 官方 v7 升級指南
• 驅動程式轉接器文件
• Prisma 設定參考

如何使用

請先遵循 references/schema-changes.md 和 references/driver-adapters.md，然後根據您的專案設定套用其餘的參考檔案。