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 대시보드에 로그인하고 Account Home > Pages에서 계정을 선택하세요.
Create a new Project와 Connect Git 옵션을 선택합니다.
배포하려는 git 프로젝트를 선택하고 Begin setup을 클릭합니다.
다음 빌드 설정을 사용합니다.
- Framework preset: Astro
- Build command: npm run build
- Build output directory: dist
Save and Deploy 버튼을 클릭합니다.

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을 사용 중이거나 확실하지 않은 경우 터미널에서 다음을 실행하세요.
Terminal window
```
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 구문을 지원하는지 확인하세요. 그렇지 않은 경우 대체 패키지를 찾아야 할 수도 있습니다.