Go 模組（Go Modules）簡介

簡介

在 Go 1.11 之後，Go Modules 成為官方推薦的套件管理機制，取代了過去的 GOPATH 與 vendor 方式。模組讓專案的相依性、版本控制與建置流程變得更可預測，也更符合現代軟體開發的需求。對於剛踏入 Go 世界的同學，或是已經有一定開發經驗卻還在使用舊式方式的開發者，了解模組的概念與操作方式是提升開發效率、降低維護成本的關鍵。

本篇文章將從 什麼是 Go Modules、如何建立與使用模組、常見的陷阱與最佳實踐，一步步帶你掌握這項必備技能，並透過實務範例說明在真實專案中如何運用。

---

核心概念

1. 模組（module）是什麼？

• 模組 是一個包含 go.mod 檔案的目錄，代表一個獨立的程式碼單位。
• go.mod 內會記錄 模組路徑（module path）與 相依套件的版本，讓 go build、go test 等指令能自動解析正確的依賴。

2. 為什麼要使用模組？

傳統 GOPATH	Go Modules
相依套件全局安裝，版本衝突容易發生	每個模組自行管理版本，互不干擾
需要手動 vendor 或 dep 來凍結依賴	go.mod + go.sum 自動鎖定版本
跨平台建置困難	go.mod 可在任何目錄下工作，無需設定 GOPATH

3. 基本檔案說明

檔案	作用
go.mod	定義模組名稱、Go 版本、相依套件與版本
go.sum	記錄相依套件的校驗碼，保證下載內容一致性
vendor/（可選）	將相依套件複製到本地，適用於離線或企業內部環境

---

程式碼範例

以下範例均以 github.com/yourname/hello 為模組路徑，示範常見操作。

1. 初始化模組

// 在專案根目錄執行
$ go mod init github.com/yourname/hello

執行後會產生 go.mod：

module github.com/yourname/hello

go 1.22

註解：go 1.22 表示此模組使用 Go 1.22 的語法與特性。

---

2. 加入第三方套件

假設要使用 gorilla/mux 這個路由套件：

// main.go
package main

import (
    "log"
    "net/http"

    "github.com/gorilla/mux" // <─ 第三方套件
)

func main() {
    r := mux.NewRouter()
    r.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte("Hello, Go Modules!"))
    })
    log.Fatal(http.ListenAndServe(":8080", r))
}

執行 go build 時，Go 會自動下載相依套件並更新 go.mod、go.sum：

$ go build
go: added github.com/gorilla/mux v1.8.1
go: added github.com/gorilla/context v1.1.1

go.mod 變為：

module github.com/yourname/hello

go 1.22

require (
    github.com/gorilla/context v1.1.1 // indirect
    github.com/gorilla/mux v1.8.1
)

---

3. 指定套件版本

若想固定在 v1.7.0（避免自動升級），使用 go get：

$ go get github.com/gorilla/mux@v1.7.0

go.mod 會自動更新為：

require github.com/gorilla/mux v1.7.0

---

4. 本地模組相互引用

假設有兩個子模組 pkg/util 與 cmd/app，cmd/app 需要引用 pkg/util：

$ mkdir -p pkg/util cmd/app
$ cd pkg/util
$ go mod init github.com/yourname/hello/pkg/util
$ cd ../../cmd/app
$ go mod init github.com/yourname/hello/cmd/app

在 cmd/app/main.go 中：

package main

import (
    "fmt"
    "github.com/yourname/hello/pkg/util"
)

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

在 pkg/util/util.go 中：

package util

func Hello() string {
    return "Hello from util package"
}

關鍵：在 cmd/app 目錄執行 go get github.com/yourname/hello/pkg/util@v0.0.0，Go 會自動在同一個工作區找到本地模組，無需額外設定。

---

5. 使用 vendor 目錄（離線部署）

$ go mod vendor   # 產生 vendor/，把所有相依套件複製進來
$ go build -mod=vendor   # 強制使用 vendor 目錄編譯

提示：在企業內部或無法連網的環境，vendor 能保證建置不會因外部網路失效而中斷。

---

常見陷阱與最佳實踐

陷阱	說明	解決方式
相依套件自動升級	go get -u 會把所有套件升到最新次要版，可能破壞相容性。	使用 版本範圍（@v1.2.3）鎖定，或在 CI 中加入 go mod tidy -v 檢查變更。
go.mod 與 go.sum 不一致	手動編輯 go.mod 後未執行 go mod tidy，導致多餘或缺少相依。	每次修改後執行 go mod tidy，讓兩個檔案保持同步。
本地模組路徑衝突	多個模組使用相同的 module path，會產生衝突。	確保每個模組的路徑在全域唯一，常用 GitHub/GitLab 的 repository URL。
忽略 replace 指令	在開發階段需要指向本機分支時忘記移除 replace，導致正式版仍指向本機路徑。	在發布前檢查 go.mod，移除不必要的 replace，或使用 go mod edit -dropreplace。
未使用 go.mod 的舊專案	直接把舊專案搬到新目錄，仍依賴 GOPATH。	先在根目錄執行 go mod init，再跑 go mod tidy 讓相依自動搬入模組。

最佳實踐

1. 始終使用 go.mod 管理相依：即使是小型腳本，也建議初始化模組，避免未來擴充時產生混亂。
2. 在 CI/CD 中加入 go mod verify：確保 go.sum 的校驗碼與實際下載的檔案一致。
3. 使用語意化版本（SemVer）：發布自己的套件時，遵循 vMAJOR.MINOR.PATCH 規則，讓使用者能安全升級。
4. 定期執行 go mod tidy：清除未使用的相依，保持 go.mod 精簡。
5. 將 go.mod、go.sum 加入版本控制：切勿忽略，否則團隊成員會因版本不一致而產生建置失敗。

---

實際應用場景

場景	為什麼需要 Go Modules
微服務架構	每個服務都是獨立的模組，版本升級不會影響其他服務。
CLI 工具	發布到 GitHub Release 時，只需提供 go.mod，使用者可直接 go install。
企業內部套件庫	透過 replace 或私有 proxy（如 GOPROXY=https://proxy.mycorp.com）管理內部相依。
開源套件	go.mod 讓貢獻者快速了解套件相依，並在 PR 中自動執行 go vet、go test。
離線環境	產生 vendor 目錄後，將整個專案搬到無網路的機器上仍能編譯。

---

總結

Go Modules 是 現代 Go 開發的基礎建設，它以簡潔的 go.mod 檔案取代了繁雜的 $GOPATH 設定，提供了：

• 版本鎖定：每個相依都有明確的版本號，避免「依賴地獄」。
• 跨平台建置：不再受限於特定工作目錄，任意位置皆可編譯。
• 可預測的 CI/CD：go.mod + go.sum 讓自動化流程更穩定。

只要掌握 初始化、加入相依、版本管理、go.mod/go.sum 的維護，再配合 最佳實踐（如 go mod tidy、go mod verify），就能在專案開發、部署與維護的每個階段，都享受到模組帶來的便利與安全性。

快把上述步驟套用到你的第一個 Go 專案吧，讓程式碼管理從此變得輕鬆、可靠！