部署到 Cloudflare Workers & Pages

快速摘要

本页面涵盖了您使用 Prisma ORM 将应用程序部署到 Cloudflare Worker 或 Cloudflare Pages 所需了解的一切。

本页面回答的问题

如何将 Prisma 部署到 Cloudflare Workers？
哪些驱动程序可在 Workers/Pages 上运行？
如何配置 DATABASE_URL 和 envs？

无需 Rust 二进制文件即可使用 Prisma ORM

如果 Prisma ORM 的 Rust 引擎二进制文件导致捆绑包大小过大、构建缓慢或部署问题（例如，在无服务器或边缘环境中），您可以在不使用它们的情况下使用它，只需配置您的 generator 块

generator client {
  provider   = "prisma-client-js" // or "prisma-client"
  engineType = "client"
}

无需 Rust 二进制文件的 Prisma ORM 已于 v6.16.0 起正式发布。

请注意，在这种情况下您需要使用驱动适配器。

使用此架构时

不会下载或附带 Rust 查询引擎二进制文件。
数据库连接池由您安装的原生 JS 数据库驱动程序维护（例如，PostgreSQL 的 @prisma/adapter-pg）。

此设置可以简化无服务器或边缘运行时的部署。在此处文档中了解更多信息。

好奇我们为什么放弃 Rust 引擎？请查看这篇博客文章，了解我们为何从 Rust 二进制引擎转向全 TypeScript 方法，以实现更快、更轻的 Prisma ORM。

部署到 Cloudflare Workers 的一般注意事项

本节涵盖了使用 Prisma ORM 部署到 Cloudflare Workers 或 Pages 时需要注意的一般事项，无论您使用哪个数据库提供商。

使用 Prisma Postgres

您可以使用 Prisma Postgres 并部署到 Cloudflare Workers。

创建 Worker 后，运行

npx prisma@latest init --db

输入您的项目名称并选择一个数据库区域。

此命令

将您的 CLI 连接到您的帐户。如果您未登录或没有帐户，您的浏览器将打开以引导您创建新帐户或登录现有帐户。
创建一个包含数据库模型 schema.prisma 文件的 prisma 目录。
创建一个包含 DATABASE_URL 的 .env 文件（例如，对于 Prisma Postgres，它应该包含类似 DATABASE_URL="prisma+postgres://accelerate.prisma-data.net/?api_key=eyJhbGciOiJIUzI..." 的内容）。

您需要安装使用 Prisma Postgres 所需的客户端扩展

npm i @prisma/extension-accelerate

并在您的应用程序代码中使用扩展程序扩展 PrismaClient

import { PrismaClient } from "./generated/client";
import { withAccelerate } from "@prisma/extension-accelerate";

export interface Env {
  DATABASE_URL: string;
}

export default {
  async fetch(request, env, ctx) {
    const prisma = new PrismaClient({
      datasourceUrl: env.DATABASE_URL,
    }).$extends(withAccelerate());

    const users = await prisma.user.findMany();
    const result = JSON.stringify(users);
    return new Response(result);
  },
} satisfies ExportedHandler<Env>;

然后设置辅助脚本以执行迁移并生成 PrismaClient，如本节所示。

注意

您需要安装 dotenv-cli 包，因为 Cloudflare Workers 不支持 .env 文件。您可以通过运行以下命令在您的项目中本地安装该包：npm install -D dotenv-cli。

使用边缘兼容驱动程序

部署使用 Prisma ORM 的 Cloudflare Worker 时，您需要使用边缘兼容驱动程序及其相应的 Prisma ORM 驱动程序适配器。

Cloudflare Workers 和 Pages 的边缘兼容驱动程序是

Neon Serverless 使用 HTTP 访问数据库
PlanetScale Serverless 使用 HTTP 访问数据库
node-postgres (pg) 使用 Cloudflare 的 connect() (TCP) 访问数据库
@libsql/client 用于通过 HTTP 访问 Turso 数据库
Cloudflare D1 用于访问 D1 数据库

node-mysql2 驱动程序也正在进行工作，未来也将支持从 Cloudflare Workers 和 Pages 访问传统 MySQL 数据库。

注意

如果您的应用程序使用 PostgreSQL，我们建议使用 Prisma Postgres。它在边缘运行时上完全受支持，并且不需要专门的边缘兼容驱动程序。对于其他数据库，Prisma Accelerate 扩展了边缘兼容性，因此您可以从任何边缘函数提供商连接到任何数据库。

将数据库连接 URL 设置为环境变量

首先，确保您的 Prisma 架构中的 datasource 块配置正确。数据库连接 URL 在 prisma.config.ts 中配置

datasource db {
  provider = "postgresql" // this might also be `mysql` or another value depending on your database
}

prisma.config.ts

import 'dotenv/config'
import { defineConfig, env } from 'prisma/config'

export default defineConfig({
  schema: 'prisma/schema.prisma',
  datasource: {
    url: env('DATABASE_URL'),
  },
})

开发

在开发中使用 Worker 时，您可以通过本地 .dev.vars 文件配置数据库连接。

假设您使用上述 DATABASE_URL 环境变量，您可以将其设置在 .dev.vars 中，如下所示

.dev.vars

DATABASE_URL="your-database-connection-string"

在上面的代码片段中，your-database-connection-string 是一个占位符，您需要将其替换为您自己的连接字符串的值，例如

.dev.vars

DATABASE_URL="postgresql://admin:mypassword42@somehost.aws.com:5432/mydb"

请注意，.dev.vars 文件与 Prisma ORM 通常使用的 .env 文件不兼容。

这意味着您需要确保 Prisma ORM 在需要时（例如，运行 prisma migrate dev 等 Prisma CLI 命令时）能够访问环境变量。

有几种方法可以实现这一点

使用 dotenv 运行 Prisma CLI 命令，以指定 CLI 应从何处读取环境变量，例如
```
dotenv -e .dev.vars -- npx prisma migrate dev
```
在 package.json 中创建一个脚本，通过 dotenv 读取 .dev.vars。然后您可以如下执行 prisma 命令：npm run env -- npx prisma migrate dev。以下是脚本的参考
package.json
```
"scripts":  { "env": "dotenv -e .dev.vars" }
```
将 DATABASE_URL 和任何其他相关环境变量复制到一个名为 .env 的新文件中，然后 Prisma ORM 就可以使用该文件。

注意

如果您使用需要 dotenv 的方法，则需要安装 dotenv-cli 包。您可以使用以下命令在您的项目中本地安装该包：npm install -D dotenv-cli。

生产

将 Worker 部署到生产环境时，您需要使用 wrangler CLI 设置数据库连接

npx wrangler secret put DATABASE_URL

该命令是交互式的，将要求您在终端的下一步中输入 DATABASE_URL 环境变量的值。

注意

此命令要求您进行身份验证，如果未登录，将要求您登录您的 Cloudflare 帐户。

免费帐户的大小限制

Cloudflare 对免费套餐的 Workers 施加了 3 MB 的大小限制。如果您的应用程序捆绑包与 Prisma ORM 超过该大小，我们建议升级到付费 Worker 计划或使用 Prisma Accelerate 部署您的应用程序。

使用 `@cloudflare/next-on-pages` 将 Next.js 应用程序部署到 Cloudflare Pages

Cloudflare 提供了使用 @cloudflare/next-on-pages 在 Cloudflare Pages 上运行 Next.js 应用程序的选项，请参阅文档获取说明。

根据一些测试，我们发现以下内容

您可以使用 PlanetScale 或 Neon Serverless 驱动程序进行部署。
使用 pg 的传统 PostgreSQL 部署不起作用，因为 pg 本身目前无法与 @cloudflare/next-on-pages 配合使用（请参见此处）。

如果您发现此内容有任何变化，请随时通过 Discord 与我们联系。

在本地使用 `node` 运行时设置 `PRISMA_CLIENT_FORCE_WASM=1`

某些框架（例如 hono）使用 node 而不是 wrangler 在本地运行 Workers。如果您使用此类框架或因其他原因在本地使用 node 运行 Worker，则需要设置 PRISMA_CLIENT_FORCE_WASM 环境变量

export PRISMA_CLIENT_FORCE_WASM=1

数据库特定注意事项和示例

本节提供了使用 Prisma ORM 部署 Cloudflare Worker 的数据库特定说明。

先决条件

作为以下部分的先决条件，您需要在本地运行一个 Cloudflare Worker 并安装 Prisma CLI。

如果您还没有，可以运行这些命令

npm create cloudflare@latest prisma-cloudflare-worker-example -- --type hello-world
cd prisma-cloudflare-worker-example
npm install prisma --save-dev && npm install @prisma/client
npx prisma init --output ../generated/prisma

您还需要一个您选择的数据库提供商的数据库实例。请参阅提供商的相应文档以设置该实例。

我们将在下面的示例中使用默认的 User 模型

model User {
  id    Int     @id @default(autoincrement())
  email String  @unique
  name  String?
}

PostgreSQL（传统）

如果您使用的是通过 TCP 访问的传统 PostgreSQL 数据库和 pg 驱动程序，您需要

使用 @prisma/adapter-pg 数据库适配器（在此处了解更多信息）
在 wrangler.toml 中设置 node_compat = true（请参阅 Cloudflare 文档）

1. 配置 Prisma 架构和数据库连接

注意

如果您没有要部署的项目，请按照先决条件中的说明启动一个基本的带有 Prisma ORM 的 Cloudflare Worker。

首先，确保数据库连接配置正确。数据库连接 URL 在 prisma.config.ts 中配置

schema.prisma

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

datasource db {
  provider = "postgresql"
}

prisma.config.ts

import 'dotenv/config'
import { defineConfig, env } from 'prisma/config'

export default defineConfig({
  schema: 'prisma/schema.prisma',
  datasource: {
    url: env('DATABASE_URL'),
  },
})

接下来，您需要将 DATABASE_URL 环境变量设置为您的数据库连接字符串的值。您将在 Cloudflare 使用的名为 .dev.vars 的文件中执行此操作

.dev.vars

DATABASE_URL="postgresql://admin:mypassword42@somehost.aws.com:5432/mydb"

由于 Prisma CLI 默认仅与 .env 文件兼容，因此您可以使用以下脚本调整 package.json，该脚本从 .dev.vars 加载环境变量。然后，您可以在执行 prisma 命令之前使用此脚本加载环境变量。

将此脚本添加到您的 package.json

package.json

{
  // ...
  "scripts": {
    // ....
    "env": "dotenv -e .dev.vars"
  },
  // ...
}

现在您可以如下执行 Prisma CLI 命令，同时确保该命令可以访问 .dev.vars 中的环境变量

npm run env -- npx prisma

2. 安装依赖项

接下来，安装所需的包

npm install @prisma/adapter-pg

3. 在 `wrangler.toml` 中设置 `node_compat = true`

在您的 wrangler.toml 文件中，添加以下行

wrangler.toml

node_compat = true

注意

对于 Cloudflare Pages，不正式支持使用 node_compat。如果您想在 Cloudflare Pages 中使用 pg，您可以在此处找到一个解决方法。

4. 迁移数据库架构（如果适用）

如果您运行了 npx prisma init，您需要迁移数据库架构以创建 Prisma 架构中定义的 User 表（如果您已拥有数据库中所需的所有表，则可以跳过此步骤）

npm run env -- npx prisma migrate dev --name init

5. 在 Worker 中使用 Prisma Client 向数据库发送查询

这是一个示例代码片段，您可以使用它来实例化 PrismaClient 并向数据库发送查询

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

export default {
  async fetch(request, env, ctx) {
    const adapter = new PrismaPg({ connectionString: env.DATABASE_URL })
    const prisma = new PrismaClient({ adapter })

    const users = await prisma.user.findMany()
    const result = JSON.stringify(users)
    return new Response(result)
  },
}

6. 在本地运行 Worker

要在本地运行 Worker，您可以运行 wrangler dev 命令

npx wrangler dev

7. 设置 `DATABASE_URL` 环境变量并部署 Worker

要部署 Worker，您首先需要通过 wrangler CLI设置 DATABASE_URL 环境变量

npx wrangler secret put DATABASE_URL

该命令是交互式的，将要求您在终端的下一步中输入 DATABASE_URL 环境变量的值。

注意

此命令要求您进行身份验证，如果未登录，将要求您登录您的 Cloudflare 帐户。

然后您可以继续部署 Worker

npx wrangler deploy

该命令将输出您可以访问已部署 Worker 的 URL。

PlanetScale

如果您使用的是 PlanetScale 数据库，您需要

使用 @prisma/adapter-planetscale 数据库适配器（在此处了解更多信息）

手动删除冲突的 cache 字段

export default {
  async fetch(request, env, ctx) {
    const adapter = new PrismaPlanetScale({
      url: env.DATABASE_URL,
      // see https://github.com/cloudflare/workerd/issues/698
      fetch(url, init) {
        delete init['cache']
        return fetch(url, init)
      },
    })
    const prisma = new PrismaClient({ adapter })

    // ...
  },
}

1. 配置 Prisma 架构和数据库连接

注意

如果您没有要部署的项目，请按照先决条件中的说明启动一个基本的带有 Prisma ORM 的 Cloudflare Worker。

首先，确保数据库连接配置正确。在您的 Prisma 架构中，将 datasource 块的 url 设置为 DATABASE_URL 环境变量

schema.prisma

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

datasource db {
  provider     = "mysql"
  relationMode = "prisma" // required for PlanetScale (as by default foreign keys are disabled)
}

prisma.config.ts

import 'dotenv/config'
import { defineConfig, env } from 'prisma/config'

export default defineConfig({
  schema: 'prisma/schema.prisma',
  datasource: {
    url: env('DATABASE_URL'),
  },
})

接下来，您需要将 DATABASE_URL 环境变量设置为您的数据库连接字符串的值。您将在 Cloudflare 使用的名为 .dev.vars 的文件中执行此操作

.dev.vars

DATABASE_URL="mysql://32qxa2r7hfl3102wrccj:password@us-east.connect.psdb.cloud/demo-cf-worker-ps?sslaccept=strict"

将此脚本添加到您的 package.json

package.json

{
  // ...
  "scripts": {
    // ....
    "env": "dotenv -e .dev.vars"
  },
  // ...
}

现在您可以如下执行 Prisma CLI 命令，同时确保该命令可以访问 .dev.vars 中的环境变量

npm run env -- npx prisma

2. 安装依赖项

接下来，安装所需的包

npm install @prisma/adapter-planetscale

3. 迁移数据库架构（如果适用）

如果您运行了 npx prisma init，您需要迁移数据库架构以创建 Prisma 架构中定义的 User 表（如果您已拥有数据库中所需的所有表，则可以跳过此步骤）

npm run env -- npx prisma db push

4. 在 Worker 中使用 Prisma Client 向数据库发送查询

这是一个示例代码片段，您可以使用它来实例化 PrismaClient 并向数据库发送查询

import { PrismaClient } from './generated/client'
import { PrismaPlanetScale } from '@prisma/adapter-planetscale'

export default {
  async fetch(request, env, ctx) {
    const adapter = new PrismaPlanetScale({
      url: env.DATABASE_URL,
      // see https://github.com/cloudflare/workerd/issues/698
      fetch(url, init) {
        delete init['cache']
        return fetch(url, init)
      },
    })
    const prisma = new PrismaClient({ adapter })

    const users = await prisma.user.findMany()
    const result = JSON.stringify(users)
    return new Response(result)
  },
}

6. 在本地运行 Worker

要在本地运行 Worker，您可以运行 wrangler dev 命令

npx wrangler dev

7. 设置 `DATABASE_URL` 环境变量并部署 Worker

要部署 Worker，您首先需要通过 wrangler CLI设置 DATABASE_URL 环境变量

npx wrangler secret put DATABASE_URL

该命令是交互式的，将要求您在终端的下一步中输入 DATABASE_URL 环境变量的值。

注意

此命令要求您进行身份验证，如果未登录，将要求您登录您的 Cloudflare 帐户。

然后您可以继续部署 Worker

npx wrangler deploy

该命令将输出您可以访问已部署 Worker 的 URL。

Neon

如果您使用的是 Neon 数据库，您需要

使用 @prisma/adapter-neon 数据库适配器（在此处了解更多信息）

1. 配置 Prisma 架构和数据库连接

注意

如果您没有要部署的项目，请按照先决条件中的说明启动一个基本的带有 Prisma ORM 的 Cloudflare Worker。

首先，确保数据库连接配置正确。数据库连接 URL 在 prisma.config.ts 中配置

schema.prisma

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

datasource db {
  provider = "postgresql"
}

prisma.config.ts

import 'dotenv/config'
import { defineConfig, env } from 'prisma/config'

export default defineConfig({
  schema: 'prisma/schema.prisma',
  datasource: {
    url: env('DATABASE_URL'),
  },
})

接下来，您需要将 DATABASE_URL 环境变量设置为您的数据库连接字符串的值。您将在 Cloudflare 使用的名为 .dev.vars 的文件中执行此操作

.dev.vars

DATABASE_URL="postgresql://janedoe:password@ep-nameless-pond-a23b1mdz.eu-central-1.aws.neon.tech/neondb?sslmode=require"

将此脚本添加到您的 package.json

package.json

{
  // ...
  "scripts": {
    // ....
    "env": "dotenv -e .dev.vars"
  },
  // ...
}

现在您可以如下执行 Prisma CLI 命令，同时确保该命令可以访问 .dev.vars 中的环境变量

npm run env -- npx prisma

2. 安装依赖项

接下来，安装所需的包

npm install @prisma/adapter-neon

3. 迁移数据库架构（如果适用）

如果您运行了 npx prisma init，您需要迁移数据库架构以创建 Prisma 架构中定义的 User 表（如果您已拥有数据库中所需的所有表，则可以跳过此步骤）

npm run env -- npx prisma migrate dev --name init

5. 在 Worker 中使用 Prisma Client 向数据库发送查询

这是一个示例代码片段，您可以使用它来实例化 PrismaClient 并向数据库发送查询

import { PrismaClient } from './generated/client'
import { PrismaNeon } from '@prisma/adapter-neon'

export default {
  async fetch(request, env, ctx) {
    const adapter = new PrismaNeon({ connectionString: env.DATABASE_URL })
    const prisma = new PrismaClient({ adapter })

    const users = await prisma.user.findMany()
    const result = JSON.stringify(users)
    return new Response(result)
  },
}

6. 在本地运行 Worker

要在本地运行 Worker，您可以运行 wrangler dev 命令

npx wrangler dev

7. 设置 `DATABASE_URL` 环境变量并部署 Worker

要部署 Worker，您首先需要通过 wrangler CLI设置 DATABASE_URL 环境变量

npx wrangler secret put DATABASE_URL

该命令是交互式的，将要求您在终端的下一步中输入 DATABASE_URL 环境变量的值。

注意

此命令要求您进行身份验证，如果未登录，将要求您登录您的 Cloudflare 帐户。

然后您可以继续部署 Worker

npx wrangler deploy

该命令将输出您可以访问已部署 Worker 的 URL。

部署到 Cloudflare Workers 的一般注意事项​

使用 Prisma Postgres​

使用边缘兼容驱动程序​

将数据库连接 URL 设置为环境变量​

开发​

生产​

免费帐户的大小限制​

使用 @cloudflare/next-on-pages 将 Next.js 应用程序部署到 Cloudflare Pages​

在本地使用 node 运行时设置 PRISMA_CLIENT_FORCE_WASM=1​

数据库特定注意事项和示例​

先决条件​

PostgreSQL（传统）​

1. 配置 Prisma 架构和数据库连接​

2. 安装依赖项​

3. 在 wrangler.toml 中设置 node_compat = true​

4. 迁移数据库架构（如果适用）​

5. 在 Worker 中使用 Prisma Client 向数据库发送查询​

6. 在本地运行 Worker​

7. 设置 DATABASE_URL 环境变量并部署 Worker​

PlanetScale​

1. 配置 Prisma 架构和数据库连接​

2. 安装依赖项​

3. 迁移数据库架构（如果适用）​

4. 在 Worker 中使用 Prisma Client 向数据库发送查询​

6. 在本地运行 Worker​

7. 设置 DATABASE_URL 环境变量并部署 Worker​

Neon​

1. 配置 Prisma 架构和数据库连接​

2. 安装依赖项​

3. 迁移数据库架构（如果适用）​

5. 在 Worker 中使用 Prisma Client 向数据库发送查询​

6. 在本地运行 Worker​

7. 设置 DATABASE_URL 环境变量并部署 Worker​

部署到 Cloudflare Workers 的一般注意事项

使用 Prisma Postgres

使用边缘兼容驱动程序

将数据库连接 URL 设置为环境变量

开发

生产

免费帐户的大小限制

使用 `@cloudflare/next-on-pages` 将 Next.js 应用程序部署到 Cloudflare Pages

在本地使用 `node` 运行时设置 `PRISMA_CLIENT_FORCE_WASM=1`

数据库特定注意事项和示例

先决条件

PostgreSQL（传统）

1. 配置 Prisma 架构和数据库连接

2. 安装依赖项

3. 在 `wrangler.toml` 中设置 `node_compat = true`

4. 迁移数据库架构（如果适用）

5. 在 Worker 中使用 Prisma Client 向数据库发送查询

6. 在本地运行 Worker

7. 设置 `DATABASE_URL` 环境变量并部署 Worker

PlanetScale

1. 配置 Prisma 架构和数据库连接

2. 安装依赖项

3. 迁移数据库架构（如果适用）

4. 在 Worker 中使用 Prisma Client 向数据库发送查询

6. 在本地运行 Worker

7. 设置 `DATABASE_URL` 环境变量并部署 Worker

Neon

1. 配置 Prisma 架构和数据库连接

2. 安装依赖项

3. 迁移数据库架构（如果适用）

5. 在 Worker 中使用 Prisma Client 向数据库发送查询

6. 在本地运行 Worker

7. 设置 `DATABASE_URL` 环境变量并部署 Worker