“글 올리는 사이트 하나 만들어 줘. 나머지는 알아서 해 줘!”
AI는 신나게 일을 시작한다. 글을 늘리고, 다국어로 만들고, 관련 글, 내부 링크, 검색, 품질 검사, 보안 검사, 자동 수정까지 붙인다. 동네 매점이었어야 할 사이트가 번역팀, 검수팀, 감사실에 ‘쉼표 결재 위원회’까지 있는 대형 공장이 된다.
그리고 마지막에 뜨는 글자는 BUILD FAILED.
AI: “고쳤습니다.” 다음 빌드: 실패. AI: “다른 데도 고쳤습니다.” 또 실패. 보스를 잡으면 다음 보스가 나온다. Cloudflare Pages와 Astro를 예로 왜 이런 일이 생기는지, 어떻게 풀면 되는지 정리했다. 특정 사이트의 실제 원인을 단정하는 글은 아니다.
1. 빌드는 대체 뭘 하는 걸까?
Markdown 원고, 이미지, 디자인, 코드는 재료일 뿐 완성된 사이트가 아니다. 빌드는 이 재료를 브라우저에서 볼 수 있는 페이지와 파일로 바꾸는 작업이다. Astro는 보통 바로 올릴 수 있는 정적 파일을 dist 폴더에 만든다.[1]
원고가 레시피라면 빌드는 요리다. 생양파랑 요리책을 상에 올려놓고 “식사 나왔습니다” 하면 손님이 화낸다.
2. Cloudflare는 어디까지 해 줄까?
Cloudflare Pages는 Git에서 코드를 가져와, 내가 정해 둔 빌드 명령을 실행하고, 결과물을 공개해 준다.[2] 보통 순서는 코드 받기 → 도구 설치 → 사전 검사 → 페이지 생성 → 결과 확인 → 배포다. 정확한 단계는 프로젝트 설정에 따라 다르다.
빌드는 만들기, 배포는 내보내기. 새 빌드가 실패하면 그 버전은 공개되지 않는다. 공장 건물은 Cloudflare가 빌려줘도, 안에 있는 미로 같은 생산 라인은 내 코드인 경우가 많다.
3. 자동으로 글을 올리는 사이트는 페이지를 만들기 전부터 바쁘다
평범한 블로그는 원고를 HTML로 바꾸면 끝이다. 그런데 자동 발행 구조는 그 앞뒤로 일을 더 붙인다. 공개해도 되는 글인지, 번역은 다 있는지, 글 ID와 URL이 맞는지, 관련 글과 내부 링크는 괜찮은지, 검색 데이터를 만들 수 있는지, 제목·이미지 설명·광고·안전 규칙은 지켰는지.
하나하나는 다 이유가 있다. 문제는 글 한 줄만 바꿔도 모든 부서가 아침 조회부터 다시 하는 구조다. 마침표 하나 고치려는데 전 직원이 안전모 쓰고 집합한다.
4. 글과 언어가 많아지면 왜 힘들어질까?
글이 10,000개라고 일이 꼭 10,000배가 되는 건 아니다. 하지만 파일 수가 늘고, 글끼리 연결이 늘고, 언어마다 짝이 되는 URL과 검색 데이터가 생긴다. 매번 모든 글을 다른 모든 글과 비교하면 규모가 커질수록 무거워진다.
그래서 바뀐 부분만 다시 계산하고, 재사용할 수 있는 결과는 저장해 두고, 단계별로 시간을 재야 한다. 뭐가 느린지는 감이 아니라 숫자로 확인하자. 책 한 권 들어올 때마다 전국 도서관 책장을 다 다시 꽂으면 사서가 먼저 운다.
5. 하나 고치면 왜 또 다른 에러가 나올까?
단계가 순서대로 돌면, 앞에서 난 에러가 뒤쪽 에러를 가린다. 원고 검사에서 멈춤 → 고침 → 링크 검사에서 멈춤 → 고침 → 페이지 생성에서 멈춤 → 고침 → 검색 데이터에서 멈춤. 이런 식이다.
고칠 때마다 새 버그가 생겼다는 뜻은 아니다. 처음부터 문제가 여러 개 줄 서 있었을 수 있다. 반대로 수정 때문에 진짜 새 문제가 생길 수도 있다. 어느 쪽인지는 로그와 변경 기록을 보고 판단한다. 던전 문을 열면 또 문이 있고, 문마다 “여기가 마지막 층”이라고 적혀 있다.
6. 빌드가 실패하는 6가지 원인
① 코드·패키지: 오타, 패키지 누락, 버전 차이. ② 입력 데이터: 원고 누락, 형식 불일치. ③ 검사 규칙: 페이지는 만들어지는데 검사에서 막힘. ④ 자원: 시간, 메모리, 파일 수 제한. ⑤ 실행 환경: 내 컴퓨터와 Cloudflare 쪽 설정 차이. ⑥ 공개 단계: 마지막 확인이나 업로드 실패.
Cloudflare Pages는 빌드 명령이 0이 아닌 종료 코드를 내면 실패로 본다.[2] 즉 맨 끝의 “Build failed”는 결과일 뿐, 원인이라고 할 수는 없다. 추리소설 표지만 봐서는 범인을 모른다.
7. 로그는 ‘처음 실패한 곳’부터 보자
Cloudflare 배포 상세 화면에서 Build log를 열 수 있다.[3] 맨 마지막 빨간 줄이 아니라 진짜로 처음 실패한 단계를 찾고, 데이터·코드·규칙·자원·환경 중 어디에 해당하는지 나눈다. 그 단계만 따로 돌려 볼 수 있으면 따로 재현한다. 임시방편과 근본 해결을 구분하고, 고친 뒤에는 뒤 단계까지 통과하는지 확인한다.
“전부 다시 돌려!”를 100번 외쳐도 없는 파일은 안 생긴다. 필요한 건 근성이 아니라 고장 난 기계 번호다.
8. Cloudflare 제한은 하나가 아니다
2026년 10월 10일 기준 공식 문서에 따르면 Pages 무료 플랜은 월 500회 빌드, 동시 빌드 1개, 빌드 1회당 20분 타임아웃, 사이트당 정적 파일 20,000개까지다.[4] 큰 사이트는 HTML 말고도 이미지와 검색용 파일이 파일 수를 늘린다는 점도 중요하다.
Workers의 요청 수와 실행 시간에는 별도 제한이 있다. Pages Functions 요청이 Workers 쪽에 잡히는 경우는 있지만, Workers 한도를 다 썼다고 Pages 빌드 실패도 같은 이유라고 단정할 수는 없다.[4][5] 경리팀이 “예산 초과!”라고 외치면 먼저 어느 통장인지 물어보자.
9. 대단해 보이는 것과 꼭 필요한 것은 다르다
개인정보 유출, 심각한 보안 문제, 중요한 페이지 깨짐이라면 공개를 막아야 한다. 하지만 관련 글 순서가 살짝 마음에 안 든다고 사이트 전체를 멈춰야 할까?
검사는 반드시 공개를 막는 것 / 경고만 하는 것 / 공개와 따로 정기적으로 돌리는 것으로 나누자. 기준은 검사 이름이 얼마나 그럴듯한지가 아니라 독자와 운영자에게 실제로 피해가 있느냐다. 검수실 문손잡이에 먼지가 있다고 공장을 영구 폐쇄하면, 검사가 본업을 잡아먹은 거다.
10. AI에게 “알아서 해 줘” 하면 기능이 불어나는 함정
“검색 노출도 신경 써 줘”, “다국어도”, “재발 방지도”, “검사도”. 이렇게 부탁하면 AI는 기능을 금방 붙여 준다. 하나씩 보면 다 맞는 말인데, 전부 일렬로 이어 붙이면 모든 부서 도장이 다 찍혀야 글 하나가 나가는 구조가 될 수 있다.
이건 AI만의 문제가 아니다. 사람이 개발해도 기능을 너무 늘리면 기술 부채가 쌓인다. AI는 그 속도가 빠를 뿐이다. 코드를 다 직접 짤 필요는 없지만, 무엇을 지키고 무엇을 미루고 어디서 멈출지는 정해야 한다. AI에게 청소를 부탁했더니 로봇청소기 감사위원회가 생겼다. 바닥은 아직 더럽다.
11. 복구는 3단계로
지혈: 새 기능은 잠깐 멈추고, 마지막으로 정상 공개된 버전을 지키고, 처음 실패한 곳을 찾는다. 개인정보나 안전 검사를 대충 꺼 버리지는 말자.
분리: 꼭 필요한 페이지 생성만 매번 돌리는 중심에 두고, 무거운 전체 분석이나 사소한 검사는 따로 떼어 낸다. 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
