Skip to content

i18n(ko-KR): update deploy/cloudflare.mdx #13536

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ArmandPhilippot merged 1 commit into from
Mar 19, 2026
Merged

i18n(ko-KR): update deploy/cloudflare.mdx #13536

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
151 changes: 3 additions & 148 deletions src/content/docs/ko/guides/deploy/cloudflare.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,12 +13,7 @@ import { Steps } from '@astrojs/starlight/components';
import StaticSsrTabs from '~/components/tabs/StaticSsrTabs.astro';
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'

프런트엔드 정적 자산과 백엔드 API를 포함한 풀스택 애플리케이션뿐만 아니라 요청 시 렌더링되는 사이트까지 [Cloudflare Workers](https://developers.cloudflare.com/workers/static-assets/) 및 [Cloudflare Pages](https://pages.cloudflare.com/)에 배포할 수 있습니다.

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

- [Cloudflare Workers에 배포하는 방법](#cloudflare-workers)
- [Cloudflare Pages에 배포하는 방법](#cloudflare-pages)
프런트엔드 정적 자산과 백엔드 API를 포함한 풀스택 애플리케이션뿐만 아니라 요청 시 렌더링되는 사이트까지 [Cloudflare Workers](https://developers.cloudflare.com/workers/static-assets/)에 배포할 수 있습니다.

:::note

Expand Down Expand Up @@ -125,14 +120,14 @@ Astro 프로젝트에서 [Cloudflare 런타임을 사용하는 방법](/ko/guide

### CI/CD로 배포하는 방법

푸시할 때 사이트를 자동으로 빌드하고 배포하기 위해 [Workers Builds (베타)](https://developers.cloudflare.com/workers/ci-cd/builds/)와 같은 CI/CD 시스템을 사용할 수도 있습니다.
푸시할 때 사이트를 자동으로 빌드하고 배포하기 위해 [Workers Builds](https://developers.cloudflare.com/workers/ci-cd/builds/)와 같은 CI/CD 시스템을 사용할 수도 있습니다.

Workers Builds를 사용하는 경우:

<Steps>
1. 위 Wrangler 섹션에서 1-3단계를 따릅니다.

2. [Cloudflare 대시보드](https://dash.cloudflare.com/)에 로그인하여 `Workers 및 Pages`로 이동합니다. `생성`을 선택합니다.
2. [Cloudflare 대시보드](https://dash.cloudflare.com/)에 로그인하여 `Compute > Workers 및 Pages`로 이동합니다. 그리고 `응용 프로그램 생성`을 선택합니다.

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

Expand All @@ -143,144 +138,6 @@ Workers Builds를 사용하는 경우:
5. `저장 및 배포`를 클릭합니다. 제공된 `workers.dev` 하위 도메인에서 이제 Worker를 미리 볼 수 있습니다.
</Steps>

## Cloudflare Pages

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

<Steps>
1. [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/get-started/)를 설치합니다.

<PackageManagerTabs>
<Fragment slot="npm">
```sh
npm install wrangler@latest --save-dev
```
</Fragment>
<Fragment slot="pnpm">
```sh
pnpm add wrangler@latest --save-dev
```
</Fragment>
<Fragment slot="yarn">
```sh
yarn add wrangler@latest --dev
```
</Fragment>
</PackageManagerTabs>

2. 사이트에서 요청 시 렌더링을 사용하는 경우, [`@astrojs/cloudflare` 어댑터](/ko/guides/integrations-guide/cloudflare/)를 설치합니다.

이 명령어는 어댑터를 설치하고 `astro.config.mjs` 파일에 필요한 변경 사항을 한 번에 적용합니다.

<PackageManagerTabs>
<Fragment slot="npm">
```sh
npx astro add cloudflare
```
</Fragment>
<Fragment slot="pnpm">
```sh
pnpm astro add cloudflare
```
</Fragment>
<Fragment slot="yarn">
```sh
yarn astro add cloudflare
```
</Fragment>
</PackageManagerTabs>

3. [Wrangler 구성 파일](https://developers.cloudflare.com/workers/wrangler/configuration/)을 생성합니다.

Cloudflare는 신규 프로젝트에 Pages 대신 Workers를 사용할 것을 권장하므로, `astro add cloudflare` 명령은 Workers 프로젝트에 특화된 `wrangler.jsonc` 및 `public/.assetsignore` 파일을 생성합니다. 그래서 `public/.assetsignore` 파일을 삭제하고 `wrangler.jsonc` 파일을 수정해야 합니다. 어댑터를 사용하지 않는다면 직접 생성해야 합니다.

`wrangler.jsonc` 파일이 다음과 같은 구조인지 확인하세요.

<StaticSsrTabs>
<Fragment slot="static">
```jsonc title="wrangler.jsonc"
{
"name": "my-astro-app",
"compatibility_date": "YYYY-MM-DD", // 배포하는 날짜로 업데이트합니다.
"pages_build_output_dir": "./dist"
}
```
</Fragment>
<Fragment slot="ssr">
```jsonc title="wrangler.jsonc"
{
"name": "my-astro-app",
"compatibility_date": "YYYY-MM-DD", // 배포하는 날짜로 업데이트합니다.
"compatibility_flags": [
"nodejs_compat",
"disable_nodejs_process_v2"
],
"pages_build_output_dir": "./dist"
}
```
</Fragment>
</StaticSsrTabs>

<ReadMore>[Astro의 요청 시 렌더링](/ko/guides/on-demand-rendering/)에 대해 더 자세히 알아보세요.</ReadMore>

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

<PackageManagerTabs>
<Fragment slot="npm">
```sh
npx astro build && wrangler pages dev ./dist
```
</Fragment>
<Fragment slot="pnpm">
```sh
pnpm astro build && wrangler pages dev ./dist
```
</Fragment>
<Fragment slot="yarn">
```sh
yarn astro build && wrangler pages dev ./dist
```
</Fragment>
</PackageManagerTabs>

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

<PackageManagerTabs>
<Fragment slot="npm">
```sh
npx astro build && wrangler pages deploy ./dist
```
</Fragment>
<Fragment slot="pnpm">
```sh
pnpm astro build && wrangler pages deploy ./dist
```
</Fragment>
<Fragment slot="yarn">
```sh
yarn astro build && wrangler pages deploy ./dist
```
</Fragment>
</PackageManagerTabs>
</Steps>

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

### CI/CD를 사용하여 사이트를 배포하는 방법

<Steps>
1. 코드를 git 리포지토리 (예: GitHub, GitLab)에 푸시합니다.

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

3. 다음과 같이 프로젝트를 구성합니다.
- **프레임워크 미리 설정**: `Astro`
- **빌드 명령:** `npm run build`
- **빌드 출력 디렉터리:** `dist`

4. **저장 및 배포** 버튼을 클릭합니다.
</Steps>

## 문제 해결

### 404 동작
Expand All @@ -296,8 +153,6 @@ Workers 프로젝트에서 사용자 정의 404 페이지를 제공하려면 `no
}
```

Pages 프로젝트에서 사용자 정의 404 페이지를 포함하면 해당 페이지가 기본적으로 제공됩니다. 그렇지 않으면 Pages는 [Cloudflare의 단일 페이지 애플리케이션 렌더링 동작](https://developers.cloudflare.com/pages/configuration/serving-pages/#single-page-application-spa-rendering)을 기본값으로 사용하고 404 페이지를 표시하는 대신 홈 페이지로 리디렉션합니다.

### 클라이언트 측 수화

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