文档章节
Hugo 模块
用模块管理站点的内容、呈现与行为:讲清模块解决什么问题、挂载与导入怎么用,并给出可运行示例、验证方法与常见坑。
开始之前,你需要
读完之后你能
- 说出模块能提供的七类组件,并解释「统一文件系统」把项目、主题、外部目录放在一起查找意味着什么;
- 用
[[module.mounts]]把项目外的目录挂进content、layouts、static、data,并解释为什么挂载是覆盖式的、必须把默认挂载写回去; - 用
[[module.imports]]引入模块,并判断同名文件、同名短代码、同一条译文最终由谁生效; - 把主题配成多个组件的组合,预测某个模板或某条译文来自哪个主题;
- 把模块的 Node.js 依赖汇总进
packages/hugoautogen/,并读懂npm dependencies are out of sync警告。
接着读:简介 · 使用模块 · 主题组件 · Node.js 依赖 · 模块配置
这一页解决什么问题
主题、短代码库、共享内容、前端依赖,在 Hugo 里都由模块(module)承载。这一章要回答的是同一个问题的两面:怎么把别人写好的东西拿来用,以及怎么只盖掉其中不满意的那一小部分。读完你能看懂一份 hugo.toml 里的 [module] 段在做什么,也能自己把项目之外的目录接进站点。
本章只讲「怎么用起来、用错会看到什么现象」,不是 [module] 的参考手册——每个配置键的类型、默认值与取值请查模块配置。
章节概览
Hugo 把模块(module)当作最基本的组织单位。一个模块可以是一个完整的 Hugo 项目,也可以是更小的可复用片段,用来提供 Hugo 七类组件(component)中的一类或几类:静态文件、内容、布局、数据、资源、国际化(i18n)资源,以及原型。
模块可以按任意组合与顺序搭配使用,也可以挂载外部目录——包括那些并非 Hugo 项目的目录——从而在效果上得到一个统一的文件系统:项目、主题、第三方模块与外部目录里的文件,都像是放在同一棵目录树中。
本章包含以下页面:
| 页面 | 内容 |
|---|---|
| 简介 | 模块是什么、能提供哪些组件、为什么有用 |
| 使用模块 | 前置条件、导入、更新、整理、缓存、vendor 与本地开发 |
| 主题组件 | 把主题拆成多个可组合组件,以及覆盖顺序 |
| Node.js 依赖 | 声明并合并各模块的 Node.js 依赖 |
读完本章你应该能够
- 说出模块能提供的七类组件(静态文件、内容、布局、数据、资源、国际化资源、原型),并解释「统一文件系统」意味着什么;
- 在项目根目录用
hugo mod init把项目变成模块,用[[module.imports]]引入别人写好的模块; - 用
[[module.mounts]]把项目外的目录挂进content、layouts、static、data,并知道挂载是覆盖式的:为某个组件定义挂载会移除该组件的默认挂载; - 把主题配置成多个组件的组合,并预测某一个模板文件、某一条译文最终取自哪个主题;
- 把各模块的 Node.js 依赖汇总到
packages/hugoautogen/package.json,并在看到npm dependencies are out of sync警告时知道该跑哪条命令。
建议阅读顺序
四页之间有依赖关系,按下面的顺序读最省力:
- 简介 —— 先建立「模块是什么、统一文件系统长什么样」,页内有一个不需要联网的挂载例子,约 15 分钟。
- 使用模块 —— 本章主干:初始化、导入、更新、缓存、vendor、本地开发与挂载,每一步都给出验证方法。
- 主题组件 —— 把主题看成一组可组合的组件,重点是优先级顺序;动手改主题、覆盖模板之前必读。
- Node.js 依赖 —— 只有当模块自带
package.json(例如 Tailwind CSS)时才需要读。
使用模块的前置条件
与模块打交道需要在机器上安装 Git 与 Go 1.18 或更高版本。此外还要把项目本身初始化为模块,也就是在项目根目录执行 hugo mod init,它会生成 go.mod 文件;这一步完成后,才能在项目配置的 [module] 区段中声明要导入的模块。具体步骤见使用模块。
实测(v0.167.0,Windows;单语言站点):
go不在PATH时,hugo mod init会直接失败:ERROR failed to init modules: binary with name "go" not found in PATH退出码为 1。也就是说,Hugo 0.167.0 的
hugo mod init是调用go命令完成的,不是自己写go.mod;只装着 Hugo 是跑不过去的。作为对照,同一台机器上只使用themes/目录里的本地模块时,构建、hugo mod npm pack、hugo mod vendor都能正常执行,不需要go——只有需要从远端下载模块时才真正用到 Go 工具链。
为什么需要模块
模块机制主要解决可复用性与依赖管理的问题:
- 主题以模块的形式分发,安装与升级都交给 Go 的依赖工具链,版本记录在
go.mod与go.sum中,构建结果可重复。 - 一个项目可以同时导入多个模块,并按顺序决定优先级,从而把「主题基础部分 + 若干可复用片段」组合成一个主题。
- 模块不仅能提供模板与静态文件,还能提供内容、数据、i18n 资源与原型,因此可以共享的不只是外观,也包括内容结构与站点行为。
- 非 Hugo 项目的目录同样可以挂载进来,把外部来源的文件纳入同一套目录结构。
模块化的目录结构
Hugo 为项目、主题与模块定义了一套标准的组件目录。导入模块时,模块内的这些目录会自动挂载到 Hugo 的统一文件系统中;也可以在项目配置里手动挂载任意目录,包括来自非 Hugo 项目的目录。项目里各目录各自的职责见目录结构,挂载的写法见使用模块中的挂载一节。
相关命令
模块的日常操作集中在 hugo mod 命令族中,本站已收录的页面包括:
- hugo mod:模块相关子命令的父命令。
- hugo mod init:把当前项目初始化为模块。
- hugo mod get:取回或升级模块依赖。
- hugo mod tidy:清理
go.mod与go.sum中不再使用的条目。 - hugo mod vendor:把依赖复制到项目内的
_vendor目录。 - hugo mod graph:打印模块依赖图。
- hugo mod npm pack:合并各模块的 Node.js 依赖。
- hugo mod clean:清理模块缓存。
本章内容
- 简介 模块解决什么问题、能提供哪七类组件,以及「统一文件系统」的含义,附一个不需要联网就能跑通的挂载示例。 (今天)
- 使用模块 模块的初始化、导入、更新、缓存、vendor 与本地开发分步做:每步给出验证标准,并汇总常见报错与成因。 (今天)
- 主题组件 把主题拆成多个组件组合成一套主题:优先级与两套合并算法,附可运行的覆盖实验和逐项对照结果。 (今天)
- Node.js 依赖 在模块中声明 Node.js 依赖并汇总到统一的 npm 工作区:可运行示例、版本优先级,以及过期警告的处理方法。 (今天)