在带有驱动适配器的 Next.js 应用中将 Prisma 升级到 v7 版本

Prisma v7 引入了 ES 模块默认设置、新的客户端实例化方式以及驱动适配器。升级 Next.js 应用需要遵循一系列步骤，而非简单提升版本号即可。

最低要求

Node.js 20.19+（推荐 22.x），TypeScript 5.4+，以及与您的 ESM 设置兼容的 Next.js 版本。

升级步骤

1. 更新依赖项

将 prisma 和 @prisma/client 同时升级到 v7。

2. 启用 ES 模块支持

在需要的地方设置 "type": "module"，并修正 CJS 之前允许的导入扩展名/路径问题。

3. 更新 Prisma 模型

应用 v7 文档中记载的生成器/提供程序相关更改，修改后重新生成模型。

4. 如有需要则安装 dotenv

当新的入口点不再以旧方式自动加载 .env 文件时，需显式加载环境变量。

5. 创建 Prisma 配置文件

在支持的配置模块中集中管理数据源 URL 和适配器设置。

6. 使用驱动程序适配器更新客户端实例化

npm install @prisma/client@7
npm install -D prisma@7

{
  "type": "module",
  "scripts": {...}
}

generator client {
  provider = "prisma-client-js"
  engineType = "binary"
  output = "./generated"
}

generator client {
  provider = "prisma-client"
}

npm install dotenv

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'),
  },
})

npm install @prisma/adapter-pg

// db/index.ts

import { PrismaClient } from '@prisma/client';

const globalForPrisma = global as unknown as {
  prisma: PrismaClient;
};
const prisma =
  globalForPrisma.prisma ||
  new PrismaClient();

if (process.env.NODE_ENV !== "production") globalForPrisma.prisma = prisma;

export default prisma;

// db/index.ts

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

// postgreSQL adapter for prisma 7
const pool = new Pool({
  connectionString: process.env.DATABASE_URL!,
});

const adapter = new PrismaPg(pool);

const globalForPrisma = global as unknown as {
  prisma: PrismaClient;
};

const prisma =
  globalForPrisma.prisma ||
  new PrismaClient({
    adapter,
  });

if (process.env.NODE_ENV !== "production") globalForPrisma.prisma = prisma;

export default prisma;

// app/api/users/route.ts

import { prisma } from '@/lib/prisma';
import { NextResponse } from 'next/server';

export async function GET() {
  try {
    const users = await prisma.user.findMany();
    return NextResponse.json(users);
  } catch (error) {
    return NextResponse.json(
      { error: 'Failed to fetch users' },
      { status: 500 }
    );
  }
}

npx prisma generate

npm run dev

rm -rf node_modules package-lock.json
npm install
npx prisma generate

应使用数据库驱动程序的适配器，而非依赖已过时的构造函数。

8. 重新生成 Prisma 客户端

在架构/配置确定后运行 prisma generate 命令。

9. 测试迁移过程

在临时数据库上运行迁移操作，测试关键的 Next.js 路由处理程序，并确认边缘/服务器运行时的导入能够正常解析。

常见问题

• lib/prisma.ts中混用了CJS/ESM导入方式
• CI环境使用了错误的Node引擎
• 修改适配器后忘记重新生成客户端
• Edge运行时导入了仅支持Node的驱动程序

将适配器及ESM相关修改放在同一个PR中，并为创建/读取/更新路径编写冒烟测试。

为服务器运行时保留一个唯一的Prisma客户端单例，以避免在Next.js开发时的热重载中耗尽连接池。

需记录哪些路由在Edge上运行、哪些在Node上运行；由于适配器不同，静默回退机制会导致仅在生产环境出现的故障。

为服务器运行时保留一个唯一的Prisma客户端单例，以避免在Next.js开发时的热重载中耗尽连接池。

重新生成客户端后，需删除过期的.next构建缓存，防止Next.js从之前的编译结果中导入旧版本的Prisma客户端。

在切换适配器时请验证连接池设置——无服务器环境与长时间运行的 Node 服务器需要不同的连接池大小。