@astrojs/ cloudflare

이 어댑터를 사용하면 서버 아일랜드, 액션, 세션을 포함한 주문형으로 렌더링되는 경로 및 기능을 Cloudflare에 배포할 수 있습니다.

Astro를 정적 사이트 빌더로 사용하고 있다면 어댑터가 필요하지 않습니다.

Astro 사이트를 배포하는 방법은 Cloudflare 배포 가이드에서 자세히 알아볼 수 있습니다.

왜 Astro Cloudflare인가요?

Cloudflare의 개발자 플랫폼을 사용하면 스토리지 및 AI와 같은 리소스에 액세스할 수 있는 풀스택 애플리케이션을 개발하고 전 세계 에지 네트워크에 배포할 수 있습니다. 이 어댑터는 Cloudflare를 통해 배포할 수 있도록 Astro 프로젝트를 빌드합니다.

설치

Astro에는 공식 통합 설정을 자동화하는 astro add 명령어가 포함되어 있습니다. 원하는 경우 대신 통합을 수동으로 설치할 수 있습니다.

astro add 명령어를 사용하여 Astro 프로젝트에서 서버 렌더링을 활성화하기 위해 Cloudflare 어댑터를 추가합니다. 이 명령어는 @astrojs/cloudflare를 설치하고 astro.config.mjs 파일을 한 번에 적절하게 수정합니다.

npx astro add cloudflare

pnpm astro add cloudflare

yarn astro add cloudflare

이제 페이지별로 주문형 렌더링을 활성화하거나, 빌드 출력 구성을 output: 'server'로 설정하여 기본적으로 모든 페이지를 서버 렌더링할 수 있습니다.

수동 설치

선호하는 패키지 매니저를 사용하여 프로젝트 의존성에 @astrojs/cloudflare 어댑터를 추가합니다.
- npm
- pnpm
- Yarn
터미널 창
npm install @astrojs/cloudflare
터미널 창
pnpm add @astrojs/cloudflare
터미널 창
yarn add @astrojs/cloudflare

astro.config.mjs 파일에 어댑터를 추가합니다.

import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  adapter: cloudflare(),
});

Astro는 package.json의 name 필드나 폴더 이름을 Worker 이름으로 사용하여 기본 구성을 자동으로 생성합니다. 사용자 지정 설정이 필요한 경우 선택적으로 Wrangler 구성 파일을 생성할 수 있습니다. 다음 예시는 Cloudflare KV 바인딩을 선언합니다.
wrangler.jsonc
```
{
  "name": "my-astro-app",
  // 여기에 바인딩을 추가하세요. 예:
  // "kv_namespaces": [{ "binding": "MY_KV", "id": "<namespace_id>" }]
}
```

옵션

Cloudflare 어댑터는 @cloudflare/vite-plugin으로부터 다음 옵션을 허용합니다.

auxiliaryWorkers
configPath
inspectorPort
persistState
remoteBindings
experimental.headersAndRedirectsDevModeSupport

또한 다음 옵션도 허용합니다.

`imageService`

타입: 'passthrough' | 'cloudflare' | 'cloudflare-binding' | 'compile' | 'custom' | { build: 'compile', runtime?: 'cloudflare-binding' | 'passthrough' }
기본값: 'cloudflare-binding'

어댑터에서 사용할 이미지 서비스를 결정합니다. 호환되지 않는 이미지 서비스가 구성된 경우 어댑터는 기본적으로 cloudflare-binding 모드를 사용합니다. 그렇지 않으면 전역으로 구성된 이미지 서비스를 사용합니다.

cloudflare: Cloudflare Image Resizing 서비스를 사용합니다.
cloudflare-binding: 이미지 변환을 위해 Cloudflare Images 바인딩을 사용합니다. 바인딩은 배포 시 자동으로 프로비저닝됩니다.
passthrough: 기존 noop 서비스를 사용합니다.
compile: 사전 렌더링된 경로에 대해 빌드 시 로컬에서 이미지를 변환하기 위해 내부 의존성 조합을 사용합니다. 주문형 렌더링 페이지에는 noop passthrough 옵션이 구성됩니다.
custom: 항상 이미지 옵션에 구성된 이미지 서비스를 사용합니다. 이 옵션은 구성된 이미지 서비스가 Cloudflare의 workerd 런타임에서 작동하는지 확인하지 않습니다.

이미지 서비스를 객체로 구성하여 빌드 시점 서비스와 런타임 서비스를 각각 독립적으로 설정할 수도 있습니다. 현재 빌드 시점 옵션으로는 'compile'만 사용할 수 있습니다. 지원되는 런타임 옵션은 'passthrough' (기본값) 및 'cloudflare-binding'입니다.

import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  adapter: cloudflare({
    imageService: { build: 'compile', runtime: 'cloudflare-binding' }
  }),
});

`sessionKVBindingName`

타입: string
기본값: SESSION

추가된 버전: @astrojs/cloudflare@12.4.0

세션 저장소에 사용되는 KV 바인딩의 이름을 설정합니다. 기본적으로 KV 네임스페이스는 배포 시 자동으로 프로비저닝되며 이름은 SESSION입니다. wrangler 구성에서 수동으로 바인딩을 설정하여 이 이름을 변경할 수 있습니다. 자세한 내용은 세션을 참조하세요.

export default defineConfig({
  adapter: cloudflare({
    sessionKVBindingName: 'MY_SESSION_BINDING',
  }),
});

{
  "kv_namespaces": [
    {
      "binding": "MY_SESSION_BINDING",
    }
  ]
}

`imagesBindingName`

타입: string
기본값: IMAGES

imageService가 cloudflare-binding으로 설정된 경우 사용되는 이미지 바인딩의 이름을 설정합니다. 기본적으로 바인딩은 배포 시 IMAGES라는 이름으로 자동으로 프로비저닝됩니다. wrangler 구성에서 수동으로 바인딩을 설정하여 이를 변경할 수 있습니다.

export default defineConfig({
  adapter: cloudflare({
    imageService: 'cloudflare-binding',
    imagesBindingName: 'MY_IMAGES',
  }),
});

{
  "images": {
    "binding": "MY_IMAGES"
  }
}

`prerenderEnvironment`

타입: 'workerd' | 'node'
기본값: 'workerd'

추가된 버전: @astrojs/cloudflare@13.1.0 새로운 기능

빌드 시점 및 개발 중에 정적 페이지를 사전 렌더링하는 데 사용되는 런타임을 제어합니다.

기본적으로 사전 렌더링된 페이지는 프로덕션 환경과 최대한 가깝게 일치하도록 Cloudflare의 workerd 런타임을 사용하여 빌드됩니다. 사전 렌더링된 페이지가 workerd와 호환되지 않는 Node.js API 또는 NPM 패키지에 의존하는 경우 이 옵션을 'node'로 설정하세요.

import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  adapter: cloudflare({
    prerenderEnvironment: 'node',
  }),
});

예를 들어, 사전 렌더링된 페이지가 node:fs를 사용하여 파일 시스템에서 읽는 경우 prerenderEnvironment를 'node'로 설정하세요. 주문형으로 렌더링된 페이지는 이 옵션의 영향을 받지 않으며 항상 workerd에서 실행됩니다.

Cloudflare 런타임

Cloudflare 런타임을 사용하면 환경 변수, Cloudflare 리소스에 대한 바인딩 및 기타 Cloudflare 전용 API에 액세스할 수 있습니다.

환경 변수 및 바인딩

환경 변수 및 바인딩은 wrangler.jsonc 구성 파일에 정의됩니다.

민감한 정보를 저장하지 않는 환경 변수를 wrangler.jsonc에 정의합니다.

{
  "vars": {
    "MY_VARIABLE": "test",
  },
}

비밀 정보 (Secrets)는 Worker에 암호화된 텍스트 값을 첨부할 수 있는 특수한 유형의 환경 변수입니다. 설정한 후 Wrangler 또는 Cloudflare 대시보드 내에서 볼 수 없도록 다르게 정의해야 합니다.

비밀 정보를 정의하려면 Wrangler 구성 파일 대신 Wrangler CLI를 통해 추가하세요.

npx wrangler secret put <KEY>

로컬 개발을 위해 비밀 정보를 설정하려면 Astro 프로젝트의 루트에 .dev.vars 파일을 추가하세요.

DB_PASSWORD=myPassword

Cloudflare 환경 변수 및 비밀 정보는 "cloudflare:workers"에서 가져올 수 있습니다.

---
import { env } from 'cloudflare:workers';

const myVariable = env.MY_VARIABLE;
const myKVNamespace = env.MY_KV;
---

또한 astro:env API와도 호환됩니다.

import { MY_VARIABLE } from 'astro:env/server';

Cloudflare 문서에서 지원되는 모든 바인딩 목록을 확인하세요.

`cf` 객체

Cloudflare cf 객체에는 지리적 위치 정보와 같은 요청 메타데이터가 포함되어 있습니다. 요청에서 직접 액세스하세요.

---
const cf = Astro.request.cf;
const country = cf?.country;
---

실행 컨텍스트

Astro.locals.cfContext를 통해 Cloudflare ExecutionContext에 액세스할 수 있습니다. 이는 waitUntil()과 같은 작업이나 페이지 내에서 Durable Object exports에 액세스하는 데 유용합니다.

---
const cfContext = Astro.locals.cfContext;
cfContext.exports.Greeter.greet('Astro');
cfContext.waitUntil(someAsyncOperation());
---

타입 지정

wrangler는 바인딩에 대한 TypeScript 타입을 생성하는 types 명령어를 제공합니다. 이를 통해 수동 타입 정의 없이도 환경에 타입을 지정할 수 있습니다.

구성 파일(예: wrangler.jsonc, .dev.vars)을 변경할 때마다 wrangler types를 실행하세요.

다음 예시는 다른 명령어보다 먼저 wrangler types를 자동으로 실행하도록 하는 스크립트 구성입니다.

{
  "scripts": {
    "dev": "wrangler types && astro dev",
    "start": "wrangler types && astro dev",
    "build": "wrangler types && astro check && astro build",
    "preview": "wrangler types && astro preview",
    "astro": "astro"
  }
}

Cloudflare 플랫폼

헤더

Astro 프로젝트의 public/ 폴더에 _headers 파일을 만들어 정적 자산에 대한 사용자 지정 헤더를 추가할 수 있습니다. 이 파일은 빌드 출력 디렉터리에 복사됩니다. _headers의 헤더는 Worker 코드에 의해 생성된 응답에는 적용되지 않습니다.

자산

Astro가 빌드한 자산은 모두 해시가 포함된 이름으로 생성되므로 긴 캐시 헤더를 가질 수 있습니다. 기본적으로 Cloudflare의 Astro는 이러한 파일에 대해 해당 헤더를 추가합니다.

리디렉션

Astro 프로젝트의 public/ 폴더에 _redirects 파일을 추가하여 정적 자산에 대한 사용자 지정 리디렉션를 선언할 수 있습니다. 이 파일은 빌드 출력 디렉터리에 복사됩니다. 동적 경로의 경우 대신 Astro에서 직접 리디렉션를 구성하세요.

라우트

정적 자산에 대한 라우팅은 빌드 디렉터리(예: ./dist)의 파일 구조를 기반으로 합니다. 일치하는 항목이 없으면 주문형 렌더링을 위해 Worker로 대체됩니다. Cloudflare Workers의 정적 자산 라우팅에 대해 자세히 알아보세요.

세션

Astro 세션 API를 사용하면 요청 간에 사용자 데이터를 쉽게 저장할 수 있습니다. 이는 사용자 데이터 및 기본 설정, 장바구니, 인증 자격 증명과 같은 항목에 사용할 수 있습니다. 쿠키 저장소와 달리 데이터 크기 제한이 없으며 다른 장치에서도 복원할 수 있습니다.

Astro는 Cloudflare 어댑터를 사용할 때 세션 저장소를 위해 Workers KV를 자동으로 구성합니다. Wrangler는 배포 시 KV 네임스페이스를 자동으로 프로비저닝할 수 있으므로 수동 설정이 필요하지 않습니다. 또는 wrangler.jsonc 파일에 수동으로 KV 바인딩을 정의하고 sessionKVBindingName 어댑터 옵션을 사용하여 사용자 지정 바인딩 이름을 설정할 수 있습니다.

---
export const prerender = false; // 'server' 모드에서는 필요하지 않음
const cart = await Astro.session?.get('cart');
---

<a href="/checkout">🛒 {cart?.length ?? 0} items</a>

기본적으로 KV 바인딩 이름은 SESSION입니다. 다른 이름을 사용하려면 어댑터 구성에서 sessionKVBindingName 옵션을 설정하세요.

Cloudflare 모듈 가져오기

Cloudflare workerd 런타임은 일부 비표준 모듈 유형 가져오기를 지원합니다. 대부분의 추가 파일 유형은 Astro에서도 사용할 수 있습니다.

.wasm 또는 .wasm?module: 인스턴스화할 수 있는 WebAssembly.Module을 내보냅니다.
.bin: 파일의 원시 이진 콘텐츠의 ArrayBuffer를 내보냅니다.
.txt: 파일 콘텐츠의 문자열을 내보냅니다.

모든 모듈 유형은 단일 기본값을 내보냅니다. 모듈은 서버 사이드 렌더링 페이지 또는 정적 사이트 생성을 위한 사전 렌더링된 페이지 모두에서 가져올 수 있습니다.

다음은 요청의 숫자 매개변수를 함께 더하여 요청에 응답하는 Wasm 모듈을 가져오는 예시입니다.

// WebAssembly 모듈 가져오기
import mod from '../util/add.wasm';

// 사용하려면 먼저 인스턴스화해야 합니다.
const addModule: any = new WebAssembly.Instance(mod);

export async function GET(context) {
  const a = Number.parseInt(context.params.a);
  const b = Number.parseInt(context.params.b);
  return new Response(`${addModule.exports.add(a, b)}`);
}

이 예시는 간단하지만, Wasm은 이미지 처리 라이브러리 임베딩이나 읽기 전용 데이터 세트에 대한 검색을 위한 작은 사전 색인 데이터베이스 임베딩과 같이 상당한 I/O가 수반되지 않는 계산 집약적인 작업을 가속화하는 데 사용될 수 있습니다.

Node.js 호환성

Cloudflare Workers는 nodejs_compat 호환성 플래그를 통해 대부분의 Node.js 런타임 API를 지원합니다. 여기에는 node:buffer, node:crypto, node:path 등과 같이 자주 사용되는 모듈이 포함됩니다. Cloudflare 문서에서 지원되는 Node.js API의 전체 목록을 확인하세요.

Node.js 호환성을 활성화하려면 Wrangler 구성에 nodejs_compat 플래그를 추가하세요.

{
  "compatibility_flags": ["nodejs_compat"],
}

그런 다음 서버 측 코드에서 node:* 가져오기 구문을 사용하세요.

export const prerender = false; // 'server' 모드에서는 필요하지 않음
import { Buffer } from 'node:buffer';

Workers 런타임에서 아직 지원되지 않는 Node.js API의 경우 Wrangler가 폴리필을 주입할 수 있습니다 (nodejs_compat 및 2024-09-23 이상의 호환성 날짜 필요).

지원되는 API 및 구성 세부 정보의 전체 목록은 Node.js 호환성에 관한 Cloudflare 문서를 참조하세요.

로컬 미리보기

astro build로 프로젝트를 빌드한 후, astro preview를 사용하여 로컬에서 Cloudflare Workers 애플리케이션을 테스트하세요. 미리보기는 Cloudflare의 workerd 런타임을 사용하여 실행되므로 프로덕션 동작과 매우 유사합니다.

의미 있는 오류 메시지

기본적으로 Wrangler에서 애플리케이션을 실행하는 동안 발생하는 오류는 축소됩니다. 더 나은 디버깅을 위해 astro.config.mjs에 vite.build.minify = false를 추가하세요.

export default defineConfig({
  adapter: cloudflare(),
  vite: {
    build: {
      minify: false,
    },
  },
});

v13 및 Astro 6로 업그레이드하기

Astro 6는 Cloudflare 개발 환경에 상당한 개선 사항을 제공하며 @astrojs/cloudflare v13 이상이 필요합니다. 이제 astro dev는 프로덕션 동작과 매우 유사하도록 Cloudflare의 Vite 플러그인과 workerd 런타임을 사용합니다.

Astro 자체 업그레이드에 대한 자세한 지침은 Astro 6 업그레이드 가이드 (EN)를 참조하세요.

이제 개발 서버가 workerd를 사용합니다

Astro 6에서 Cloudflare 사용자를 위한 가장 큰 변화는 astro dev 및 astro preview가 이제 Cloudflare Vite 플러그인을 사용하여 Node.js 대신 실제 Workers 런타임(workerd)에서 사이트를 실행한다는 것입니다. 즉, 이제 개발 환경이 동일한 런타임, API 및 동작을 갖춘 프로덕션 환경의 훨씬 더 가까운 복제본이 됩니다.

이러한 변화는 이전에는 프로덕션에서만 나타났을 문제를 개발 중에 파악하는 데 도움이 되며, Durable Objects, R2 바인딩, Workers AI와 같은 기능이 이제 Cloudflare 플랫폼에 배포했을 때와 정확히 동일하게 작동합니다.

이 변화는 대부분의 프로젝트에서 투명하게 적용됩니다. 프로젝트에 astro dev를 위한 특별한 구성이 있었거나 개발 중에 Node.js 전용 동작에 의존하고 있었다면 그에 따라 코드나 구성을 조정하세요.

새 옵션: `prerenderEnvironment`

Astro 6에서는 이제 사전 렌더링된 페이지가 개발 및 빌드 중에 기본적으로 Cloudflare의 workerd 런타임에서 실행됩니다. 이전에는 이러한 페이지가 항상 Node.js에서 실행되었습니다.

사전 렌더링된 페이지가 Node.js API(예: node:fs) 또는 workerd와 호환되지 않는 NPM 패키지에 의존하는 경우, Cloudflare 어댑터 구성에서 prerenderEnvironment: 'node'를 설정하여 사전 렌더링에 대한 이전 동작을 복원하세요.

주문형 렌더링 페이지는 이 옵션의 영향을 받지 않으며 계속해서 workerd에서 실행됩니다.

구성 세부 정보는 prerenderEnvironment를 참조하세요.

일부 의존성은 사전 컴파일이 필요할 수 있습니다

새로운 workerd 환경은 require 및 module.exports와 같은 Node.js 전용 구문을 포함하여 CommonJS 구문을 지원하지 않습니다. 즉, 일부 프로젝트 의존성이 개발 서버나 빌드 중에 오류를 발생시킬 수 있습니다.

의존성을 제어할 수 있는 경우, Vite 플러그인을 만들고 optimizeDeps.include 옵션을 사용하여 의존성을 사전 컴파일할 수 있습니다.

예를 들어, Expressive Code 구문 강조 도구를 사용하기 위해 postcss 의존성을 사전 컴파일하는 Vite 플러그인을 만들 수 있습니다.

function noExternalPlugin() {
  return {
    name: "optimize-dependencies",
    configEnvironment(environment) {
      // 서버 환경에만 관심이 있습니다
      if (environment !== 'client') {
        return {
          optimizeDeps: {
            include: [
              "postcss"
              // 또는 의존성에 직접 의존하지 않는 경우 이 구문을 사용할 수 있습니다
              // "expressive-code > postcss"
            ]
          }
        }
      }
    }
  }
}

변경됨: Wrangler 엔트리포인트 구성

이전에는 Wrangler 구성의 main 필드가 빌드된 worker 파일(예: dist/_worker.js/index.js)을 가리켰습니다. Astro 6에서는 이것이 Cloudflare 어댑터가 제공하는 새로운 통합 엔트리포인트인 @astrojs/cloudflare/entrypoints/server를 가리키도록 변경되었습니다.

새로운 엔트리포인트를 사용하도록 wrangler.jsonc를 업데이트하세요.

{
  "main": "dist/_worker.js/index.js",
  "main": "@astrojs/cloudflare/entrypoints/server",
  "name": "my-astro-app",
  // ... 나머지 구성
}

이 단일 엔트리포인트는 astro dev와 프로덕션 배포를 모두 처리합니다.

제거됨: `Astro.locals.runtime` API

Astro.locals.runtime 객체는 Cloudflare Workers API에 직접 액세스하는 방식이 도입됨에 따라 제거되었습니다. 제공된 인터페이스를 통해 환경 변수, cf 객체, 캐시 및 실행 컨텍스트에 직접 액세스하세요.

환경 변수 액세스:

이전에는 Astro.locals.runtime.env를 통해 환경 변수에 액세스했습니다. 이제 대신 env를 직접 가져오세요.

const { env } = Astro.locals.runtime;
import { env } from 'cloudflare:workers';

cf 객체 액세스:

이전에는 Astro.locals.runtime.cf를 통해 cf 객체에 액세스했습니다. 이제 요청에서 직접 액세스하세요.

const { cf } = Astro.locals.runtime;
const cf = Astro.request.cf;

캐시 API 액세스:

이전에는 Astro.locals.runtime.caches를 통해 캐시 API에 액세스했습니다. 이제 전역 caches 객체를 직접 사용하세요.

const { caches } = Astro.locals.runtime;

caches.default.put(request, response);

실행 컨텍스트 액세스:

Astro.locals.runtime.ctx 객체는 Cloudflare ExecutionContext를 포함하는 Astro.locals.cfContext로 대체되었습니다.

const ctx = Astro.locals.runtime.ctx;
const ctx = Astro.locals.cfContext;

변경됨: 이제 Wrangler 구성 파일은 선택 사항입니다

단순한 프로젝트의 경우 이제 Wrangler 구성 파일은 선택 사항입니다. Cloudflare 바인딩(KV, D1, Durable Objects 등)과 같은 사용자 지정 구성이 없는 경우 Astro가 자동으로 기본 구성을 생성합니다.

wrangler.jsonc에 다음과 같은 기본 구성만 포함되어 있는 경우:

{
  "main": "@astrojs/cloudflare/entrypoints/server",
  "compatibility_date": "2025-05-21",
  "assets": {
    "directory": "./dist",
    "binding": "ASSETS",
  },
}

이 파일을 안전하게 삭제할 수 있습니다. Astro가 이 구성을 자동으로 처리합니다. 또는 프로젝트 이름과 기타 사용자 지정 설정만 포함된 최소한의 wrangler.jsonc를 만들 수도 있습니다.

{
  "name": "my-astro-app",
}

변경됨: 사용자 지정 엔트리포인트 API

어댑터 옵션에서 사용자 지정 workerEntryPoint 구성을 사용하고 있었다면 이 옵션은 제거되었습니다. 대신 Wrangler 구성에 사용자 지정 엔트리포인트를 지정하고, createExports() 함수를 사용하는 대신 표준 Cloudflare Worker 내보내기 객체를 직접 만드세요.

어댑터 구성에서 workerEntryPoint 옵션을 제거합니다.

import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  adapter: cloudflare({
    workerEntryPoint: {
      path: 'src/worker.ts',
      namedExports: ['MyDurableObject'],
    },
  }),
});

대신 wrangler.jsonc에 엔트리포인트를 지정합니다.
wrangler.jsonc
```
{
  "main": "./src/worker.ts"
}
```

사용자 지정 worker 엔트리 파일을 업데이트하여 표준 Worker 구문을 사용합니다. @astrojs/cloudflare/handler에서 핸들러를 가져와 Durable Objects와 같은 사용자 지정 내보내기와 함께 표준 Cloudflare Worker 객체를 내보냅니다.

import { handle } from '@astrojs/cloudflare/handler';
import { DurableObject } from 'cloudflare:workers';

export class MyDurableObject extends DurableObject<Env> {
  // ...
}

export default {
  async fetch(request, env, ctx) {
    await env.MY_QUEUE.send('log');
    return handle(request, env, ctx);
  },
  async queue(batch, _env) {
    let messages = JSON.stringify(batch.messages);
    console.log(`consumed from our queue: ${messages}`);
  },
} satisfies ExportedHandler<Env>;

이제 매니페스트는 어댑터에 의해 내부적으로 생성되므로 핸들러에 전달할 필요가 없습니다.

제거됨: `cloudflareModules` 옵션

Cloudflare가 .sql, .wasm 및 기타 모듈 유형 가져오기를 네이티브로 지원하므로 cloudflareModules 어댑터 옵션은 더 이상 필요하지 않아 제거되었습니다.

Cloudflare 어댑터 구성에서 cloudflareModules 옵션을 사용하고 있었다면 제거하세요.

import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  adapter: cloudflare({
    cloudflareModules: true
  })
});

새 기능: `astro preview` 지원

배포 전 로컬에서 Cloudflare Workers 애플리케이션을 테스트하려면 astro preview를 사용하세요. 미리보기는 Cloudflare의 workerd 런타임을 사용하여 실행되므로 프로덕션 동작과 매우 유사합니다. 미리보기 서버를 시작하려면 astro build를 실행한 후 astro preview를 실행하세요.

제거됨: Cloudflare Pages 지원

Astro Cloudflare 어댑터는 더 이상 Cloudflare Pages 배포를 지원하지 않습니다. 최상의 경험과 기능 지원을 위해 Cloudflare Workers로 마이그레이션해야 합니다.

자세한 마이그레이션 지침은 Cloudflare의 Pages에서 Workers로의 마이그레이션 가이드를 참조하세요.

변경됨: `imageService` 기본값

이미지 작업 시 향상된 경험을 제공하기 위해 imageService의 기본값이 'compile'에서 'cloudflare-binding'으로 변경되었습니다.

cloudflare-binding 서비스는 Cloudflare Images 바인딩을 사용하여 런타임에 이미지를 변환하며, 바인딩은 배포 시 자동으로 프로비저닝됩니다.

이미지 변환이 빌드 시 사전 렌더링된 경로에서만 가능했던 이전 동작으로 되돌리려면 어댑터 구성에서 imageService: 'compile'을 명시적으로 설정하세요.

변경됨: Cloudflare 환경에 배포

Astro 5.x에서는 Astro 프로젝트를 한 번 빌드한 후 wrangler deploy --env some-env 명령어를 사용하여 특정 Cloudflare 환경에 배포할 수 있었습니다.

Astro 6.0부터 이 통합은 Cloudflare Vite 플러그인에 의존하며 이 동작이 변경되었습니다. 이제 환경은 빌드 단계에서 결정됩니다. 따라서 각 환경에 대해 프로젝트를 별도로 빌드해야 합니다.

특정 Cloudflare 환경에 배포하려면 명령어 앞에 CLOUDFLARE_ENV 변수를 추가하세요. 예를 들어, CLOUDFLARE_ENV=some-env astro build && wrangler deploy 명령어는 Astro 프로젝트를 빌드하고 some-env 환경을 사용하여 Wrangler로 배포합니다.

wrangler dev 마이그레이션 가이드에서 Cloudflare 환경을 업데이트하는 방법을 알아보세요.