커밋·푸시는 했는데 사이트엔 안 보인다 — 원인 세 겹 벗겨낸 하루

GitHub엔 분명히 올라갔는데 사이트엔 안 보였다. 배포 지연인 줄 알았는데 실제 원인은 YAML 문법 에러였고, 고친 뒤에도 안 보여서 한 번 더 헤맸다 — 이번엔 브라우저 캐시였다.

이 글은 이런 분께

“분명히 커밋·푸시 했는데 사이트엔 왜 안 보이지?” 겪어본 분
Vercel 배포 화면의 빨간 “Error” 표시를 처음 보고 당황한 분
배포는 성공했다는데도 화면이 안 바뀔 때 뭘 의심해야 할지 모르는 분

Before — 분명히 푸시했는데 사이트가 그대로였다

사례글 2개를 커밋하고 GitHub에 푸시까지 끝냈다. 늘 그랬듯 1~2분 기다렸다가 사이트를 새로고침했는데, 글 개수가 그대로였다. “아직 배포 중이겠지” 하고 좀 더 기다려도 마찬가지였다.

1차 원인 — Vercel 대시보드에서 발견한 빨간 “Error”

Vercel 대시보드 화면을 직접 열어봐 달라고 부탁했더니, 방금 올린 커밋 옆에 초록색 “Ready”가 아니라 **빨간색 “Error”**가 떠 있었다. 배포 자체가 실패한 거였다 — 지연이 아니라 애초에 안 됐던 것.

막힘 → 해결: 로컬에서 에러를 그대로 재현

Vercel 로그를 직접 볼 권한은 없어서, 로컬에서 같은 빌드 명령을 그대로 돌려봤다.

npm run build

에러 메시지가 정확히 원인을 짚어줬다.

can not read a block mapping entry; a multiline key may not be an implicit key
  Location:
    src/content/wiki/w3-case-plan-before-build.md:4:2

4번째 줄, summary: 값이 문제였다.

summary: "바로 만들지 말고 어떻게 할 건지 먼저 알려줘"라고 못박았더니, ...

값이 큰따옴표(")로 시작하니까 YAML은 “아, 여기부터 따옴표로 감싼 문장이구나” 하고 읽다가, 첫 번째 닫는 큰따옴표("...알려줘")에서 문장이 끝난 줄 알아버렸다. 그런데 뒤에 라고 못박았더니...가 그대로 남아있으니 YAML 입장에선 “이게 뭐지?” 하고 파싱이 깨진 것.

고친 법: 문장 전체를 작은따옴표로 한 번 더 감쌌다.

summary: '"바로 만들지 말고 어떻게 할 건지 먼저 알려줘"라고 못박았더니, ...'

이렇게 하니 npm run build가 로컬에서 에러 없이 끝났고, 커밋·푸시해서 Vercel도 “Ready”로 바뀌었다.

2차 원인 — 배포는 됐는데 화면은 그대로

배포가 “Ready”로 바뀐 걸 확인했는데도, 사이트를 새로고침하니 여전히 글 개수가 그대로였다. 배포 성공 = 화면 반영일 줄 알았는데 아니었다.

막힘 → 해결: 캐시를 의심하고, `fetch`로 직접 확인

브라우저가 예전 페이지를 그대로 보여주고 있는 건 아닌지 의심됐다. 브라우저 캐시를 아예 안 쓰는 방식으로 서버에 직접 요청해서 확인했다.

fetch(url, { cache: 'no-store' }).then(r => r.text())

결과: 새 글 내용이 응답에 이미 들어있었다. 서버(Vercel)는 이미 새 버전을 주고 있었는데, 브라우저 탭이 이전 페이지를 계속 보여주고 있었던 것뿐이었다. 강력 새로고침(location.reload(true))을 하니 그제야 화면에도 3주차 섹션과 새 글 2개가 나타났다.

After — 세 겹이었던 원인, 하나씩 벗겨낸 결과

겹	처음 의심	진짜 원인	확인 방법
1겹	”배포가 아직 안 끝났나?”	YAML 문법 에러로 빌드 자체가 실패	Vercel 대시보드에서 “Error” 확인 → 로컬 `npm run build`로 재현
2겹	”빌드는 됐는데 왜 화면은 그대로?”	브라우저 탭 캐시 (서버는 이미 최신)	`fetch(cache:'no-store')`로 서버 응답 직접 확인
3겹	”아까 실패했던 배포는 이제 안 뜨나?”	Vercel은 실패 기록을 지우지 않고 그대로 남김 (최신 배포만 Ready면 됨)	대시보드에서 배포 목록 시간순 확인

세 원인 다 “왜 안 되지?”라는 같은 질문에서 시작했지만 층위가 완전히 달랐다 — 하나는 코드(YAML 문법), 하나는 브라우저(캐시), 하나는 그냥 오해(Vercel 기록 방식). 겉보기엔 똑같이 “화면에 안 보임”이라 처음엔 헷갈렸지만, 하나씩 증거로 좁혀가니 순서대로 다 풀렸다.

배운 것 / 재사용 자산

YAML frontmatter 규칙: summary: 같은 값에 큰따옴표를 쓰고 싶으면, 값 전체를 작은따옴표('...')로 한 번 더 감싸야 한다. 그냥 문장 중간에 큰따옴표만 넣으면 YAML이 어디서 끝나는지 못 알아본다.

사이트에 새 글이 안 보일 때 체크리스트

GitHub에 실제로 푸시됐나 (git push 결과 확인)
Vercel 대시보드에서 최신 배포가 “Ready”인가, “Error”인가
“Error”면 로컬에서 npm run build로 그대로 재현해서 에러 메시지 읽기
고쳐서 다시 커밋·푸시 → “Ready” 확인
그래도 화면이 그대로면 브라우저 캐시 의심 → 강력 새로고침으로 재확인

Vercel 배포 기록 이해: 한 번 “Error”난 배포는 나중에 고쳐도 그 기록 자체가 “Ready”로 바뀌지 않는다. 지나간 기록은 그대로 남고, 중요한 건 제일 최신 배포가 Ready인지만 보면 된다는 것.