Cloudflare Workers에서 하위 디렉토리를 라우팅하는 설정 방법

이 사이트는 2025-11-28 시점에서, 2개의 Astro 프로젝트로 가동하고 있다.

• hsbt.horse/*: 루트
• hsbt.horse/tools/*: 도구

루트 wrangler.json은 공식 문서대로 간단하게 기재하면 문제 없다.

{
  "name": "root",
  "compatibility_date": "2025-11-19",
  "route": "hsbt.horse/*",
  "assets": {
    "directory": "./dist/",
    "not_found_handling": "404-page"
  },
  "preview_urls": false
}

한편, tools 쪽은 한 번 더 추가하지 않으면 기대대로 동작하지 않았다.

문제 : 서브 디렉토리 라우팅이 404

wrangler.json은 다음과 같이 설명됩니다.

{
  "name": "tool",
  "compatibility_date": "2025-11-19",
  "route": "hsbt.horse/tools/*",
  "assets": {
    "directory": "./dist/",
    "not_found_handling": "404-page"
  },
  "preview_urls": false
}

쓰는 방법은 문제 없지만, 이대로 배포하면 404 에러가 된다.

원인은, route에 기재한/tools/*라고 하는 계층구조에 맞추어,dist/tools하하가 업로드 되는 거동이 wrangler의 사양같기 때문에.

솔루션 : astro.config.mjs에서 base 및 outDir 설정

이 방법은 src/pages를 tools/로 취급하는 경우에 이용하면 된다.

astro.config.mjs에서 base와 outDir을 아래와 같이 하면 기대대로 움직이게 된다.

export default defineConfig({
  site: "https://hsbt.horse",
  base: "/tools/",
  outDir: "./dist/tools",
})

base은 Astro가 생성하는 링크나 자산 경로에 접두사를 추가합니다.

outDir은 빌드 출력 대상을 ./dist/tools로 변경하고 wrangler가 기대하는 계층 구조에 맞춘다.

몰안: src/pages/tools의 아래에 각종 페이지를 구현해 간다

astro.config.mjs의 설정은 변경하지 않습니다. base는 설정하지 않으며 outDir도 dist에서 변경하지 않습니다.

그 대신, src/pages하하의 파일 베이스 라우팅측에 구현 규약을 정해 대응해 가는 방법.

src/pages/tools 부하에 필요한 페이지를 실장해 나가는 것으로 설정 변경 없이, dist/tools에 각종 페이지를 출력할 수 있다.

그러나 이 방법이라면 _astro 디렉토리(각종 번들된 JS, CSS, 에셋)가 dist 바로 아래에 만들어져 버리기 때문에 dist/tools하하의 HTML은 배포되지만, 에셋이 배포되지 않게 된다.

요약

Cloudflare Workers에서 서브디렉토리 아래에 프로젝트를 배포하는 경우, wrangler의 route 설정뿐만 아니라 Astro측의 base과 outDir도 조정할 필요가 있다.

계층 구조를 갖추면 wrangler가 올바르게 파일을 업로드할 수 있게 된다.