Astro 사이트를 Cloudflare에 배포하세요

프런트엔드 정적 자산과 백엔드 API를 포함한 풀스택 애플리케이션뿐만 아니라 SSR 사이트까지 Cloudflare Workers와 Cloudflare Pages 모두에 배포할 수 있습니다.

이 가이드에는 다음이 포함됩니다.

Cloudflare Workers에 배포하는 방법
Cloudflare Pages에 배포하는 방법

Astro 프로젝트에서 Cloudflare 런타임을 사용하는 방법에 대해 더 자세히 알아보세요.

전제 조건

시작하려면 다음이 필요합니다.

Cloudflare 계정. 아직 계정이 없다면 프로세스 중에 무료 Cloudflare 계정을 만들 수 있습니다.

Cloudflare Workers

Wrangler를 사용하여 배포하는 방법

Wrangler CLI를 설치합니다.
터미널 창
```
npm install wrangler@latest --save-dev
```
사이트에서 요청 시 렌더링을 사용하는 경우, @astrojs/cloudflare 어댑터를 설치합니다.

이 명령어는 어댑터를 설치하고 astro.config.mjs 파일에 필요한 변경 사항을 한 번에 적용합니다.
터미널 창
```
npx astro add cloudflare
```
그런 다음 public/ 폴더에 .assetsignore 파일을 만들고 다음 줄을 추가하세요.
public/.assetsignore
```
_worker.js
_routes.json
```
Astro의 요청 시 렌더링 (SSR이라고도 함)에 대해 더 자세히 알아보세요.
Wrangler 구성 파일을 생성합니다.
- Static
- SSR
wrangler.jsonc
{ "$schema": "node_modules/wrangler/config-schema.json", "name": "my-astro-app", // 오늘 날짜로 업데이트합니다. "compatibility_date": "2025-03-25", "assets": { "directory": "./dist" } }
wrangler.jsonc
{ "$schema": "node_modules/wrangler/config-schema.json", "name": "my-astro-app", "main": "./dist/_worker.js/index.js", // 오늘 날짜로 업데이트합니다. "compatibility_date": "2025-03-25", "compatibility_flags": ["nodejs_compat"], "assets": { "binding": "ASSETS", "directory": "./dist" }, "observability": { "enabled": true } }
Wrangler를 사용하여 프로젝트를 로컬에서 미리 봅니다.
터미널 창
```
npx astro build && npx wrangler dev
```
npx wrangler deploy를 사용하여 배포합니다.
터미널 창
```
npx astro build && npx wrangler deploy
```

자산이 업로드되면 Wrangler는 사이트를 검사할 수 있는 미리보기 URL을 제공합니다.

바인딩과 같은 Cloudflare 런타임 API를 사용하는 방법에 대해 더 자세히 알아보세요.

CI/CD로 배포하는 방법

푸시할 때 사이트를 자동으로 빌드하고 배포하기 위해 Workers Builds (베타)와 같은 CI/CD 시스템을 사용할 수도 있습니다.

Workers Builds를 사용하는 경우:

위 Wrangler 섹션에서 1-3단계를 따릅니다.
Cloudflare 대시보드에 로그인하여 Workers 및 Pages로 이동합니다. 생성을 선택합니다.
리포지토리 가져오기에서 Git 계정을 선택한 다음 Astro 프로젝트가 포함된 리포지토리를 선택합니다.
다음과 같이 프로젝트를 구성합니다.
- 빌드 명령: npx astro build
- 배포 명령: npx wrangler deploy
저장 및 배포를 클릭합니다. 제공된 workers.dev 하위 도메인에서 이제 Worker를 미리 볼 수 있습니다.

Cloudflare Pages

Wrangler를 사용하여 배포하는 방법

Wrangler CLI를 설치합니다.
터미널 창
```
npm install wrangler@latest --save-dev
```
사이트에서 요청 시 렌더링을 사용하는 경우, @astrojs/cloudflare 어댑터를 설치합니다.

이 명령어는 어댑터를 설치하고 astro.config.mjs 파일에 필요한 변경 사항을 한 번에 적용합니다.
터미널 창
```
npx astro add cloudflare
```
Astro의 요청 시 렌더링에 대해 더 자세히 알아보세요.
Wrangler를 사용하여 프로젝트를 로컬에서 미리 봅니다.
터미널 창
```
npx astro build && npx wrangler pages dev ./dist
```
npx wrangler deploy를 사용하여 배포합니다.
터미널 창
```
npx astro build && npx wrangler pages deploy ./dist
```

자산이 업로드되면 Wrangler는 사이트를 검사할 수 있는 미리보기 URL을 제공합니다.

Git을 사용하여 사이트를 배포하는 방법

코드를 git 리포지토리 (예: GitHub, GitLab)에 푸시합니다.
Cloudflare 대시보드에 로그인하여 Workers 및 Pages로 이동합니다. 생성을 선택하고 Pages 탭을 선택합니다. 그리고 git 리포지토리를 연결합니다.
다음과 같이 프로젝트를 구성합니다.
- 프레임워크 미리 설정: Astro
- 빌드 명령: npm run build
- 빌드 출력 디렉터리: dist
저장 및 배포 버튼을 클릭합니다.

문제 해결

클라이언트 측 수화

Cloudflare의 Auto Minify 설정으로 인해 클라이언트 측 하이드레이션이 실패할 수 있습니다. 콘솔에 Hydration completed but contains mismatches가 표시되면 Cloudflare 설정에서 Auto Minify를 비활성화하세요.

Node.js 런타임 API

Cloudflare SSR 어댑터와 함께 주문형 렌더링을 사용하는 프로젝트를 빌드한다면 [Error] Could not resolve "XXXX. The package "XXXX" wasn't found on the file system but is built into node.와 같은 오류 메시지와 함께 서버는 빌드에 실패합니다.

이는 서버 측 환경에서 사용 중인 패키지 또는 가져오기가 Cloudflare 런타임 API와 호환되지 않음을 의미합니다.
Node.js 런타임 API를 직접 가져오는 경우, 해결 방법에 대한 추가 단계는 Cloudflare의 Node.js 호환성에 대한 Astro 문서에서 참조할 수 있습니다.
Node.js 런타임 API를 가져오는 패키지를 가져오는 경우, 패키지 작성자에게 문의하여 node:* import 구문을 지원하는지 확인하세요. 그렇지 않은 경우 대체 패키지를 찾아야 할 수도 있습니다.