模块版本编号

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

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

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

另请参阅

• 当您在代码中使用外部软件包时，您可以使用 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

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

次要版本

表示对模块的公共 API 进行向后兼容的更改。此版本保证向后兼容性和稳定性。

示例

vx.4.x

此版本更改了模块的公共 API，但不会中断调用代码。这可能包括对模块自身依赖项的更改或添加新函数、方法、结构字段或类型。

换句话说，此版本可能通过另一个开发人员可能想要使用的函数包含增强功能。但是，使用以前小版本的开发人员不必更改其代码。

补丁版本

表示不影响模块的公共 API 或其依赖项的更改。此版本保证向后兼容性和稳定性。

示例

vx.x.1

增加此数字的更新仅适用于小更改，例如错误修复。使用代码的开发人员可以安全地升级到此版本，而无需更改其代码。

主版本

表示模块公共 API 中向后不兼容的更改。此版本不保证它将与之前的 major 版本向后兼容。

示例

v1.x.x

v1 或更高版本号表示该模块可稳定使用（其预发布版本除外）。

请注意，由于版本 0 不提供稳定性或向后兼容性保证，因此将模块从 v0 升级到 v1 的开发人员有责任适应打破向后兼容性的更改。

模块开发人员只有在必要时才应将此数字增加到 v1 以上，因为版本升级会对使用升级模块中函数的代码的开发人员造成重大中断。这种中断包括公共 API 的向后不兼容更改，以及使用该模块的开发人员需要在从模块导入包的任何位置更新包路径。

高于 v1 的 major 版本更新也将有新的模块路径。这是因为模块路径将附加 major 版本号，如下例所示

module example.com/mymodule/v2 v2.0.0

重大版本更新会将此模块变为一个新的模块，它与模块的先前版本具有独立的历史记录。如果您正在开发要发布给其他人的模块，请参阅模块发布和版本控制工作流中的“发布重大 API 变更”。

有关模块指令的更多信息，请参阅go.mod 参考。