模块版本编号

模块开发者使用模块版本号的每个部分来表明该版本的稳定性和向后兼容性。对于每个新版本，模块的发布版本号具体反映了自上一个版本以来模块变化的性质。

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

本主题描述了模块版本号的含义。

另请参阅

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