CloudflareDeployer

CloudflareDeployer 會封裝你的 Mastra 伺服器，並產生符合 Cloudflare wrangler 設定的 wrangler.jsonc 檔案。Cloudflare 會將其部署為 Cloudflare Worker。

安裝

要使用 CloudflareDeployer，請安裝 @mastra/deployer-cloudflare 套件：

npm

npm install @mastra/deployer-cloudflare@latest

pnpm

pnpm add @mastra/deployer-cloudflare@latest

Yarn

yarn add @mastra/deployer-cloudflare@latest

Bun

bun add @mastra/deployer-cloudflare@latest

使用範例

匯入 CloudflareDeployer，並在 Mastra 設定中將其設為 deployer：

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { CloudflareDeployer } from '@mastra/deployer-cloudflare'

export const mastra = new Mastra({
  deployer: new CloudflareDeployer({
    name: 'your-project-name',
    routes: [
      {
        pattern: 'example.com/*',
        zone_name: 'example.com',
        custom_domain: true,
      },
    ],
    vars: {
      NODE_ENV: 'production',
    },
    d1_databases: [
      {
        binding: 'DB',
        database_name: 'my-database',
        database_id: 'd1-database-id',
        preview_database_id: 'your-preview-database-id',
      },
    ],
    kv_namespaces: [
      {
        binding: 'CACHE',
        id: 'kv-namespace-id',
      },
    ],
  }),
})

建構函式選項

CloudflareDeployer 建構函式接受與 wrangler.jsonc 相同的設定選項。所有可用選項請參閱 Wrangler 設定文檔。

密鑰

.env 檔案中的環境變數不會寫入 wrangler.jsonc，以免密鑰被提交至原始碼版本控制系統。

要讓 Cloudflare Worker 使用 .env 中的密鑰，請將其上載為 Cloudflare Secrets：

npx wrangler secret bulk .env

只有 NODE_ENV 之類的非敏感設定值才應在 CloudflareDeployer 建構函式中使用 vars。

建置輸出

執行 mastra build 後，deployer 會產生符合 Cloudflare wrangler 設定的 wrangler.jsonc 檔案。該檔案會指向 .mastra/output 內的檔案，因此以 Wrangler 部署前必須先執行 mastra build。

Cloudflare 繫結

使用 Cloudflare deployer 時，可以在 Mastra 設定檔案中從 cloudflare:workers 匯入運行階段繫結。執行 mastra build 時，Mastra 會自動保留 cloudflare:workers 之類以協定為基礎的運行階段匯入，而不會嘗試將其安裝為 npm 依賴套件。

src/mastra/index.ts

import { env } from 'cloudflare:workers'
import { Mastra } from '@mastra/core'
import { registerApiRoute } from '@mastra/core/server'
import { CloudflareDeployer } from '@mastra/deployer-cloudflare'

export const mastra = new Mastra({
  deployer: new CloudflareDeployer({
    name: 'my-worker',
    kv_namespaces: [{ binding: 'CACHE', id: 'your-kv-namespace-id' }],
  }),
  server: {
    apiRoutes: [
      registerApiRoute('/bindings', {
        method: 'GET',
        requiresAuth: false,
        handler: async c => {
          await env.CACHE.put('status', 'ok')
          return c.json({ status: await env.CACHE.get('status') })
        },
      }),
    ],
  },
})

將繫結直接放在 new Mastra({...}) 內

Mastra 的 Babel plugin 會延遲執行 new Mastra(...)，讓執行時可以使用 env。該呼叫以外的程式碼會在模組載入時求值，早於 env 填入值。

// ✅ Works — binding is inside new Mastra(), so it's deferred
export const mastra = new Mastra({
  storage: new D1Store({ binding: env.DB }),
})

// ❌ Breaks — env.DB is undefined at module load
const storage = new D1Store({ binding: env.DB })
export const mastra = new Mastra({ storage })