# Astro 6, Cloudflare Pages 지원 종료: 무엇이 달라지고 어떻게 대응해야 하나

> Canonical: https://oaty.lol/posts/removed-cloudflare-pages-support
> Markdown alternate: https://oaty.lol/posts/removed-cloudflare-pages-support.md
> Published: 2026-04-21T04:01:58.273Z
> Updated: 2026-04-25T03:48:54.576Z
> Category: Web
> Tags: Astro

Astro 6부터 공식 Cloudflare 어댑터(@astrojs/cloudflare)는 Cloudflare Pages 배포를 기본적으로 지원하지 않습니다. 앞으로는 Cloudflare Workers로의 전환이 필수이며, 기존 Pages 사용자라면 마이그레이션을 고려해야 합니다.

Astro 6부터 공식 Cloudflare 어댑터(`@astrojs/cloudflare`)는 **Cloudflare Pages 배포를 기본적으로 지원하지 않습니다.** 앞으로는 Cloudflare Workers로의 전환이 필수이며, 기존 Pages 사용자라면 마이그레이션을 고려해야 합니다.

## **변경 사항의 배경**

2026년 1월, Astro 프레임워크를 개발한 The Astro Technology Company가 Cloudflare에 합류했습니다. 이 합류는 단순한 인수가 아니라 Astro 팀 전원이 Cloudflare 직원으로서 Astro 풀타임 개발을 계속하는 구조로, MIT 오픈소스 라이선스와 기존 로드맵은 그대로 유지됩니다. 이러한 배경 속에서 Astro 6가 출시되었고, 그 과정에서 Cloudflare Workers 중심의 아키텍처 통합이 가속화되었습니다.

Cloudflare 자체도 **신규 프로젝트에는 Cloudflare Workers를 사용할 것을 공식 권장**하고 있습니다. Pages는 정적 호스팅에 최적화된 플랫폼이지만, Workers는 엣지 런타임에서 서버사이드 렌더링(SSR), 미들웨어, API 엔드포인트 등 동적 기능을 훨씬 유연하게 처리할 수 있기 때문입니다..

## **Astro 6 + Cloudflare 어댑터의 구체적 변화**

### **Cloudflare Pages 지원이 '제거'된 이유**

Astro 6는 Vite의 환경 API(Vite Environment API)를 기반으로 완전히 재설계된 개발 서버를 탑재했습니다. 이 새로운 구조는 배포 타겟과 동일한 런타임에서 로컬 개발이 가능하게 합니다. 즉, Cloudflare Workers 런타임(workerd)을 로컬에서 그대로 에뮬레이션하여 프로덕션과 개발 환경의 불일치를 최소화합니다.

Cloudflare Pages는 이 새로운 아키텍처와의 통합 복잡도가 높아, 공식 어댑터에서 기본 지원 대상에서 제외되었습니다. 단, 수동 설정을 통해 Pages를 계속 사용하는 것이 완전히 불가능한 것은 아닙니다.

### **현재 공식 지원 구조**

| **항목**   | **변경 전 (Astro 5 이하)**      | **변경 후 (Astro 6)**        |
| -------- | -------------------------- | ------------------------- |
| 기본 배포 타겟 | Cloudflare Pages / Workers | **Cloudflare Workers 전용** |
| Pages 지원 | 공식 지원                      | 수동 설정 필요, 비권장             |
| 로컬 개발 환경 | 일반 Node.js                 | Workers 런타임 에뮬레이션         |
| Vite 버전  | Vite 5/6                   | Vite 7+ (Vite 8 주의)       |

## **Cloudflare Pages를 사용 중인 경우 어떻게 해야 하나**

### **1. Cloudflare Workers로 마이그레이션 (권장)**

가장 권장되는 방법은 기존 Pages 프로젝트를 **Cloudflare Workers로 마이그레이션**하는 것입니다. Cloudflare는 Pages에서 Workers로의 공식 마이그레이션 가이드를 제공하고 있으며, 주요 절차는 다음과 같습니다.

* `wrangler.toml` (또는 `wrangler.json`) 설정 파일 추가

* `astro.config.mjs`에서 어댑터를 `@astrojs/cloudflare`로 유지하되 Workers 모드로 설정

* `public/.assetsignore` 파일 생성

* Cloudflare 대시보드에서 Workers 프로젝트로 신규 배포 연결

Workers로 전환하면 **서버 아일랜드, 액션, 세션** 등 Astro 6의 새로운 기능을 모두 활용할 수 있게 됩니다.

### **2. 정적 사이트라면 어댑터 불필요**

만약 현재 Astro를 **완전 정적 사이트(SSG)** 빌더로만 활용하고 있다면, 어댑터 자체가 필요 없습니다. 빌드된 정적 파일을 Cloudflare Pages에 계속 배포하는 것은 아무 문제가 없습니다. 이 경우 `astro.config.mjs`에서 adapter 설정을 제거하면 됩니다.

### **3. 불가피하게 Pages를 유지해야 하는 경우**

어떤 이유로든 당장 Workers로 이전이 어렵다면, **수동 설정(manual configuration)** 을 통해 Pages를 계속 사용할 수 있습니다. 단, 이 방법은 공식 권장 사항이 아니며 향후 지원이 완전히 끊길 수 있으므로 임시 방편으로만 활용해야 합니다.

## **마이그레이션 시 주의사항**

마이그레이션 과정에서 몇 가지 기술적 주의사항이 있습니다.

* **Vite 버전 고정:** Astro 6와 Cloudflare 어댑터를 함께 사용할 때, 일부 Cloudflare 모듈이 Vite 8을 간접적으로 끌어와 충돌이 발생할 수 있습니다. package.json에서 Vite 버전을 7로 고정하는 것이 안전합니다.

* **Node.js API 호환성:** Cloudflare Workers 런타임은 기본적으로 Node.js API를 완전히 지원하지 않습니다. node:\* import 구문 사용 시 Cloudflare 설정에서 Node.js 호환성을 명시적으로 활성화해야 합니다.

* **환경 변수 접근 방식 변경:** Workers 환경에서는 환경 변수 접근 방식이 일반 Node.js 어댑터와 다릅니다.

* **커스텀 404 페이지:** Workers 프로젝트에서 사용자 정의 404 페이지를 제공하려면 not\_found\_handling 설정을 별도로 추가해야 합니다.

* **Auto Minify 비활성화:** Cloudflare의 Auto Minify 설정이 활성화되어 있으면 클라이언트 측 하이드레이션이 실패할 수 있으므로 Cloudflare 대시보드에서 비활성화해야 합니다.

## **왜 Workers가 더 나은 선택인가**

Cloudflare Workers는 단순한 대체재가 아니라 기능 면에서 Pages보다 우월한 플랫폼입니다. **엣지 네트워크의 300개 이상 PoP(접속 거점)** 에서 코드를 실행하며, KV, R2, D1, Durable Objects 등 Cloudflare의 핵심 개발자 서비스와 훨씬 긴밀하게 통합됩니다. 또한 Astro가 Cloudflare에 합류한 이상, 앞으로의 신기능 개발과 최적화는 Workers를 중심으로 이루어질 것이 명확합니다.

Astro 6가 제공하는 재설계된 개발 서버는 로컬에서 Workers와 동일한 런타임 환경을 에뮬레이션하므로, "로컬에서 됐는데 배포하니 안 된다"는 고질적인 문제가 대폭 줄어들게 됩니다. 이는 개발 생산성과 안정성 모두에서 실질적인 개선입니다.

## **정리: 지금 당장 해야 할 체크리스트**

1. **현재 Astro 프로젝트가 SSR을 사용하는지 확인** → SSG라면 어댑터 제거 후 Pages 배포 유지 가능

2. **SSR 사용 중이라면 Cloudflare Workers 마이그레이션 계획 수립**

3. `@astrojs/cloudflare`\*\* 어댑터를 최신 버전으로 업데이트\*\*

4. `wrangler.toml`\*\* 설정 파일 추가 및 Workers 프로젝트로 재배포\*\*

5. **Node.js 호환성 설정 및 Vite 버전 충돌 여부 확인**

6. **Cloudflare 대시보드에서 Auto Minify 비활성화 확인**

Astro 6의 Cloudflare Pages 지원 종료는 단순한 기능 삭제가 아니라, Astro와 Cloudflare가 더욱 긴밀히 통합되는 과정에서 나온 전략적 방향 전환입니다. Workers로의 마이그레이션을 서두르는 것이 장기적으로 안정적이고 기능이 풍부한 개발 환경을 확보하는 최선의 방법입니다.

**출처:**

1. [Astro 공식 문서 - Cloudflare 어댑터 (영문)](https://docs.astro.build/en/guides/integrations-guide/cloudflare/#removed-cloudflare-pages-support)

2. [Astro 공식 문서 - Cloudflare 어댑터 (한국어)](https://docs.astro.build/ko/guides/integrations-guide/cloudflare/)

3. [Cloudflare 공식 블로그 - Astro 합류 발표](https://blog.cloudflare.com/ko-kr/astro-joins-cloudflare/)