模組版本編號

模組開發人員會使用模組版本號碼的每個部分來表示版本的穩定性和向下相容性。針對每個新版本，模組的版本號碼會特別反映模組自前一個版本以來變更的性質。

當您開發使用外部模組的程式碼時，您可以使用版本號碼來了解外部模組的穩定性，以便考慮升級。當您開發自己的模組時，您的版本號碼會向其他開發人員表示模組的穩定性和向下相容性。

本主題說明模組版本號碼的意義。

另請參閱

• 當您在程式碼中使用外部套件時，您可以使用 Go 工具管理這些依賴項。如需詳細資訊，請參閱 管理依賴項。
• 如果您開發供其他人使用的模組，您會在發布模組時套用版本號碼，並在模組的存放庫中標記模組。如需詳細資訊，請參閱 發布模組。

已發布的模組會以語意版本控制模型發布版本號碼，如下圖所示

下表說明版本號碼的各個部分如何表示模組的穩定性和向下相容性。

開發中

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

版本號碼可以採用下列其中一種形式

偽版本號碼

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 參考。