배포 후 브라우저 캐시까지 확인하는 Futory 운영 루틴

요약

Futory는 Next.js Markdown 블로그에 글을 추가하고, npm run test:theme, npm run test:content, npm run build를 통과한 뒤 호스트의 /opt/wordblog로 동기화하고 PM2/Nginx를 통해 공개합니다. 이 과정에서 서버 빌드와 공개 URL 확인이 모두 성공해도 운영자는 한 가지를 더 봐야 합니다. 바로 브라우저 캐시와 정적 자산 반영 여부입니다.

블로그 운영에서 캐시는 성능을 높여주지만, 배포 직후에는 혼란을 만들 수 있습니다. 서버에는 새 글이 있고 /posts도 HTTP 200을 반환하는데, 사용자의 브라우저에는 이전 목록이나 오래된 스타일이 남아 보일 수 있습니다. 특히 Futory처럼 다크/라이트 모드 토글, CSS 변수, Markdown 콘텐츠, Next.js 정적 청크가 함께 움직이는 구조에서는 “서버가 최신인가”와 “사용자가 최신 화면을 보는가”를 구분해야 합니다.

이 글은 Futory 운영 맥락에서 배포 후 캐시 문제를 어떻게 판별하고, 어떤 순서로 확인하며, AI 자동화 루틴에 어떤 검증 문장을 넣어야 하는지 정리합니다. 목표는 막연히 “새로고침해 보세요”라고 말하는 것이 아니라, 실제 배포가 성공했는지 확인한 뒤 필요한 경우에만 하드 리프레시 안내를 하는 것입니다.

서버 반영과 브라우저 반영은 다르다

자동 배포가 끝나면 가장 먼저 확인할 것은 서버 반영입니다. 새 Markdown 파일이 스테이징에 추가되었고, 콘텐츠 검증과 테마 검증이 통과했으며, 빌드가 성공해야 합니다. 그다음 호스트 /opt/wordblog에 파일을 동기화하고, 호스트에서도 다시 테스트와 빌드를 실행한 뒤 pm2 restart futory-wordblog --update-env로 프로세스를 갱신합니다.

여기까지 통과하면 서버 측 조건은 어느 정도 충족됩니다. 하지만 사용자가 보는 화면은 네트워크, CDN, 브라우저 캐시, 정적 파일 해시, 서비스 워커 유무 같은 요소의 영향을 받습니다. Futory는 현재 Next.js 정적 자산과 Nginx 프록시를 통해 페이지를 제공하므로, 배포 직후에는 공개 URL을 직접 요청해서 HTML에 오늘 날짜와 새 글 slug가 보이는지 확인하는 절차가 필요합니다.

즉 운영 로그에는 두 줄이 분리되어 남아야 합니다. 하나는 “빌드와 PM2 재시작이 성공했다”이고, 다른 하나는 “공개 도메인에서 새 글 URL과 /posts가 200이며 오늘 날짜가 노출된다”입니다. 두 번째 확인이 있어야 독자 관점의 배포 완료라고 말할 수 있습니다.

Futory에서 확인해야 할 캐시 지점

Markdown 콘텐츠 목록

새 글은 content/posts/*.md에 추가됩니다. 빌드 시점에 이 파일들이 읽히고 목록 페이지와 상세 페이지에 반영됩니다. 따라서 배포 후에는 새 글 상세 URL뿐 아니라 /posts 목록도 확인해야 합니다. 상세 URL이 열리더라도 목록에 노출되지 않으면 정렬, 날짜, frontmatter, 빌드 산출물 중 하나를 다시 봐야 합니다.

오늘 날짜가 화면에 보이는지도 중요합니다. cron은 KST 기준 날짜로 글을 만들기 때문에 서버 UTC 시간과 다를 수 있습니다. 공개 페이지에서 오늘 KST 날짜가 보이지 않으면 날짜 계산이나 빌드 대상이 꼬였을 가능성이 있습니다.

Next.js 정적 청크

Next.js는 빌드할 때 정적 자산을 해시가 포함된 파일로 생성합니다. 코드나 스타일이 바뀌면 새 청크가 만들어지고 HTML은 그 새 파일을 참조해야 합니다. 서버의 .next가 새로 빌드되었는데 PM2가 이전 프로세스를 계속 잡고 있거나, Nginx가 오래된 응답을 주면 사용자는 이전 화면을 볼 수 있습니다.

그래서 배포 루틴에서는 빌드 성공만 보지 말고 PM2 재시작 후 잠시 재시도하면서 공개 URL을 확인해야 합니다. Next.js 프로세스가 부팅 중일 때 즉시 요청하면 실패할 수 있으므로, 짧은 재시도는 실패를 줄여줍니다. 반대로 충분히 기다렸는데도 이전 내용만 보인다면 동기화 대상이나 빌드 위치를 의심해야 합니다.

테마 토글과 CSS 변수

Futory의 다크/라이트 모드는 components/ThemeToggle.tsx, app/theme-init.tsx, CSS의 data-theme 변수 흐름에 의존합니다. 콘텐츠만 추가하는 날에도 이 기능을 보존해야 합니다. 예전에 스테이징과 라이브의 차이를 제대로 비교하지 않고 동기화하면 라이브에만 있던 UI 기능이 사라질 수 있다는 위험을 확인했습니다.

따라서 새 글 배포에서도 npm run test:theme는 필수입니다. 캐시 문제를 조사할 때도 “테마 코드가 사라졌는가”와 “브라우저가 이전 CSS를 들고 있는가”를 분리해야 합니다. 소스와 빌드 산출물에 새 코드가 있고 공개 페이지가 200이라면 사용자에게 하드 리프레시를 안내할 수 있습니다. 하지만 소스에서 테마 파일이 빠졌다면 캐시 문제가 아니라 배포 회귀입니다.

AI 자동화에 넣을 운영 문장

AI에게 배포를 맡길 때는 “빌드하고 올려줘”보다 구체적인 기준이 필요합니다. Futory의 자동 게시 루틴에는 다음과 같은 문장이 유용합니다.

1. 새 글 파일만 추가하고 기존 글과 테마 파일은 삭제하지 않는다.

2. 스테이징에서 test:theme, test:content, build를 통과한 뒤에만 호스트 동기화를 진행한다.

3. 호스트에서도 같은 검증과 빌드를 반복한 뒤 PM2를 재시작한다.

4. 공개 도메인에서 새 slug와 /posts를 확인하고, 오늘 날짜가 보이는지 검사한다.

5. 공개 확인이 성공했는데 브라우저에서 이전 화면이 보이면 캐시 가능성을 안내하되, 먼저 서버 응답을 근거로 남긴다.

이 기준은 단순한 체크리스트가 아니라 자동화의 안전장치입니다. AI는 빠르게 파일을 만들고 명령을 실행할 수 있지만, 운영자는 “어떤 조건을 만족해야 성공인가”를 명확히 정의해야 합니다. 조건이 구체적일수록 실패한 상태로 PM2를 재시작하거나, 공개 확인 없이 성공 보고를 하는 일을 줄일 수 있습니다.

캐시 의심 상황에서의 판단 순서

캐시가 의심될 때는 감으로 판단하지 말고 순서를 지키는 편이 좋습니다. 먼저 서버에서 새 글 파일이 존재하는지 확인합니다. 다음으로 빌드 로그와 PM2 재시작 결과를 확인합니다. 그다음 curl로 공개 URL을 요청해 HTML에 새 제목, slug, 날짜가 포함되는지 봅니다. 이 세 단계가 모두 맞다면 서버는 최신 상태일 가능성이 높습니다.

그 이후에는 브라우저 쪽을 봅니다. 일반 새로고침 대신 하드 리프레시를 하고, 모바일과 데스크톱 중 한쪽만 오래된 화면을 보는지도 확인합니다. 특정 브라우저만 문제라면 로컬 캐시일 가능성이 커집니다. 반대로 모든 환경에서 이전 화면이라면 배포 또는 프록시 캐시를 다시 봐야 합니다.

이 판단 순서를 운영 문서와 자동화 로그에 남겨두면 다음 문제가 빨리 해결됩니다. “안 보여요”라는 피드백을 받았을 때 바로 배포를 되돌리는 대신, 서버 응답과 브라우저 캐시를 분리해 볼 수 있기 때문입니다.

자주 묻는 질문

공개 URL이 200이면 배포가 끝난 것인가요?

200 응답은 중요한 조건이지만 충분조건은 아닙니다. 새 글 slug가 열리고, /posts 목록에서 오늘 날짜와 제목이 보이는지까지 확인해야 합니다. 단순히 홈페이지나 기존 페이지가 200인 것만으로는 새 콘텐츠 반영을 보장할 수 없습니다.

사용자가 이전 화면을 본다면 바로 재배포해야 하나요?

먼저 공개 응답을 확인해야 합니다. 서버 응답에 새 글과 오늘 날짜가 포함되어 있다면 브라우저 캐시일 수 있으므로 하드 리프레시를 안내할 수 있습니다. 서버 응답에도 새 글이 없다면 재배포가 아니라 빌드 위치, 동기화 대상, PM2 재시작 여부를 다시 확인해야 합니다.

콘텐츠만 추가해도 테마 테스트가 필요한가요?

필요합니다. 콘텐츠 배포 과정에서 전체 프로젝트 동기화가 일어나기 때문입니다. 스테이징이 오래되었거나 라이브에만 있던 파일을 덮어쓰면 다크/라이트 모드가 사라질 수 있습니다. Futory에서는 콘텐츠 변경일에도 npm run test:theme를 먼저 통과시키는 기준을 유지합니다.

AI가 캐시 문제까지 자동으로 해결할 수 있나요?

일부는 가능합니다. AI는 공개 URL 요청, HTML 검사, PM2 상태 확인, 빌드 산출물 확인을 자동화할 수 있습니다. 하지만 사용자의 브라우저 로컬 캐시까지 직접 지울 수는 없습니다. 그래서 자동화는 서버가 최신 상태라는 근거를 만들고, 필요한 경우 사용자에게 하드 리프레시 같은 명확한 행동을 안내하는 역할을 해야 합니다.

결론

배포 성공은 빌드 로그 하나로 결정되지 않습니다. Futory처럼 Next.js Markdown 블로그를 자동으로 운영한다면 새 글 작성, 콘텐츠 검증, 테마 검증, 호스트 빌드, PM2 재시작, 공개 URL 확인, 브라우저 캐시 안내까지 하나의 루틴으로 묶어야 합니다.

캐시는 성능을 위한 좋은 도구지만, 배포 직후에는 운영자가 판단해야 할 변수가 됩니다. 중요한 것은 캐시를 막연한 핑계로 쓰지 않는 것입니다. 서버 소스와 빌드, 공개 응답을 먼저 확인하고, 그 근거가 있을 때만 브라우저 캐시를 의심해야 합니다. 이런 기준이 쌓이면 AI와 함께 운영하는 블로그는 더 빠르게 글을 발행하면서도, 독자가 실제로 보는 화면까지 안정적으로 관리할 수 있습니다.