Hugo 的特殊目录

2026年2月1日星期日 · simons · 本文共 1940 个字，预计需要阅读 4 分钟

Hugo 的特殊目录遵循“约定优于配置”原则，每个目录都有特定用途。以下是所有特殊目录的详细说明：

📁 核心目录结构

your-site/
├── archetypes/          # 内容模板
├── assets/             # 资源文件（预处理器处理）
├── config/             # 配置文件
├── content/            # 网站内容（核心）
├── data/               # 数据文件
├── layouts/            # 布局模板
├── static/             # 静态文件（直接复制）
├── themes/             # 主题目录
├── i18n/               # 国际化翻译文件
├── resources/          # 缓存资源（Hugo生成）
├── public/             # 最终输出（构建后生成）
└── hugo.toml           # 配置文件（可选位置）

🔧 详细目录解析

1. `archetypes/` - 内容模板

作用：定义新内容页面的初始 Front Matter 模板

hugo new posts/my-post.md  # 使用 archetype 创建内容

文件示例 archetypes/posts.md：

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

2. `assets/` - 资源处理目录

作用：存放需要 Hugo Pipes 处理的文件（Sass/SCSS、JS、图像处理）

assets/
├── css/
│   ├── main.scss       # 会被编译为 CSS
│   └── variables.scss
├── js/
│   ├── app.js          # 可被压缩、合并
│   └── vendor/
└── images/
    └── logo.svg        # 可被处理

模板中使用：

{{ $css := resources.Get "css/main.scss" | toCSS | minify | fingerprint }}
<link rel="stylesheet" href="{{ $css.Permalink }}">

3. `config/` - 配置目录（可选）

作用：替代单一配置文件，支持模块化配置

config/
├── _default/           # 默认配置
│   ├── hugo.toml
│   ├── menus.toml
│   └── params.toml
├── production/         # 生产环境配置
└── development/       # 开发环境配置

4. `content/` - 内容核心

作用：所有网站内容的 Markdown 文件

content/
├── _index.md          # 主页
├── about/
│   └── index.md      # about页面
├── posts/            # 文章章节
│   ├── _index.md     # 文章列表页
│   ├── first-post.md
│   └── second-post.md
└── blog/             # 另一个章节
    └── _index.md

5. `data/` - 数据文件

作用：存储 YAML、JSON、TOML 或 XML 格式的数据，可在模板中使用

data/
├── authors.yaml       # 作者信息
├── settings.json      # 网站设置
└── products/
    └── list.toml     # 产品数据

data/authors.yaml 示例：

- id: john
  name: John Doe
  bio: Web Developer
  avatar: /images/john.jpg

模板中使用：

{{ range site.Data.authors }}
  <div>{{ .name }} - {{ .bio }}</div>
{{ end }}

6. `layouts/` - 布局模板

作用：定义网站的外观和结构，覆盖主题的布局

layouts/
├── _default/          # 默认布局
│   ├── baseof.html   # 基础模板
│   ├── list.html     # 列表页
│   └── single.html   # 单页
├── partials/          # 可重用组件
│   ├── header.html
│   ├── footer.html
│   └── sidebar.html
├── shortcodes/        # 短代码
├── 404.html          # 404页面
├── index.html        # 主页布局
└── section/
    └── posts.html    # posts章节专用布局

7. `static/` - 静态文件

作用：直接复制到 public/ 目录，不经过处理

static/
├── favicon.ico
├── robots.txt
├── downloads/
│   └── manual.pdf    # 直接访问 /downloads/manual.pdf
└── old-site/         # 旧站点文件

8. `themes/` - 主题目录

作用：存放主题文件，可多个主题

themes/
└── my-theme/         # 主题包含相同目录结构
    ├── layouts/
    ├── assets/
    ├── static/
    └── theme.toml

9. `i18n/` - 国际化文件

作用：多语言翻译字典

i18n/
├── en.toml           # 英文翻译
├── zh.toml           # 中文翻译
└── ja.yaml           # 日文翻译

10. `resources/` - 资源缓存（自动生成）

作用：Hugo 处理资源时的缓存目录，不应手动修改

resources/_gen/       # 生成的资源缓存
├── assets/
├── images/
└── js/

11. `public/` - 最终输出（构建后生成）

作用：包含完整的静态网站，可部署到任何服务器

hugo                  # 生成 public/ 目录
hugo -d ./docs        # 指定输出目录

🎯 优先级规则（重要！）

当相同文件出现在多个位置时，Hugo 按以下优先级使用：

项目根目录 → 主题目录

具体路径优先级（从高到低）：

layouts/ (项目) → layouts/ (主题)
assets/ (项目) → assets/ (主题)
static/ (项目) → static/ (主题)
content/ (项目) → content/ (主题)
data/ (项目) → data/ (主题)
i18n/ (项目) → i18n/ (主题)
archetypes/ (项目) → archetypes/ (主题)

📊 目录功能对比表

目录	是否必需	是否处理	构建时	示例用途
content/	✅ 是	✅ Markdown渲染	生成HTML	博客文章、页面
layouts/	❌ 否	✅ Go模板渲染	生成HTML	页面布局、组件
static/	❌ 否	❌ 直接复制	原样复制	图片、PDF、字体
assets/	❌ 否	✅ 资源管道	处理优化	SCSS编译、JS压缩
data/	❌ 否	✅ 数据加载	加载到内存	配置文件、元数据
archetypes/	❌ 否	✅ 模板扩展	创建时使用	文章模板
i18n/	❌ 否	✅ 翻译加载	加载到内存	多语言字符串
config/	❌ 否	✅ 配置解析	启动时加载	网站设置

🛠️ 实用工作流示例

1. 创建新文章

# 使用 archetype 模板
hugo new posts/2024/my-article.md

# 不使用模板
hugo new --kind post posts/2024/another-article.md

2. 处理资源文件

{{/* 处理 SCSS 文件 */}}
{{ $styles := resources.Get "scss/main.scss" | toCSS | postCSS | minify }}

{{/* 处理并调整图片 */}}
{{ $image := resources.Get "images/photo.jpg" }}
{{ $small := $image.Resize "300x" }}
{{ $medium := $image.Resize "600x" }}
<img src="{{ $small.RelPermalink }}" srcset="{{ $small.RelPermalink }} 300w, {{ $medium.RelPermalink }} 600w">

3. 组织大型项目

my-site/
├── content/
│   ├── en/           # 英文内容
│   └── zh/           # 中文内容
├── layouts/
│   ├── _default/
│   └── partials/
│       ├── header/
│       ├── footer/
│       └── widgets/
├── assets/
│   ├── scss/
│   │   ├── components/
│   │   └── pages/
│   └── js/
│       ├── modules/
│       └── vendors/
└── data/
    ├── team/         # 团队成员
    ├── products/     # 产品目录
    └── settings/     # 配置数据

💡 最佳实践

保持 content/ 整洁：只放 Markdown 文件，资源放在 assets/ 或 static/
利用 assets/ 处理：图片压缩、CSS/JS 优化通过 assets/ 完成
渐进式覆盖：从主题复制需要的布局文件到项目 layouts/ 进行修改
数据驱动内容：动态内容使用 data/ 目录管理
版本控制排除：将 resources/_gen/ 和 public/ 加入 .gitignore

🚀 部署建议

# 完整构建命令
hugo \
  --minify \          # 压缩 HTML、CSS、JS
  --cleanDestinationDir \  # 清理输出目录
  --environment production

# 只构建特定语言
hugo --config config_zh.toml

# 带草稿构建（用于预览）
hugo --buildDrafts

理解这些特殊目录的作用和优先级，能让你更高效地组织和管理 Hugo 项目。每个目录都有其明确职责，遵循这个结构能让项目保持清晰和可维护。