Hugo有个特别坑的地方。
你写了一篇文章，push上去了，但网站上看不到。
没有报错，没有提示，就是看不到。
可能的原因，我踩过不止一次。
原因一：draft:true
这个最常见。
Hugo新建的文章，默认draft是true。
---
title: "我的文章"
date: 2026-05-08
draft: true # 草稿，不发布
---
发布前要改成false。
draft: false
或者在frontmatter里直接不写这一行，默认就是false。
原因二：frontmatter格式错误
Hugo支持三种frontmatter格式：YAML、TOML、JSON。
我用的是YAML，最容易出错。
YAML对缩进敏感：
# 正确
title: "标题"
tags: [tag1, tag2]
# 错误：缩进不对
title: "标题"
tags: [tag1, tag2]
YAML对引号敏感：
# 单引号、双引号都可以
title: "标题"
title: '标题'
# 但引号不匹配会出错
title: "标题' # 错误
原因三：文件名含特殊字符
Hugo文件名支持英文、数字、中文、中划线、下划线。
不支持的字符，比如:、?、#，会导致解析问题。
建议文件名只用：
- 英文小写
- 数字
- 中划线
- - 下划线
_
比如：my-first-post.md ✓
我的文章.md ✓
My First Post.md ✗ （有空格）
原因四：categories/tags格式不对
如果用了categories或tags，要确保格式正确。
# 正确：数组格式
tags: [tag1, tag2]
categories: [实战方法论]
# 错误：字符串格式（虽然有些主题支持）
tags: "tag1"
数组格式是标准写法。
原因五：日期格式不对
日期格式要标准：
# 标准ISO格式
date: 2026-05-08
# 带时间
date: 2026-05-08T10:30:00+08:00
如果日期写成了2026/05/08或者2026.05.08，可能会出问题。
原因六：路径问题
Hugo文章放在content/posts/目录下。
如果目录名不对，或者文章放错了位置，就不会显示。
比如：
content/post/（少了个s）→ 不行content/posts/my-article/（放进了子目录）→ 主题可能不支持
确保文章直接在content/posts/下。
排查方法
如果文章不显示，怎么排查？
方法一：本地预览
hugo server --buildDrafts
加--buildDrafts可以看到草稿。
本地能看到的，服务器上一般也能看到。
如果本地看不到，就是文件本身有问题。
方法二：检查hugo stats
hugo
看看有没有报错信息。
方法三：检查config
确认[taxonomies]里定义了tag和category：
[taxonomies]
tag = "tags"
category = "categories"
如果不定义，tags和categories不起作用。
我的教训
有一次我写了好几篇文章，push上去发现只有两篇显示。
查了半天，发现那三篇的frontmatter里draft:写的是true。
改完push，才显示出来。
还有一个教训：
创建完源文件后，必须确认content/posts/目录里有对应文件。
有时候文件名打错了，或者放错位置了，不容易发现。
养成习惯：创建完就ls看一眼。
总结
Hugo文章不显示的六个原因：
- draft:true → 改成false
- frontmatter格式错误 → 检查缩进和引号
- 文件名含特殊字符 → 改成纯英文或中文
- categories/tags格式不对 → 用数组格式
- 日期格式不对 → 用ISO格式
- 路径问题 → 确认在content/posts/下
排查用hugo server --buildDrafts本地预览。
习惯：创建完文件就确认一下目录。