모노레포에서 사이트 하나만 Cloudflare Pages로 배포하기 초안

항목값
Root directorysites/hub
Build commandcd ../.. && npm ci && npm run build --workspace sites/hub
Build output directorydist
Environment variablesNODE_VERSION = 22
Framework presetNone

sites/hub 하나를 모노레포에서 직접 배포하는 Pages 프로젝트의 설정이다.

사이트 7개를 저장소 하나에 모아 두고 있다. sites/ 아래에 사이트별 폴더가 있고, packages/seo에 공통 코드가 있는 npm workspaces 구조다. 그런데 코드를 합친 뒤에도 Cloudflare Pages는 계속 합치기 전의 옛 저장소를 빌드하고 있었다. 모노레포에서 고친 내용이 실제 사이트에 한 번도 나간 적이 없었다.

기존 프로젝트의 저장소는 바꿀 수 없었다

처음에는 기존 Pages 프로젝트의 연결 저장소만 모노레포로 바꾸려고 했다. 대시보드의 Settings → Builds에는 그런 기능이 없었다. 찾아본 범위에서는 “프로젝트를 지우고 새로 만들라”는 커뮤니티 답변만 있었고, 공식 문서에서 저장소를 바꾸는 절차는 찾지 못했다.

남은 길은 둘이었다. 기존 프로젝트를 그대로 두고 GitHub Actions에서 wrangler pages deploy로 결과물만 올리거나, 모노레포에 연결된 프로젝트를 새로 만들거나.

새로 만드는 쪽을 골랐다. 사이트 하나만 먼저 옮기면 되는 상황이었고, API 토큰을 발급해 저장소에 넣는 절차 없이 대시보드에서 끝낼 수 있었다. 대신 pages.dev 주소가 새로 생긴다.

Root directory를 넣고도 cd ../.. 를 하는 이유

모순처럼 보이지만 두 값의 역할이 다르다.

Root directory는 결과물 폴더의 기준이다. sites/hub로 두면 Build output directory에 dist만 적어도 sites/hub/dist를 찾는다.

설치는 저장소 루트에서 해야 한다. package-lock.json이 루트에 있고, 사이트가 ../../packages/seo를 가져다 쓴다. sites/hub 안에서 설치하면 workspace 전체의 잠금 파일을 쓰지 못한다.

그래서 빌드 명령이 루트로 올라가 npm ci를 하고, --workspace sites/hub로 그 사이트만 빌드한다. Astro는 자기 폴더에 dist를 만들고, Pages는 Root directory 기준으로 그 폴더를 가져간다.

NODE_VERSION은 환경마다 다른 버전이 잡히는 게 싫어서 넣었다. 같은 저장소를 Workers 빌드로 잘못 올렸을 때 로그에 nodejs@24.18.0이 찍혔고, 내 컴퓨터는 25 버전이다. 22로 지정한 값으로 빌드가 통과하는 것은 확인했다. 다른 버전에서 실제로 깨지는지는 시험하지 않았다.

표에 없는 설정이 하나 더 있다. 저장소 하나에 사이트가 여러 개라서, 기본 설정이면 어느 사이트를 고치든 이 프로젝트가 다시 빌드된다. Settings → Builds의 Build watch paths에 이 사이트와 공통 패키지 경로만 넣으면 된다.

sites/hub/*
packages/*

배포는 됐는데 canonical이 옛 주소였다

첫 배포가 성공한 뒤 실제 주소에 요청을 보내 봤다.

curl -s https://<새 프로젝트>.pages.dev/ | grep -o '<link rel="canonical"[^>]*>'
<link rel="canonical" href="https://<옛 프로젝트>.pages.dev/">

새 사이트가 “내 원본은 옛 사이트”라고 선언하고 있었다. robots.txt의 sitemap 주소도 옛 주소였다. 이대로 두면 검색엔진은 새 사이트를 옛 사이트의 복사본으로 본다.

원인은 코드에 있었다. 이 저장소는 사이트 주소를 한 파일에서만 정의한다.

// packages/seo/sites.mjs
export const SITES = {
  hub: {
    liveUrl: 'https://<옛 프로젝트>.pages.dev',   // 지금 실제로 서비스하는 주소
    targetUrl: 'https://smalluniverse.org',        // 최종적으로 쓸 도메인
    domainReady: false,                            // 도메인이 이 사이트를 직접 서비스하면 true
  },
}

export function siteUrl(key) {
  const site = SITES[key]
  const url = site.domainReady && site.targetUrl ? site.targetUrl : site.liveUrl
  return url.replace(/\/$/, '')
}

canonical, og:url, sitemap, robots.txt가 전부 siteUrl()에서 나온다. 프로젝트를 새로 만들면서 pages.dev 주소가 바뀌었는데 liveUrl은 옛 주소 그대로였다.

고칠 곳은 한 줄이었다. liveUrl을 새 주소로 바꿔 main에 병합했고, 15초 간격으로 확인해 보니 45초쯤 지났을 때 실제 주소의 canonical이 바뀌어 있었다.

domainReady 스위치는 예전 실수 때문에 있다

사이트마다 주소를 따로 적던 시절에, 아직 연결하지 않은 도메인을 canonical로 선언한 사이트가 여럿 있었다. 크롤러가 canonical을 따라가면 404나 DNS 없음이 나왔고, 어느 페이지도 색인되지 않았다.

지금은 도메인이 실제로 이 사이트를 서비스하는 것을 확인한 뒤에만 domainReady를 true로 올린다. 그 전까지는 살아 있는 pages.dev 주소를 canonical로 쓴다. 확인은 스크립트로 한다.

npm run domains
hub  domainReady=true
     liveUrl   https://<새 프로젝트>.pages.dev   200  OK   canonical https://<새 프로젝트>.pages.dev/
     targetUrl https://smalluniverse.org          200  OK   canonical https://<새 프로젝트>.pages.dev/

각 주소에 요청을 보내 상태 코드와 본문의 canonical을 읽어 오는 50줄쯤 되는 스크립트다. “도메인을 붙였다”는 기억과 실제 응답이 다른 경우를 여러 번 겪고 나서 만들었다.

브랜치를 올리면 미리보기 배포가 생긴다

Git에 연결된 Pages 프로젝트는 main이 아닌 브랜치를 push해도 빌드한다. 이 배포는 Preview로 표시되고 <해시>.<프로젝트>.pages.dev 주소를 받는다. PR을 병합하기 전에 실제 빌드 결과를 볼 수 있어서 편하다. 다만 미리보기 주소도 누구나 열 수 있다.

다음 단계인 도메인 연결은 티스토리에 걸려 있던 도메인을 옮긴 글에 이어서 적었다.