版本编号

版本编号

本文介绍 Minecraft 和 NeoForge 的版本编号方式，并提供一些 Mod 版本编号建议。

Minecraft

Minecraft 的版本编号方式多年来有过变化。

1.0 到 1.21.11 使用受语义化版本启发的 major.minor.<patch> 格式，补丁号为零时省略，以保持简洁。例如 1.21 和 1.21.11。

26.1 及之后的版本使用受日历版本启发的 year.release.<patch> 格式，同样省略不需要的补丁号。例如 26.1 和 26.1.1。

正式发布前

游戏正式发布之前，版本编号方式经常变化，出现过 a1.1（Alpha 1.1）、b1.7.3（Beta 1.7.3），甚至还有不遵循明确编号规则的 infdev 版本。

大型更新时期

Minecraft 1.0 正式发布时采用了新的版本编号规则：以 1 作为主版本号，第二个数字表示通常每年发布一次的大型更新，第三个数字表示小版本或补丁。例如，Minecraft 1.20.2 的主版本号是 1，次版本号是 20，补丁号是 2。这套格式从 2011 年 Minecraft 1.0 发布时一直沿用到 2026 年初的 26.1 更新。在 Minecraft 开始采用小型更新（drop）之前，它一直运作良好；小型更新只递增补丁号，最终导致 1.21 这一更新系列持续了将近两年。

快照

1.21.11 及更早版本的快照不使用普通版本号，而采用 YYwWWa 格式。YY 表示年份的最后两位，例如 23；WW 表示当年的周数，例如 01。因此，23w01a 是 2023 年第一周发布的快照。

末尾的 a 用于区分同一周发布的多个快照；第二个快照会命名为 23w01b 之类。Mojang 过去偶尔会这样做。其他后缀也曾用于特殊快照，例如 2020 年无限维度愚人节玩笑 20w14infinite。

预发布版和发布候选版

快照周期接近结束时，Mojang 会开始发布预发布版（pre-release）。预发布版被视为已完成功能开发，只专注修复错误。其版本号采用目标版本的语义化格式，并加上 -preX 后缀。例如，1.20.2 的第一个预发布版为 1.20.2-pre1。通常会有多个预发布版，后续依次使用 -pre2、-pre3 等后缀。

预发布周期结束后，Mojang 会发布第一个发布候选版，例如在版本号后加上 -rc1，得到 1.20.2-rc1。Mojang 希望只发布一个候选版，在没有出现新问题时直接将其作为正式版发布。如果发现意外错误，也可能像预发布版一样继续发布 -rc2、-rc3 等版本。

小型更新时期

Minecraft 从每年一次大型更新、年内提供补丁的方式，转向每季度一次小型更新后，Mojang 决定将版本编号改为 year.release.<patch>。例如，26.1 是首个采用新规则的版本，表示 2026 年的第一次小型更新。如果需要发布热修复，版本号为 26.1.1；2026 年第二次小型更新则为 26.2。

快照、预发布版和发布候选版

开发下一次更新时，Mojang 会发布称为快照的早期版本。快照中的游戏内容变化很快，也相当不稳定，但可以帮助玩家提前了解下一次更新的方向。26.1 及之后的快照采用目标版本的日历版本格式，并附加 -snapshot-X。例如，26.1-snapshot-1 是 26.1 更新的第一个快照，后续快照使用 snapshot-2、snapshot-3 等编号。

快照周期接近结束时，Mojang 开始发布预发布版。此时功能开发被视为完成，后续只专注修复错误。相应后缀为 -pre-X；例如，26.1 的首个预发布版为 26.1-pre-1。通常会有多个预发布版，依次使用 -pre-2、-pre-3 等后缀。

预发布周期结束后，Mojang 会发布第一个发布候选版，例如 26.1-rc-1。Mojang 希望只发布一个候选版，在没有新问题时直接将其作为正式版发布。如果发现意外错误，也可能继续发布 -rc-2、-rc-3 等版本。

NeoForge

NeoForge 使用调整后的语义化版本规则：主版本号取 Minecraft 的次版本号，次版本号取 Minecraft 的补丁号，最后一个数字才是 NeoForge 自身的版本号。例如，NeoForge 20.2.59 是 Minecraft 1.20.2 对应的第 60 个 NeoForge 版本，因为编号从 0 开始。当时认为 Minecraft 开头的 1 不会改变，因此将其省略。后来这一前提发生变化，NeoForge 改为包含完整的 Minecraft 版本号；必要时将 Minecraft 补丁号补为 0。例如，NeoForge 26.1.0.5-beta 是 Minecraft 26.1 对应的第 6 个版本。

NeoForge 的一些配置也使用 Maven 版本范围，例如 neoforge.mods.toml 中的 Minecraft 和 NeoForge 版本范围。它与语义化版本大体兼容，但并不完全一致，例如不会按语义化版本规则处理 pre 标签。

Mod

不存在适用于所有项目的最佳版本编号方式。开发风格、项目规模等因素都会影响选择，有时也可以结合多种方式。本节通过实际项目示例介绍一些常见方案。

Mod 文件名通常为 modid-<version>.jar。例如，Mod ID 为 examplemod，版本号为 1.2.3 时，文件名就是 examplemod-1.2.3.jar。

提示 版本编号方案是建议，并非强制规则，尤其是什么时候提升版本号、提升哪一部分，都由项目自行决定。你可以采用其他适合自己的方案。

语义化版本

语义化版本（semantic versioning，简称 semver）由三部分组成：major.minor.patch。代码库发生重大变化时提升主版本号，通常对应重要的新功能和错误修复；增加较小功能时提升次版本号；只包含错误修复的更新则提升补丁号。

通常认为，0.x.x 表示开发中的版本；第一次完整发布时，应将版本号提升到 1.0.0。

实践中，“次版本号用于新功能、补丁号用于修复”的约定经常不会被严格遵循。Minecraft 本身就是典型例子：大型功能更新体现在次版本号中，小型功能更新体现在补丁号中，而错误修复又会体现在上文介绍的快照中。

这些数字的大小取决于更新频率。例如，原文撰写时 Supplementaries 的版本为 2.6.31。版本号出现三位甚至四位数字完全正常，尤其是补丁号。

“精简”和“扩展”的语义化版本

有时会看到只包含两个数字的语义化版本，可以称为“精简”或“两段式”版本号，格式只有 major.minor。这种方式常用于仅添加少量简单内容的小型 Mod：除适配 Minecraft 版本外，很少需要更新，因此版本号可能长期停留在 1.0。

“扩展”或“四段式”版本号包含四个数字，例如 1.0.0.0。具体含义因 Mod 而异，可能是 major.api.minor.patch、major.minor.patch.hotfix，也可能是其他格式，没有统一标准。

在 major.api.minor.patch 中，主版本号与 API 版本号彼此独立，可以分别提升。这种方式常见于向其他 Mod 开发者提供 API 的项目。例如，原文撰写时 Mekanism 的版本为 10.4.5.19。

major.minor.patch.hotfix 则将补丁层级进一步拆分。Create 采用这种思路，原文撰写时版本为 0.5.1f。注意，Create 用字母表示热修复，而非第四个数字，以便与普通语义化版本保持兼容。

说明 “精简语义化版本”“扩展语义化版本”“两段式版本号”和“四段式版本号”都不是正式术语，也不是标准化格式。

Alpha、Beta 和正式版

与 Minecraft 本身一样，Mod 开发常使用软件工程中传统的 alpha、beta 和 release 阶段。alpha 表示不稳定或实验版本，有时也称 experimental 或 snapshot；beta 表示相对稳定但尚未正式发布的版本；release 表示稳定的正式版，有时也称 stable。

一些 Mod 通过提升主版本号表示 Minecraft 版本适配变化。例如，JEI 在 Minecraft 1.19.2 上使用 13.x.x.x，1.19.4 使用 14.x.x.x，1.20.1 使用 15.x.x.x；它没有提供 1.19.3 和 1.20.0 版本。另一些 Mod 会将阶段标签附加到版本名末尾，例如原文撰写时 MineColonies 的版本为 1.1.328-BETA。

加入 Minecraft 版本

通常会在 Mod 文件名中包含所支持的 Minecraft 版本，方便使用者判断兼容性。Minecraft 版本可以放在 Mod 版本号之前或之后，前一种更常见。例如，原文撰写时适用于 Minecraft 1.20.2 的 JEI 16.0.0.28，可以命名为 jei-1.20.2-16.0.0.28 或 jei-16.0.0.28-1.20.2。

加入 Mod 加载器名称

NeoForge 只是众多 Mod 加载器之一，许多开发者会同时适配多个平台。因此，需要区分同一个 Mod、同一个版本但面向不同加载器的文件。

通常在文件名中加入加载器名称即可，例如 jei-neoforge-1.20.2-16.0.0.28、jei-1.20.2-neoforge-16.0.0.28 或 jei-1.20.2-16.0.0.28-neoforge。适配其他加载器时，将 neoforge 替换为 forge、fabric、quilt 或相应加载器名称。

关于 Maven

用于依赖托管的 Maven 在版本比较细节上与语义化版本有所不同，尽管总体仍采用 major.minor.patch 模式。NeoForge 的一些配置使用相应的 Maven 版本范围（MVR）系统，参见上文。选择版本编号方案时，务必确保它与 MVR 兼容，否则其他 Mod 就无法声明依赖你的 Mod 的特定版本。

来源： NeoForged/Documentation（26.1）。中文翻译依据提交 4a680cdd4d15。