前言
本静态站点用于演示之用，使用 Hugo 构建，以及 Markdown 供应内容。
流行的静态站点框架有以下几个：
- Jekyll (基于 Ruby 容易上手) https://www.jekyll.com.cn/docs/home/
- Hexo (基于 Node.js 容易上手) https://hexo.io/docs/
- Hugo (基于 Go) https://gohugo.io/documentation/
演示站点有两个访问入口：
- https://jimbowhy.gitee.io/
- https://jimboyeah.github.io/
此站点提供了一篇关于 Hugo 静态站点生成框架的入门教程。
- Hugo 不完美教程 - IX: Menus 菜单组织
- Hugo 不完美教程 - VIII: Functions 内置函数
- Hugo 不完美教程 - VII: Variables 对象变量
- Hugo 不完美教程 - VI: Multilingual 多语言支持
- Hugo 不完美教程 - V: Templates 模板机制
- Hugo 不完美教程 - V: Templates 其它模板
- Hugo 不完美教程 - IV: Hugo Pipes 管道处理
- Hugo 不完美教程 - III: Hugo Modules 模块
- Hugo 不完美教程 - II: Hugo 目录组织
- Hugo 不完美教程 - I: Hugo Web Framework
代码仓库地址如下，查看 hugo-project 分支是原文件，master 分支是发布的静态站点文件：
- https://github.com/jimboyeah/jimboyeah.github.io/tree/hugo-project
- https://gitee.com/jimbowhy/jimbowhy/tree/hugo-project/
shot.jpg
title: "III: Hugo Modules 模块"
description: "坚果的 Hugo 教程"
date: 2020-08-06T20:14:08-04:00
featured_image_: "/assets/IMG_20181101_233654_s.jpg"
thumb_image_: "/assets/micro_s.png"
summary: Hugo Modules 是基于 Go Modules 实现的，模块 Hugo 构建的核心块，一个模块可以一个 Hugo 工程，也可以是 Hugo 定义的 7 种小模块 static, content, layouts, data, assets, i18n, archetypes，可以按喜欢的方式组件使用模块，甚至从工程外部装入模块目录以构建一个大型的虚拟联合文件系统。
tags: ["hugo"]
目录：
[TOC]
Hugo Modules 模块
- https://github.com/golang/go/wiki/Modules
- https://blog.golang.org/using-go-modules
- https://zhuanlan.zhihu.com/p/59687626
Hugo Modules 是基于 Go Modules 实现的，模块 Hugo 构建的核心块，一个模块可以一个 Hugo 工程，也可以是 Hugo 定义的 7 种小模块 static, content, layouts, data, assets, i18n, archetypes，可以按喜欢的方式组件使用模块，甚至从工程外部装入模块目录以构建一个大型的虚拟联合文件系统。
Go Modules 有哪些特点：
- Go Modules 是官方正式推出的包依赖管理项目；
- Go Modules 出现的目的之一就是为了解决 GOPATH 的问题，相当替换 GOPATH。旧项目必须在 $GOPATH/src 里进行，现在允许在任何目录下使用 go.mod 管理项目依赖。
- 使用模块代理协议 Module proxy protocol，通过这个协议可以使用 Go 模块镜像，使用 github 获取依赖。
- Tag 必须遵循语义化版本控制，如果没有将忽略 Tag，然后根据你的 Commit 时间和哈希值再为你生成一个假定的符合语义化版本控制的版本号。
- Go Modules 默认认为，只要你的主版本号不变，那这个模块版本肯定就不包含 Breaking changes，因为语义化版本控制这么规定。
- Global Caching 全局缓存数据，同一个模块版本的数据只缓存一份，共享使用，位于 GOPATH/pkg/sum 目录下；
- 使用 go clean -modcache 清理所有已缓存的模块版本数据。
- 使用 go mod 命令管理模块。
另外在 Go1.11 之后 GOCACHE 已经不允许设置为 off 了，默认使用模块数据缓存。
Go Moduels 项目配置文件 go.mod 描述了当前项目，也可以看作是当前模块的元信息，每一行都以一个动词开头，目前有以下 5 个动词:
- module 用于定义当前项目的模块路径。
- go 用于设置预期的 Go 版本。
- require 用于设置一个特定的模块版本。
- exclude 用于从使用中排除一个特定的模块版本。
- replace 用于将一个模块版本替换为另外一个模块版本。
这里的填写格式基本为包引用路径+版本号，另外比较特殊的是 go $version，目前从 Go1.13 的代码里来看，还只是个标识作用。
模块基本用法
在国内网络访问 proxy.golang.org 会有问题，使用 Go Modules 代理可以解决，使用 go env 设置 Go 使用环境变量：
go env -w GO111MODULE="on"
go env -w GOPROXY=https://goproxy.io,direct
goget 也是一个常用的模块安装工具，它可以从 github 获取安装 golang.org 上的模块：
go get github.com/leconio/goget
goget golang.org/x/xxx
使用 go mod 命令创建模块项目：
go mod init github.com/islishude/gomodtest
这时可看到目录内多了 go.mod 文件，内容很简单只有两行：
module github.com/islishude/gomodtest
go 1.12
首行为当前的模块名称，接下来是 go 的使用版本。这两行和 npm package.json 的 name 和 engine 字段的功能很类似。
创建一个 main.go 来测试模块的管理功能，引用 quote 模块作为测试：
package main
import (
"fmt"
"rsc.io/quote"
)
func main() {
fmt.Println(quote.Hello())
}
后面就可以直接使用 go run、go build、go test 等命令，因为使用了 Go Module，它们能自动下载相关依赖包。
>go build
go: finding module for package rsc.io/quote
go: downloading rsc.io/quote v1.5.2
...
执行完成，go.mod 会自动更新一个依赖设置：
module github.com/islishude/gomodtest
go 1.14
require rsc.io/quote v1.5.2
Hugo 中的模块
将 Hugo 项目初始为一个模块：
hugo mod init github.com/gohugoio/myShortcodes
相应地会在模块配置文件上添加当前模块的名称定义：
module github.com/gohugoio/myShortcodes
在 Hugo 项目中，模块配置错误会出现以下信息：
Module "xxx" not found
这时，需要检查引用模块名是不是正确的，是否已经安装。比如引用主题目录下的 gohugo-theme-iris 模块，但在在配置文件中写成 hugo-theme-iris，就会导致模块找不到。
将主题模块导入，Hugo 文档使用的主题是模块方式导入的，见 config.toml 配置文件：
[module]
[module.hugoVersion]
min = "0.56.0"
[[module.imports]]
path = "github.com/gohugoio/gohugoioTheme"
模块导入可以设置 Hugo 版本要求 [module.hugoVersion]。
通常，以 Github 仓库创建主题的方式为常用，
hugo mod init github.com//
设置 Module Imports 后会下载主题，可以使用 hugo mod get 来管理版本：
# Update All Modules
hugo mod get -u
# Update All Modules Recursively New in v0.65.0
hugo mod get -u ./...
# Update One Module
hugo mod get -u github.com/gohugoio/myShortcodes
# Get a Specific Version
hugo mod get github.com/gohugoio/[email protected]
# Print Dependency Graph
hugo mod graph
使用专用的供应目录来存储 Modules，以下命令会将依赖模块放到 _vendor 目录下管理，对后面的构建生效：
hugo mod vendor
注意：
- 可以在 module tree 任意层级上使用此命令。
- 供应化管理 Vendoring 不会保存 themes 目录下的模块。
- 大多数命令接收 --ignoreVendor 选项来忽略 _vendor 目录。
管理命令参考
升级次级或补丁版本号：
go get -u rsc.io/quote
仅升级补丁版本号：
go get -u=patch rscio/quote
升降级版本号，可以使用比较运算符控制：
go get foo@'移出所有代码中不需要的包：
go mod tidy
如果仅仅修改 go.mod 配置文件，比如要移出 crypto 包
go mod edit --droprequire=golang.org/x/crypto
对文件进行文本格式化。
go mod edit -fmt
模块发布包的新版本和其它包管理工具基本一致，可以直接打标签，不过打标签之前需要在 go.mod 中写入相应的版本号：
$ go mod edit --module=github.com/islishude/gomodtest/v2
$ cat go.mod
module github.com/islishude/gomodtest/v2
go 1.12
require (
golang.org/x/crypto v0.0.0-20190313024323-a1f597ede03a // indirect
rsc.io/quote v1.5.2
)
官方推荐将上述过程在一个新分支来避免混淆，那么类如上述例子可以创建一个 v2 分支，但这个不是强制要求的。
还有一种方式发布新版本，那就是在主线版本种加入 v2 文件夹，相应的也需要内置 go.mod 这个文件。