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

프런트엔드 개발자가 정적 (JAMstack) 및 SSR 웹사이트를 공동 작업하고 배포할 수 있는 플랫폼인 Cloudflare Pages에 Astro 프로젝트를 배포할 수 있습니다.

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

Cloudflare Pages Dashboard를 통해 배포하는 방법
Wrangler, Cloudflare CLI를 사용하여 배포하는 방법
@astrojs/cloudflare를 사용하여 SSR 사이트를 배포하는 방법

전제 조건

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

Cloudflare 계정. 아직 계정이 없다면 프로세스 중에 무료 Cloudflare 계정을 만들 수 있습니다.
GitHub 또는 GitLab 저장소에 푸시된 앱 코드.

Git으로 사이트를 배포하는 방법

Cloudflare Pages에서 새 프로젝트를 설정하세요.
코드를 Git 저장소 (GitHub, GitLab)에 푸시합니다.
Cloudflare 대시보드에 로그인하고 계정 홈 > Workers 및 Pages > 개요 탭에서 계정을 선택하세요.
응용 프로그램 생성을 선택하고 Pages 탭을 선택한 후 Git에 연결 옵션을 선택합니다.
배포하려는 git 프로젝트를 선택하고 설정 시작을 클릭합니다.
다음 빌드 설정을 사용합니다.
- 프레임워크 미리 설정: Astro
- 빌드 명령: npm run build
- 빌드 출력 디렉터리: dist
저장 및 배포 버튼을 클릭합니다.

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

Wrangler CLI를 설치합니다.
wrangler login을 사용하여 Cloudflare 계정으로 Wrangler를 인증하세요.
빌드 명령을 실행합니다.
npx wrangler pages deploy dist를 사용하여 배포합니다.

# Wrangler CLI 설치
npm install -g wrangler
# CLI에서 Cloudflare 계정에 로그인
wrangler login
# Run your build command
npm run build
# 새 배포 만들기
npx wrangler pages deploy dist

자산이 업로드되면 Wrangler는 사이트를 검사할 수 있는 미리보기 URL을 제공합니다. Cloudflare Pages 대시보드에 로그인하면 새 프로젝트가 표시됩니다.

Wrangler를 사용하여 로컬에서 미리보기 활성화

미리보기가 작동하려면 wrangler를 설치해야 합니다.

pnpm add wrangler --save-dev

그런 다음 Astro의 내장 미리보기 명령 대신 wrangler를 실행하도록 미리보기 스크립트를 업데이트할 수 있습니다.

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

SSR 사이트 배포 방법

@astrojs/cloudflare 어댑터를 사용하여 Cloudflare Pages에 배포할 Astro SSR 사이트를 빌드할 수 있습니다.

아래 단계에 따라 어댑터를 설정하세요. 그런 다음 위에 설명된 접근 방식 중 하나를 사용하여 배포할 수 있습니다.

빠른 설치

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

npx astro add cloudflare

수동 설치

대신 어댑터를 수동으로 설치하려면 다음 두 단계를 완료하세요.

선호하는 패키지 관리자를 사용하여 프로젝트 종속성에 @astrojs/cloudflare 어댑터를 추가하세요. npm을 사용 중이거나 확실하지 않은 경우 터미널에서 다음을 실행하세요.
터미널 창
```
npm install @astrojs/cloudflare
```

astro.config.mjs 파일에 다음을 추가하세요:

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

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

Astro의 SSR에 대해 자세히 알아보세요.

문제 해결

클라이언트 측 수화

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 구문을 지원하는지 확인하세요. 그렇지 않은 경우 대체 패키지를 찾아야 할 수도 있습니다.