Hugo 静态网站构建实战手册

项目结构

深入了解 Hugo 项目的标准目录、页面包、资源目录和模板覆盖规则

项目结构 #

Hugo 项目遵循约定式目录结构。理解每个目录的职责，能帮助你快速判断文件应该放在哪里、为什么主题可以被覆盖、为什么某些资源会被处理而另一些会被原样复制。

标准目录 #

my-hugo-site/
├── archetypes/      # 新建内容时使用的原型模板
├── assets/          # 需要 Hugo Pipes 处理的资源
├── content/         # Markdown、HTML 等内容文件
├── data/            # JSON、YAML、TOML 数据文件
├── i18n/            # 多语言翻译文件
├── layouts/         # 站点级模板，会覆盖主题模板
├── static/          # 原样复制到 public/ 的静态文件
├── themes/          # 主题目录
├── public/          # 构建输出目录，通常不提交
├── resources/       # 资源处理缓存，通常不提交
└── hugo.toml        # 站点配置文件

archetypes/ #

archetypes/ 用来定义新建内容时的默认 Front Matter。运行 hugo new content posts/hello.md 时，Hugo 会根据内容路径选择合适的 archetype。

常见默认模板：

---
title: "{{ replace .File.ContentBaseName "-" " " | title }}"
date: {{ .Date }}
draft: true
categories: []
tags: []
description: ""
---

可以为不同栏目创建专用模板：

archetypes/
├── default.md
├── posts.md
└── docs.md

assets/ #

assets/ 存放需要 Hugo 处理的资源，例如：

  • SCSS/Sass
  • 需要打包的 JavaScript 或 TypeScript
  • 需要裁剪、压缩、生成 WebP 的图片
  • 需要加指纹哈希的 CSS、JS、字体

模板中用 resources.Get 读取：

{{ $css := resources.Get "scss/main.scss" | css.Sass | minify | fingerprint }}
<link rel="stylesheet" href="{{ $css.RelPermalink }}" integrity="{{ $css.Data.Integrity }}">

如果资源需要构建、压缩、指纹、图片处理，优先放到 assets/。

content/ #

content/ 是网站内容的根目录。Hugo 会根据目录生成 Section，根据 Front Matter 生成页面元数据。

示例：

content/
├── _index.md
├── about.md
├── posts/
│   ├── _index.md
│   ├── my-first-post.md
│   └── 2026/
│       └── hugo-notes.md
└── docs/
    ├── _index.md
    └── hugo-tutorial/
        ├── _index.md
        └── quick-start.md

_index.md 与普通页面 #

_index.md 表示分支页面，通常对应栏目首页或列表页。

content/posts/_index.md  -> /posts/
content/docs/_index.md   -> /docs/

普通 Markdown 文件表示单页：

content/about.md                -> /about/
content/posts/my-first-post.md  -> /posts/my-first-post/

Page Bundles #

Page Bundles 可以把页面和相关资源放在一起，适合图文文章、文档附件、作品集页面。

Leaf Bundle #

Leaf Bundle 表示单个页面，入口文件是 index.md：

content/posts/my-trip/
├── index.md
├── cover.jpg
├── gallery-1.jpg
└── route.pdf

在模板中可以通过 Page Resources 获取同目录资源：

{{ with .Resources.GetMatch "cover.jpg" }}
  {{ $img := .Resize "1200x webp" }}
  <img src="{{ $img.RelPermalink }}" alt="{{ $.Title }}">
{{ end }}

Branch Bundle #

Branch Bundle 表示栏目或分支，入口文件是 _index.md：

content/docs/hugo-tutorial/
├── _index.md
├── overview.md
└── quick-start.md

它可以包含子页面、子栏目和栏目资源。

data/ #

data/ 存放结构化数据，支持 JSON、YAML、TOML。适合放作者信息、友情链接、产品列表、团队成员等。

示例：

# data/authors.yaml
kok:
  name: KOK
  bio: 用一段文字记录生命的成长
  url: https://kok.plus

模板中读取：

{{ with site.Data.authors.kok }}
  <a href="{{ .url }}">{{ .name }}</a>
{{ end }}

i18n/ #

i18n/ 用于多语言翻译。例如：

# i18n/zh.toml
[read_more]
other = "阅读全文"

# i18n/en.toml
[read_more]
other = "Read more"

模板中使用：

{{ i18n "read_more" }}

layouts/ #

layouts/ 存放站点级模板。它的优先级高于主题里的 themes/主题名/layouts/，因此常用于覆盖主题模板。

常见结构：

layouts/
├── _default/
│   ├── baseof.html
│   ├── list.html
│   └── single.html
├── partials/
│   ├── head.html
│   ├── header.html
│   └── footer.html
├── shortcodes/
│   └── notice.html
├── posts/
│   └── single.html
└── 404.html

覆盖规则的核心思路：

  • 站点根目录 layouts/ 优先于主题 layouts/
  • 更具体的模板优先于通用模板
  • Section 模板优先于 _default 模板

例如 content/posts/hello.md 会优先寻找 layouts/posts/single.html，找不到再使用 layouts/_default/single.html。

static/ #

static/ 中的文件会原样复制到 public/，不经过 Hugo Pipes。

static/
├── images/avatar.jpg    -> /images/avatar.jpg
├── favicon.ico          -> /favicon.ico
└── files/resume.pdf     -> /files/resume.pdf

适合放：

  • favicon
  • 不需要处理的图片
  • PDF、压缩包、验证文件
  • 第三方静态脚本

如果图片需要裁剪、转 WebP、生成不同尺寸，建议放到 Page Bundle 或 assets/。

themes/ #

themes/ 存放主题。主题可以通过下载、Git submodule、Git subtree 或 Hugo Modules 引入。

themes/
└── ananke/
    ├── archetypes/
    ├── assets/
    ├── layouts/
    ├── static/
    └── theme.toml

不建议直接修改第三方主题源码。更推荐：

  • 在站点 layouts/ 中覆盖模板
  • 在站点 assets/ 或 static/ 中添加自定义资源
  • 使用主题提供的配置项
  • 真要深度修改时 fork 主题

public/ 与 resources/ #

public/ 是构建输出目录：

hugo --minify

Hugo 会把生成结果写入 public/。这个目录通常不提交到主分支，除非你的部署流程明确要求提交构建产物。

resources/ 是资源处理缓存，常见于图片处理、Sass 编译等场景。它可以加速构建，但一般也不需要提交。

.gitignore 常见写法：

/public/
/resources/
/.hugo_build.lock

配置文件 #

Hugo 支持 TOML、YAML、JSON 三种配置格式：

hugo.toml
hugo.yaml
hugo.json

推荐新项目使用 hugo.toml。复杂项目可以拆分到 config/ 目录：

config/
├── _default/
│   ├── hugo.toml
│   ├── menus.toml
│   └── params.toml
├── production/
│   └── hugo.toml
└── development/
    └── hugo.toml

文件放置判断 #

需求推荐位置
写文章、页面、文档content/
文章私有图片Page Bundle
全站头像、favicon、附件static/
需要编译和加指纹的 CSS/JSassets/
可复用页面结构layouts/partials/
自定义短代码layouts/shortcodes/
结构化数据data/
多语言翻译i18n/

下一步 #

继续阅读 配置管理，学习如何让站点真正按你的规则运行。

评论

0%