go.mod 檔案參考

每個 Go 模組都由一個 go.mod 檔案定義，該檔案描述了模組的屬性，包括它對其他模組和 Go 版本的依賴關係。

這些屬性包括

當前模組的 模組路徑。這應該是一個 Go 工具可以下載模組的位置，例如模組程式碼的倉庫位置。它與模組的版本號結合使用時，可作為唯一的識別符號。它也是模組中所有包的包路徑字首。有關 Go 如何找到模組的更多資訊，請參閱 Go 模組參考。
當前模組所需的最低 Go 版本。
當前模組所需的其他模組的最低版本列表。
可選地，指示如何用另一個模組版本或本地目錄替換所需模組，或者排除所需模組的特定版本。

執行 go mod init 命令時，Go 會生成一個 go.mod 檔案。以下示例建立一個 go.mod 檔案，將模組路徑設定為 example/mymodule

$ go mod init example/mymodule

使用 go 命令來管理依賴項。這些命令確保 go.mod 檔案中描述的需求保持一致，並且 go.mod 檔案的內容有效。這些命令包括 go get、 go mod tidy 和 go mod edit 命令。

有關 go 命令的參考，請參閱 Command go。您可以透過命令列輸入 go help command-name 來獲取幫助，例如 go help mod tidy。

另請參閱

使用 Go 工具管理依賴項時，Go 工具會修改 go.mod 檔案。更多資訊，請參閱管理依賴項。
有關 go.mod 檔案的更多詳細資訊和限制，請參閱 Go 模組參考。

示例

go.mod 檔案包含如下例所示的指令。本文件的其他地方描述了這些指令。

module example.com/mymodule

go 1.14

require (
    example.com/othermodule v1.2.3
    example.com/thismodule v1.2.3
    example.com/thatmodule v1.2.3
)

replace example.com/thatmodule => ../thatmodule
exclude example.com/thismodule v1.3.0

module

宣告模組的模組路徑，該路徑是模組的唯一識別符號（與模組版本號結合使用時）。模組路徑成為模組中所有包的匯入字首。

更多資訊，請參閱 Go 模組參考中的 module 指令。

語法

module module-path

模組路徑 (module-path): 模組的模組路徑，通常是 Go 工具可以下載模組的倉庫位置。對於 v2 及更高版本的模組，此值必須以主要版本號結尾，例如 /v2。

示例

以下示例將 example.com 替換為可以下載模組的倉庫域名。

v0 或 v1 模組的模組宣告
```
module example.com/mymodule
```
v2 模組的模組路徑
```
module example.com/mymodule/v2
```

注意事項

模組路徑必須唯一標識您的模組。對於大多數模組，該路徑是 go 命令可以找到程式碼的 URL（或程式碼的重定向地址）。對於永遠不會直接下載的模組，模組路徑可以只是您控制的某個名稱，以確保唯一性。字首 example/ 也保留用於此類示例。

更多詳情，請參閱管理依賴項。

在實踐中，模組路徑通常是模組源的倉庫域名以及倉庫中模組程式碼的路徑。當下載模組版本以代表模組使用者解決依賴關係時，go 命令依賴於此形式。

即使您最初不打算讓您的模組可供其他程式碼使用，使用其倉庫路徑也是一種最佳實踐，可以幫助您在以後釋出模組時避免重新命名。

如果您最初不知道模組最終的倉庫位置，可以考慮暫時使用一個安全的替代品，例如您擁有的域名或您控制的名稱（例如您的公司名稱），以及模組名稱或源目錄的路徑。更多資訊，請參閱管理依賴項。

例如，如果您正在 stringtools 目錄中開發，您的臨時模組路徑可能是 <company-name>/stringtools，如下例所示，其中 company-name 是您公司的名稱

go mod init <company-name>/stringtools

go

指示模組是根據指令指定的 Go 版本的語義編寫的。

更多資訊，請參閱 Go 模組參考中的 go 指令。

語法

go minimum-go-version

最低 Go 版本 (minimum-go-version): 編譯此模組中包所需的最低 Go 版本。

示例

模組必須在 Go 1.14 或更高版本上執行
```
go 1.14
```

注意事項

go 指令設定了使用此模組所需的最低 Go 版本。在 Go 1.21 之前，該指令僅為建議性；現在它是一項強制要求：Go 工具鏈拒絕使用聲明瞭更新 Go 版本的模組。

go 指令是選擇要執行哪個 Go 工具鏈的輸入。有關詳細資訊，請參閱“Go 工具鏈”。

go 指令影響新語言特性的使用

對於模組中的包，編譯器會拒絕使用在 go 指令指定的版本之後引入的語言特性。例如，如果一個模組具有 go 1.12 指令，其包不能使用像 1_000_000 這樣的數字文字，這些特性是在 Go 1.13 中引入的。
如果舊版 Go 構建了模組中的某個包並遇到編譯錯誤，則錯誤會指出該模組是為較新版本 Go 編寫的。例如，假設一個模組具有 go 1.13，並且一個包使用了數字文字 1_000_000。如果使用 Go 1.12 構建該包，編譯器會指出程式碼是為 Go 1.13 編寫的。

go 指令也影響 go 命令的行為

在 go 1.14 或更高版本中，可能會啟用自動 vendoring（供應商）。如果檔案 vendor/modules.txt 存在且與 go.mod 一致，則無需顯式使用 -mod=vendor 標誌。
在 go 1.16 或更高版本中，all 包模式僅匹配主模組中的包和測試間接匯入的包。這與自從引入模組以來 go mod vendor 保留的包集相同。在較低版本中，all 還包括主模組中包匯入的包的測試、這些包的測試等等。
在 go 1.17 或更高版本中
- go.mod 檔案為每個提供主模組中包或測試間接匯入的任何包的模組包含一個顯式的 require 指令。（在 go 1.16 及更低版本中，僅當最小版本選擇否則會選擇不同版本時才包含間接依賴項。）此附加資訊使得模組圖修剪和惰性模組載入成為可能。
- 由於 // indirect 依賴項可能比以前的 go 版本多得多，因此間接依賴項記錄在 go.mod 檔案中的一個單獨塊中。
- go mod vendor 會省略供應商依賴項的 go.mod 和 go.sum 檔案。（這允許在 vendor 子目錄中呼叫 go 命令時識別正確的主模組。）
- go mod vendor 在 vendor/modules.txt 檔案中記錄每個依賴項的 go.mod 檔案中的 go 版本。
在 go 1.21 或更高版本中
- go 行聲明瞭使用此模組所需的最低 Go 版本。
- go 行必須大於或等於所有依賴項的 go 行。
- go 命令不再嘗試保持與先前舊版 Go 的相容性。
- go 命令更謹慎地在 go.sum 檔案中保留 go.mod 檔案的校驗和。

一個 go.mod 檔案最多隻能包含一個 go 指令。如果不存在 go 指令，大多數命令會新增一個當前 Go 版本的 go 指令。

toolchain

宣告與此模組一起使用的建議 Go 工具鏈。僅當模組是主模組且預設工具鏈早於建議的工具鏈時才生效。

更多資訊請參閱“Go 工具鏈”和 Go 模組參考中的 toolchain 指令。

語法

toolchain toolchain-name

toolchain 名稱 (toolchain-name): 建議的 Go 工具鏈名稱。標準工具鏈名稱採用 goV 形式，其中 V 是 Go 版本，例如 go1.21.0 和 go1.18rc1。特殊值 default 停用自動工具鏈切換。

示例

建議使用 Go 1.21.0 或更高版本
```
toolchain go1.21.0
```

注意事項

有關 toolchain 行如何影響 Go 工具鏈選擇的詳細資訊，請參閱“Go 工具鏈”。

godebug

指示應用於此模組主包的預設 GODEBUG 設定。這些設定會覆蓋任何工具鏈預設設定，並被主包中顯式的 //go:debug 行覆蓋。

語法

godebug debug-key=debug-value

debug 鍵 (debug-key): 要應用的設定名稱。可以在 GODEBUG 歷史中找到設定列表及其引入版本。
debug 值 (debug-value): 為設定提供的值。如果沒有另外指定，0 表示停用，1 表示啟用指定的行為。

示例

使用 Go 1.23 新的 asynctimerchan=0 行為
```
godebug asynctimerchan=0
```
使用 Go 1.21 的預設 GODEBUG，但採用舊的 panicnil=1 行為
```
godebug (
    default=go1.21
    panicnil=1
)
```

注意事項

GODEBUG 設定僅應用於當前模組中主包和測試二進位制檔案的構建。當模組作為依賴項使用時，它們不起作用。

有關向後相容性的詳細資訊，請參閱“Go、向後相容性和 GODEBUG”。

require

將模組宣告為當前模組的依賴項，並指定所需模組的最低版本。

更多資訊，請參閱 Go 模組參考中的 require 指令。

語法

require module-path module-version

模組路徑 (module-path): 模組的模組路徑，通常是模組源的倉庫域名和模組名稱的連線。對於 v2 及更高版本的模組，此值必須以主要版本號結尾，例如 /v2。
模組版本 (module-version): 模組的版本。這可以是釋出版本號，例如 v1.2.3，也可以是 Go 生成的偽版本號，例如 v0.0.0-20200921210052-fa0125251cc4。

示例

依賴已釋出版本 v1.2.3
```
require example.com/othermodule v1.2.3
```
透過使用 Go 工具生成的偽版本號來依賴倉庫中尚未打標籤的版本
```
require example.com/othermodule v0.0.0-20200921210052-fa0125251cc4
```

注意事項

當您執行 go get 等 go 命令時，Go 會為每個包含匯入包的模組插入 require 指令。當模組在倉庫中尚未打標籤時，Go 會在您執行命令時為其分配一個生成的偽版本號。

您可以使用 replace 指令讓 Go 從非其倉庫的位置依賴模組。

更多關於版本號的資訊，請參閱模組版本號。

更多關於管理依賴項的資訊，請參閱以下內容

tool

將包新增為當前模組的依賴項，並在當前工作目錄在此模組內時使其可用以使用 go tool 執行。

語法

tool package-path

包路徑 (package-path): 工具的包路徑，它是包含該工具的模組以及模組內實現該工具的包路徑（可能為空）的連線。

示例

聲明當前模組中實現的工具

module example.com/mymodule

tool example.com/mymodule/cmd/mytool

宣告在單獨模組中實現的工具

module example.com/mymodule

tool example.com/atool/cmd/atool

require example.com/atool v1.2.3

注意事項

您可以使用 go tool 透過完全限定的包路徑執行在您的模組中宣告的工具，或者在沒有歧義的情況下，透過最後一個路徑段執行。在上面的第一個示例中，您可以執行 go tool mytool 或 go tool example.com/mymodule/cmd/mytool。

在工作區模式下，您可以使用 go tool 執行任何工作區模組中宣告的工具。

工具使用與模組本身相同的模組圖構建。需要一個 require 指令來選擇實現該工具的模組版本。任何 replace 指令或 exclude 指令也適用於該工具及其依賴項。

更多資訊請參閱工具依賴項。

replace

用另一個模組版本或本地目錄替換特定版本（或所有版本）的模組內容。Go 工具在解析依賴項時將使用替換路徑。

更多資訊，請參閱 Go 模組參考中的 replace 指令。

語法

replace module-path [module-version] => replacement-path [replacement-version]

模組路徑 (module-path): 要替換的模組的模組路徑。
模組版本 (module-version): 可選。要替換的特定版本。如果省略此版本號，則該模組的所有版本都將被箭頭右側的內容替換。
替換路徑 (replacement-path): Go 應該查詢所需模組的路徑。這可以是一個模組路徑，也可以是替換模組本地檔案系統上的目錄路徑。如果這是模組路徑，您必須指定一個 replacement-version 值。如果這是本地路徑，則不能使用 replacement-version 值。
替換版本 (replacement-version): 替換模組的版本。僅當 replacement-path 是模組路徑（而不是本地目錄）時才能指定替換版本。

示例

用模組倉庫的分支替換

在以下示例中，example.com/othermodule 的任何版本都被其程式碼的指定分支替換。
```
require example.com/othermodule v1.2.3

replace example.com/othermodule => example.com/myfork/othermodule v1.2.3-fixed
```
當您用另一個模組路徑替換一個模組路徑時，請不要更改您正在替換的模組中包的匯入語句。

更多關於使用模組程式碼分支副本的資訊，請參閱從您自己的倉庫分支依賴外部模組程式碼。
用不同的版本號替換

以下示例指定應使用版本 v1.2.3，而不是該模組的任何其他版本。
```
require example.com/othermodule v1.2.2

replace example.com/othermodule => example.com/othermodule v1.2.3
```
以下示例用同一模組的 v1.2.3 版本替換模組版本 v1.2.5。
```
replace example.com/othermodule v1.2.5 => example.com/othermodule v1.2.3
```
用原生代碼替換

以下示例指定應使用本地目錄作為該模組所有版本的替換。
```
require example.com/othermodule v1.2.3

replace example.com/othermodule => ../othermodule
```
以下示例指定應使用本地目錄僅作為 v1.2.5 的替換。
```
require example.com/othermodule v1.2.5

replace example.com/othermodule v1.2.5 => ../othermodule
```
更多關於使用模組程式碼本地副本的資訊，請參閱依賴本地目錄中的模組程式碼。

注意事項

當您希望 Go 使用另一個路徑查詢模組的源時，使用 replace 指令可以暫時用另一個值替換模組路徑值。這實際上是將 Go 對模組的搜尋重定向到替換位置。您無需更改包匯入路徑即可使用替換路徑。

構建當前模組時，使用 exclude 和 replace 指令控制構建時依賴項解析。這些指令在依賴於當前模組的模組中會被忽略。

replace 指令在以下情況中非常有用

您正在開發一個新模組，其程式碼尚未入庫。您想使用本地版本進行客戶端測試。
您已經發現依賴項存在問題，並克隆了依賴項的倉庫，然後正在使用本地倉庫測試修復。

請注意，僅靠 replace 指令不會將模組新增到模組圖。還需要一個引用被替換模組版本的 require 指令，可以在主模組的 go.mod 檔案中，也可以在依賴項的 go.mod 檔案中。如果您沒有要替換的特定版本，可以使用一個虛假版本，如下例所示。請注意，這將破壞依賴您的模組的模組，因為 replace 指令僅在主模組中應用。

require example.com/mod v0.0.0-replace

replace example.com/mod v0.0.0-replace => ./mod

更多關於替換所需模組的資訊，包括使用 Go 工具進行更改，請參閱

更多關於版本號的資訊，請參閱模組版本號。

exclude

指定要從當前模組的依賴圖排除的模組或模組版本。

更多資訊，請參閱 Go 模組參考中的 exclude 指令。

語法

exclude module-path module-version

模組路徑 (module-path): 要排除的模組的模組路徑。
模組版本 (module-version): 要排除的特定版本。

示例

排除 example.com/theirmodule 的 v1.3.0 版本
```
exclude example.com/theirmodule v1.3.0
```

注意事項

使用 exclude 指令排除間接依賴但由於某種原因無法載入的模組的特定版本。例如，您可以使用它排除校驗和無效的模組版本。

構建當前模組（您正在構建的主模組）時，使用 exclude 和 replace 指令控制構建時依賴項解析。這些指令在依賴於當前模組的模組中會被忽略。

您可以使用 go mod edit 命令排除模組，如下例所示。

go mod edit -exclude=example.com/theirmodule@v1.3.0

更多關於版本號的資訊，請參閱模組版本號。

retract

指示由 go.mod 定義的模組的某個版本或某個版本範圍不應被依賴。當版本過早釋出或釋出後發現了嚴重問題時，retract 指令很有用。

更多資訊，請參閱 Go 模組參考中的 retract 指令。

語法

retract version // rationale
retract [version-low,version-high] // rationale

版本 (version): 要撤回的單個版本。
版本下限 (version-low): 要撤回的版本範圍的下限。
版本上限 (version-high): 要撤回的版本範圍的上限。範圍包含 version-low 和 version-high。
理由 (rationale): 解釋撤回原因的可選註釋。可能會在傳送給使用者的訊息中顯示。

示例

撤回單個版本

retract v1.1.0 // Published accidentally.

撤回一系列版本

retract [v1.0.0,v1.0.5] // Build broken on some platforms.

注意事項

使用 retract 指令表示您的模組的先前版本不應被使用。使用者不會透過 go get、go mod tidy 或其他命令自動升級到被撤回的版本。使用者不會看到被撤回的版本作為 go list -m -u 的可用更新。

撤回的版本應該保持可用，以便已經依賴它們的使用者能夠構建他們的包。即使撤回的版本從源倉庫中刪除，它仍可能在 proxy.golang.org 等映象上可用。依賴撤回版本的使用者在對相關模組執行 go get 或 go list -m -u 時可能會收到通知。

go 命令透過讀取模組最新版本中 go.mod 檔案中的 retract 指令來發現撤回的版本。最新版本按優先順序順序為

其最高的釋出版本（如果有）
其最高的預釋出版本（如果有）
倉庫預設分支尖端的偽版本。

當您新增撤回時，幾乎總是需要打一個新的、更高的版本標籤，以便命令在模組的最新版本中看到它。

您可以釋出一個其唯一目的是表明撤回的版本。在這種情況下，新版本也可以撤回自身。

例如，如果您不小心打上了 v1.0.0 的標籤，您可以打上 v1.0.1 的標籤，幷包含以下指令

retract v1.0.0 // Published accidentally.
retract v1.0.1 // Contains retraction only.

不幸的是，一旦版本釋出，就無法更改。如果您之後在不同的提交上打上 v1.0.0 的標籤，go 命令可能會在 go.sum 或校驗和資料庫中檢測到校驗和不匹配。

撤回的模組版本通常不會出現在 go list -m -versions 的輸出中，但您可以使用 -retracted 來顯示它們。更多資訊，請參閱 Go 模組參考中的 go list -m。