본문으로 건너뛰기

Cloudflare배포자

그만큼CloudflareDeployerMastra 서버를 번들로 묶어 생성합니다.wrangler.jsoncCloudflare를 준수하는 파일랭글러 구성. Cloudflare는 이를 Cloudflare 작업자로 배포합니다.

설치
설치에 대한 직접 링크

CloudflareDeployer를 사용하려면 @mastra/deployer-cloudflare 패키지를 설치하세요.

npm install @mastra/deployer-cloudflare@latest

사용예
사용예에 대한 직접 링크

CloudflareDeployer를 가져와 Mastra 구성의 배포자로 설정하세요.

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에 기록되지 않습니다. 따라서 비밀 값이 소스 제어에 커밋되는 것을 방지할 수 있습니다. .env의 비밀 값을 Cloudflare Worker에서 사용할 수 있게 하려면 Cloudflare Secrets로 업로드하세요.

npx wrangler secret bulk .env

CloudflareDeployer 생성자의 vars는 NODE_ENV와 같이 민감하지 않은 구성 값에만 사용하세요.

빌드 출력
빌드 출력에 대한 직접 링크

mastra build를 실행하면 배포자가 Cloudflare의 wrangler 구성을 준수하는 wrangler.jsonc 파일을 생성합니다. 이 파일은 .mastra/output 내부의 파일을 가리키므로 Wrangler로 배포하기 전에 mastra build를 실행해야 합니다.

Cloudflare 바인딩
Cloudflare 바인딩에 대한 직접 링크

Cloudflare 배포자를 사용하면 Mastra 구성 파일에서 cloudflare:workers의 런타임 바인딩을 가져올 수 있습니다. Mastra는 mastra build 중에 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 플러그인은 실행 시 env를 사용할 수 있도록 new Mastra(...)의 실행을 지연합니다. 이 호출 외부의 코드는 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