从 v6 升级到 v7：破坏性变更全览

v7 是一次大换血：查询引擎从 Rust 换成 WASM 编译的查询编译器（Rust-free Client），跑在 JS 主线程，包体更小、查询更快。但升级像搬家——家具还是那些，摆放方式全变了。本章先列全 18 项变更，再给实操路径。

升级前：环境与安装

v7 提高了环境门槛：Node ≥ 20.19（推荐 22.x）、TS ≥ 5.4（推荐 5.9.x）。先检查 node --version / tsc --version，不达标先升级运行时，再替换依赖：

npm install @prisma/client@7
npm install -D prisma@7
npm install @prisma/adapter-pg pg   # PostgreSQL 额外装适配器

18 项破坏性变更全览

#	变更
1	Node ≥ 20.19、TS ≥ 5.4，老环境装不上
2	ESM-only + “type”: “module”
3	生成器换 prisma-client，output 必填
4	导入改为生成目录，import 全改
5	datasource 的 url/directUrl/shadowDatabaseUrl 弃用
6	驱动适配器强制
7	连接池默认值变（pg 无超时）
8	Accelerate：prisma:// 不进适配器
9	SSL 校验收紧，自签证书报 P1010
10	环境变量不自动加载
11	prisma.config.ts 成默认配置中心
12	Metrics 移除
13	映射枚举回退 v6 行为
14	middleware 移除 → 客户端扩展
15	seeding 不自动执行
16	migrate dev / db push 不自动 generate
17	CLI 旗标调整（db execute、migrate diff）
18	PRISMA_* 环境变量移除；MongoDB 留 v6

ESM-only 与 tsconfig

Prisma 7 以 ES Module 发布。package.json 要加 "type": "module"，tsconfig 同步调整：

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

ESM 下本地导入要带 .js 后缀；本书示例多用 tsx 运行、可省略后缀，用 node 直接跑 ESM 时需带 .js。嫌烦可引入 tsup，选一条保持一致。

生成器与导入路径

生成器换名字并补上 output：

generator client {
  provider = "prisma-client"   // 原来是 prisma-client-js
  output   = "./generated/prisma"
}

output 必填，客户端不再默认进 node_modules；重新 generate 后导入改指向生成目录：

// 改前
import { PrismaClient } from "@prisma/client";
// 改后
import { PrismaClient } from "./generated/prisma/client";

prisma.config.ts 接管配置

datasource 的 url/directUrl/shadowDatabaseUrl 弃用，连接信息移到项目根目录 prisma.config.ts：

import "dotenv/config";
import { defineConfig, env } from "prisma/config";

export default defineConfig({
  schema: "prisma/schema.prisma",
  migrations: { path: "prisma/migrations", seed: "tsx prisma/seed.ts" },
  datasource: { url: env("DATABASE_URL") },
});

v6.18.0 起 prisma init 就会生成它。以前用 directUrl 跑迁移的，把直连地址放进 datasource.url——CLI 就用它。

驱动适配器与连接池

实例化必须传驱动程序适配器（Driver Adapter，简称驱动适配器）：

import { PrismaClient } from "./generated/prisma/client";
import { PrismaPg } from "@prisma/adapter-pg";

const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL });
export const prisma = new PrismaClient({ adapter });

连接池默认值变了：pg 默认无连接超时（v6 是 5 秒），频繁超时就调回 v6 行为。Accelerate 用户注意：prisma:// URL 不能进适配器，要用 new PrismaClient({ accelerateUrl }) 配合 $extends(withAccelerate())。

middleware 移除与行为变化

$use() 中间件（middleware）已移除，统一改用客户端扩展（Client Extensions）。seeding 与 generate 不再自动执行，显式跑：

npx prisma generate
npx prisma db seed

CLI 旗标也动了：--skip-generate、--skip-seed 移除；db execute 的 --schema/--url 没了；migrate diff 换 --from-config-datasource。SSL 校验默认收紧，自签证书报 P1010，可传 ssl: { rejectUnauthorized: false } 或配置系统 CA。环境变量不再自动加载，先 import "dotenv/config"。

升级路径实操

1. 更新依赖（三小步）：
   • 运行时：npm install @prisma/client@7
   • CLI：npm install -D prisma@7
   • PostgreSQL 加 @prisma/adapter-pg、pg，构建工具按需装 tsup
2. package.json 加 "type": "module"，scripts 改 tsx --watch。
3. 改 tsconfig：module: "ESNext"、moduleResolution: "bundler"。
4. schema.prisma：生成器换 prisma-client 并写 output；datasource 只留 provider。
5. 新建 prisma.config.ts，迁入连接、迁移路径、种子脚本。
6. 客户端实例化改成适配器写法，全局替换导入路径。
7. npx prisma generate 重新生成，npm run dev 验证；报错查第 53 章速查表。

参考来源

• Prisma 官方：Upgrade to v7（guides/upgrade-prisma-orm/v7.mdx）、版本基线 _version.md
• dev.to：How to Upgrade to Prisma v7 (in Expressjs)?（en-tutorials/077）