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 指令的參考，請參閱指令 go。您可以輸入 go help 指令名稱，例如 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

模組

宣告模組的模組路徑，這是模組的唯一識別碼（與模組版本號碼結合使用時）。模組路徑會成為模組中所有套件的匯入前置字元。

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

語法

module 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

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，其套件可能無法使用 Go 1.13 中推出的數值文字常數，例如 1_000_000。
如果較舊的 Go 版本建置了此模組的套件之一，並且遭遇編譯錯誤，錯誤會指出模組是針對較新的 Go 版本撰寫。例如，假設模組有 go 1.13，而套件使用了數值文字常數 1_000_000。如果使用 Go 1.12 建置此套件，編譯器會指出此程式碼是針對 Go 1.13 撰寫的。

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

在 go 1.14 或更新版本，自動販售可能會啟用。如果檔案 vendor/modules.txt 存在且與 go.mod 一致，就無需明確使用 -mod=vendor 旗標。
在 go 1.16 或更新版本，all 套件樣式只會比對由 <a href="/ref/mod#glos-main-module">主模組中的套件和測試所傳遞輸出的套件。這是自模組推出以來，<a href="/ref/mod#go-mod-vendor">go mod vendor</a> 保留的相同套件集。在較早的版本中，all 也包含由主模組中的套件所輸入的套件之測試、這些套件的測試，以此類推。


在 go 1.17 或更新版本
go.mod 檔案包含一份明確的 require 指示，針對每個模組所提供任何套件，由主模組中的套件或測試間接導入。（在 go 1.16 及更低版本中，僅在 最小版本選擇 會選擇不同版本的情況下，才會包含間接的相依關係。）這些額外資訊能讓 模組圖表整理 和 延遲載入模組 能夠順利運作。
由於在之前的 go 版本中可能會產生更多 // indirect 相依關係，所以 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 指示。
工具鏈
宣告建議的 Go 工具鏈，與這個模組一起使用。只在模組是主模組且預設的工具鏈較建議的工具鏈舊時才會生效。
請參閱 Go 模組參考文件中的「Go 工具鏈」和 toolchain 指示 以取得更多資訊。
語法
toolchain toolchain-name

    工具鏈名稱
    建議的 Go 工具鏈名稱。標準的工具鏈名稱會採用 goV 的格式表示 Go 版本 V，例如 go1.21.0 和 go1.18rc1。特殊值 default 會停用自動的工具鏈切換。

範例

建議使用 Go 1.21.0 或以上的版本toolchain go1.21.0



附註
請參閱「Go 工具鏈」，以取得關於 toolchain 行如何影響 Go 工具鏈選擇的詳細資訊。
godebug
指定要套用至該模組主要套件的預設 GODEBUG 設定。這些會覆寫任何工具鏈預設值，而後會被主要套件中的明確 //go:debug 行覆寫。
語法
godebug debug-key=debug-value

    debug-key
    要套用設定的名稱。設定清單及各個設定所引進的版本可以在 [GODEBUG 歷程記錄](https://go.dev.org.tw/doc/godebug#history) 中找到。
    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

    模組路徑
    模組的模組路徑，通常是模組來源儲存庫網域和模組名稱的串接。對於 v2 以上的模組版本，此值必須以主版本號結束，例如 /v2。
    module-version
    模組的版本。這可以是發行版本號（例如 v1.2.3），或 Go 所產生的偽版本序號（例如 v0.0.0-20200921210052-fa0125251cc4）。

範例

要求發行版本 v1.2.3require example.com/othermodule v1.2.3


要求尚未在其儲存庫中標記為已標籤的版本，方法是使用 Go 工具產生的偽版本序號require example.com/othermodule v0.0.0-20200921210052-fa0125251cc4



附註
當你執行 go 指令（例如 go get）時，Go 會為包含已導入套件的每個模組插入 require 指令。當模組尚未在其儲存庫中標記為已標籤時，Go 會在你執行指令時，指派由它產生的偽版本序號。
你可以使用 replace 指令，讓 Go 從其儲存庫以外的位置要求模組。
如需關於版本序號的更多資訊，請參閱 模組版本編號。
如需關於管理相依套件的更多資訊，請參閱以下內容

新增相依套件
取得特定相依套件版本
找出可用的更新
升級或降級相依套件
同步你的程式碼的相依套件

replace
用其他模組版本或本機目錄取代特定版本（或所有版本）的模組內容。解析相依項時，Go 工具會使用取代路徑。
更多詳細資訊，請參閱 Go 模組參考中的 replace 指令。
語法
replace module-path [module-version] => replacement-path [replacement-version]

    模組路徑
    要取代的模組之模組路徑。
    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

當您使用另一個取代一個模組路徑時，請勿變更要取代的模組中套件的 import 語句。
更多關於使用分岔的模組程式碼副本的資訊，請參閱 讓自己的儲存庫分岔版本需要外部模組程式碼。


取代成不同的版本號
以下範例指定應使用 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

更多關於使用模組程式碼本機副本的資訊，請參閱 在本機目錄中要求模組程式碼。


附註
使用 replace 指令，當您要 Go 使用其他路徑尋找模組來源時，暫時用其他值取代模組路徑值。此舉會將 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 Modules 參考文件中的 exclude 指令。
語法
exclude module-path module-version

    模組路徑
    要排除的模組的模組路徑。
    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 Modules 參考文件中的 retract 指令。
語法
retract version // rationale
retract [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 或 Checksum 資料庫 偵測到不一致的總和。
模組的已收回版本通常不會顯示在 go list -m -versions 的輸出中，不過您可以使用 -retracted 來顯示它們。更多資訊，請參閱 Go 模組參考中的 go list -m。