梦行志Hugo 里该用 index.zh-cn.md，还是文章同名 .md？
码艺轩｜为什么我的文章目录更适合用 index.zh-cn.md
很多时候，一个文件名看起来只是习惯问题，但在 Hugo 里，它其实关系到页面是不是 page bundle、资源文件能不能跟着文章走、以及多语言版本会不会被正确识别。
这次我就遇到了一个很实际的问题：对于这篇文章，我到底应该用 P:\oklifeme\content\posts\code-art-studio\hugo-loveit-shortcode-debug\index.zh-cn.md，还是 P:\oklifeme\content\posts\code-art-studio\hugo-loveit-shortcode-debug\hugo-loveit-shortcode-debug.md？
如果只凭直觉，很多人会觉得第二种更“工整”，因为文件名和文章 slug 一样，看起来更直观。但如果把 Hugo 的 page bundle 和多语言机制一起考虑进去，答案其实没有那么随意。
先说结论
在我这个场景里，我更推荐使用：index.zh-cn.md。
原因很简单：我的文章已经放在一个独立目录里，这个目录本身就是为了和封面图、正文插图、其他资源文件放在一起使用的；而 Hugo 的 leaf bundle 正是围绕 index.md 这一类文件命名建立起来的。
同时，Hugo 的多语言内容支持文件名后缀形式，像 about.fr.md、my-page.zh-cn.md 这样的命名会被 Hugo 识别为对应语言的内容文件，而没有语言后缀的文件则会落到默认语言上。
也就是说，index.zh-cn.md 这类命名其实同时满足了两件事：
- 它是 page bundle 体系下的主内容文件命名方式。
- 它又能明确告诉 Hugo：这是一篇
zh-cn语言版本的文章。
为什么不是同名 slug 文件
hugo-loveit-shortcode-debug.md 这种命名当然不是绝对错误，但它更像是“普通单文件页面”的思路，而不是“目录型 leaf bundle”的思路。
Hugo 对 leaf bundle 的典型结构，是在某个目录里放一个 index.md 作为页面主体，然后把封面图、插图、PDF、元数据等资源放在同目录或子目录中，由这个 bundle 一起管理。
换句话说，如果你已经采用了这种结构：
content/posts/code-art-studio/hugo-loveit-shortcode-debug/
├── index.zh-cn.md
├── cover.webp
└── images/
├── 01-debug-start.webp
├── 02-deep-night-debug.webp
├── 03-bug-core.webp
└── 04-ending-mood.webp那这个目录本身就已经在表达：“这是一篇页面文章 + 一组页面资源”的 bundle。在这种前提下，再把正文文件命名成 hugo-loveit-shortcode-debug.md，就会显得不如 index.zh-cn.md 那么贴合 Hugo 的 bundle 约定。
page bundle 真正解决了什么
很多人第一次接触 Hugo 时，会把“文章 Markdown 文件”和“文章资源文件”分开理解。但 page bundle 的价值就在于：它把一篇文章和它相关的附件资源当成一个整体管理。
这意味着当你用 leaf bundle 时：
- 封面图可以跟文章放在同一个目录里。
- 正文里的插图可以放在
images/子目录里统一引用。 - 页面资源的组织方式会更稳定，也更适合后期维护。
而这个机制的中心，就是 index.md 这一类文件。所以如果你的文章目录已经明显是 bundle 结构，正文文件就最好不要再走“普通文件页”的命名思路。
多语言场景下为什么更该用 index.zh-cn.md
如果站点配置了多语言，Hugo 会根据文件名中的语言后缀去识别页面属于哪个语言版本，比如 my-page.en.md、my-page.fr.md、my-page.zh-cn.md 这种写法。
对 leaf bundle 来说，这种规则同样适用。所以如果你的站点已经在用中文语言代码，或者未来准备加英文版本，那么：index.zh-cn.md 是一个非常顺手的命名。
因为以后你如果要补英文版，直接在同目录下加一个 index.en.md 即可，结构会非常统一。
那什么时候不该用 index.zh-cn.md
也不是所有场景都必须上 index.zh-cn.md。如果你的站点根本没有启用多语言，那 Hugo 并不需要你额外通过文件名去声明 zh-cn，这时最理想的命名通常就是单纯的：index.md。
没有语言后缀的内容文件会归到默认语言上，而默认语言由站点配置决定。所以更准确地说，在你的两个候选项里，我推荐 index.zh-cn.md；但如果把范围放大到“最优命名”，那还要再看你站点有没有真正启用多语言。
回到我的实际项目
对我这篇文章来说，目录里已经放了封面图、正文插图，未来可能还会继续增加预览图或其他资源。这本质上已经是一个标准的 leaf bundle 使用场景了。
既然如此，再结合中文语言版本的需求，index.zh-cn.md 就是更顺手、也更符合 Hugo 习惯的方案。而 hugo-loveit-shortcode-debug.md 虽然文件名看起来更像文章 slug，但它更适合“不走 bundle 目录”的单文件内容思路，不适合我现在这种“文章和资源一起打包管理”的结构。
最后的建议
如果你和我一样，文章目录已经是这种结构：content/posts/code-art-studio/hugo-loveit-shortcode-debug/，那就优先这样命名：
- 已启用多语言：
index.zh-cn.md - 没启用多语言：
index.md
至于 hugo-loveit-shortcode-debug.md，它不是不能用，但放在这个目录结构里，不是最贴合 Hugo page bundle 逻辑的选项。
文件名这件事，表面看很小。但一旦你开始认真整理封面图、正文插图、预览图、SEO 图片、多语言版本，那个更符合框架习惯的命名方式，后面会替你省下很多重复调整的时间。
–全文完–
“同频之人，终会相遇；同行之路，终有光亮。”
“技术终归是工具，而我们一次次认真把问题理顺，守住的其实不只是页面样式和代码输出，还有那一点不愿被混乱打败的心气，是每一个深夜仍愿点灯前行的人。”
「码艺轩・以技立身，实干谋生」系列 · 持续更新
本文采用 CC BY-NC-SA 4.0 许可协议，转载请注明来自：https://oklife.me。
