部署到 Cloudflare Workers & Pages

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

部署到 Cloudflare Workers 時的一般考量

本節涵蓋部署到 Cloudflare Workers 或 Pages 以及使用 Prisma ORM 時，無論您使用何種資料庫供應商，都需注意的一般事項。

使用邊緣相容的驅動程式

當部署使用 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 資料庫成為可能。

注意：Prisma Accelerate 讓您可以從任何邊緣函數供應商存取任何資料庫。不需要邊緣相容的驅動程式。

將您的資料庫連線 URL 設定為環境變數

首先，請確保 DATABASE_URL 在您的 Prisma schema 中設定為 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 CLI 命令（如 prisma migrate dev）時。

有幾種方法可以實現這一點：

使用 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 vars 複製到一個名為 .env 的新檔案中，Prisma ORM 即可使用該檔案。

注意：如果您使用需要 dotenv 的方法，則需要安裝 dotenv-cli 套件。例如，您可以使用此命令在本機專案中安裝該套件：npm install -D dotenv-cli。

生產環境

當將您的 Worker 部署到生產環境時，您需要使用 wrangler CLI 設定資料庫連線

npx wrangler secret put DATABASE_URL

該命令是互動式的，將要求您在終端機的下一步中輸入 DATABASE_URL env var 的值。

注意：此命令需要您進行身份驗證，如果您尚未登入，將要求您登入您的 Cloudflare 帳戶。

免費帳戶的大小限制

Cloudflare 對於免費方案上的 Workers 有 3 MB 的大小限制。如果您的應用程式套件與 Prisma ORM 超過該大小，我們建議升級到付費 Worker 方案或使用 Prisma Accelerate 來部署您的應用程式。

如果您在使用 pg 和 @prisma/adapter-pg 套件時遇到此問題，您可以將 pg 替換為自訂的 @prisma/pg-worker 套件，並使用與其對應的 @prisma/adapter-pg-worker 轉接器。

@prisma/pg-worker 是 pg 的最佳化輕量版本，旨在用於 Worker 中。它是 pg 的直接替代品，並且與 Prisma ORM 完全相容。

使用 `@cloudflare/next-on-pages` 將 Next.js 應用程式部署到 Cloudflare Pages

Cloudflare 提供使用 @cloudflare/next-on-pages 在 Cloudflare Pages 上執行 Next.js 應用程式的選項，請參閱文件以取得說明。

根據一些測試，我們發現以下內容：

您可以使用 PlanetScale 或 Neon Serverless Driver 進行部署。
使用 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

資料庫特定考量與範例

本節提供資料庫特定的說明，用於將 Cloudflare Worker 與 Prisma ORM 一起部署。

先決條件

作為以下章節的先決條件，您需要在本機執行 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
npx prisma init

您還需要您選擇的資料庫供應商的資料庫實例。請參閱供應商的相關文件以設定該實例。

在下面的範例中，我們將使用預設的 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 文件）

如果您遇到大小問題，且由於該問題而無法部署應用程式，則可以使用我們更精簡的 pg 驅動程式套件變體 @prisma/pg-worker 以及與其對應的 @prisma/adapter-pg-worker 轉接器。

@prisma/pg-worker 是 pg 的最佳化輕量版本，旨在用於 Worker 中。它是 pg 的直接替代品，並且與 Prisma ORM 完全相容。

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 載入 env vars。然後，您可以使用此腳本在執行 prisma 命令之前載入 env vars。

將此腳本新增至您的 package.json

package.json

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

現在您可以執行 Prisma CLI 命令，同時確保該命令可以存取 .dev.vars 中的 env vars

npm run env -- npx prisma

2. 安裝依賴項

接下來，安裝所需的套件

npm install @prisma/adapter-pg
npm install pg
npm install @types/pg --save-dev # if you're using TypeScript

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'
import { Pool } from 'pg'

export default {
  async fetch(request, env, ctx) {
    const pool = new Pool({ connectionString: env.DATABASE_URL })
    const adapter = new PrismaPg(pool)
    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 env var 的值。

注意：此命令需要您進行身份驗證，如果您尚未登入，將要求您登入您的 Cloudflare 帳戶。

然後您可以繼續部署 Worker

npx wrangler deploy

該命令將輸出您可以存取已部署 Worker 的 URL。

PlanetScale

如果您使用 PlanetScale 資料庫，則需要：

使用 @prisma/adapter-planetscale 資料庫轉接器（透過 driverAdapters 預覽功能）

手動移除衝突的 cache 欄位 (了解更多)

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

    // ...
  },
}

1. 設定 Prisma schema 和資料庫連線

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

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 中的 env vars

npm run env -- npx prisma

2. 安裝依賴項

接下來，安裝所需的套件

npm install @prisma/adapter-planetscale
npm install @planetscale/database

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'
import { Client } from '@planetscale/database'

export default {
  async fetch(request, env, ctx) {
    const client = new Client({
      url: env.DATABASE_URL,
      // see https://github.com/cloudflare/workerd/issues/698
      fetch(url, init) {
        delete init['cache']
        return fetch(url, init)
      },
    })
    const adapter = new PrismaPlanetScale(client)
    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 env var 的值。

注意：此命令需要您進行身份驗證，如果您尚未登入，將要求您登入您的 Cloudflare 帳戶。

然後您可以繼續部署 Worker

npx wrangler deploy

該命令將輸出您可以存取已部署 Worker 的 URL。

Neon

如果您使用 Neon 資料庫，則需要：

使用 @prisma/adapter-neon 資料庫轉接器（透過 driverAdapters 預覽功能）

1. 設定 Prisma schema 和資料庫連線

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

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 中的 env vars

npm run env -- npx prisma

2. 安裝依賴項

接下來，安裝所需的套件

npm install @prisma/adapter-neon
npm install @neondatabase/serverless

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'
import { Pool } from '@neondatabase/serverless'

export default {
  async fetch(request, env, ctx) {
    const neon = new Pool({ connectionString: env.DATABASE_URL })
    const adapter = new PrismaNeon(neon)
    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 env var 的值。

注意：此命令需要您進行身份驗證，如果您尚未登入，將要求您登入您的 Cloudflare 帳戶。

然後您可以繼續部署 Worker

npx wrangler deploy

該命令將輸出您可以存取已部署 Worker 的 URL。

部署到 Cloudflare Workers 時的一般考量​

使用邊緣相容的驅動程式​

將您的資料庫連線 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 時的一般考量

使用邊緣相容的驅動程式

將您的資料庫連線 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