# 简介
> 模块的基本概念、可提供的组件类型，以及模块化带来的好处。
- 官方英文原文：https://gohugo.io/hugo-modules/introduction/
- 本页规范地址：https://hugozh.cn/hugo-modules/introduction/
- 最近更新：2026-10-02
- 最后提交：912b1d3 chore(site): 添加 static/CNAME（hugozh.cn），供 GitHub Pages 等平台绑定自定义域名
- 站点：Hugo 中文文档（https://hugozh.cn/）· 社区维护的非官方中文翻译，如有出入以官方英文原文为准

---
## 模块是什么

Hugo 用模块（module）作为最基本的组织单位。一个模块既可以是一个完整的 Hugo 项目，也可以是更小的、可复用的片段，用来提供 Hugo 七类组件（component）中的一类或几类：

| 组件类型 | 目录 | 说明 |
| --- | --- | --- |
| 静态文件 | `static/` | 构建时原样复制的文件 |
| 内容 | `content/` | 页面、页面包与页面资源 |
| 布局 | `layouts/` | 模板与局部模板 |
| 数据 | `data/` | 数据文件，供模板读取 |
| 资源 | `assets/` | 交给资源管道处理后再发布的文件 |
| 国际化资源 | `i18n/` | 翻译表 |
| 原型 | `archetypes/` | 新建内容时使用的模板 |

也就是说，模块能共享的不只是主题外观，还包括内容、数据、翻译与内容骨架。

## 统一文件系统

模块可以按任意方式组合，并且可以把外部目录挂载进来，包括那些并非 Hugo 项目的目录。挂载之后，效果上就得到了一个统一的文件系统：Hugo 查找内容、模板、资源与数据时，看到的是同一棵目录树，而不必关心某个文件原本属于项目、主题还是别的仓库。

结合模块导入的优先级，这套机制让「复用」与「覆盖」变成同一件事：项目里放一份同路径的文件，就能覆盖来自模块的那一份。

## 示例项目

官方文档给出了两个可以直接参考的项目：

<https://github.com/bep/docuapi>
: 一个在测试该功能时迁移到 Hugo 模块的主题，很适合用来说明「非 Hugo 项目如何挂载进 Hugo 的目录结构」。

<https://github.com/bep/my-modular-site>
: 一个用于测试的简单站点。

第一个示例尤其值得留意：它原本不是 Hugo 项目，但通过挂载，把自身的文件纳入了 Hugo 的组件目录中。这正是模块机制区别于传统主题安装方式的地方——不必把文件复制或搬运到项目里，也不必要求来源项目遵循 Hugo 的目录约定。

## 与其他章节的关系

要从零开始把一个项目变成模块，需要先安装 Git 与 Go，再执行 `hugo mod init`，然后在配置中声明导入，见[使用模块](/hugo-modules/use-modules/)。主题现在也以模块的形式分发，多个主题可以组合成一套主题，其查找与覆盖顺序见[主题组件](/hugo-modules/theme-components/)。如果模块带有需要构建的前端依赖，见 [Node.js 依赖](/hugo-modules/nodejs-dependencies/)。

模块把组件的搜索范围从项目目录扩展到了远端仓库与任意本地目录，因此项目目录结构的含义也随之放大：项目里的同名文件始终拥有更高的优先级。