컨텐츠로 건너뛰기

@astrojs/ cloudflare

이 어댑터를 사용하면 Astro가 요청 시 렌더링되는 라우트Cloudflare에 배포할 수 있습니다.

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

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

Cloudflare는 CDN, 웹 보안 및 기타 서비스를 제공합니다. 이 어댑터는 Astro 빌드 프로세스를 향상하여 Cloudflare를 통한 배포용 프로젝트를 준비합니다.

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

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

터미널 창
npx astro add cloudflare

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

터미널 창
npm install @astrojs/cloudflare

그런 다음 어댑터와 원하는 요청 시 렌더링 모드astro.config.mjs 파일에 추가하세요.

astro.config.mjs
import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';
export default defineConfig({
output: 'server',
adapter: cloudflare(),
});

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

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

  • cloudflare: Cloudflare Image Resizing 서비스를 사용합니다.
  • passthrough: 기존 noop 서비스를 사용합니다.
  • compile: Astro의 기본 서비스 (sharp)를 사용하지만 빌드 시 사전 렌더링된 경로에서만 사용됩니다. 주문형 렌더링 페이지에 대한 SSR 중에는 모든 astro:assets 기능이 비활성화됩니다.
  • custom: 항상 이미지 옵션에 구성된 이미지 서비스를 사용합니다. 이 옵션은 구성된 이미지 서비스가 Cloudflare의 workerd 런타임에서 작동하는지 확인하지 않습니다.
astro.config.mjs
import {defineConfig} from "astro/config";
import cloudflare from '@astrojs/cloudflare';
export default defineConfig({
adapter: cloudflare({
imageService: 'cloudflare'
}),
output: 'server'
})

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

타입: { enabled?: boolean }
기본값: { enabled: false }

enabled 속성을 사용하면 astro dev에서 Cloudflare 런타임을 활성화할 수 있습니다.

타입: { configPath?: string }
기본값: { configPath: 'wrangler.toml' }

configPath를 사용하면 Astro 프로젝트의 루트를 기준으로 Wrangler 구성 파일을 정의할 수 있습니다.

platformProxy.experimentalJsonConfig

섹션 제목: platformProxy.experimentalJsonConfig

타입: { experimentalJsonConfig?: boolean }
기본값: { experimentalJsonConfig?: false }

experimentalJsonConfig 속성은 유틸리티가 JSON 구성 파일 (예: wrangler.json)을 읽는지 여부를 정의합니다.

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

persist 속성은 바인딩 데이터가 지속되는지 여부와 위치를 정의합니다. true는 Wrangler에서 사용하는 것과 동일한 위치를 기본값으로 지정하므로 둘 간에 데이터를 공유할 수 있습니다. false인 경우 데이터가 파일 시스템에 저장되지 않고, 파일 시스템에서 읽을 수 없게 됩니다.

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

import cloudflare from '@astrojs/cloudflare';
import { defineConfig } from 'astro/config';
export default defineConfig({
adapter: cloudflare({
platformProxy: {
enabled: true,
configPath: 'wrangler.json',
experimentalJsonConfig: true,
persist: {
path: './.cache/wrangler/v3'
},
},
}),
});

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

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

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

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

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

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

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

타입: true | false
기본값: true

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

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

Cloudflare 런타임은 환경 변수와 Cloudflare 바인딩에 대한 액세스를 제공합니다. Cloudflare 런타임은 wrangler.dev.vars 구성 파일에 있는 바인딩을 사용합니다.

예를 들어, wrangler.toml 파일에 환경 변수 구성이 설정된 경우:

wrangler.toml
[vars]
MY_VARIABLE = "test"

환경 변수 외에 secrets도 정의해야 하는 경우 Astro 프로젝트의 루트에 .dev.vars 파일을 추가해야 합니다.

.dev.vars
DB_PASSWORD=myPassword

다음과 같이 Astro 로컬을 사용하여 바인딩에 액세스할 수 있습니다.

src/pages/index.astro
---
const { env } = Astro.locals.runtime;
---

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

src/pages/api/someFile.js
export function GET(context) {
const runtime = context.locals.runtime;
return new Response('Some body');
}

MY_VARIABLE 바인딩의 값에 액세스하려면 코드에 다음을 추가하세요.

src/pages/index.astro
---
const { env } = Astro.locals.runtime;
const myVariable = env.MY_VARIABLE;
---

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

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

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

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

src/env.d.ts
type Runtime = import('@astrojs/cloudflare').Runtime<Env>;
declare namespace App {
interface Locals extends Runtime {
otherLocals: {
test: string;
};
}
}

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

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

Cloudflare Pages를 사용하여 사용자 지정 리디렉션을 선언할 수 있습니다. 이를 통해 요청을 다른 URL로 리디렉션할 수 있습니다. Astro 프로젝트의 public/ 폴더에 _redirects 파일을 추가할 수 있습니다. 이 파일은 빌드 출력 디렉터리에 복사됩니다.

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

어댑터 구성에서 추가 라우팅 패턴을 지정하거나 사용자 정의 _routes.json 파일을 생성하여 자동 생성을 완전히 재정의할 수 있습니다.

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

Cloudflare 모듈 가져오기

섹션 제목: Cloudflare 모듈 가져오기

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

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

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

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

pages/add/[a]/[b].js
// 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를 포함하지 않는 계산 집약적인 작업을 가속화할 수 있습니다.

기본적으로 Cloudflare는 Node.js 런타임 API를 지원하지 않습니다. 일부 구성에서는 Cloudflare가 Node.js 런타임 API의 하위 집합을 지원합니다. Cloudflare의 문서에서 지원되는 Node.js 런타임 API를 찾을 수 있습니다.

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

pages/api/endpoint.js
export const prerender = false;
import { Buffer } from 'node:buffer';

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

astro.config.mjs
import {defineConfig} from "astro/config";
import cloudflare from '@astrojs/cloudflare';
export default defineConfig({
adapter: cloudflare({}),
output: 'server',
vite: {
ssr: {
external: ['node:buffer'],
},
},
})

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

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

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

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

의미 있는 오류 메시지

섹션 제목: 의미 있는 오류 메시지

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

astro.config.mjs
export default defineConfig({
adapter: cloudflare(),
output: 'server',
vite: {
build: {
minify: false,
},
},
});

더 많은 통합

UI 프레임워크

SSR 어댑터

기타 통합

기여하기 커뮤니티 후원하기