2026-05-28 · 바이브코딩

Next.js Markdown 블로그에서 재빌드 루틴을 안정화하는 방법

Futory 운영 사례를 기준으로 Markdown 글 추가 후 콘텐츠 검증, 테마 검증, Next.js 빌드, 실행 프로세스 확인, 공개 페이지 검증을 반복 가능한 재빌드 루틴으로 정리했습니다.

요약

Next.js Markdown 블로그는 파일을 추가하는 것만으로 운영이 끝나지 않습니다. 정적 생성, 캐시, 실행 중인 앱 프로세스, Nginx 프록시가 함께 맞아야 새 글이 공개 페이지에 보입니다. Futory처럼 매일 글을 추가하는 블로그에서는 재빌드 루틴을 안정화하는 것이 중요합니다.

이 글은 Markdown 글 추가 후 어떤 순서로 검증하고 빌드하며 공개 페이지를 확인하면 좋은지 정리합니다.

Markdown 파일과 빌드는 분리해서 생각하기

운영자가 가장 먼저 확인해야 할 것은 글 파일이 올바른 위치에 있는지입니다.

/opt/futory/content/posts

하지만 이 파일이 존재한다고 해서 공개 페이지가 갱신된 것은 아닙니다. Next.js는 빌드 산출물과 실행 프로세스를 통해 페이지를 제공합니다. 따라서 파일 추가와 서비스 반영은 별도의 단계입니다.

재빌드 전 확인할 항목

새 글을 추가한 뒤 바로 빌드하기 전에 frontmatter를 확인합니다.

title은 목록과 상세 페이지에서 자연스럽게 보이는가
description은 검색 결과에 노출돼도 어색하지 않은가
date는 KST 기준 운영 날짜와 맞는가
category는 기존 규칙인 바이브코딩을 따르는가
tags는 글의 주제를 정확히 표현하는가

이 단계에서 오류를 잡으면 빌드 실패나 목록 정렬 문제를 줄일 수 있습니다.

검증 스크립트를 먼저 실행하기

Futory에는 콘텐츠와 테마를 확인하는 검증 명령이 있습니다.

npm run test:content
npm run test:theme

test:content는 Markdown 콘텐츠 규칙을 확인하고, test:theme는 글 추가와 상관없이 기존 테마 기능이 유지되는지 확인합니다. 콘텐츠 릴리즈라고 해도 UI 기능이 깨지면 성공한 배포라고 보기 어렵습니다.

빌드와 실행 확인

검증이 통과하면 빌드를 실행합니다.

npm run build

빌드가 성공한 뒤에는 내부 앱과 공개 도메인을 각각 확인합니다.

curl -I http://127.0.0.1:8042/
curl -I https://futory.oig.kr/

Futory의 흐름은 다음과 같습니다.

futory.oig.kr → nginx → 127.0.0.1:8042 → next-server → /opt/futory

이 구조를 기준으로 보면 문제가 생겼을 때 어느 구간에서 실패했는지 빠르게 좁힐 수 있습니다.

캐시까지 고려하기

응답 헤더에 x-nextjs-cache, Cache-Control, ETag가 보이면 캐시가 관여하고 있다는 뜻입니다. 따라서 빌드가 성공했는데도 공개 페이지가 바로 바뀌지 않는다면 실행 프로세스 재시작, Next.js 캐시, 브라우저 캐시를 함께 확인해야 합니다.

마무리

재빌드 루틴은 복잡할 필요가 없습니다. 같은 순서를 매번 반복하면 됩니다.

1. 글 파일 추가

2. frontmatter 확인

3. 콘텐츠 검증

4. 테마 검증

5. 빌드

6. 내부 앱 확인

7. 공개 도메인 확인

이 순서를 지키면 Futory의 일일 게시 흐름을 안정적으로 유지할 수 있습니다.

자주 묻는 질문

글을 추가할 때마다 빌드가 필요한가요?

정적 생성이나 캐시가 포함된 Next.js 블로그라면 빌드가 필요합니다. 파일만 추가하고 실행 중인 앱이 새 산출물을 보지 못하면 공개 페이지는 그대로일 수 있습니다.

빌드는 성공했는데 공개 페이지가 안 바뀌면 어떻게 하나요?

먼저 내부 앱 127.0.0.1:8042를 확인하고, 그 다음 공개 도메인을 확인합니다. 내부 앱은 바뀌었는데 공개 도메인만 오래된 상태라면 Nginx, 캐시, 브라우저 캐시를 확인해야 합니다.

테마 검증은 콘텐츠 배포와 무슨 관계가 있나요?

콘텐츠 변경 중에도 기존 UI 기능이 깨질 수 있습니다. 테마 검증은 새 글의 내용이 아니라 블로그 경험 전체가 유지되는지 확인하는 안전장치입니다.

결론

재빌드 루틴은 글 파일을 서비스에 안전하게 반영하기 위한 운영 기준입니다. Futory에서는 콘텐츠 검증, 테마 검증, 빌드, 내부 앱 확인, 공개 도메인 확인을 하나의 흐름으로 유지하는 것이 좋습니다.