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

프런트엔드 정적 자산과 백엔드 API를 포함한 풀스택 애플리케이션뿐만 아니라 요청 시 렌더링되는 사이트까지 Cloudflare Workers에 배포할 수 있습니다.

:::note

Cloudflare는 새 프로젝트에 Cloudflare Workers를 사용할 것을 권장합니다. Pages를 사용하는 기존 프로젝트의 경우 Cloudflare 마이그레이션 가이드 및 호환성 매트릭스를 참조하세요.

:::

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

전제 조건

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

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

Cloudflare Workers

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

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

이 명령어는 어댑터를 설치하고 astro.config.mjs 파일에 필요한 변경 사항을 한 번에 적용합니다.
- npm
- pnpm
- Yarn
```
npx astro add cloudflare
```
```
pnpm astro add cloudflare
```
```
yarn astro add cloudflare
```
Astro의 요청 시 렌더링에 대해 더 자세히 알아보세요.
Wrangler 구성 파일을 생성합니다.

astro add cloudflare 명령어를 실행하면 이 파일이 자동으로 생성됩니다. 어댑터를 사용하지 않는 경우 직접 생성해야 합니다.
- 정적 사이트
- 요청 시 렌더링
```
  {
    "name": "my-astro-app",
    "compatibility_date": "YYYY-MM-DD", // 배포하는 날짜로 업데이트합니다.
    "assets": {
      "directory": "./dist",
    }
  }
```
```
  {
    "main": "dist/_worker.js/index.js",
    "name": "my-astro-app",
    "compatibility_date": "YYYY-MM-DD", // 배포하는 날짜로 업데이트합니다.
    "compatibility_flags": [
      "nodejs_compat",
      "global_fetch_strictly_public"
    ],
    "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 대시보드에 로그인하여 Compute > Workers 및 Pages로 이동합니다. 그리고 응용 프로그램 생성을 선택합니다.
리포지토리 가져오기에서 Git 계정을 선택한 다음 Astro 프로젝트가 포함된 리포지토리를 선택합니다.
다음과 같이 프로젝트를 구성합니다.
- 빌드 명령: npx astro build
- 배포 명령: npx wrangler deploy
저장 및 배포를 클릭합니다. 제공된 workers.dev 하위 도메인에서 이제 Worker를 미리 볼 수 있습니다.

문제 해결

404 동작

Workers 프로젝트에서 사용자 정의 404 페이지를 제공하려면 not_found_handling을 설정해야 합니다. Cloudflare 문서의 라우팅 동작 섹션에서 이에 대해 더 자세히 알아볼 수 있습니다.

{
  "assets": {
    "directory": "./dist",
    "not_found_handling": "404-page"
  }
}

클라이언트 측 수화

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

Node.js 런타임 API

Cloudflare 어댑터와 함께 주문형 렌더링을 사용하는 프로젝트를 빌드한다면 [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 구문을 지원하는지 확인하세요. 그렇지 않은 경우 대체 패키지를 찾아야 할 수도 있습니다.