@astrojs/ cloudflare
이 어댑터를 사용하면 Astro가 요청 시 렌더링되는 라우트를 Cloudflare에 배포할 수 있습니다.
Astro를 정적 사이트 빌더로 사용하는 경우 어댑터가 필요하지 않습니다.
Cloudflare Pages 배포 가이드에서 Astro 사이트를 배포하는 방법을 알아보세요.
왜 Astro Cloudflare인가?
섹션 제목: 왜 Astro Cloudflare인가?Cloudflare는 CDN, 웹 보안 및 기타 서비스를 제공합니다. 이 어댑터는 Astro 빌드 프로세스를 향상하여 Cloudflare를 통한 배포용 프로젝트를 준비합니다.
Astro에는 공식 통합 설정을 자동화하는 astro add
명령이 포함되어 있습니다. 원하는 경우 대신 통합을 수동으로 설치할 수 있습니다.
Astro 프로젝트에서 SSR을 활성화하려면 astro add
명령을 사용하여 Cloudflare 어댑터를 추가하세요. 그러면 @astrojs/cloudflare
가 설치되고 astro.config.mjs
파일이 한 번에 적절하게 변경됩니다.
npx astro add cloudflare
pnpm astro add cloudflare
yarn astro add cloudflare
수동 설치
섹션 제목: 수동 설치먼저, 선호하는 패키지 관리자를 사용하여 @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({ output: 'server', adapter: cloudflare(),});
imageService
섹션 제목: imageService타입: 'passthrough' | 'cloudflare' | 'compile' | 'custom'
기본값: 'compile'
어댑터에서 사용되는 이미지 서비스를 결정합니다. 호환되지 않는 이미지 서비스가 구성되면 어댑터는 기본적으로 compile
모드로 설정됩니다. 그렇지 않으면 전역적으로 구성된 이미지 서비스를 사용합니다.
cloudflare
: Cloudflare Image Resizing 서비스를 사용합니다.passthrough
: 기존noop
서비스를 사용합니다.compile
: Astro의 기본 서비스 (sharp)를 사용하지만 빌드 시 사전 렌더링된 경로에서만 사용됩니다. 주문형 렌더링 페이지에 대한 SSR 중에는 모든astro:assets
기능이 비활성화됩니다.custom
: 항상 이미지 옵션에 구성된 이미지 서비스를 사용합니다. 이 옵션은 구성된 이미지 서비스가 Cloudflare의workerd
런타임에서 작동하는지 확인하지 않습니다.
import {defineConfig} from "astro/config";import cloudflare from '@astrojs/cloudflare';
export default defineConfig({ adapter: cloudflare({ imageService: 'cloudflare' }), output: 'server'})
platformProxy
섹션 제목: platformProxyCloudflare 런타임이 astro dev
에 추가되는지 여부와 방법을 결정합니다. 여기에는 로컬 workerd
바인딩에 대한 프록시와 Cloudflare 특정 값의 에뮬레이션이 포함되어 있어 Node.js 개발 프로세스에서 런타임을 에뮬레이션할 수 있습니다. Cloudflare 런타임에 대해 자세히 알아보세요.
제공되는 프록시는 최선을 다해 실제 프로덕션을 에뮬레이션한 것입니다. 최대한 실제와 비슷하게 설계되었으나 약간의 차이와 불일치가 있을 수 있습니다.
platformProxy.enabled
섹션 제목: platformProxy.enabled타입: { enabled?: boolean }
기본값: { enabled: false }
enabled
속성을 사용하면 astro dev
에서 Cloudflare 런타임을 활성화할 수 있습니다.
platformProxy.configPath
섹션 제목: platformProxy.configPath타입: { configPath?: string }
기본값: { configPath: 'wrangler.toml' }
configPath
를 사용하면 Astro 프로젝트의 루트를 기준으로 Wrangler 구성 파일을 정의할 수 있습니다.
platformProxy.experimentalJsonConfig
섹션 제목: platformProxy.experimentalJsonConfig타입: { experimentalJsonConfig?: boolean }
기본값: { experimentalJsonConfig?: false }
experimentalJsonConfig
속성은 유틸리티가 JSON 구성 파일 (예: wrangler.json
)을 읽는지 여부를 정의합니다.
platformProxy.persist
섹션 제목: platformProxy.persist타입: { persist?: boolean | { path: string } }
기본값: { persist: true }
persist
속성은 바인딩 데이터가 지속되는지 여부와 위치를 정의합니다. true
는 Wrangler에서 사용하는 것과 동일한 위치를 기본값으로 지정하므로 둘 간에 데이터를 공유할 수 있습니다. false
인 경우 데이터가 파일 시스템에 저장되지 않고, 파일 시스템에서 읽을 수 없게 됩니다.
wrangler
의 --persist-to
옵션은 내부적으로 v3
라는 하위 디렉터리를 추가하지만 @astrojs/cloudflare
persist
속성은 그렇지 않습니다. 예를 들어 wrangler dev --persist-to ./my-directory
를 실행하는 것과 동일한 위치를 재사용하려면 persist: { path: "./my-directory/v3" }
을 지정해야 합니다.
다음 구성은 개발 서버를 실행할 때 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.extend
섹션 제목: routes.extend이 옵션을 사용하면 요청 시 생성되는 경로를 결정하기 위해 생성된 _routes.json
파일에 사용자 지정 패턴 (예: /fonts/*
)을 추가하거나 제외할 수 있습니다. 이는 자동으로 생성할 수 없는 경로 패턴을 추가해야 하거나 사전 렌더링된 경로를 제외해야 하는 경우 유용할 수 있습니다.
사용자 지정 경로 패턴에 대한 자세한 내용은 Cloudflare의 라우팅 문서에서 확인할 수 있습니다. 지정된 경로는 자동으로 중복 제거되지 않으며 기존 경로에 그대로 추가됩니다.
routes.extend.include
섹션 제목: routes.extend.include타입: { pattern: string }[]
기본값: undefined
Cloudflare 어댑터가 요청 시 생성할 추가 경로를 routes.extend.include
배열에 구성합니다.
routes.extend.exclude
섹션 제목: routes.extend.exclude타입: { pattern: string }[]
기본값: undefined
주문형 렌더링에서 제외할 경로를 routes.extend.exclude
배열에 구성합니다. 대신 이러한 경로는 사전 렌더링되어 정적으로 제공되며 SSR 함수를 호출하지 않습니다. 또한 이 옵션을 사용하면 SSR 함수를 통해 요청을 라우팅하지 않고도 정적 자산 (예: 이미지, 글꼴, CSS, js, html, txt, json 등) 파일을 직접 제공할 수 있습니다.
export default defineConfig({ adapter: cloudflare({ routes: { extend: { include: [{ pattern: '/static' }], // 주문형 렌더링을 위해 사전 렌더링된 페이지를 SSR 함수로 라우팅합니다. exclude: [{ pattern: '/pagefind/*' }], // 빌드 시 정적으로 생성되는 Starlight의 pagefind 검색을 사용합니다. } }, }),});
cloudflareModules
섹션 제목: cloudflareModules타입: true | false
기본값: true
.wasm
, .bin
, .txt
모듈 가져오기를 활성화합니다.
이 기능은 기본적으로 활성화되어 있습니다. 비활성화하려면 cloudflareModules: false
를 설정하세요.
Cloudflare 런타임
섹션 제목: Cloudflare 런타임Cloudflare 런타임은 환경 변수와 Cloudflare 바인딩에 대한 액세스를 제공합니다. Cloudflare 런타임은 wrangler
및 .dev.vars
구성 파일에 있는 바인딩을 사용합니다.
예를 들어, wrangler.toml
파일에 환경 변수 구성이 설정된 경우:
[vars]MY_VARIABLE = "test"
환경 변수 외에 secrets
도 정의해야 하는 경우 Astro 프로젝트의 루트에 .dev.vars
파일을 추가해야 합니다.
DB_PASSWORD=myPassword
다음과 같이 Astro 로컬을 사용하여 바인딩에 액세스할 수 있습니다.
---const { env } = Astro.locals.runtime;---
context.locals
를 통해 API 엔드포인트에서 런타임에 액세스할 수 있습니다.
export function GET(context) { const runtime = context.locals.runtime;
return new Response('Some body');}
MY_VARIABLE
바인딩의 값에 액세스하려면 코드에 다음을 추가하세요.
---const { env } = Astro.locals.runtime;const myVariable = env.MY_VARIABLE;---
Cloudflare 문서에서 지원되는 모든 바인딩 목록을 참조하세요.
타입 설정
섹션 제목: 타입 설정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 플랫폼
섹션 제목: Cloudflare 플랫폼Headers
섹션 제목: HeadersAstro 프로젝트의 public/
폴더에 _headers
파일을 추가하여 사용자 정의 헤더를 응답에 첨부할 수 있습니다. 이 파일은 빌드 출력 디렉터리에 복사됩니다.
Assets
섹션 제목: AssetsAstro가 빌드한 자산은 모두 해시로 이름이 지정되므로 긴 캐시 헤더가 제공될 수 있습니다. 기본적으로 Cloudflare의 Astro는 이러한 파일에 대한 헤더를 추가합니다.
Redirects
섹션 제목: RedirectsCloudflare Pages를 사용하여 사용자 지정 리디렉션을 선언할 수 있습니다. 이를 통해 요청을 다른 URL로 리디렉션할 수 있습니다. Astro 프로젝트의 public/
폴더에 _redirects
파일을 추가할 수 있습니다. 이 파일은 빌드 출력 디렉터리에 복사됩니다.
Routes
섹션 제목: RoutesCloudflare 라우팅은 _routes.json
파일을 사용하여 어떤 요청이 SSR 함수로 라우팅되는지, 어떤 요청이 정적 자산으로 제공되는지 결정합니다. 기본적으로 _routes.json
파일은 프로젝트의 파일 및 구성을 기반으로 자동으로 생성됩니다.
어댑터 구성에서 추가 라우팅 패턴을 지정하거나 사용자 정의 _routes.json
파일을 생성하여 자동 생성을 완전히 재정의할 수 있습니다.
사용자 정의 _routes.json
섹션 제목: 사용자 정의 _routes.json사용자 정의 public/_routes.json
파일을 생성하면 자동 생성이 재정의됩니다. 자세한 내용은 사용자 지정 _routes.json
생성에 대한 Cloudflare 문서를 참조하세요.
Cloudflare 모듈 가져오기
섹션 제목: Cloudflare 모듈 가져오기Cloudflare worker 런타임은 일부 비표준 모듈 타입 가져오기를 지원합니다. 대부분의 추가 파일 타입은 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 호환성
섹션 제목: 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({}), output: 'server', vite: { ssr: { external: ['node:buffer'], }, },})
또한 활성화를 지원하는 방법에 대한 Cloudflare 문서를 따라야 합니다. 자세한 지침은 Node.js 호환성 활성화에 대한 Cloudflare 문서를 참조하세요.
프로젝트가 Node.js 런타임 API를 사용하는 서버로 패키지를 가져오는 경우, Cloudflare에 배포할 때 문제가 발생할 수 있습니다. 이 문제는 node:*
import 구문을 사용하지 않는 패키지에서 발생합니다. 패키지가 위 import 구문을 지원하는지 확인하기 위해 패키지 작성자에게 문의하는 것이 좋습니다. 패키지가 이를 지원하지 않으면 다른 패키지를 사용해야 할 수도 있습니다.
Wrangler로 미리보기
섹션 제목: Wrangler로 미리보기wrangler
를 사용하여 애플리케이션을 로컬에서 실행하려면 미리 보기 스크립트를 업데이트하세요.
"preview": "wrangler pages dev ./dist"
wrangler
를 사용하면 Cloudflare 바인딩, 환경 변수, cf 객체에 액세스할 수 있습니다. Wrangler와 함께 작동하도록 핫 리로드 또는 astro dev 서버를 사용하려면 사용자 정의 설정이 필요할 수 있습니다. 커뮤니티 예시를 참조하세요.
의미 있는 오류 메시지
섹션 제목: 의미 있는 오류 메시지현재 Wrangler에서 애플리케이션을 실행하는 동안 발생하는 오류는 코드 축소로 인해 그다지 유용하지 않습니다. 더 나은 디버깅을 위해 astro.config.mjs
파일에 vite.build.minify = false
설정을 추가할 수 있습니다.
export default defineConfig({ adapter: cloudflare(), output: 'server', vite: { build: { minify: false, }, },});