# 主题组件
> 把主题拆成多个组件，通过继承与覆盖顺序组合成一套完整主题。
- 官方英文原文：https://gohugo.io/hugo-modules/theme-components/
- 本页规范地址：https://hugozh.cn/hugo-modules/theme-components/
- 最近更新：2026-10-02
- 最后提交：912b1d3 chore(site): 添加 static/CNAME（hugozh.cn），供 GitHub Pages 等平台绑定自定义域名
- 站点：Hugo 中文文档（https://hugozh.cn/）· 社区维护的非官方中文翻译，如有出入以官方英文原文为准

---
## 把主题组合起来

一个项目可以把主题配置为任意多个主题组件（theme component）的组合：

```toml
theme = ["my-shortcodes", "base-theme", "hyde"]
```

这种组合还可以嵌套：主题组件本身也能在自己的 `hugo.toml` 中引入其他主题组件，这就是主题继承（theme inheritance）。

上面的定义在 `hugo.toml` 中创建了一个由 3 个主题组件构成的主题，优先级从左到右排列。查找任意文件、数据条目等内容时，Hugo 会先看项目本身，然后是 `my-shortcodes`、`base-theme`，最后才是 `hyde`。

## 覆盖顺序

Hugo 会根据文件类型使用两套不同的合并算法：

| 文件类型 | 合并方式 | 优先级规则 |
| --- | --- | --- |
| `i18n` 与 `data` 文件 | 按文件内部的翻译 ID 与数据键深度合并 | 键相同时以最靠左的值为准 |
| `static`、`layouts`（模板）与 `archetypes` 文件 | 按文件层级合并 | 最靠左的那份文件被选用 |

也就是说，内容与数据的合并发生在键的粒度上，同一份翻译表或数据文件里的不同条目可以来自不同模块；而静态文件与模板的合并发生在整个文件的粒度上，只能「整份替换」，不能把两个模板拼在一起。

## 名称与配置

`theme` 定义中使用的名称必须与站点 `/themes` 目录下的某个子目录同名，例如 `/your-site/themes/my-shortcodes`。

还需要注意，作为主题一部分的组件可以有自己的配置文件（例如 `hugo.toml`）。目前主题组件能够配置的内容有一些限制：

- `params`（全局与各语言）
- `menu`（全局与各语言）
- `outputformats` 与 `mediatypes`

这里同样适用前述规则：ID 相同时，最靠左的参数、菜单等取值会胜出。上述命名空间支持中还留有一些隐藏且处于实验阶段的用法，官方会继续改进；同时官方也鼓励主题作者自行建立命名空间，以免名称冲突。

## 与模块机制的关系

主题组件的查找顺序并不是一套独立机制，而是模块导入优先级在主题上的体现：`theme` 中列出的组件相当于被依次导入，越靠前优先级越高，项目自身的文件则始终排在最前面。因此，覆盖主题中的某个模板，只需在项目里放置相对路径相同的文件；覆盖翻译表中某一条译文，也只需在项目里定义同一个翻译 ID。

关于模块的导入、更新与挂载，见[使用模块](/hugo-modules/use-modules/)；关于项目目录的职责划分，见[目录结构](/getting-started/directory-structure/)。