> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/llms.txt

# CloudflareDeployer

`CloudflareDeployer` 會封裝 Mastra 伺服器，並產生符合 Cloudflare [wrangler 設定](https://developers.cloudflare.com/workers/wrangler/configuration/)的 `wrangler.jsonc` 檔案。Cloudflare 會將其部署為 Cloudflare Worker。

## 安裝

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

**npm**:

```bash
npm install @mastra/deployer-cloudflare@latest
```

**pnpm**:

```bash
pnpm add @mastra/deployer-cloudflare@latest
```

**Yarn**:

```bash
yarn add @mastra/deployer-cloudflare@latest
```

**Bun**:

```bash
bun add @mastra/deployer-cloudflare@latest
```

## 使用範例

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

```typescript
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 設定文件](https://developers.cloudflare.com/workers/wrangler/configuration/)。

## Secret

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

若要讓 Cloudflare Worker 使用 `.env` 中的 secret，請將它們上傳為 [Cloudflare Secrets](https://developers.cloudflare.com/workers/configuration/secrets/)：

```bash
npx wrangler secret bulk .env
```

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

## 建置輸出

執行 `mastra build` 後，deployer 會產生符合 Cloudflare [wrangler 設定](https://developers.cloudflare.com/workers/wrangler/configuration/)的 `wrangler.jsonc` 檔案。該檔案會指向 `.mastra/output` 內的檔案，因此使用 Wrangler 部署前必須先執行 `mastra build`。

## Cloudflare binding

使用 Cloudflare deployer 時，可在 Mastra 設定檔中從 `cloudflare:workers` 匯入執行階段 binding。執行 `mastra build` 時，Mastra 會自動保留 `cloudflare:workers` 這類以通訊協定為基礎的執行階段匯入，不會嘗試將其安裝為 npm 相依套件。

```typescript
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` 尚未填入內容。
>
> ```typescript
> // ✅ 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 })
> ```