跳至主要內容

CloudflareDeployer

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

安裝
「安裝」的直接連結

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

npm install @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 設定文件。

Secret
「Secret」的直接連結

.env 檔案中的環境變數不會寫入 wrangler.jsonc，以免 secret 被提交至版本控制。

若要讓 Cloudflare Worker 使用 .env 中的 secret，請將它們上傳為 Cloudflare Secrets：

npx wrangler secret bulk .env

CloudflareDeployer 建構函式中的 vars 僅應用於 NODE_ENV 等非敏感設定值。

建置輸出
「建置輸出」的直接連結

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

Cloudflare binding
「Cloudflare binding」的直接連結

使用 Cloudflare deployer 時，可在 Mastra 設定檔中從 cloudflare:workers 匯入執行階段 binding。執行 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') })
        },
      }),
    ],
  },
})
請將 binding 直接放在 new Mastra({...}) 內

Mastra 的 Babel 外掛會延後執行 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 })
On this page