博客 on Sisy's Blog

Hugo 文章不显示 - 未来日期/时区

Fri, 17 Apr 2026 00:00:00 +0000

起因

今天上传新文章的时候发现部署成功了，而且一点报错都没有，但就是看不到新文章出现在公网的博客上。后来研究了半天，本地 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 判断时区的逻辑大致如下：

文章中明确指定了时区

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

1
2


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

文章中没有指定时区
1

date: 2026-04-17
这时 Hugo 会按以下优先级确定时区：
- 先看配置文件中的 timeZone 字段：
1 2

# hugo.yaml timeZone: "Asia/Shanghai"
- 如果没配置，就使用编译机器的系统时区（即 TZ 环境变量或操作系统默认时区）。

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

解决方法

编译时加 --buildFuture 参数：
1

hugo --buildFuture
在 Hugo 配置文件中永久开启：
1 2

# hugo.yaml buildFuture: true
给文章日期加上具体时间和时区，确保落在"过去"：
1

date: 2026-04-17T00:00:00+08:00
在 Hugo 配置文件中设置默认时区，避免依赖系统环境：
1 2

# hugo.yaml timeZone: "Asia/Shanghai"

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

将博客迁移至 Hugo

Thu, 19 Mar 2026 00:00:00 +0000

前言

我的博客之前用的是 Astro 的某个主题，但是 Astro 作为博客构建工具的使用体验并不好，因为它本身的设计哲学实际更侧重于为文档站点服务。

前段时间 MoonWX 在 Q 群里分享 ntzyz 大佬的博客站，感觉大佬这个很简洁干练，不是很花哨，但是又很有技术博客的 feeling，而且并不丑，相反还蛮好看的。（顺带一提这位还是 BGP 大神，之后有空还想 peer 一下）

博客底部标注了由 Hugo 构建，使用 Hugo Theme Stack 主题，而且 Hugo Theme Stack 的 Github README 里提供了一个 starter 项目，可以作为 template 使用。那么我就直接用这个 starter 来搭建我的博客吧，希望能有个更好的使用体验。

Stack 主题在 README 中提供了双语文档，这里不多赘述。

迁移过程

托管到 GitHub Pages

首先按照常规操作，想要托管到 GitHub Pages 的话，使用 starter 的 template 来创建新的仓库的时候，需要注意仓库的命名最好为 <username>.github.io，这里我就是 sisypheovo.github.io，以便于直接被识别为 GitHub Pages 的托管仓库。

创建好仓库之后，在仓库的 Settings -> Pages 页面中，将 Build and deployment 中的 Source选项设置为 GitHub Actions，以便自动化部署，毕竟 starter 里已经提供了 GitHub Actions 的 workflow 文件了。

这样就完成了托管，在 https://sisypheovo.github.io/ 就可以直接访问到博客了，只不过内容还全是一些示例和模板，而且侧边栏之类的相比 ntzyz 大佬的博客也差远了.

使用自定义域名

常规来讲，要将任何普通内容部署到自己的域名下，最常用的做法肯定还是通过面板，比如 1Panel 之类的。购买并配置域名之后，把编译产物上传到服务器上就行了，然后配一配 DNS 解析、HTTPS 和反向代理等等配置就行了。

但是因为是使用 GitHub Pages 的静态博客，而且域名托管在 Cloudflare，就我知道的而言，有两种方法：

用 CNAME 文件配置自定义域名，并在 Cloudflare 中添加 CNAME 记录，指向 <username>.github.io，服务器只做 DNS 解析。
服务器使用反向代理，将自定义域名的请求转发到 GitHub Pages 的 URL 上。

我个人感觉第一种方法更简单一些，毕竟不需要额外的服务器来做反向代理了，而且有 Github Pages 提供的各种自动化和安全服务，还有免费的 HTTPS 和证书。

第二种就是可以自己做缓存、加速，自定义后端逻辑之类的，还能隐藏真实托管源，但是我也不太需要这些功能，所以就直接用第一种方法了。

首先去到 Cloudflare 的管理面板，在 域注册 -> 管理域 中选择对应的域名（我这里就是 sisy.cc），进入到域名的管理页面中，在 DNS -> 记录 选项卡中添加一条 CNAME 记录：

类型	名称	内容	代理状态	TTL	操作
CNAME	blog	sisypheovo.github.io	仅 DNS	自动	编辑

添加完成之后，还是回到仓库的 Settings -> Pages 页面中，将 Build and deployment 中的 Custom domain选项设置为 blog.sisy.cc，勾选上 Enforce HTTPS 选项，这样就完成了自定义域名的配置，过一段时间之后访问 blog.sisy.cc 就可以访问到博客了。

顺带一提，如果不是用 GitHub Pages，而是自己搭建的服务器，那么配置自定义域名的方式会有所不同，比如需要在编译产物的根目录下放置 CNAME 文件，内容是 blog.sisy.cc。

配置

这个主题我说白了用明白还是蛮好用的（等于不好上手吧，额），但是前期配置比较痛苦，因为它各个功能的配置项都比较分散，文档也不全，配置项上的注释也没几个字，很多东西莫名其妙的。

一些普通的配置解读

config/_default/markup.toml 文件中配置了 Markdown 的渲染方式，使用了 Goldmark 这个渲染器，并且启用了各种扩展功能，比如 Latex、表格、脚注、定义列表等等。
config/_default/modules.toml: 这个是 Hugo Modules 的配置文件，里面指定了使用的 Hugo Theme Stack 主题的版本和路径。
config/_default/permalinks.toml 文件中配置了文章的 URL 结构，比如 posts 的 URL 就是 /posts/:slug/，也就是 https://blog.sisy.cc/posts/xxx/ 这样的结构；page 的 URL 就是 /:slug/，也就是 https://blog.sisy.cc/xxx/。
config/_default/related.toml: 不知道，看不懂，先放着

`config.toml`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


baseurl = "https://blog.sisy.cc/" # 博客的基础 URL，用于生成链接和资源路径
languageCode = "zh" # 博客的默认语言代码，这里设置为中文
title = "Sisy's Blog" # 博客的标题，会显示在浏览器标签页、页脚的标注、头像下面的标题

# Theme i18n support
# See all available values at https://github.com/CaiJimmy/hugo-theme-stack/tree/master/i18n
defaultContentLanguage = "zh"

# Set hasCJKLanguage to true if DefaultContentLanguage is in [zh ja ko]
# This will make .Summary and .WordCount behave correctly for CJK languages.
hasCJKLanguage = true

# Disqus 评论系统的短名称，在 Disqus 上添加站点的时候会生成一个短名称，用于标识这个站点的评论系统
disqusShortname = "sisypheovo"

[pagination]
 pagerSize = 5

`_language.toml`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


# Rename this file to languages.toml to enable multilingual support
[zh]
 languageName = "中文" # 语言名称，会显示在页面左下角的语言切换器中
 languagedirection = "ltr" # 语言的书写方向，ltr 表示从左到右，rtl 表示从右到左
 title = "Sisy's Blog" # 博客标题，在中文环境下会覆盖掉 config.toml 中的 title 配置
 weight = 1 # 语言的权重，数值越小优先级越高。

[en]
 languageName = "English"
 languagedirection = "ltr"
 title = "Sisy's Blog"
 weight = 2

特别对于权重而言，像这样不是 en 权重最大的话，创建各个博客文章的 index markdown 文件的时候，必须要有 index.en.md、index.zh.md，而不是 index.md 和 index.zh.md，否则默认的 index.md 文件会被视为 zh 的版本。也要记得跟普通的 i18n 情况不一样，index.md 不再是 en 的默认版本了。

另外，对于如上配置，各语言下内容的 URL 结构为 /xxx/ 和 /en/xxx/。

非内容的各个字符串（比如页脚文本）的翻译，可以通过在 i18n/ 目录下创建对应语言的 TOML 文件来配置，比如 i18n/zh.toml 中可以配置中文环境下的各种字符串的翻译。默认部分可以直接从示例仓库的这里复制整个文件过来，非常方便。

`menu.toml`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


# 像这样在左侧菜单中添加一个不指向任何页面的链接菜单项
# 像这里我就做了一个 RSS 的链接，权重设置为 99，确保它在菜单的最下面显示。不过 icon 需要自己找一找。
# Hugo 的 RSS 订阅链接通常是 `/index.xml`，内容是由 Hugo 自动生成的，不需要手动创建。
[[main]]
 identifier = "rss"
 name = "RSS"
 url = "/index.xml"
 weight = 99

 [main.params]
 icon = "rss"

# 这个很好理解，是显示在头像和简介下方的社交链接，样例也给了两个 icon 状的示范。
[[social]]
 identifier = "github"
 name = "GitHub"
 url = "https://github.com/SisypheOvO"

 [social.params]
 icon = "brand-github"

关于自定义菜单内容，还可以参考这篇文档，除了在 menu.toml 文件中配置以 main 标识的这种非页面的链接菜单项之外，指向正常页面的菜单项是通过在各个页面（仓库中 /content/page/ 下的各个内容）各自的 index.md 文件前言部分中的 menu 字段来配置的。也就是说，各个 page 和每个菜单项是同步创建且一一对应的（除了在 menu.toml 中配置的项）。如以下这个简单的配置：

1
2
3
4
5
6
7


---
menu:
 main: # 默认是 main 就行
 weight: 4 # 标识这个 page 的排序，需要跨文件管理它们
 params:
 icon: people # 显示在菜单项左边的图标，默认是 svg 格式，放在 `static/icons/` 目录下
---

需要注意的是，如果想要添加一些自定义布局的页面，还最好需要额外创建一个 layouts/ 目录，在里面放置对应的自定义布局 HTML 文件。

以下是一个配置好的菜单示例：

`params.toml`

这个文件的配置项就比较多了，内容也比较杂乱，比如博客的主页显示、RSS 输出、favicon、文章排序、页脚信息、日期格式、侧边栏信息、文章信息、页面小部件、社交媒体信息、配色方案等等。关于这里配置的指导，在官方文档的这个 Config 部分解释的还是比较全面的，可以优先参考。

以下我挑一些非常适合新手起步的配置项来讲，其他要么已经解释的很清楚，要么就无需过多调整：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


favicon = "img/favicon.png" # 显示在浏览器标签页上的图标，写过 web 都懂

# 显示在所有页脚的内容
[footer]
 since = 2023 # 博客开始运营的年份，最终会显示为 "© 2023 - 2026 博客标题"
 customText = "sisy's blog" # 显示在 since 这一行下方

# 显示在博客右半侧的各种小组件，分为主页显示的和在子页面显示的组件两种
[widgets]
 homepage = [
 { type = "search" },
 { type = "archives", params = { limit = 5 } },
 { type = "categories", params = { limit = 10 } },
 { type = "tag-cloud", params = { limit = 10 } },
 ]
 page = [{ type = "toc" }]

[comments]
 enabled = true
 provider = "disqus" # 评论系统提供商

各个页面是否开启评论也可以通过在对应文件的前言中添加 comments: false 来单独控制，是否开启 toc 也是一样的，添加 toc: false 就行了。

以下是一个配置好的小组件示例：

优化

配置阶段就基本完结了，接下来就可以简单优化一下美观性了，比如我很想要 select 元素原始的下拉箭头，可以在 assets/scss/custom.scss 中添加：

1
2
3
4


.menu-bottom-section #i18n-switch select {
 appearance: auto;
 -webkit-appearance: auto;
}

Stack 主题适合用的两个 icon 源：Tabler、SVG Repo.

这一系列流程下来，博客就基本上安定下来，后续唯一的工作就是将旧的文章转移过来，然后写点新东西了。