정답부터 말하면, Cloudflare Pages 모노레포 빌드 경로 필터는 한 저장소에 여러 앱이 들어 있을 때 “어떤 폴더가 바뀌면 이 프로젝트를 다시 빌드할지”를 정해 두는 운영 장치입니다. 마케팅 페이지, 관리자 화면, 문서 사이트, Workers 코드가 한 저장소에 섞여 있다면 모든 커밋마다 전체 배포를 돌릴 필요가 없습니다. 먼저 프로젝트별 루트 디렉터리를 나누고, 포함 경로와 제외 경로를 보수적으로 잡은 뒤, Preview 배포에서 실제 변경 파일과 빌드 로그가 맞는지 확인하는 순서가 가장 안전합니다.
빠른 요약: Cloudflare Pages에서 모노레포를 운영한다면 ① 앱별 폴더 구조 정리 ② Pages 프로젝트의 빌드 명령·루트 경로 확인 ③ include/exclude 경로 필터 설계 ④ 문서·공용 패키지 변경 시 예외 규칙 추가 ⑤ Preview 배포로 검증 순서로 진행하세요. Cloudflare 화면, 플랜, 빌드 옵션, wrangler 관련 기능은 수시로 달라질 수 있으므로 실제 적용 전 대시보드와 공식 문서를 다시 확인하는 것이 좋습니다.
1. 이 설정이 필요한 상황
모노레포는 하나의 Git 저장소 안에 여러 서비스를 함께 두는 방식입니다. 예를 들어 apps/site에는 랜딩 페이지, apps/admin에는 사내 관리자 화면, packages/ui에는 공용 UI 컴포넌트, workers/api에는 서버리스 API 코드를 둘 수 있습니다. 이런 구조는 코드 공유와 리뷰에는 편하지만, 배포 자동화에서는 작은 변경도 여러 프로젝트 빌드를 동시에 일으키기 쉽습니다. 문서 한 줄을 수정했는데 공개 사이트와 내부 화면이 모두 다시 빌드되면 대기 시간이 길어지고 로그 추적도 흐려집니다.
Cloudflare Pages의 경로 필터는 이 문제를 줄이는 데 유용합니다. 특정 Pages 프로젝트가 관심을 가져야 할 폴더를 정해 두면, 관련 없는 파일 변경은 빌드를 건너뛰는 방식으로 운영할 수 있습니다. 특히 여러 팀이 하나의 저장소를 공유하거나, PR마다 Preview 배포가 자동으로 만들어지는 환경에서 효과가 큽니다. 핵심은 무조건 빌드를 줄이는 것이 아니라, 실제 결과물에 영향을 주는 변경은 놓치지 않으면서 불필요한 배포만 줄이는 것입니다.
2. 먼저 정리할 폴더 구조
경로 필터를 넣기 전에는 저장소 구조를 글로 먼저 정리해야 합니다. Cloudflare 설정 화면에서 바로 값을 넣다 보면 공용 패키지나 설정 파일을 빠뜨리기 쉽습니다. 아래처럼 프로젝트, 빌드 명령, 결과물 위치, 의존 폴더를 한 번에 적어 두면 필터 설계가 쉬워집니다.
| 구분 | 예시 경로 | 필터에 넣을지 | 확인 포인트 |
|---|---|---|---|
| 공개 사이트 | apps/site/** |
포함 | 페이지, 라우트, 정적 파일 변경 시 빌드 필요 |
| 관리자 화면 | apps/admin/** |
다른 프로젝트에서 제외 | 별도 Pages 프로젝트라면 서로 간섭하지 않게 분리 |
| 공용 UI | packages/ui/** |
포함 | 여러 앱이 쓰면 관련 프로젝트 모두 빌드 필요 |
| 문서 | docs/** |
상황별 | 사이트에 노출되지 않으면 제외 가능 |
| 루트 설정 | package.json, pnpm-lock.yaml |
포함 권장 | 의존성 변경은 빌드 결과에 영향 가능 |
이 표를 기준으로 “이 파일이 바뀌면 실제 산출물이 달라지는가?”를 질문하면 됩니다. 애매한 경로는 처음부터 제외하지 말고 포함해 둔 뒤, 일정 기간 로그를 보며 줄이는 편이 안전합니다. 빌드 시간을 아끼려다 필요한 Preview가 만들어지지 않으면 팀 전체 검토 흐름이 더 느려질 수 있습니다.
3. Cloudflare Pages에서 확인할 기본 항목
대시보드에서는 먼저 대상 Pages 프로젝트가 어느 저장소와 브랜치에 연결되어 있는지 확인합니다. 그다음 빌드 명령, 출력 디렉터리, 루트 디렉터리 설정을 함께 봐야 합니다. 모노레포에서는 루트 디렉터리를 앱 폴더로 잡는 방식과 저장소 루트를 유지한 채 빌드 명령에서 앱을 지정하는 방식이 모두 쓰입니다. 어떤 방식을 쓰는지에 따라 경로 필터의 기준도 달라집니다.
예를 들어 저장소 루트를 기준으로 pnpm --filter site build를 실행한다면, apps/site/**뿐 아니라 packages/ui/**, 루트의 lock 파일, 패키지 매니저 설정도 영향을 줄 수 있습니다. 반대로 루트 디렉터리가 apps/site로 지정되어 있고 외부 패키지를 거의 쓰지 않는다면 필터 범위가 더 단순해집니다. 설정 화면 이름과 위치는 Cloudflare 업데이트에 따라 바뀔 수 있으므로, 현재 대시보드의 Build settings와 공식 문서의 최신 설명을 함께 보는 방식이 안전합니다.
4. include와 exclude를 잡는 실전 순서
첫 설정은 작게 시작하지 말고 “필요한 변경을 넉넉히 포함”하는 쪽이 좋습니다. 추천 순서는 다음과 같습니다.
- 해당 Pages 프로젝트의 앱 폴더를 포함 경로로 넣습니다.
- 공용 패키지, 공용 설정, lock 파일처럼 결과물에 영향을 주는 루트 파일을 추가합니다.
- 문서, 실험용 폴더, 다른 앱 폴더처럼 결과물과 무관한 경로를 제외 후보로 따로 적습니다.
- PR 하나를 만들어 앱 폴더만 수정했을 때 빌드가 시작되는지 확인합니다.
- 다른 앱 폴더만 수정했을 때 빌드가 건너뛰어지는지 확인합니다.
- 공용 패키지를 수정했을 때 필요한 프로젝트가 모두 다시 빌드되는지 확인합니다.
필터 규칙은 팀의 저장소 습관과 함께 관리해야 합니다. 새 패키지를 추가하거나 앱 폴더 이름을 바꾸면 경로 필터도 같이 바뀌어야 합니다. 그래서 변경 체크리스트에 “Pages 경로 필터 영향 확인” 항목을 넣는 것이 좋습니다.
5. Preview 배포로 검증하는 방법
경로 필터는 설정만 저장하고 끝내면 안 됩니다. 반드시 Preview 배포를 통해 실제 동작을 확인해야 합니다. 먼저 테스트 PR을 세 개로 나눕니다. 첫 번째는 대상 앱 파일을 수정하고, 두 번째는 무관한 앱 파일을 수정하고, 세 번째는 공용 패키지를 수정합니다. 각 PR에서 Cloudflare가 빌드를 시작하는지, 건너뛰는지, 로그에 어떤 경로 판단이 남는지 확인합니다.
검증할 때는 단순히 성공 또는 실패만 보지 말고, “왜 이 빌드가 실행되었는지”를 팀 노트에 남겨야 합니다. 특히 공용 패키지가 있는 구조에서는 하나의 변경이 여러 Pages 프로젝트에 영향을 줄 수 있습니다. 사이트 A와 사이트 B가 같은 UI 패키지를 쓰는데 A만 빌드된다면 필터가 너무 좁은 것입니다. 반대로 관리자 화면만 바꿨는데 공개 사이트가 계속 빌드된다면 필터가 너무 넓을 수 있습니다.
6. 운영 체크리스트
- 저장소 안의 앱 폴더와 공용 패키지 폴더를 최신 상태로 적어 둡니다.
- Pages 프로젝트별 빌드 명령, 루트 디렉터리, 출력 디렉터리를 표로 남깁니다.
- include 경로에는 앱 폴더, 공용 패키지, lock 파일, 설정 파일을 먼저 포함합니다.
- exclude 경로는 충분히 검증한 뒤에만 적용합니다.
- 브랜치 이름, PR Preview, Production 배포의 동작 차이를 따로 확인합니다.
- Cloudflare 대시보드 화면, 플랜별 제한, 빌드 옵션은 바뀔 수 있으므로 정기적으로 재확인합니다.
- 새 앱이나 새 패키지를 추가할 때 경로 필터 수정 여부를 리뷰 항목에 넣습니다.
체크리스트의 목적은 담당자가 바뀌어도 같은 기준으로 배포를 판단하게 만드는 것입니다. 모노레포는 시간이 지날수록 폴더가 늘어나기 때문에, 처음에 만든 필터가 몇 달 뒤에도 맞는다고 가정하면 안 됩니다.
7. 자주 생기는 실수
가장 흔한 실수는 앱 폴더만 포함하고 공용 패키지를 빠뜨리는 것입니다. 화면 컴포넌트, 테마, 빌드 설정, 타입 정의가 공용 폴더에 있는데 필터가 앱 폴더만 보면 실제 화면이 바뀌어도 Preview가 만들어지지 않을 수 있습니다. 두 번째 실수는 lock 파일을 무시하는 것입니다. 의존성 버전이 바뀌면 같은 코드라도 결과물이 달라질 수 있으므로 루트 파일 변경도 빌드 조건에 넣는 편이 안전합니다.
세 번째 실수는 제외 규칙을 너무 공격적으로 쓰는 것입니다. docs/**처럼 명확한 경로는 제외하기 쉽지만, 문서 생성 결과물이 사이트에 포함되는 구조라면 이야기가 달라집니다. 네 번째 실수는 설정 변경 후 기록을 남기지 않는 것입니다. 누가 어떤 이유로 필터를 바꿨는지 남기지 않으면 다음 장애 때 원인 파악이 늦어집니다. 여기서 말하는 장애는 서비스 판단이 아니라 배포 자동화 흐름의 이상 여부를 뜻합니다.
8. 비용과 속도를 함께 보는 관점
빌드를 줄이면 대기 시간이 줄고 팀의 피드백 속도도 빨라집니다. 다만 절감만 목표로 삼으면 위험합니다. Cloudflare의 요금제, 빌드 시간 제한, 동시 빌드 조건, 기능 제공 범위는 변경될 수 있습니다. 따라서 현재 플랜에서 어떤 제한이 있는지 확인하고, 필터 적용 전후의 빌드 횟수와 평균 대기 시간을 기록하는 방식이 좋습니다.
운영팀은 “이번 달 빌드 횟수가 얼마나 줄었는가”보다 “필요한 Preview가 누락되지 않았는가”를 먼저 봐야 합니다. 배포 자동화는 빠른 것보다 신뢰할 수 있는 것이 중요합니다. 필터 적용 뒤 일주일 정도는 건너뛴 빌드와 실행된 빌드를 함께 표로 모아 두면 과도한 제외 규칙을 빨리 찾을 수 있습니다.
9. 추천 적용 시나리오
소규모 팀이라면 처음에는 공개 사이트 하나만 대상으로 경로 필터를 적용해 보세요. 앱 폴더, 공용 UI, 루트 의존성 파일을 포함하고, 관리자 화면과 실험 폴더만 제외 후보로 둡니다. 한 주 동안 PR Preview 로그를 보며 누락이 없으면 다른 Pages 프로젝트로 확장합니다. 대규모 팀이라면 저장소 구조 문서와 배포 정책 문서를 먼저 맞춘 뒤, 프로젝트별 필터를 코드 리뷰 체크리스트와 연결하는 편이 좋습니다.
Cloudflare Pages 모노레포 빌드 경로 필터는 한 번 설정하면 끝나는 버튼이 아니라, 저장소 구조와 함께 관리하는 운영 규칙입니다. 폴더가 늘고 빌드 명령이 바뀌면 필터도 다시 봐야 합니다. 이 원칙만 지키면 불필요한 배포를 줄이면서도 필요한 Preview 검토 흐름은 유지할 수 있습니다.
FAQ
Q1. 모노레포가 아니어도 경로 필터가 필요한가요?
단일 앱 저장소라면 효과가 크지 않을 수 있습니다. 다만 문서, 실험 코드, 도구 스크립트가 같은 저장소에 많고 이 변경들이 사이트 결과물과 무관하다면 빌드 조건을 정리할 가치가 있습니다.
Q2. 공용 패키지는 모두 포함해야 하나요?
해당 Pages 프로젝트 결과물에 영향을 주는 공용 패키지는 포함하는 편이 안전합니다. 어떤 패키지가 실제로 쓰이는지 불명확하면 처음에는 포함하고, 로그와 의존 관계를 확인한 뒤 줄이세요.
Q3. exclude 규칙부터 넣어도 되나요?
가능은 하지만 초반에는 추천하지 않습니다. 제외 규칙은 누락 위험이 커서, 먼저 포함 규칙으로 안전 범위를 만들고 Preview 테스트를 반복한 뒤 적용하는 방식이 더 안정적입니다.
Q4. 설정 후 어떤 로그를 봐야 하나요?
PR별 변경 파일, 빌드 실행 여부, 건너뛴 이유, 빌드 명령, 결과 링크를 함께 봐야 합니다. 단순 성공 여부만 보면 필터가 너무 넓거나 좁은 문제를 놓칠 수 있습니다.
Q5. Cloudflare 화면이 글과 다르면 어떻게 하나요?
Cloudflare Pages의 대시보드, 요금제, 빌드 옵션, Workers와의 연동 기능은 업데이트로 바뀔 수 있습니다. 이 글은 설정 순서의 기준을 제시하는 것이며, 실제 적용 전에는 현재 계정 화면과 공식 문서를 최신 기준으로 확인하세요.
