요청할 때가 아니라 빌드할 때 만들기
이 글은 2026년 11월 4일 RAONIZ 저장소의 build.js와 src/site.js를 확인한 기록입니다. 방문자의 요청마다 서버가 화면을 만드는 대신, 빌드할 때 HTML 파일을 만들어 Hosting에 올리는 구조입니다.
회사 소개와 제품 설명처럼 여러 사람이 같은 내용을 읽는 페이지에는 이 방식이 단순합니다. 대신 글을 수정했다고 공개 페이지가 바로 바뀌지는 않습니다. 소스 수정, 빌드, 배포를 모두 거쳐야 합니다. 앱의 기능이나 사용자별 데이터를 이 정적 사이트가 처리한다는 뜻도 아닙니다.
한 개의 글에서 두 언어와 기존 주소까지
createSitePages()는 언어마다 홈·제품·정책·개발 노트를 만들고, 각 페이지의 URL과 출력 파일을 기록합니다. 한국어 글은 /ko/insights/…/, 영어 글은 /en/insights/…/로 나뉩니다. 이전 .html 주소도 같은 콘텐츠를 제공하도록 별도 출력합니다.
기존 주소를 남기면 오래된 링크를 방문한 사람이 길을 잃는 일을 줄일 수 있습니다. 다만 같은 콘텐츠가 여러 주소에 있으므로 대표 주소인 canonical과 언어 대체 링크가 맞는지 확인해야 합니다. 폴더 이름만 번역하는 작업으로 끝나지 않는 부분입니다.
스타일과 스크립트의 파일 이름이 바뀌는 이유
스크립트 빌더는 필요한 파일을 합친 결과에 SHA-256 해시를 계산하고 일부를 파일 이름에 넣습니다. HTML은 main.[해시].js처럼 해당 내용에 대응하는 이름을 참조합니다. 스타일도 같은 방식으로 묶습니다.
코드가 바뀌면 자산 URL도 달라지므로 예전 파일이 캐시에 남아 있어도 새 HTML이 새 자산을 요청할 수 있습니다. 해시는 코드의 품질이나 보안을 검증한 표시가 아니라 파일 내용을 구분하는 장치입니다. 이미지처럼 이름을 그대로 쓰는 다른 자산의 캐시는 별도로 봐야 합니다.
수정 뒤 실행하는 검사
저장소에서 다음 명령을 순서대로 실행하면 생성 과정과 기본 검사를 확인할 수 있습니다. build는 전용 출력 폴더 dist를 다시 만들며 원본 public 자산을 복사합니다. 출력 파일을 직접 고치면 다음 빌드에서 사라집니다.
npm run build
npm test
npm run verify빌드 감사는 내부 링크·앵커·로컬 자산·언어 메타데이터와 소스/출력 일치를 검사합니다. verify는 이미 만들어진 출력물을 읽어서 검사하며 파일을 다시 생성하지 않습니다. 실패 메시지에는 빠진 경로나 앵커가 나오므로 소스에서 원인을 고친 뒤 다시 빌드합니다.
생성에 성공한 뒤에도 남는 확인
검사를 통과해도 휴대전화에서 글이 잘 읽히는지, 실제 설치 링크가 열리는지, 오디오 조작이 가능한지는 별도로 봐야 합니다. 한·영 문장이 길어졌을 때 버튼과 목차가 넘치지 않는지도 실제 화면에서 확인합니다.
이 빌드 과정만으로 Core Web Vitals가 개선되었다고 말할 수는 없습니다. 성능 주장이 필요하다면 같은 페이지와 조건을 비교하고 현장 데이터와 실험실 결과를 구분해야 합니다. Core Web Vitals 안내를 참고하고, 파일 배포 이후의 갱신 문제는 캐시 글에서 이어서 살펴볼 수 있습니다.