오늘 날짜로 쓴 Hugo 글이 아침 9시까지 안 보입니다 — timeZone을 넣고 시각별로 재 봤습니다

Hugo 글 머리에 date: 2026-10-11처럼 날짜만 적어 두면, 한국에서 그날 아침에 빌드해도 글이 안 나옵니다. 오후에 다시 빌드하면 나옵니다.

예전에 이 블로그의 다른 글에서 Hugo는 터미널에서 주는 TZ 환경변수를 보지 않는다는 것까지는 재 봤습니다. 그때 “timeZone 을 넣으면 어떻게 달라지는지는 확인하지 못했습니다"라고 적고 끝냈습니다. 이번에 그걸 쟀습니다. Hugo v0.165.0 extended, 2026-10-06 측정입니다.

빌드 시각을 고정하고 글 네 편을 넣었습니다

운영 중인 저장소는 건드리지 않고 사본을 떠서 했습니다. 시각을 바꿔 가며 빌드하려면 컴퓨터 시계를 돌려야 하나 했는데, Hugo에 --clock 옵션이 있습니다. 빌드할 때 Hugo가 “지금"으로 쓸 시각을 정해 주는 옵션입니다.

$ hugo --config hugo.toml --clock 2026-10-11T03:00:00+09:00 -d out-none
$ hugo --config hugo.toml,lab/cfg/seoul.toml --clock 2026-10-11T03:00:00+09:00 -d out-seoul

seoul.toml은 timeZone = 'Asia/Seoul' 한 줄짜리 파일입니다. 원래 설정 위에 덧씌웠습니다. 제 사이트 설정에는 timeZone이 없으니 첫 줄이 지금 제 사이트와 같은 조건입니다.

시험용 글은 날짜 적는 방식만 다르게 네 편 만들었습니다.

a: date: 2026-10-11                  # 날짜만
b: date: 2026-10-11T08:00:00         # 시각은 있고 오프셋은 없음
c: date: 2026-10-11T00:00:00+09:00   # 오프셋 +09:00 명시
d: date: 2026-10-11T00:00:00Z        # UTC 명시

오프셋은 “이 시각이 UTC보다 몇 시간 빠른가"를 적은 꼬리표입니다. 한국은 +09:00, UTC는 Z입니다. 글이 빌드 결과물에 들어갔는지는 out/posts/<slug>/index.html 파일이 있는지로 봤습니다.

전날 23:59부터 17:00까지, 열네 번 빌드한 결과

O가 결과물에 들어간 것, -가 빠진 것입니다. 시각은 모두 한국 시각입니다.

timeZone이 없으면 오프셋 없는 날짜를 UTC로 읽습니다. 그래서 a의 2026-10-11은 UTC 자정, 한국 시각으로는 09:00에야 지난 시각이 됩니다. b의 08:00도 UTC 08:00으로 읽혀 한국 시각 17:00이 돼서야 나타납니다.

timeZone = 'Asia/Seoul'을 넣으면 같은 글자를 한국 시각으로 읽습니다. a는 자정부터, b는 아침 8시부터 들어갑니다. 굵게 표시한 칸이 이 한 줄로 바뀐 칸입니다.

다른 사람이 쓴 글에서도 같은 증상을 찾을 수 있습니다. 한 블로거는 “timeZone을 정하지 않았고, UTC로는 아직 어제였기 때문"에 글이 안 보였다고 적고 timeZone = "Asia/Taipei"로 풀었습니다 (Joel Kitching). 2019년에는 미래 글을 판정하기 전에 날짜를 로컬 시간대로 바꿔 달라는 요청이 Hugo 저장소에 올라왔는데, 메인테이너가 date: 2019-09-12 같은 값은 UTC 자정으로 읽힌다고 답했고 이슈는 이듬해 닫혔습니다 (gohugo/hugo #6325).

오프셋을 적은 날짜는 timeZone을 따르지 않습니다

표에서 c와 d 열은 두 설정의 결과가 완전히 같습니다. c(+09:00)는 자정부터, d(Z)는 한국 시각 09:00부터 나옵니다. timeZone을 서울로 바꿔도 d는 여전히 9시입니다.

Hugo 설정 문서도 timeZone을 “시간대 오프셋이 없는 날짜를 파싱할 때 쓰는 시간대"라고 적고 있습니다. 오프셋을 적은 날짜는 이미 시간대가 정해져 있으니 손대지 않는다는 뜻이고 측정도 그대로였습니다.

그러니 글마다 +09:00까지 적는다면 timeZone은 공개 시각에 영향이 없습니다. 반대로 날짜만 적는 습관이라면 이 설정 한 줄이 공개 시각을 9시간 앞당깁니다.

공개 여부 말고 피드와 구조화 데이터도 바뀝니다

빌드에서 빠지느냐 마느냐 말고도 바뀌는 게 있었습니다. 같은 네 편을 17시에 빌드해 날짜가 찍히는 곳을 뽑았습니다.

a (날짜만)
  설정 없음  ld+json  "datePublished":"2026-10-11T00:00:00Z"
             RSS      Sun, 11 Oct 2026 00:00:00 +0000
  서울       ld+json  "datePublished":"2026-10-11T00:00:00+09:00"
             RSS      Sun, 11 Oct 2026 00:00:00 +0900

ld+json은 검색엔진에 글 정보를 건네는 구조화 데이터, RSS는 구독기가 읽는 글 목록 파일입니다. 숫자는 그대로인데 꼬리의 오프셋만 바뀝니다. 실제 가리키는 시각은 9시간 당겨진 것입니다. 화면에 보이는 날짜(2026년 10월)는 네 편 모두 두 설정에서 같았습니다.

c와 d는 여기서도 적힌 오프셋 그대로 나왔습니다. 그래서 날짜 적는 방식이 섞인 사이트는 한 피드 안에 오프셋이 섞입니다. 제 사이트가 지금 그렇습니다.

$ curl -s https://birchholt.com/index.xml | grep -o '<pubDate>[^<]*'
<pubDate>Tue, 06 Oct 2026 21:54:00 +0900
...
<pubDate>Wed, 26 Aug 2026 00:00:00 +0000

초기 글은 날짜만, 최근 글은 +09:00까지 적었기 때문입니다. 운영 글 전체를 두 설정으로 빌드해 diff로 비교해 보니, 결과물에 생기는 글 목록은 양쪽이 똑같았고 바뀐 파일은 RSS와 날짜만 적은 글 12편의 페이지(ld+json)였습니다. RSS 항목 17개 중 12개의 pubDate가 +0000에서 +0900으로 바뀌었습니다.

sitemap은 바뀌지 않았습니다. 제 사이트는 enableGitInfo = true라 sitemap의 lastmod를 git 커밋 시각에서 가져오는데, 커밋 시각에는 이미 +09:00이 붙어 있습니다. 커밋되지 않은 시험용 글은 lastmod가 date로 떨어져서 sitemap 오프셋도 RSS처럼 바뀌었습니다.

넣는 순간 빌드가 멈추는 값들

설정 값은 시간대 이름이어야 합니다. 흔히 떠올리는 표기 두 개는 빌드를 멈춥니다.

timeZone = 'KST'
ERROR failed to init config: invalid timeZone for language "ko": unknown time zone KST

timeZone = 'UTC+9'
ERROR failed to init config: invalid timeZone for language "ko": unknown time zone UTC+9

Etc/GMT-9는 통과했고 한국 시각으로 읽었습니다. 이름에 -9가 붙었는데 UTC+9가 되는, 부호가 거꾸로인 표기라 헷갈리기 쉽습니다.

더 고약한 건 제 맥에서는 되고 리눅스에서는 안 되는 경우였습니다. 리눅스용 Hugo v0.165.0을 받아 우분투 24.04 컨테이너에서 같은 사본을 빌드했습니다.

설정 문서에도 “쓸 수 있는 값의 목록은 시스템에 따라 다를 수 있다"는 문장이 있습니다. 결과로 보면 Hugo는 시간대 정보를 운영체제의 tzdata에서 읽는 것 같습니다. 소문자가 맥에서만 통한 건 맥 파일시스템이 대소문자를 가리지 않기 때문으로 추정합니다(원인까지 확인하지는 않았습니다). 우분투 24.04 기본 이미지에는 tzdata가 없었고 그 상태에서는 정확한 이름도 실패했습니다. 로컬에서 통과했다고 다른 곳에서도 통과하는 값이 아닙니다. 이름은 Asia/Seoul로 대소문자까지 맞춰 적는 게 안전합니다.

마지막으로 설정 문서의 예시에 있는 Local입니다. 이건 반대로 TZ 환경변수를 따릅니다.

timeZone = 'Local', 빌드 시각 03:00 KST, 날짜만 적은 글
  TZ=Asia/Seoul  → 포함, "2026-10-11T00:00:00+09:00"
  TZ=UTC         → 제외 (09:00에 다시 빌드하니 포함, "...T00:00:00Z")

설정이 없을 때는 TZ를 안 보던 Hugo가 Local을 넣으면 보기 시작합니다. 로컬과 빌드 서버의 공개 여부가 갈라지는 조건을 일부러 만드는 값이라, 저라면 쓰지 않겠습니다.

날짜 한 줄을 적기 전에 고를 것

제 사이트 설정에는 아직 timeZone을 넣지 않았습니다. 넣으면 공개되는 글 목록은 그대로지만 날짜만 적은 글 12편의 RSS·구조화 데이터 날짜가 9시간씩 당겨지기 때문에, 그게 필요한지부터 보고 정하려고 합니다. 이번에 잰 것으로 고르면 이렇습니다.

1. 날짜만 적는 습관이면 timeZone = 'Asia/Seoul'을 넣습니다. “오늘 날짜 글"이 한국 시각 자정부터 나옵니다.
2. 글마다 +09:00까지 적는다면 timeZone은 공개 시각에 아무 영향이 없습니다. 날짜만 적은 옛 글의 오프셋만 바뀝니다.
3. 넣기 전에 두 설정으로 빌드해 diff -rq로 결과물을 비교합니다. 바뀌는 파일 목록이 곧 영향 범위입니다.
4. 값은 Asia/Seoul 그대로 적습니다. KST·UTC+9는 빌드가 멈추고, 소문자는 리눅스에서 멈춥니다. Local은 피합니다.
5. 오늘 날짜 글이 안 보이면 --clock으로 시각을 바꿔 빌드해 봅니다. 몇 시부터 나오는지가 Hugo가 그 날짜를 어느 시간대로 읽었는지 알려 줍니다.

TZ를 바꿔도 안 되던 문제는 timeZone에서 풀리고 +09:00을 적은 글은 처음부터 그 문제가 없습니다.