部署到 Cloudflare Workers & Pages

本頁涵蓋了將使用 Prisma ORM 的應用程式部署到 Cloudflare Worker 或 Cloudflare Pages 所需瞭解的一切。

部署到 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 "@prisma/client/edge";
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 schema 中將 `DATABASE_URL` 設定為 `datasource` 的 `url`

datasource db {
  provider = "postgresql" // this might also be `mysql` or another value depending on your database
  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 無伺服器驅動程式進行部署。
使用 `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 和 `pg` 驅動程式訪問的傳統 PostgreSQL 資料庫，您需要

使用 `@prisma/adapter-pg` 資料庫介面卡（透過 `driverAdapters` 預覽功能）
在 `wrangler.toml` 中設定 `node_compat = true`（請參閱 Cloudflare 文件）

1. 配置 Prisma schema & 資料庫連線

注意

如果您沒有要部署的專案，請按照先決條件中的說明啟動一個包含 Prisma ORM 的基本 Cloudflare Worker。

首先，確保資料庫連線已正確配置。在您的 Prisma schema 中，將 `datasource` 塊的 `url` 設定為 `DATABASE_URL` 環境變數。您還需要啟用 `driverAdapters` 功能標誌

schema.prisma

generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["driverAdapters"]
}

datasource db {
  provider = "postgresql"
  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. 遷移您的資料庫 schema（如果適用）

如果您在上面運行了 `npx prisma init`，您需要遷移您的資料庫 schema 以建立 Prisma schema 中定義的 `User` 表（如果您的資料庫中已有所需的所有表，則可以跳過此步驟）

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

5. 在 Worker 中使用 Prisma Client 向資料庫傳送查詢

這是一個您可以用來例項化 `PrismaClient` 並向資料庫傳送查詢的程式碼片段示例

import { PrismaClient } from '@prisma/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` 資料庫介面卡（透過 `driverAdapters` 預覽功能）

手動刪除衝突的 `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 schema & 資料庫連線

注意

如果您沒有要部署的專案，請按照先決條件中的說明啟動一個包含 Prisma ORM 的基本 Cloudflare Worker。

首先，確保資料庫連線已正確配置。在您的 Prisma schema 中，將 `datasource` 塊的 `url` 設定為 `DATABASE_URL` 環境變數。您還需要啟用 `driverAdapters` 功能標誌

schema.prisma

generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["driverAdapters"]
}

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

接下來，您需要將 `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. 遷移您的資料庫 schema（如果適用）

npm run env -- npx prisma db push

4. 在 Worker 中使用 Prisma Client 向資料庫傳送查詢

這是一個您可以用來例項化 `PrismaClient` 並向資料庫傳送查詢的程式碼片段示例

import { PrismaClient } from '@prisma/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` 資料庫介面卡（透過 `driverAdapters` 預覽功能）

1. 配置 Prisma schema & 資料庫連線

注意

如果您沒有要部署的專案，請按照先決條件中的說明啟動一個包含 Prisma ORM 的基本 Cloudflare Worker。

首先，確保資料庫連線已正確配置。在您的 Prisma schema 中，將 `datasource` 塊的 `url` 設定為 `DATABASE_URL` 環境變數。您還需要啟用 `driverAdapters` 功能標誌

schema.prisma

generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["driverAdapters"]
}

datasource db {
  provider = "postgresql"
  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. 遷移您的資料庫 schema（如果適用）

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

5. 在 Worker 中使用 Prisma Client 向資料庫傳送查詢

這是一個您可以用來例項化 `PrismaClient` 並向資料庫傳送查詢的程式碼片段示例

import { PrismaClient } from '@prisma/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 schema & 資料庫連線​

2. 安裝依賴項​

3. 在 `wrangler.toml` 中設定 node_compat = true​

4. 遷移您的資料庫 schema（如果適用）​

5. 在 Worker 中使用 Prisma Client 向資料庫傳送查詢​

6. 在本地執行 Worker​

7. 設定 `DATABASE_URL` 環境變數並部署 Worker​

PlanetScale​

1. 配置 Prisma schema & 資料庫連線​

2. 安裝依賴項​

3. 遷移您的資料庫 schema（如果適用）​

4. 在 Worker 中使用 Prisma Client 向資料庫傳送查詢​

6. 在本地執行 Worker​

7. 設定 `DATABASE_URL` 環境變數並部署 Worker​

Neon​

1. 配置 Prisma schema & 資料庫連線​

2. 安裝依賴項​

3. 遷移您的資料庫 schema（如果適用）​

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 schema & 資料庫連線

2. 安裝依賴項

3. 在 `wrangler.toml` 中設定 `node_compat = true`

4. 遷移您的資料庫 schema（如果適用）

5. 在 Worker 中使用 Prisma Client 向資料庫傳送查詢

6. 在本地執行 Worker

7. 設定 `DATABASE_URL` 環境變數並部署 Worker

PlanetScale

1. 配置 Prisma schema & 資料庫連線

2. 安裝依賴項

3. 遷移您的資料庫 schema（如果適用）

4. 在 Worker 中使用 Prisma Client 向資料庫傳送查詢

6. 在本地執行 Worker

7. 設定 `DATABASE_URL` 環境變數並部署 Worker

Neon

1. 配置 Prisma schema & 資料庫連線

2. 安裝依賴項

3. 遷移您的資料庫 schema（如果適用）

5. 在 Worker 中使用 Prisma Client 向資料庫傳送查詢

6. 在本地執行 Worker

7. 設定 `DATABASE_URL` 環境變數並部署 Worker