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.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（或重定向到程式碼的 URL）。對於永遠不會直接下載的模組，模組路徑可以是您控制的某個名稱，以確保唯一性。字首 example/ 也保留用於此類示例。

有關更多詳細資訊，請參閱管理依賴項。

實際上，模組路徑通常是模組源的倉庫域和倉庫內模組程式碼的路徑。go 命令在下載模組版本以代表模組使用者解決依賴項時依賴此形式。

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

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

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

go mod init <company-name>/stringtools

go

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

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

語法

go minimum-go-version

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 及更低版本中，只有當最小版本選擇會選擇不同版本時，才包含間接依賴項。）此額外資訊支援模組圖修剪和惰性模組載入。
- 由於間接依賴項可能比以前的 go 版本多得多，因此間接依賴項記錄在 go.mod 檔案中的單獨塊中。
- go mod vendor 省略了 vendored 依賴項的 go.mod 和 go.sum 檔案。（這允許在 vendor 的子目錄中呼叫 go 命令來識別正確的主模組。）
- go mod vendor 將每個依賴項的 go.mod 檔案中的 go 版本記錄在 vendor/modules.txt 中。
在 go 1.21 或更高版本中
- go 行聲明瞭與此模組一起使用的最低 Go 版本要求。
- go 行必須大於或等於所有依賴項的 go 行。
- go 命令不再嘗試與舊版 Go 保持相容性。
- go 命令在 go.sum 檔案中保留 go.mod 檔案的校驗和方面更加謹慎。

一個 go.mod 檔案最多可以包含一個 go 指令。如果不存在，大多數命令將新增一個帶有當前 Go 版本的 go 指令。

toolchain

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

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

語法

toolchain toolchain-name

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-key: 要應用的設定名稱。可在 GODEBUG 歷史記錄中找到設定列表及其引入版本。
debug-value: 提供給設定的值。如果未另行指定，則 0 停用，1 啟用命名行為。

示例

使用新的 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.5 替換為同一模組的 v1.2.3 版本。
```
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。