“글 올리는 사이트 만들어 줘. 나머지는 알아서 해.”
AI는 기꺼이 기사, 언어, 관련 글, 검색, 품질 검사, 보안 검사, 자동 수정을 추가한다. 작은 매점이 번역부와 검수부, 감사실, 쉼표 승인 위원회까지 있는 대형 공장이 된다. 그러다 출고 문에 뜬다. BUILD FAILED.
AI는 “수정했습니다”라고 말한다. 다음 빌드도 실패한다. 또 고치면 다른 곳이 실패한다. 최종 보스를 잡을 때마다 다음 최종 보스가 나온다. Cloudflare Pages와 Astro로 이 구조를 설명한다. 특정 개인 사이트의 실제 원인을 확정하는 글은 아니다.
1. 빌드는 무엇을 할까?
Markdown 원고, 사진, 디자인, 프로그램은 재료일 뿐 완성된 사이트는 아니다. 빌드는 재료를 브라우저가 볼 수 있는 페이지와 파일로 가공한다. Astro는 일반적으로 배포할 정적 파일을 dist 폴더에 만든다.[1]
원고가 요리법이라면 빌드는 요리다. 생양파와 요리책을 내놓고 “식사 나왔습니다”라고 할 수는 없다.
2. Cloudflare가 맡는 일은?
Cloudflare Pages는 Git에서 코드를 가져와 프로젝트가 지정한 명령을 실행하고 결과물을 공개할 수 있다.[2] 소스 받기, 도구 설치, 사전 검사, 페이지 생성, 결과 확인, 배포가 일반적인 흐름이지만 실제 단계는 설정에 따라 다르다.
빌드는 제조, 배포는 출고와 공개다. 빌드가 실패하면 새 버전은 성공적으로 공개되지 않는다. 공장 건물은 Cloudflare가 제공해도 내부의 미로 같은 생산라인은 사이트가 만든 것일 수 있다.
3. 기사 공장은 페이지 생성 전부터 바쁘다
단순한 블로그는 원고를 HTML로 바꾸면 끝난다. 자동 공장은 공개 상태, 번역, 기사 ID와 URL, 관련 글, 내부 링크, 검색 자료, 제목 구조, 이미지 설명, 광고와 안전 규칙까지 검사할 수 있다.
개별 작업은 그럴듯하다. 한 문장만 바꿔도 모든 부서가 아침 회의를 다시 하는 구조가 문제다. 오타 하나 때문에 전 직원이 안전모를 쓰고 집합한다.
4. 글과 언어가 늘면 왜 힘들까?
글이 만 개라고 무조건 계산이 만 배가 되는 것은 아니다. 하지만 파일과 연결 관계는 늘어난다. 다국어 사이트는 언어별 URL과 번역 상태도 관리해야 한다. 모든 글을 다른 모든 글과 매번 비교하면 점점 무거워질 수 있다.
변경된 부분만 계산하고 이전 결과를 재사용하며 실제 걸린 시간을 측정해야 한다. 책 한 권 추가할 때마다 전국 도서관의 서가를 다시 정리하면 사서가 먼저 운다.
5. 하나를 고쳤는데 왜 다음 에러가 나오나?
단계가 순서대로 진행되면 앞쪽 실패가 뒤쪽 실패를 가린다. 원고 검사를 고쳐야 링크 검사가 실행되고, 링크를 고쳐야 페이지 생성까지 가고, 그다음 검색 데이터에서 실패할 수 있다.
매번 수정이 새 버그를 만들었다는 뜻은 아니다. 원래 있던 여러 문제가 차례를 기다렸을 수도 있다. 물론 수정 중 회귀 오류가 생길 수도 있으니 로그와 변경 사항을 함께 봐야 한다. 문을 열면 문이 또 나오고, 매번 “마지막 층”이라고 적혀 있다.
6. 빌드 실패의 여섯 가지 종류
코드·부품: 문법, 패키지, 버전 문제. 입력: 없거나 형식이 틀린 원고. 검사: 페이지가 생성되어도 규칙에서 탈락. 자원: 시간, 메모리, 파일 수 초과. 환경: 로컬과 클라우드 설정 차이. 배포: 결과 확인이나 업로드 실패.
Cloudflare Pages는 설정된 빌드 명령이 0이 아닌 종료 코드를 반환하면 실패로 처리한다.[2] 마지막 “Build failed”는 원인이라기보다 결과다. 추리소설 표지만 보고 범인을 단정할 수는 없다.
7. 로그는 처음 실패한 곳부터
Cloudflare의 배포 세부 화면에서 Build log를 볼 수 있다.[3] 마지막 빨간 글자 대신 처음 실제 실패한 단계를 찾고 데이터, 코드, 규칙, 제한, 환경으로 분류한다. 가능하면 그 단계만 재현하고 임시 회피와 근본 수정을 구분한다. 수정 뒤에는 이어지는 단계까지 확인한다.
“전체 다시 실행!”을 백 번 외쳐도 사라진 파일이 나타나지는 않는다. 필요한 건 기합이 아니라 고장 난 기계 번호다.
8. Cloudflare의 제한은 각각 다르다
2026년 10월 10일 기준 공식 문서에 따르면 Pages 무료 플랜은 월 500번 빌드, 동시 빌드 1개, 한 번에 20분 제한, 사이트당 정적 파일 20,000개 제한이 있다.[4] HTML 외에도 그림과 검색 자료가 파일 수를 늘릴 수 있다.
Workers 요청량과 실행 제한은 별개다. Pages Functions 요청이 Workers에 포함될 수 있지만, Workers 할당량을 소진했다는 사실만으로 Pages 빌드 실패의 원인을 단정할 수 없다.[4][5] 지갑이 여러 개인데 “돈이 없어!”만 외치면 어느 지갑인지 물어야 한다.
9. 복잡한 검사와 필요한 검사는 다르다
개인정보 유출, 심각한 보안 문제, 필수 페이지 손상은 공개를 막아야 한다. 하지만 관련 기사 추천 순서가 조금 아쉽다고 사이트 전체를 멈춰야 할까?
검사를 공개 차단, 경고, 별도 정기 점검으로 나누자. 기준은 실제 위험이지 검사 이름의 위엄이 아니다. 감사실 문손잡이에 먼지가 묻어서 공장 영구 폐쇄라면 감사실이 본업을 삼킨 것이다.
10. AI에게 “알아서” 맡길 때의 함정
“검색도”, “번역도”, “재발 방지도”, “감사도”를 반복하면 AI는 기능을 빠르게 늘린다. 하나씩은 좋아 보이지만 전부 이어 놓으면 전 부서가 승인해야 글 하나가 출고되는 시스템이 된다.
인간도 이런 기술 부채를 만든다. AI는 속도를 높일 뿐이다. 사람이 모든 코드를 직접 작성할 필요는 없지만, 무엇을 반드시 막고 무엇을 나중에 처리할지 정해야 한다. 청소를 맡긴 AI가 로봇청소기 관리위원회를 만들었다. 바닥은 그대로다.
11. 복구는 세 단계로 나누자
안정화: 새로운 부가 기능을 잠시 멈추고 마지막 정상 공개본을 보관하며 첫 실패를 찾는다. 개인정보나 안전 검사는 함부로 끄지 않는다.
분리: 페이지 생성에 꼭 필요한 작업만 기본 흐름에 두고 무거운 전수 검사와 분석은 독립 작업으로 이동한다. Cloudflare의 Build watch paths와 빌드 캐시는 도움이 되지만, 사용자 제작 프로그램을 자동으로 변경분만 처리하게 해 주지는 않는다.[6][7]
재발 방지: 단계별 시간, 오류 종류, 파일 수, 공개 성공률, 복구 시간을 기록한다. “AI가 고쳤다고 말함”이 아니라 “끝까지 제대로 공개됨”이 성공 기준이다.
12. 최종 보스는 공장 배선일지도
대량 기사와 다국어, 링크, 검사는 실제로 어려운 일이다. 하지만 모든 일을 빌드 한 번에 묶을 필요는 없다. 왜 특정 경고가 공개를 막는지, 왜 전부 재계산하는지, 한 곳이 멈춰도 다른 일이 진행될 수 없는지 따져 보자.
좋은 공장은 위험한 물건은 막고 안전한 물건은 보내며 고장 난 기계 번호를 알려 준다.
AI: “전부 완성했습니다!” 사람: “그럼 공개됐어?” AI: “빌드가 실패했습니다.”
완전 자동화된 건 변명 생산뿐이었다.
- Astro Docs, CLI reference: astro build docs.astro.build
- Cloudflare Docs, Build configuration (updated 2026-09-18) developers.cloudflare.com
- Cloudflare Docs, Debugging Pages (updated 2026-06-02) developers.cloudflare.com
- Cloudflare Docs, Pages limits (updated 2026-09-05) developers.cloudflare.com
- Cloudflare Docs, Workers limits (updated 2026-09-05) developers.cloudflare.com
- Cloudflare Docs, Build watch paths (updated 2026-04-21) developers.cloudflare.com
- Cloudflare Docs, Build caching (updated 2026-05-27) developers.cloudflare.com
