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()
});

모드

현재 @astrojs/cloudflare 어댑터와 함께 Pages Functions를 사용할 때 지원되는 두 가지 모드가 있습니다.

Advanced 모드: 이 모드는 dist에서 _worker.js를 선택하는 advanced 모드 또는 페이지가 프로젝트 루트의 functions 폴더 밖에서 worker를 컴파일하는 directory 모드에서 함수를 실행하려는 경우에 사용됩니다.

모드가 설정되지 않은 경우 기본값은 "advanced"입니다.
directory 모드: 이 모드는 directory 모드에서 함수를 실행하려는 경우에 사용됩니다. 즉, 어댑터는 앱의 클라이언트 측 부분을 동일한 방식으로 컴파일하지만 worker 스크립트는 프로젝트 루트의 functions 폴더로 이동합니다. 어댑터는 해당 폴더에 [[path]].js만 배치하므로 버전 제어에서 확인할 수 있는 추가 플러그인 및 페이지 미들웨어를 추가할 수 있습니다.
astro.config.mjs
```
export default defineConfig({
  adapter: cloudflare({ mode: "directory" }),
});
```

Pages Functions 사용하기

Pages Functions을 사용하면 전용 서버를 실행하지 않고도 서버 측 코드를 실행하여 동적 기능을 활성화할 수 있습니다.

시작하려면 프로젝트 루트에 /functions 디렉터리를 만드세요. 이 디렉터리에 Functions 파일을 작성하면 미리 지정된 경로에 사용자 지정 기능이 있는 Worker가 자동으로 생성됩니다. Functions 작성에 대해 자세히 알아보려면 Pages Functions 문서를 참조하세요.

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

문제 해결

오류가 발생하는 경우 로컬에서 사용 중인 node 버전 (node -v)이 환경 변수에 지정한 버전과 일치하는지 다시 확인하세요.

Cloudflare에는 Astro의 기본 최소 버전보다 최신 버전인 Node v16.13이 필요하므로 적어도 v16.13을 사용하고 있는지 다시 확인하세요.

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

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

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