配置使用 Accelerate URL 的 Prisma 7

Prisma 7（2025年11月19日发布）的配置变化较大，导致许多针对Prisma 6的教程不再适用。以下内容来自对文档的阅读、生成的声明文件的分析，以及在首次设置SQL/Postgres时遇到的错误处理——尤其适用于从MongoDB和Mongoose转过来的人。

对于新手而言，升级过程的变化尤为显著：在旧版本教程中第一次成功创建的PrismaClient在v7版本的第一天往往就已经不正确。应将构造函数参数和配置文件视为核心概念的一部分，而非可选的进阶内容。

1. 第一个重大变化：prisma.config.ts

安装完成后，Prisma会生成一个新的根文件：

prisma.config.ts

早期版本将DATABASE_URL放在schema.prisma中，而现在的连接配置则位于prisma.config.ts里。

生成的形状：

// This file was generated by Prisma and assumes you have installed the following:
// npm install --save-dev prisma dotenv
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"),
  },
});

发生了什么变化？

• env("DATABASE_URL") 不再是模式文件的处理内容。
• 与环境相关的配置被移至新文件中。
• schema.prisma仍专注于模型定义。

2. 解决tsconfig.json根目录问题

如果tsconfig.json中包含：

"rootDir": "./src"

TypeScript会拒绝位于src之外的prisma.config.ts。需扩大根目录范围：

"rootDir": "./"

3. 迁移并生成客户端代码

在模型定义完成后：

npx prisma migrate dev
npx prisma generate

模式文件的生成模块会指定客户端代码的来源路径：

generator client {
  provider = "prisma-client"
  output   = "../src/generated/prisma"
}

在创建PrismaClient之前，生成过程看似正常。

4. 最令人困惑的错误：“预期1个参数，实际得到0个”

这种无参数的构造方式：

const prisma = new PrismaClient();

请从生成的client模块中导入PrismaClient，而非其他同级类文件。即便如此，Prisma 7仍可能拒绝零参数的情况：

Expected 1 argument, but got 0.

旧教程中仍展示无参数构造函数。但查看生成的client/class文件后可知，现在的构造函数需要配置参数，包括：

accelerateURL

5. 介绍accelerateURL（Prisma 7新功能）

Prisma 7与Prisma Accelerate深度集成——具备全局查询缓存和连接池功能。Accelerate的目标是：

• 实现全局查询缓存
• 降低延迟
• 为无服务器环境提供连接池

在这种模式下，PrismaClient必须指定accelerateURL。

6. Prisma现已推出自有云数据库

Prisma控制台可以：

• 创建数据库
• 生成 Accelerate API 密钥
• 为客户端提供 accelerateURL

一个实际问题在于：以以下格式开头的普通 Neon 风格 URL：

" postgresql:// "

不符合 Accelerate 所要求的协议标准：

" prisma:// " or " prisma+postgres:// "

这种不匹配会导致如下错误：

InvalidDatasourceError: Error validating `accelerateUrl`: the URL must
start with the protocol `prisma://` or `prisma+postgres://`

7. 最终可用的 PrismaClient 配置（Prisma 7）

可行的配置方式如下：

import { withAccelerate } from "@prisma/extension-accelerate";
import { PrismaClient } from "../src/generated/prisma/client.js";
import { DATABASE_URL } from "../config/index.js";

export const prisma = new PrismaClient({
  accelerateUrl: DATABASE_URL as string
}).$extends(withAccelerate());

什么是 $extends？

$extends() 用于将 Accelerate 等功能添加到客户端中。

8. 重要提示：需要两个环境变量

以这种模式配置 Prisma 7 时通常需要：

DATABASE_URL → Accelerate URL

DIRECT_DATABASE_URL → 直接的 PostgreSQL 连接字符串

prisma.config.ts 应该在数据迁移时使用直接连接的 URL：

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

然后进行迁移并重新生成：

npx prisma migrate dev
npx prisma generate

以加速功能为导向的架构也会改变操作习惯。迁移和检查过程仍需要直接的数据库地址，而应用流量则可能通过加速端点传输。如果将这两种地址混用——在需要加速地址的位置使用直接的 Postgres 地址，或反之——就会产生错误，而这些错误看起来与正在编辑的应用代码行并无关联。请在 .env 文件中明确标注这两个值，一旦任一协议前缀有误，应在系统启动时立即报错。

对于从 Prisma 6 迁移的团队而言，这并非可直接升级的操作，而需要遵循一系列检查清单：添加 prisma.config.ts 文件，必要时扩大 rootDir 的范围，在启用 Accelerate 功能时不要使用零参数来创建 PrismaClient，接入 $extends(withAccelerate()) 机制，并分离环境变量。一旦熟悉了这些操作步骤，日常的模型构建工作就会再次变得得心应手。

结论

Prisma 7 引入的变革——如 prisma.config.ts、必需的客户端参数、accelerateURL 以及 $extends——在 Prisma 6 的相关文档中阐述得不够充分。一旦弄清楚 Accelerate 的 URL 规则以及双环境分离机制，无论是初次使用 SQL 的用户还是从 v6 升级的用户，都能更轻松地完成客户端配置。