@astrojs/ cloudflare

이 어댑터를 사용하면 Astro가 서버 아일랜드, 액션, 세션을 포함하여 요청 시 렌더링되는 라우트 및 기능을 Cloudflare에 배포할 수 있습니다.

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

Cloudflare 배포 가이드에서 Astro 사이트를 배포하는 방법을 알아보세요.

왜 Astro Cloudflare인가?

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

설치

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

Astro 프로젝트의 서버 렌더링을 활성화하려면 astro add 명령을 사용하여 Cloudflare 어댑터를 추가하세요. 그러면 @astrojs/cloudflare가 설치되고 astro.config.mjs 파일이 한 번에 적절하게 변경됩니다.

npx astro add cloudflare

pnpm astro add cloudflare

yarn astro add cloudflare

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

수동 설치

먼저, 선호하는 패키지 관리자를 사용하여 @astrojs/cloudflare 어댑터를 프로젝트 종속성에 추가하세요.

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(),
});

옵션

Cloudflare 어댑터는 다음 옵션을 허용합니다.

`cloudflareModules`

타입: boolean
기본값: true

.wasm, .bin, .txt 모듈의 가져오기를 활성화합니다.

이 기능은 기본적으로 활성화되어 있습니다. 비활성화하려면 cloudflareModules를 false로 설정하세요.

`imageService`

타입: 'passthrough' | 'cloudflare' | 'compile' | 'custom'
기본값: 'compile'

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

cloudflare: Cloudflare Image Resizing 서비스를 사용합니다.
passthrough: 기존 noop 서비스를 사용합니다.
compile: Astro의 기본 서비스 (sharp)를 사용하지만 빌드 시 사전 렌더링된 경로에서만 사용됩니다. 요청 시 렌더링되는 페이지의 경우 모든 astro:assets 기능이 비활성화됩니다.
custom: 항상 이미지 옵션에 구성된 이미지 서비스를 사용합니다. 이 옵션은 구성된 이미지 서비스가 Cloudflare의 workerd 런타임에서 작동하는지 확인하지 않습니다.

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

export default defineConfig({
  adapter: cloudflare({
     imageService: 'cloudflare'
  }),
})

`platformProxy`

Cloudflare 런타임이 astro dev에 추가되는지 여부와 방법을 결정합니다. 여기에는 로컬 workerd 바인딩에 대한 프록시와 Cloudflare 특정 값의 에뮬레이션이 포함되어 있어 Node.js 개발 프로세스에서 런타임을 에뮬레이션할 수 있습니다. Cloudflare 런타임에 대해 자세히 알아보세요.

`platformProxy.enabled`

타입: boolean
기본값: true

개발 모드에서 Cloudflare 런타임을 활성화할지 여부를 결정합니다.

`platformProxy.configPath`

타입: string
기본값: undefined

Wrangler 구성 파일의 경로를 정의합니다. 값을 설정하지 않으면 프로젝트 루트에 존재하는 wrangler.toml, wrangler.json 및 wrangler.jsonc를 추적합니다.

`platformProxy.environment`

타입: string
기본값: undefined

사용할 Cloudflare 환경을 설정합니다. Wrangler 구성 파일에 정의된 환경을 선택해야 하며, 그렇지 않으면 오류가 발생합니다.

`platformProxy.persist`

타입: boolean | { path: string }
기본값: true

바인딩 데이터를 파일 시스템에 로컬로 저장할지 여부와 저장 위치를 설정합니다.

true로 설정하면 바인딩 데이터는 .wrangler/state/v3/에 저장됩니다. 이는 wrangler의 기본 설정과 동일합니다.
false로 설정하면 바인딩 데이터가 파일 시스템에 저장되지 않습니다.
{ path: string }으로 설정하면 바인딩 데이터가 지정된 경로에 저장됩니다.

다음 구성은 개발 서버를 실행할 때 Cloudflare 런타임을 활성화하고 wrangler.json 구성 파일을 사용하는 예시를 보여줍니다. 또한 파일 시스템에 데이터를 유지하기 위한 사용자 정의 위치를 지정합니다.

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

export default defineConfig({
  adapter: cloudflare({
    platformProxy: {
      enabled: true,
      configPath: 'wrangler.json',
      persist: {
        path: './.cache/wrangler/v3'
      },
    },
  }),
});

`routes.extend`

Cloudflare Workers에서는 이 옵션을 사용할 수 없습니다. 자세한 내용은 Cloudflare Workers에서의 라우팅을 참조하세요.

Cloudflare Pages에서 이 옵션을 사용하면 요청 시 생성되는 경로를 결정하기 위해 생성된 _routes.json 파일에 사용자 지정 패턴 (예: /fonts/*)을 추가하거나 제외할 수 있습니다. 이는 자동으로 생성할 수 없는 경로 패턴을 추가해야 하거나 사전 렌더링된 경로를 제외해야 하는 경우 유용할 수 있습니다.

사용자 지정 경로 패턴에 대한 자세한 내용은 Cloudflare의 라우팅 문서에서 확인할 수 있습니다. 지정된 경로는 자동으로 중복 제거되지 않으며 기존 경로에 그대로 추가됩니다.

`routes.extend.include`

타입: { pattern: string }[]
기본값: undefined

Cloudflare 어댑터가 요청 시 생성할 추가 경로를 routes.extend.include 배열에 구성합니다.

routes.extend.exclude

타입: { pattern: string }[]
기본값: undefined

주문형 렌더링에서 제외할 경로를 routes.extend.exclude 배열에 구성합니다. 대신 이러한 경로는 사전 렌더링되어 정적으로 제공되며 서버 함수를 호출하지 않습니다. 또한 이 옵션을 사용하면 서버 함수를 통해 요청을 라우팅하지 않고도 정적 자산 (예: 이미지, 글꼴, CSS, js, html, txt, json 등) 파일을 직접 제공할 수 있습니다.

export default defineConfig({
  adapter: cloudflare({
    routes: {
      extend: {
        include: [{ pattern: '/static' }], // 주문형 렌더링을 위해 사전 렌더링된 페이지를 서버 함수로 라우팅합니다.
        exclude: [{ pattern: '/pagefind/*' }], // 빌드 시 정적으로 생성되는 Starlight의 pagefind 검색을 사용합니다.
      }
    },
  }),
});

`sessionKVBindingName`

타입: string
기본값: SESSION

추가된 버전: astro@5.6.0

sessionKVBindingName 옵션을 사용하면 세션 스토리지에 사용되는 KV 바인딩의 이름을 지정할 수 있습니다. 기본적으로 SESSION으로 설정되어 있지만, 사용자 정의 KV 바인딩 이름과 일치하도록 변경할 수 있습니다. 자세한 내용은 세션을 참조하세요.

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

Cloudflare 런타임

사용

Cloudflare 런타임은 환경 변수와 Cloudflare 리소스에 대한 바인딩 접근 권한을 제공합니다. Cloudflare 런타임은 wrangler.toml/wrangler.json 구성 파일에 있는 바인딩을 사용합니다.

Astro.locals.runtime에서 바인딩에 접근할 수 있습니다.

---
const { env } = Astro.locals.runtime;
---

context.locals를 통해 API 엔드포인트에서 런타임에 액세스할 수 있습니다.

export function GET(context) {
  const runtime = context.locals.runtime;

  return new Response('Some body');
}

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

환경 변수 및 비밀

Cloudflare 런타임은 환경 변수를 일종의 바인딩으로 취급합니다.

예를 들어, wrangler.json에서 다음과 같이 환경 변수를 정의할 수 있습니다.

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

비밀은 암호화된 텍스트 값을 Worker에 연결할 수 있도록 하는 특별한 유형의 환경 변수입니다. 설정 후에는 보이지 않도록 다르게 정의해야 합니다.

secrets를 정의하려면 Wrangler 구성 파일이 아닌 Wrangler CLI를 통해 추가하세요.

npx wrangler secret put <KEY>

로컬 개발 환경에서 비밀을 설정하려면 Astro 프로젝트의 루트에 .dev.vars 파일도 추가해야 합니다.

DB_PASSWORD=myPassword

그러면 Astro.locals.runtime에서 사용할 수 있는 env 객체를 통해 비밀을 포함한 환경 변수에 접근할 수 있습니다.

---
const { env } = Astro.locals.runtime;
const myVariable = env.MY_VARIABLE;
const secret = env.DB_PASSWORD;
---

Cloudflare 환경 변수와 비밀은 astro:env API와 호환됩니다.

타입 설정

wrangler는 바인딩을 위한 TypeScript 타입을 생성하는 types 명령을 제공합니다. 이를 통해 수동으로 타입을 설정하지 않고도 locals의 타입을 설정할 수 있습니다. 자세한 내용은 Cloudflare 문서를 참조하세요.

구성 파일 (예: wrangler.toml, .dev.vars)을 변경할 때마다 wrangler types를 실행해야 합니다.

자동으로 다른 명령보다 먼저 wrangler types를 실행하는 pnpm 스크립트를 만들 수 있습니다.

{
  "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"
  }
}

Runtime을 사용하여 runtime 객체의 타입을 설정할 수 있습니다.

type Runtime = import('@astrojs/cloudflare').Runtime<Env>;

declare namespace App {
  interface Locals extends Runtime {
    otherLocals: {
      test: string;
    };
  }
}

Cloudflare 플랫폼

Headers

Astro 프로젝트의 public/ 폴더에 _headers 파일을 추가하여 사용자 정의 헤더를 응답에 첨부할 수 있습니다. 이 파일은 빌드 출력 디렉터리에 복사됩니다.

이 기능은 Cloudflare Workers와 Pages에서 사용할 수 있습니다.

Assets

Astro가 빌드한 자산은 모두 해시로 이름이 지정되므로 긴 캐시 헤더가 제공될 수 있습니다. 기본적으로 Cloudflare의 Astro는 이러한 파일에 대한 헤더를 추가합니다.

Redirects

요청을 다른 URL로 리디렉션하기 위해 사용자 정의 리디렉션을 선언할 수 있습니다. 이렇게 하려면 Astro 프로젝트의 public/ 폴더에 _redirects 파일을 추가하세요. 이 파일은 빌드 출력 디렉터리로 복사됩니다.

이 기능은 Cloudflare Workers와 Pages에서 사용할 수 있습니다.

Routes

Cloudflare Workers의 라우팅

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

Cloudflare Pages와 달리 Workers에서는 _routes.json 파일이 필요하지 않습니다.

현재 Cloudflare 어댑터는 항상 이 파일을 생성합니다. 이 문제를 해결하려면 public/ 폴더에 .assetsignore 파일을 만들고 다음 줄을 추가하세요.

_worker.js
_routes.json

Cloudflare Pages의 라우팅

Cloudflare Pages의 라우팅은 _routes.json 파일을 사용하여 어떤 요청이 서버 함수로 라우팅되고 어떤 요청이 정적 자산으로 제공되는지 결정합니다. 기본적으로 _routes.json 파일은 프로젝트의 파일 및 구성을 기반으로 자동으로 생성됩니다.

어댑터 구성에서 따라야 하는 추가 라우팅 패턴을 지정하거나, 사용자 정의 _routes.json 파일을 만들어 자동 생성을 완전히 덮어쓸 수 있습니다.

사용자 정의 public/_routes.json파일을 생성하면 자동 생성이 재정의됩니다. 자세한 내용은 사용자 지정 _routes.json 생성에 대한 Cloudflare 문서를 참조하세요.

세션

Astro 세션 API를 사용하면 요청 간에 사용자 데이터를 쉽게 저장할 수 있습니다. 이는 사용자 데이터 및 환경 설정, 쇼핑 카트, 인증 자격 증명과 같은 용도로 활용될 수 있습니다. 쿠키 저장소와는 달리 데이터 크기에 제한이 없으며, 다른 기기에서도 복원할 수 있습니다.

Cloudflare 어댑터를 사용하는 경우 Astro는 세션 스토리지를 위해 Workers KV를 자동으로 구성합니다. 세션을 사용하기 전에 데이터를 저장할 KV 네임스페이스를 생성하고 Wrangler 구성 파일에 KV 바인딩을 설정해야 합니다. 기본적으로 Astro는 KV 바인딩 이름이 SESSION일 것으로 예상하지만, 어댑터 구성에서 sessionKVBindingName 옵션을 설정하여 원하는 다른 이름을 선택할 수 있습니다.

Wrangler CLI를 사용하여 KV 네임스페이스를 생성하고 새 네임스페이스의 ID를 기록해 두세요.
터미널 창
```
npx wrangler kv namespace create "SESSION"
```
Wrangler 구성에서 KV 네임스페이스를 선언하고, 네임스페이스 ID를 이전 명령에서 반환된 ID로 설정합니다.
- wrangler.json
- wrangler.toml
wrangler.json
{ "kv_namespaces": [ { "binding": "SESSION", "id": "<KV_NAMESPACE_ID>" } ] }
wrangler.toml
kv_namespaces = [ { binding = "SESSION", id = "<KV_NAMESPACE_ID>" } ]

그러면 서버 코드에서 세션을 사용할 수 있습니다.

---
export const prerender = false;
const cart = await Astro.session?.get('cart');
---

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

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는 Node.js 런타임 API를 지원하지 않습니다. 일부 구성에서는 Cloudflare가 Node.js 런타임 API의 하위 집합을 지원합니다. Cloudflare의 문서에서 지원되는 Node.js 런타임 API를 찾을 수 있습니다.

이러한 API를 사용하려면 페이지 또는 엔드포인트가 서버 측에서 렌더링되어야 하며 (사전 렌더링되지 않음) import {} from 'node:*' 가져오기 구문을 사용해야 합니다.

export const prerender = false;
import { Buffer } from 'node:buffer';

또한 node:* import 구문을 허용하려면 Astro 구성에서 vite 구성을 수정해야 합니다.

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

export default defineConfig({
  adapter: cloudflare({}),
  vite: {
    ssr: {
      external: ['node:buffer'],
    },
  },
})

또한 활성화를 지원하는 방법에 대한 Cloudflare 문서를 따라야 합니다. 자세한 지침은 Node.js 호환성 활성화에 대한 Cloudflare 문서를 참조하세요.

Wrangler로 미리보기

wrangler를 사용하여 애플리케이션을 로컬에서 실행하려면 미리보기 스크립트를 업데이트하세요.

Workers를 사용하는 경우:

"preview": "wrangler dev ./dist"

Pages를 사용하는 경우:

"preview": "wrangler pages dev ./dist"

wrangler를 사용하여 개발하면 Cloudflare 바인딩, 환경 변수, cf 객체에 액세스할 수 있습니다. Wrangler와 함께 작동하도록 핫 리로드 또는 Astro 개발 서버를 사용하려면 사용자 정의 설정이 필요할 수 있습니다. 커뮤니티 예시를 참조하세요.

의미 있는 오류 메시지

현재 Wrangler에서 애플리케이션을 실행하는 동안 발생하는 오류는 코드 축소로 인해 그다지 유용하지 않습니다. 더 나은 디버깅을 위해 astro.config.mjs 파일에 vite.build.minify = false 설정을 추가할 수 있습니다.

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

@astrojs/ cloudflare

왜 Astro Cloudflare인가?

설치

수동 설치

옵션

cloudflareModules

imageService

platformProxy

platformProxy.enabled

platformProxy.configPath

platformProxy.environment

platformProxy.persist

routes.extend

routes.extend.include