起因

今天上传新文章的时候发现部署成功了，而且一点报错都没有，但就是看不到新文章出现在公网的博客上。后来研究了半天，本地 hugo 编译时，查看编译产物发现 hugo 根本就没有编译新文章。

排查

那么就开始查错。一开始以为是文章的 markdown 文件哪里写错了，导致 hugo 无法正确解析，或者图片内容过多，导致无法编译，甚至于怀疑 title 过长，超出文件系统的限制导致 hugo 采取保守编译措施，结果都不是。

最有可能出错的地方还是文章的 yaml 头部，所以可以先把其他部分全去掉。图片全部删除，索引也全部删除，内容也全部删除，最后就剩 yaml 头了。结果还真是不行。那么就只能怀疑 yaml 头部的某个字段了。

于是就开始单一变量法，修改一些字段的值，看看会不会编译成功。结果发现，与 title、封面、tags、categories、description 都没什么关系，只要把日期改成以前的日期，就能出现在最终编译产物里了。

1
2
3
4
5
6
7
8
9

---
title: "使用"
date: 2026-04-16
description: 从零开始
tags:
    - Docker
categories:
    - 自部署
---

关于日期

？？？日期还不能是今天吗？首先难道 hugo 还会根据日期来判断是否编译吗？感觉有点逆天了。。最终搜索结果表明 hugo 默认不编译发布日期在未来的文章（即 hugo 的编译参数 buildFuture 默认为 false）。也就是说，如果你把日期改成了未来的日期，hugo 就会认为这是篇"未来文章"，直接跳过编译，而且不会报任何警告。

但是问题是。。我把日期改成了今天啊！难道 hugo 还会根据时区来判断吗？结果是 hugo 还真会用当前时间戳精确到秒来比较，如果编译时刻早于 2026-04-17T00:00:00 所解析出的时间（受时区影响），hugo 就认为这篇文章是"未来文章"，直接跳过，而且不会报任何警告。

关于时区

Hugo 判断时区的逻辑大致如下：

1. 文章中明确指定了时区

   如果 date 带有时区偏移，则直接使用：

   1 2	date: 2026-04-17T10:00:00+08:00 # 明确是东八区 date: 2026-04-17T02:00:00Z # 明确是 UTC

2. 文章中没有指定时区

   1	date: 2026-04-17

   这时 Hugo 会按以下优先级确定时区：

   • 先看配置文件中的 timeZone 字段：

   1 2	# hugo.yaml timeZone: "Asia/Shanghai"

   • 如果没配置，就使用编译机器的系统时区（即 TZ 环境变量或操作系统默认时区）。

感觉 CI/CD 环境尤其容易被这个坑，因为服务器默认 UTC。

解决方法

1. 编译时加 --buildFuture 参数：

   1	hugo --buildFuture

2. 在 Hugo 配置文件中永久开启：

   1 2	# hugo.yaml buildFuture: true

3. 给文章日期加上具体时间和时区，确保落在"过去"：

   1	date: 2026-04-17T00:00:00+08:00

4. 在 Hugo 配置文件中设置默认时区，避免依赖系统环境：

   1 2	# hugo.yaml timeZone: "Asia/Shanghai"

还有一个排查技巧：用 hugo list future 可以列出所有被 Hugo 判定为"未来"的文章，方便确认是不是这个原因。