前言

shot.jpg

本靜態(tài)站點用于演示之用，使用 Hugo 構(gòu)建，以及 Markdown 供應(yīng)內(nèi)容。

流行的靜態(tài)站點框架有以下幾個：

• 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/

此站點提供了一篇關(guān)于 Hugo 靜態(tài)站點生成框架的入門教程。

• Hugo 不完美教程 - IX: Menus 菜單組織
• Hugo 不完美教程 - VIII: Functions 內(nèi)置函數(shù)
• 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 分支是發(fā)布的靜態(tài)站點文件：

• 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 實現(xiàn)的，模塊 Hugo 構(gòu)建的核心塊，一個模塊可以一個 Hugo 工程，也可以是 Hugo 定義的 7 種小模塊 static, content, layouts, data, assets, i18n, archetypes，可以按喜歡的方式組件使用模塊，甚至從工程外部裝入模塊目錄以構(gòu)建一個大型的虛擬聯(lián)合文件系統(tǒng)。
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 實現(xiàn)的，模塊 Hugo 構(gòu)建的核心塊，一個模塊可以一個 Hugo 工程，也可以是 Hugo 定義的 7 種小模塊 static, content, layouts, data, assets, i18n, archetypes，可以按喜歡的方式組件使用模塊，甚至從工程外部裝入模塊目錄以構(gòu)建一個大型的虛擬聯(lián)合文件系統(tǒng)。

Go Modules 有哪些特點：

• Go Modules 是官方正式推出的包依賴管理項目；
• Go Modules 出現(xiàn)的目的之一就是為了解決 GOPATH 的問題，相當(dāng)替換 GOPATH。舊項目必須在 $GOPATH/src 里進行，現(xiàn)在允許在任何目錄下使用 go.mod 管理項目依賴。
• 使用模塊代理協(xié)議 Module proxy protocol，通過這個協(xié)議可以使用 Go 模塊鏡像，使用 github 獲取依賴。
• Tag 必須遵循語義化版本控制，如果沒有將忽略 Tag，然后根據(jù)你的 Commit 時間和哈希值再為你生成一個假定的符合語義化版本控制的版本號。
• Go Modules 默認認為，只要你的主版本號不變，那這個模塊版本肯定就不包含 Breaking changes，因為語義化版本控制這么規(guī)定。
• Global Caching 全局緩存數(shù)據(jù)，同一個模塊版本的數(shù)據(jù)只緩存一份，共享使用，位于 GOPATH/pkg/sum 目錄下；
• 使用 go clean -modcache 清理所有已緩存的模塊版本數(shù)據(jù)。
• 使用 go mod 命令管理模塊。

另外在 Go1.11 之后 GOCACHE 已經(jīng)不允許設(shè)置為 off 了，默認使用模塊數(shù)據(jù)緩存。

Go Moduels 項目配置文件 go.mod 描述了當(dāng)前項目，也可以看作是當(dāng)前模塊的元信息，每一行都以一個動詞開頭，目前有以下 5 個動詞:

• module 用于定義當(dāng)前項目的模塊路徑。
• go 用于設(shè)置預(yù)期的 Go 版本。
• require 用于設(shè)置一個特定的模塊版本。
• exclude 用于從使用中排除一個特定的模塊版本。
• replace 用于將一個模塊版本替換為另外一個模塊版本。

這里的填寫格式基本為包引用路徑+版本號，另外比較特殊的是 go $version，目前從 Go1.13 的代碼里來看，還只是個標(biāo)識作用。

模塊基本用法

在國內(nèi)網(wǎng)絡(luò)訪問 proxy.golang.org 會有問題，使用 Go Modules 代理可以解決，使用 go env 設(shè)置 Go 使用環(huán)境變量：

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 命令創(chuàng)建模塊項目：

go mod init github.com/islishude/gomodtest

這時可看到目錄內(nèi)多了 go.mod 文件，內(nèi)容很簡單只有兩行：

module github.com/islishude/gomodtest

go 1.12

首行為當(dāng)前的模塊名稱，接下來是 go 的使用版本。這兩行和 npm package.json 的 name 和 engine 字段的功能很類似。

創(chuàng)建一個 main.go 來測試模塊的管理功能，引用 quote 模塊作為測試：

package main

import (
    "fmt"

    "rsc.io/quote"
)

func main() {
    fmt.Println(quote.Hello())
}

后面就可以直接使用 go run、go build、go test 等命令，因為使用了 Go Module，它們能自動下載相關(guān)依賴包。

>go build
go: finding module for package rsc.io/quote
go: downloading rsc.io/quote v1.5.2
...

執(zhí)行完成，go.mod 會自動更新一個依賴設(shè)置：

module github.com/islishude/gomodtest

go 1.14

require rsc.io/quote v1.5.2

Hugo 中的模塊

將 Hugo 項目初始為一個模塊：

hugo mod init github.com/gohugoio/myShortcodes

相應(yīng)地會在模塊配置文件上添加當(dāng)前模塊的名稱定義：

module github.com/gohugoio/myShortcodes

在 Hugo 項目中，模塊配置錯誤會出現(xiàn)以下信息：

Module "xxx" not found

這時，需要檢查引用模塊名是不是正確的，是否已經(jīng)安裝。比如引用主題目錄下的 gohugo-theme-iris 模塊，但在在配置文件中寫成 hugo-theme-iris，就會導(dǎo)致模塊找不到。

將主題模塊導(dǎo)入，Hugo 文檔使用的主題是模塊方式導(dǎo)入的，見 config.toml 配置文件：

[module]
  [module.hugoVersion]
    min = "0.56.0"
  [[module.imports]]
    path = "github.com/gohugoio/gohugoioTheme"

模塊導(dǎo)入可以設(shè)置 Hugo 版本要求 [module.hugoVersion]。

通常，以 Github 倉庫創(chuàng)建主題的方式為常用，

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

設(shè)置 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/myShortcodes@v1.0.7

# Print Dependency Graph
hugo mod graph

使用專用的供應(yīng)目錄來存儲 Modules，以下命令會將依賴模塊放到 _vendor 目錄下管理，對后面的構(gòu)建生效：

hugo mod vendor 

注意：

• 可以在 module tree 任意層級上使用此命令。
• 供應(yīng)化管理 Vendoring 不會保存 themes 目錄下的模塊。
• 大多數(shù)命令接收 --ignoreVendor 選項來忽略 _vendor 目錄。

管理命令參考

升級次級或補丁版本號：

go get -u rsc.io/quote

僅升級補丁版本號：

go get -u=patch rscio/quote

升降級版本號，可以使用比較運算符控制：

go get foo@'<v1.6.2'

移出所有代碼中不需要的包：

go mod tidy

如果僅僅修改 go.mod 配置文件，比如要移出 crypto 包

go mod edit --droprequire=golang.org/x/crypto

對文件進行文本格式化。

go mod edit -fmt

模塊發(fā)布包的新版本和其它包管理工具基本一致，可以直接打標(biāo)簽，不過打標(biāo)簽之前需要在 go.mod 中寫入相應(yīng)的版本號：

$ 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
)

官方推薦將上述過程在一個新分支來避免混淆，那么類如上述例子可以創(chuàng)建一個 v2 分支，但這個不是強制要求的。

還有一種方式發(fā)布新版本，那就是在主線版本種加入 v2 文件夾，相應(yīng)的也需要內(nèi)置 go.mod 這個文件。