0008 - Hugo 博客文章排序问题：从踩坑到解决

需求背景

我希望博客首页的文章能按标号倒序排列，即：

0007 → 0006 → 0005 → 0004 → 0003 → 0002 → 0001

最新的文章（标号最大）显示在最上面，最早的文章（标号最小）显示在最下面。

踩坑过程

尝试一：修改 hugo.toml 配置

想法：在配置文件中添加排序参数

操作：在 hugo.toml 中添加：

[params]
order = "desc"

结果：❌ 失败，没有任何效果

原因：PaperMod 主题不支持这个参数，Hugo 也没有这个内置配置项

尝试二：自定义 home.html 按日期倒序

想法：创建自定义首页模板，强制按日期倒序

操作：创建 layouts/_default/home.html，添加：

{{- $pages = $pages.ByDate.Reverse }}

结果：❌ 失败，排序仍然不对

原因：大部分文章的日期都是同一天（2026-03-07），Hugo 无法区分同一天的文章顺序

尝试三：自定义 home.html 按标题倒序

想法：既然日期相同，那就按标题排序

操作：修改 layouts/_default/home.html，添加：

{{- $pages = sort $pages "Title" "desc" }}

结果：❌ 失败，排序仍然不对

原因：标题中包含中文，字符串排序结果不符合预期

尝试四：为文章添加精确时间戳 ✅

想法：既然日期相同导致无法区分，那就给每篇文章添加精确的时间戳

操作：修改每篇文章的 Front Matter，添加具体时间：

# 0001 号文章
date: 2026-03-07T01:00:00+08:00

# 0002 号文章
date: 2026-03-07T02:00:00+08:00

# 0003 号文章
date: 2026-03-07T03:00:00+08:00

# ... 以此类推

结果：✅ 成功！文章按时间戳倒序正确排列

问题根源分析

为什么之前的尝试都失败了？

1. Hugo 默认按日期排序：Hugo 默认使用 date 字段对文章排序
2. 日期精度不足：当多篇文章日期相同时，Hugo 无法区分它们的顺序
3. 同一天发布多篇文章：我在同一天发布了 6 篇文章（0001-0006），它们的 date 都是 2026-03-07

为什么时间戳方案有效？

时间戳格式 2026-03-07T01:00:00+08:00 包含：

• 日期：2026-03-07
• 时间：01:00:00
• 时区：+08:00

这样即使是同一天发布的文章，也能通过具体时间区分顺序。

最终解决方案

步骤一：删除自定义模板

如果之前创建了 layouts/_default/home.html，先删除它：

rm layouts/_default/home.html

让 Hugo 使用默认的排序方式。

步骤二：为每篇文章添加精确时间戳

修改每篇文章的 Front Matter：

---
title: "0001 - 文章标题"
date: 2026-03-07T01:00:00+08:00    # 添加具体时间
lastmod: 2026-03-07T01:00:00+08:00  # 同步更新 lastmod
draft: false
---

步骤三：时间戳命名规则

为了方便管理，我采用了以下规则：

这样编号和时间戳一一对应，方便记忆和维护。

步骤四：构建并部署

cd /Users/wsq/Documents/blog_wqq/my-tech-blog
hugo
cd public
git add .
git commit -m "为文章添加精确时间戳"
git push -f origin main

经验总结

1. Hugo 排序机制

Hugo 默认按 date 字段排序，支持以下排序方式：

2. 时间戳格式

Hugo 支持多种日期格式：

2026-03-07              # 只有日期
2026-03-07T01:00:00     # 日期 + 时间
2026-03-07T01:00:00+08:00  # 完整格式（推荐）

推荐使用完整格式，包含时区信息，避免时区问题。

3. 最佳实践

1. 新文章发布时：立即添加精确时间戳
2. 时间戳规则：按文章编号递增，方便管理
3. 同步更新 lastmod：保持 date 和 lastmod 一致
4. 避免同日期：即使是同一天发布，也要用不同时间区分

快速命令参考

批量修改时间戳

如果需要批量修改多篇文章的时间戳，可以使用以下命令：

# 查看当前所有文章的日期
grep -r "^date:" content/posts/

# 使用 sed 批量替换（示例）
sed -i '' 's/date: 2026-03-07$/date: 2026-03-07T01:00:00+08:00/' content/posts/0001-*.md

验证排序结果

本地预览：

hugo server -D

然后访问 http://localhost:1313/ 查看排序效果。

常见问题

Q1: 为什么不用 weight 参数？

Hugo 支持 weight 参数来手动指定排序权重，但需要额外配置：

---
title: "文章标题"
weight: 1  # 数字越小越靠前
---

这种方式需要手动管理权重，不如时间戳直观。

Q2: 能不能按文件名排序？

可以，但需要自定义模板：

{{- $pages = sort $pages "File.TranslationBaseName" "desc" }}

不过这种方式对文件名格式有要求，不如时间戳灵活。

Q3: 如何让旧文章也能正确排序？

对于已有的旧文章，需要逐个修改时间戳。建议：

1. 先确定每篇文章的发布顺序
2. 按顺序分配时间戳
3. 批量修改并部署

总结

解决 Hugo 文章排序问题的关键是：确保每篇文章有唯一的、可排序的时间标识。

通过添加精确时间戳，我们实现了：

• ✅ 文章按标号倒序排列
• ✅ 同一天发布的文章也能区分顺序
• ✅ 排序规则简单易懂
• ✅ 方便后续维护

希望这篇踩坑记录能帮助到遇到类似问题的朋友！

完成时间：2026-03-08