模組版本編號

模組開發者使用模組版本號的每個部分來表明該版本的穩定性和向後相容性。對於每個新版本，模組的釋出版本號具體反映了自上一個版本以來模組變化的性質。

當您開發使用外部模組的程式碼時，在考慮升級時，可以使用版本號來了解外部模組的穩定性。當您開發自己的模組時，您的版本號將向其他開發者表明您模組的穩定性和向後相容性。

本主題描述了模組版本號的含義。

另請參閱

• 當您在程式碼中使用外部包時，可以使用 Go 工具管理這些依賴項。欲瞭解更多資訊，請參閱管理依賴項。
• 如果您正在開發供他人使用的模組，您在釋出模組時會應用版本號，並在其倉庫中標記該模組。欲瞭解更多資訊，請參閱釋出模組。

已釋出的模組採用語義版本控制模型釋出，版本號如下面插圖所示

下表描述了版本號的各個部分如何表示模組的穩定性和向後相容性。

版本階段	示例	給開發者的資訊
開發中	自動偽版本號 v0.x.x	表明模組仍處於開發中且不穩定。此版本不提供向後相容性或穩定性保證。
主版本	v1.x.x	表明向後不相容的公共 API 更改。此版本不保證與之前的主版本向後相容。
次版本	vx.4.x	表明向後相容的公共 API 更改。此版本保證向後相容性和穩定性。
補丁版本	vx.x.1	表明不影響模組公共 API 或其依賴項的更改。此版本保證向後相容性和穩定性。
預釋出版本	vx.x.x-beta.2	表明這是一個預釋出里程碑，例如 alpha 或 beta。此版本不提供穩定性保證。

開發中

表明模組仍處於開發中且不穩定。此版本不提供向後相容性或穩定性保證。

版本號可以採用以下形式之一

偽版本號

v0.0.0-20170915032832-14c0d48ead0c

v0 版本號

v0.x.x

偽版本號

當模組在其倉庫中未被標記時，Go 工具將生成一個偽版本號，供呼叫模組中函式的程式碼的 go.mod 檔案使用。

注意： 作為最佳實踐，始終讓 Go 工具生成偽版本號，而不是自己建立。

當使用模組功能的程式碼開發者需要針對尚未用語義版本標籤標記的提交進行開發時，偽版本很有用。

偽版本號由三部分組成，用破折號分隔，形式如下

語法

baseVersionPrefix-timestamp-revisionIdentifier

組成部分

• baseVersionPrefix (vX.0.0 或 vX.Y.Z-0) 是一個值，它要麼來自修訂版之前的語義版本標籤，要麼在沒有此類標籤時來自 vX.0.0。

• timestamp (yymmddhhmmss) 是修訂版建立的 UTC 時間。在 Git 中，這是提交時間，而不是作者時間。

• revisionIdentifier (abcdefabcdef) 是提交雜湊的 12 個字元字首，或者在 Subversion 中，是零填充的修訂號。

v0 版本號

以 v0 版本釋出的模組將具有正式的語義版本號，包含主版本、次版本和補丁版本部分，以及可選的預釋出識別符號。

儘管 v0 版本可以在生產環境中使用，但它不提供穩定性或向後相容性保證。此外，v1 及更高版本允許破壞使用 v0 版本的程式碼的向後相容性。因此，使用 v0 模組中函式的程式碼開發者有責任適應不相容的更改，直到 v1 釋出。

預釋出版本

表明這是一個預釋出里程碑，例如 alpha 或 beta。此版本不提供穩定性保證。

示例

vx.x.x-beta.2

模組開發者可以透過附加連字元和預釋出識別符號，將預釋出識別符號與任何主版本.次版本.補丁版本組合使用。

次版本

表明模組公共 API 的向後相容更改。此版本保證向後相容性和穩定性。

示例

vx.4.x

此版本更改了模組的公共 API，但不會破壞呼叫程式碼。這可能包括模組自身依賴項的更改，或新增新函式、方法、結構欄位或型別。

換句話說，此版本可能包含透過新功能進行的增強，其他開發者可能希望使用這些功能。但是，使用以前次版本的開發者無需更改其程式碼。

補丁版本

表明不影響模組公共 API 或其依賴項的更改。此版本保證向後相容性和穩定性。

示例

vx.x.1

遞增此數字的更新僅用於次要更改，例如錯誤修復。使用程式碼的開發者可以安全地升級到此版本，而無需更改其程式碼。

主版本

表明模組公共 API 中的向後不相容更改。此版本不保證與之前的主版本向後相容。

示例

v1.x.x

v1 或更高版本號表示模組穩定可用（預釋出版本除外）。

請注意，由於版本 0 不提供穩定性或向後相容性保證，因此將模組從 v0 升級到 v1 的開發者有責任適應破壞向後相容性的更改。

模組開發者應僅在必要時將此數字遞增到 v1 之外，因為版本升級對使用升級模組中功能的開發者來說意味著重大的中斷。這種中斷包括公共 API 的向後不相容更改，以及使用模組的開發者需要在匯入模組中的包的任何地方更新包路徑。

主版本更新到高於 v1 的數字也將有一個新的模組路徑。這是因為模組路徑將附加主版本號，如下例所示

module example.com/mymodule/v2 v2.0.0

主版本更新使這成為一個新模組，其歷史與模組的先前版本分開。如果您正在開發要釋出給其他人的模組，請參閱模組釋出和版本控制工作流中的“釋出破壞性 API 更改”。

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