@astrojs/ cloudflare

이 어댑터를 사용하면 Astro가 hybrid 또는 server 렌더링된 사이트를 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 파일이 한 번에 적절하게 변경됩니다.

npm

npx astro add cloudflare

pnpm

pnpm astro add cloudflare

Yarn

yarn astro add cloudflare

수동 설치

섹션 제목: 수동 설치

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

npm

npm install @astrojs/cloudflare

pnpm

pnpm add @astrojs/cloudflare

Yarn

yarn add @astrojs/cloudflare

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

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'
기본값: 'passthrough'

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

• 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'
})

platformProxy

섹션 제목: platformProxy

Cloudflare 런타임이 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: "./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: './.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 등) 파일을 직접 제공할 수 있습니다.

astro.config.mjs

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

wasmModuleImports

섹션 제목: wasmModuleImports

타입: true | false
기본값: false

.wasm?module import 구문을 사용하여 .wasm 파일을 ES 모듈로 직접 가져올지 여부입니다.

astro build 및 astro dev 모두에서 이 기능을 활성화하려면 astro.config.mjs 파일에 wasmModuleImports: true를 추가하세요. Wasm 모듈 사용에 대해 자세히 알아보세요.

astro.config.mjs

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

export default defineConfig({
  adapter: cloudflare({
     wasmModuleImports: true
  }),
  output: 'server'
})

Cloudflare 런타임

섹션 제목: Cloudflare 런타임

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를 실행해야 합니다.

노트

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

package.json

{
  "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 객체의 타입을 설정할 수 있습니다.

src/env.d.ts

/// <reference types="astro/client" />

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

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

Cloudflare 플랫폼

섹션 제목: Cloudflare 플랫폼

Headers

섹션 제목: Headers

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

Assets

섹션 제목: Assets

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

Redirects

섹션 제목: Redirects

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

Routes

섹션 제목: Routes

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

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

사용자 정의 _routes.json

섹션 제목: 사용자 정의 _routes.json

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

Wasm 모듈 사용

섹션 제목: Wasm 모듈 사용

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

pages/add/[a]/[b].js

import mod from '../util/add.wasm?module';

// 모듈을 공유하기 위해 미리 인스턴스화
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:*' 가져오기 구문을 사용해야 합니다.

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'],
    },
  },
})

Additionally, you’ll need to follow Cloudflare’s documentation on how to enable support. For detailed guidance, please refer to the Cloudflare documentation on enabling Node.js compatibility.

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

패키지 호환성에 미치는 영향

프로젝트가 Node.js 런타임 API를 사용하는 서버로 패키지를 가져오는 경우, Cloudflare에 배포할 때 문제가 발생할 수 있습니다. 이 문제는 node:* import 구문을 사용하지 않는 패키지에서 발생합니다. 패키지가 위 import 구문을 지원하는지 확인하기 위해 패키지 작성자에게 문의하는 것이 좋습니다. 패키지가 이를 지원하지 않으면 다른 패키지를 사용해야 할 수도 있습니다.

Wrangler로 미리보기

섹션 제목: Wrangler로 미리보기

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 프레임워크

• 

  @astrojs/alpinejs

• 

  @astrojs/lit

• 

  @astrojs/preact

• 

  @astrojs/react

• 

  @astrojs/solid⁠-⁠js

• 

  @astrojs/svelte

• 

  @astrojs/vue

SSR 어댑터

• 

  @astrojs/cloudflare

• 

  @astrojs/netlify

• 

  @astrojs/node

• 

  @astrojs/vercel

기타 통합

• 

  @astrojs/db

• 

  @astrojs/markdoc

• 

  @astrojs/mdx

• 

  @astrojs/partytown

• 

  @astrojs/sitemap

• 

  @astrojs/tailwind