模块版本编号

模块的开发人员使用模块版本号的每个部分来表示版本的稳定性和向后兼容性。对于每个新版本，模块的发布版本号具体反映了自上一版本以来模块更改的性质.

当您开发使用外部模块的代码时，您可以在考虑升级时使用版本号来了解外部模块的稳定性。当您开发自己的模块时，您的版本号将向其他开发人员表明您的模块的稳定性和向后兼容性.

本主题介绍模块版本号的含义.

另请参见

• 当您在代码中使用外部包时，您可以使用 Go 工具管理这些依赖项。有关更多信息，请参阅管理依赖项.
• 如果您正在开发模块供其他人使用，请在发布模块时应用版本号，并在其存储库中标记模块。有关更多信息，请参阅发布模块.

发布的模块在语义版本控制模型中使用版本号发布，如下图所示:

下表描述了版本号的各个部分如何表示模块的稳定性和向后兼容性.

开发中

表示模块仍在开发中且不稳定.此版本不提供向后兼容性或稳定性保证.

版本号可以采用以下形式之一:

伪版本号

v0.0.0-20170915032832-14c0d48ead0c

v0 版本号

v0.x.x

伪版本号

当模块尚未在其存储库中标记时，Go 工具将生成一个伪版本号，以便在调用模块中函数的代码的 go.mod 文件中使用。

注意: 作为最佳实践，始终允许 Go 工具生成伪版本号，而不是创建自己的版本号。

当使用模块函数的代码开发人员需要针对尚未使用语义版本标签标记的提交进行开发时，伪版本很有用。

伪版本号由破折号分隔的三部分组成，如以下形式所示：

句法

基本版本前缀-时间戳-修订标识符

组成部分

• 基本版本前缀 (vX.0.0 或 vX.Y.Z-0) 是从修订版之前的语义版本标记派生的值，或者从 vX.0.0（如果没有此类标记）派生的值。

• 时间戳 (yymmddhhmmss) 是创建修订版的 UTC 时间。在 Git 中，这是提交时间，而不是作者时间。

• 修订标识符 (abcdefabcdef) 是提交哈希的 12 个字符前缀，或者在 Subversion 中，是一个零填充的修订号。

v0 版本号

使用 v0 编号发布的模块将具有正式的语义版本号，其中包含主要、次要和补丁部分，以及可选的预发布标识符。

虽然 v0 版本可以在生产中使用，但它不能保证稳定性或向后兼容性。此外，允许 v1 及更高版本破坏使用 v0 版本的代码的向后兼容性。因此，在 v0 模块中具有代码使用函数的开发人员负责适配不兼容的更改，直到 v1 发布。

预发布版本

表示这是一个预发布里程碑，例如 alpha 或 beta。此版本不提供稳定性保证。

示例

vx.x.x-beta.2

模块的开发人员可以通过附加连字符和预发布标识符，将预发布标识符与任何 major.minor.patch 组合一起使用。

次要版本

表示向后兼容的模块公共 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 参考.