Build

문제

빌드가 성공했습니다. 파이프라인은 그것만 보고 다음 단계로 넘어갑니다. 빌드 성공이 “이 결과물을 내보내도 된다”는 뜻인지는 따로 확인한 적이 없습니다.

추천

빌드도 lint와 같은 규율을 따릅니다. 새 게이트를 추가했으면 먼저 고의로 깨뜨려 exit 1이 나오는지 확인합니다. 빌드를 컴파일 성공 여부로만 두지 말고, 결과물이 지켜야 할 불변 조건을 빌드 단계에 직접 검사로 넣습니다.

이유

빌드는 “코드가 문법적으로 맞는가”만 확인하는 관문이 되기 쉽습니다. 하지만 그 관문을 통과한 결과물이 실제로 온전한지는 다른 문제입니다. 예를 들어 문서 사이트라면 “링크가 전부 존재하는 페이지를 가리키는가”는 컴파일과 무관하지만 배포 전에 반드시 걸려야 하는 조건입니다.

이 사이트가 그 예입니다. astro.config.mjs는 starlight-links-validator를 빌드 플러그인으로 물려서, 존재하지 않는 슬러그로 가는 내부 링크가 하나라도 있으면 빌드 자체를 실패시킵니다. 링크 하나를 빠뜨렸는지 아닌지가 “빌드가 됐다/안 됐다”로 바로 드러납니다. 배포한 뒤에 사람이 클릭해 보고 알아채는 방식이 아닙니다.

같은 원리로 scripts/verify-build.mjs는 빌드 산출물(dist/)을 IA(src/ia.mjs)와 대조해 두 방향을 모두 검사합니다. IA가 정의한 페이지가 dist에 빠짐없이 있는지, 그리고 dist에는 없지만 소스에는 남아 있는 orphan 파일이 없는지입니다. 둘 중 하나라도 어긋나면 process.exit(1)로 끝납니다. 이 조건도 컴파일과 별개입니다. 컴파일만으로는 잡히지 않습니다.

두 사례 모두 규칙은 같습니다. 빌드 스크립트에 검사를 넣었으면, 그 검사가 실제로 실패할 수 있는지부터 확인합니다. 조건을 일부러 깨서 exit 1이 나오는 것을 본 적이 없는 검사는, 통과해도 “검사를 통과했다”는 증거가 되지 않습니다. lint와 마찬가지로 정규식이나 경로 하나만 어긋나도 조용히 전부 통과하는 채로 죽을 수 있습니다.

예시

새 빌드 게이트를 넣을 때는 다음 순서를 따릅니다.

1. 검사를 추가한다 (예: 링크 검증, IA-dist 대조)
2. 일부러 깨뜨린다 — 존재하지 않는 슬러그로 링크를 하나 만든다
3. npm run build가 실제로 exit 1로 끝나는지 확인한다
4. 링크를 고치고 다시 빌드해 초록을 확인한다

하지 말 것

빌드 성공을 “배포해도 된다”로 곧장 읽기. 컴파일 성공과 결과물의 무결성은 다른 질문입니다.

검사를 추가하고 정상 케이스에서 초록만 보고 끝내기. 실패 케이스를 한 번도 안 만들어 보면 그 검사가 애초에 exit 1을 낼 수 있는지조차 모릅니다.