使用 Hugo 模块

前提条件

初始化新模块

使用 hugo mod init 初始化新的 Hugo 模块。如果无法猜测模块路径，您必须将其作为参数提供，例如：

hugo mod init github.com/<your_user>/<your_project>

另请参阅 CLI 文档。

使用模块作为主题

使用模块作为主题的最简单方法是在配置中导入它。

1. 初始化 hugo 模块系统：hugo mod init github.com/<your_user>/<your_project>

2. 导入主题：

   module:
     imports:
     - path: github.com/spf13/hyde
   

   [module]
     [[module.imports]]
       path = 'github.com/spf13/hyde'
   

   {
      "module": {
         "imports": [
            {
               "path": "github.com/spf13/hyde"
            }
         ]
      }
   }
   

更新模块

添加模块作为导入到配置时，模块将被下载和添加。请参阅 配置模块。

要更新或管理版本，您可以使用 hugo mod get。

一些示例：

更新所有模块

hugo mod get -u

递归更新所有模块

hugo mod get -u ./...

更新一个模块

hugo mod get -u github.com/gohugoio/myShortcodes

获取特定版本

hugo mod get github.com/gohugoio/myShortcodes@v1.0.7

另请参阅 CLI 文档。

在模块中进行和测试更改

对项目中导入的模块进行本地开发的一种方法是在 go.mod 中添加替换指令到包含源代码的本地目录：

replace github.com/bep/hugotestmods/mypartials => /Users/bep/hugotestmods/mypartials

如果您运行 hugo server，配置将重新加载，并且 /Users/bep/hugotestmods/mypartials 将被添加到监视列表。

您可以使用模块配置的 replacements 选项，而不是修改 go.mod 文件。

打印依赖关系图

从相关模块目录使用 hugo mod graph，它将打印依赖关系图，包括供应商、模块替换或禁用状态。

例如：

hugo mod graph

github.com/bep/my-modular-site github.com/bep/hugotestmods/mymounts@v1.2.0
github.com/bep/my-modular-site github.com/bep/hugotestmods/mypartials@v1.0.7
github.com/bep/hugotestmods/mypartials@v1.0.7 github.com/bep/hugotestmods/myassets@v1.0.4
github.com/bep/hugotestmods/mypartials@v1.0.7 github.com/bep/hugotestmods/myv2@v1.0.0
DISABLED github.com/bep/my-modular-site github.com/spf13/hyde@v0.0.0-20190427180251-e36f5799b396
github.com/bep/my-modular-site github.com/bep/hugo-fresh@v1.0.1
github.com/bep/my-modular-site in-themesdir

另请参阅 CLI 文档。

供应商化您的模块

hugo mod vendor 将所有模块依赖写入 _vendor 目录，然后将用于所有后续构建。

注意：

• 您可以在模块树的任何级别运行 hugo mod vendor。
• 供应商化不会存储位于 themes 目录中的模块。
• 大多数命令接受 --ignoreVendorPaths 标志，这将不使用 _vendor 中与给定 glob 模式 匹配的模块路径的供应商化模块。

另请参阅 CLI 文档。

整理 go.mod、go.sum

运行 hugo mod tidy 以移除 go.mod 和 go.sum 中未使用的条目。

另请参阅 CLI 文档。

清理模块缓存

运行 hugo mod clean 以删除整个模块缓存。

注意，您还可以使用 maxAge 配置 modules 缓存。请参阅 配置缓存。

另请参阅 CLI 文档。

模块工作区

在 Go 1.18 中添加了工作区支持，Hugo 在 v0.109.0 版本中获得了可靠的支持。

工作区的一个常见用例是简化网站及其主题模块的本地开发。

可以在 *.work 文件中配置工作区，并使用 module.workspace 设置激活，为此用途通常通过 HUGO_MODULE_WORKSPACE 操作系统环境变量控制。

请参阅 Hugo Docs 仓库中的 hugo.work 文件示例：

go 1.20

use .
use ../gohugoioTheme

使用 use 指令，列出您要工作的所有模块，指向其相对位置。如上面的示例所示，建议始终在列表中包含主项目（.）。

这样，您可以启动启用了该工作区的 Hugo 服务器：

HUGO_MODULE_WORKSPACE=hugo.work hugo server --ignoreVendorPaths "**"

上面添加了 --ignoreVendorPaths 标志以忽略 _vendor 中的任何供应商化依赖项。如果您不使用供应商化，则不需要该标志。但现在服务器设置为监视工作区中的文件和目录，您可以看到本地更改重新加载。