로컬에서 정상 빌드되던 Hugo·Blowfish 블로그가 Cloudflare Pages에서는 다음 오류로 실패했다.
can't evaluate field Locale in type *langs.Language이번 원인은 글이나 테마 파일의 문법 오류가 아니라 로컬과 Cloudflare 빌드 환경의 Hugo 버전 불일치였다. Cloudflare에 HUGO_VERSION을 지정한 뒤 재배포해 해결했다.
1. 실패 로그에서 오류와 버전 경고 확인#
Cloudflare Pages의 Deployments → 실패한 배포 → Build log를 열어 로그를 확인한다. 이번 실패 로그의 핵심 부분은 다음과 같다.
hugo v0.147.7 ... +extended
WARN Module "blowfish" is not compatible with this Hugo version:
0.163.0/0.166.0 extended
can't evaluate field Locale in type *langs.Language
Failed: build command exited with code: 1위 로그는 버전과 오류 메시지를 중심으로 발췌했다. 0.163.0/0.166.0은 이때 사용한 Blowfish가 선언한 Hugo 최소·최대 버전이며, 실행된 Hugo 버전은 앞줄의 0.147.7이다.
홈·404·카테고리 등 여러 페이지에서 같은 오류가 반복됐다. 공통 템플릿을 렌더링하는 과정에서 실패한 것이므로, 오류에 나열된 글 파일을 각각 수정할 문제가 아니었다.
Failed: build command exited with code: 1은 빌드 실패 결과다. 원인을 찾을 때는 그 앞의 실제 오류 메시지와 비호환 경고를 함께 읽어야 한다.
2. 로컬과 Cloudflare의 Hugo 버전 비교#
로컬 터미널에서 사용 중인 버전을 확인한다.
hugo version이 블로그의 로컬·기존 GitHub Actions 환경과 실패한 배포의 차이는 다음과 같았다.
| 확인 대상 | Hugo 버전 |
|---|---|
| 로컬·기존 GitHub Actions | 0.165.0 Extended |
| 실패한 Cloudflare 빌드 | 0.147.7 Extended |
| 사용한 Blowfish의 최소 요구 버전 | 0.163.0 Extended |
두 환경 모두 Extended였지만 Cloudflare의 버전이 요구사항보다 낮았다. Extended 사용 여부만 확인해서는 이 문제를 발견할 수 없다.
템플릿이 참조하는 Locale을 해당 Hugo 버전에서 처리하지 못했고, 모듈 호환성 경고도 같은 방향을 가리켰다. 따라서 테마의 Locale 참조를 삭제하는 대신 배포 환경을 정상 동작하던 Hugo 버전에 맞췄다.
위 0.147.7은 이번 실패 당시 실제 실행된 값이다. Cloudflare의 기본 Hugo 버전이 모든 시점·프로젝트에서 같다는 의미는 아니다. 다른 환경에서도 먼저 자신의 빌드 로그를 확인한다.
3. HUGO_VERSION 지정 후 재배포#
Cloudflare의 해당 Pages 프로젝트 → Settings → Variables and secrets에서 실패한 배포가 사용하는 환경을 선택한다. 이번 배포는 운영 브랜치의 Production 환경이다.
다음 변수를 등록한다.
| 변수 | 값 | 역할 |
|---|---|---|
HUGO_VERSION | 0.165.0 | Cloudflare 빌드에서 사용할 Hugo 버전 지정 |
HUGO_ENVIRONMENT | production | Hugo의 실행 환경 구분 |
이번 버전 오류를 해결하는 설정은 HUGO_VERSION이다. HUGO_ENVIRONMENT=production만 추가해도 Hugo 버전이 바뀌는 것은 아니다.
0.165.0은 이 블로그에서 정상 동작을 확인한 버전이다. 다른 테마를 사용한다면 무조건 이 값을 복사하기보다 로컬에서 검증한 버전과 테마 요구사항에 맞춰 지정한다. Cloudflare도 특정 Hugo 버전이 필요하면 HUGO_VERSION 환경변수를 사용하도록 안내한다. Hugo 버전 지정 공식 문서
설정을 저장한 뒤 Deployments → 실패한 배포의 메뉴 → Retry deployment를 실행한다. 변수 저장만으로 기존 빌드 결과가 바뀌지는 않으므로 새 빌드가 필요하다.
Preview 배포에서만 같은 오류가 발생한다면 Preview 환경에도 변수가 설정되어 있는지 확인한다. Production에 등록한 값이 Preview에도 적용됐다고 가정하지 않는다.
4. 새 빌드 로그와 배포 결과 확인#
새 로그에서 Hugo 실행 버전이 설정값과 일치하는지, 테마가 요구하는 Extended 빌드인지 확인한다. 이 프로젝트의 기준은 0.165.0과 +extended 표시다.
이후 템플릿 렌더링과 정적 파일 업로드까지 완료됐는지 확인한다. 이번 재시도에서는 저장소 복제·빌드·배포가 모두 성공했다.
환경변수를 바꿨는데도 실패한다면 다음을 구분해서 확인한다.
- 로그가 계속 이전 버전: 변수 이름·값, Production·Preview 적용 환경, 새 배포를 실행했는지 확인한다.
- 버전은 맞지만 같은 오류: 빌드가 사용하는 테마·서브모듈 커밋과 로컬 구성이 같은지 확인한다. 이 글의 사례와 원인이 같다고 단정하지 않는다.
- 다른 오류로 변경됨: 새 로그의 오류를 기준으로 다시 점검한다.
--minify추가나 DNS 변경은 Hugo 버전 불일치의 해결 방법이 아니다.
이번에는 버전 설정으로 해결되어 테마 소스 수정이나 커스텀 도메인 변경이 필요하지 않았다.
빌드가 성공했는데 특정 글만 보이지 않는다면 별도 문제다. 배포 대상 커밋에 글과 이미지가 포함됐는지, 글의 draft가 false인지, 작성일이 빌드 시점보다 미래인지 확인한다. 기본 hugo --minify 빌드는 초안과 미래 날짜의 글을 게시하지 않는다. 로컬의 hugo server -D와 게시 결과가 다를 수 있는 이유다. Hugo 빌드 옵션
Cloudflare Pages의 전체 배포 설정은 GitHub 연동과 Hugo 빌드 설정에서 확인할 수 있다.