import ReadMore from '/components/ReadMore.astro'; import { Steps } from '@astrojs/starlight/components'; import StaticSsrTabs from '/components/tabs/StaticSsrTabs.astro';

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

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

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

:::note

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

:::

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

전제 조건

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

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

Cloudflare Workers

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

```bash npm install wrangler@latest --save-dev ```

2. 사이트에서 요청 시 렌더링을 사용하는 경우, @astrojs/cloudflare 어댑터를 설치합니다.

이 명령어는 어댑터를 설치하고 `astro.config.mjs` 파일에 필요한 변경 사항을 한 번에 적용합니다. ```bash npx astro add cloudflare ``` 그런 다음 `public/` 폴더에 `.assetsignore` 파일을 만들고 다음 줄을 추가하세요. ```txt title="public/.assetsignore" _worker.js _routes.json ``` <ReadMore>[Astro의 요청 시 렌더링](/ko/guides/on-demand-rendering/)에 대해 더 자세히 알아보세요.</ReadMore>

3. Wrangler 구성 파일을 생성합니다.

<StaticSsrTabs> <Fragment slot="static"> ```jsonc // wrangler.jsonc { "$schema": "node_modules/wrangler/config-schema.json", "name": "my-astro-app", // 오늘 날짜로 업데이트합니다. "compatibility_date": "2025-03-25", "assets": { "directory": "./dist", "not_found_handling": "404-page" // 사용자 정의 `src/pages/404.astro` 페이지가 존재하는 경우 } } ``` </Fragment> <Fragment slot="ssr"> ```jsonc // 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 } } ``` </Fragment> </StaticSsrTabs>

4. Wrangler를 사용하여 프로젝트를 로컬에서 미리 봅니다.

```bash npx astro build && npx wrangler dev ```

5. npx wrangler deploy를 사용하여 배포합니다.

```bash npx astro build && npx wrangler deploy ```

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

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

CI/CD로 배포하는 방법

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

Workers Builds를 사용하는 경우:

2. Cloudflare 대시보드에 로그인하여 Workers 및 Pages로 이동합니다. 생성을 선택합니다.

3. 리포지토리 가져오기에서 Git 계정을 선택한 다음 Astro 프로젝트가 포함된 리포지토리를 선택합니다.

4. 다음과 같이 프로젝트를 구성합니다.

   • 빌드 명령: npx astro build
   • 배포 명령: npx wrangler deploy

5. 저장 및 배포를 클릭합니다. 제공된 workers.dev 하위 도메인에서 이제 Worker를 미리 볼 수 있습니다.

Cloudflare Pages

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

```bash npm install wrangler@latest --save-dev ```

2. 사이트에서 요청 시 렌더링을 사용하는 경우, @astrojs/cloudflare 어댑터를 설치합니다.

이 명령어는 어댑터를 설치하고 `astro.config.mjs` 파일에 필요한 변경 사항을 한 번에 적용합니다. ```bash npx astro add cloudflare ``` <ReadMore>[Astro의 요청 시 렌더링](/ko/guides/on-demand-rendering/)에 대해 더 자세히 알아보세요.</ReadMore>

3. Wrangler를 사용하여 프로젝트를 로컬에서 미리 봅니다.

```bash npx astro build && npx wrangler pages dev ./dist ```

4. npx wrangler deploy를 사용하여 배포합니다.

```bash npx astro build && npx wrangler pages deploy ./dist ```

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

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

2. Cloudflare 대시보드에 로그인하여 컴퓨팅(Workers) > Workers 및 Pages로 이동합니다. 생성을 선택하고 Pages 탭을 선택합니다. 그리고 git 리포지토리를 연결합니다.

3. 다음과 같이 프로젝트를 구성합니다.

   • 프레임워크 미리 설정: Astro
   • 빌드 명령: npm run build
   • 빌드 출력 디렉터리: dist

4. 저장 및 배포 버튼을 클릭합니다.

문제 해결

클라이언트 측 수화

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