版本编号

本文介绍 Minecraft 和 NeoForge 的版本编号方式，并为 Mod 的版本管理提供一些建议。本文对应 Minecraft 1.21.1 文档快照，其中关于版本惯例和示例 Mod 版本的表述以原文撰写时为准。

Minecraft

Minecraft 使用语义化版本编号。语义化版本（简称 semver）的格式为 major.minor.patch，即主版本号、次版本号和修订号。例如，Minecraft 1.20.2 的主版本号是 1，次版本号是 20，修订号是 2。

从 2011 年发布 Minecraft 1.0 开始，Minecraft 一直使用主版本号 1。在此之前，编号方式经常变化，出现过 a1.1（Alpha 1.1）、b1.7.3（Beta 1.7.3），以及没有明确编号规则的 infdev 版本。原文认为，主版本号 1 已沿用十余年，再加上关于 Minecraft 2 的玩笑，因此这一惯例不太可能改变。

快照版

快照版不采用标准的 semver 格式，而是使用 YYwWWa：YY 是年份的最后两位（例如 23），WW 是当年的周数（例如 01）。例如，23w01a 是 2023 年第一周发布的快照。

后缀 a 用于区分同一周内发布的多个快照。如果发布第二个快照，名称就可能是 23w01b。Mojang 过去偶尔使用过这种方式。快照也可能使用其他后缀，例如 20w14infinite，即 2020 年无限维度愚人节版本。

预发布版与发布候选版

快照开发周期接近结束时，Mojang 会开始发布预发布版。预发布版被视为该版本功能已完整，后续工作主要是修复错误。编号使用目标版本的 semver 编号，并添加 -preX 后缀。例如，1.20.2 的首个预发布版名为 1.20.2-pre1。通常会有多个预发布版，后续依次使用 -pre2、-pre3 等后缀。

预发布周期完成后，Mojang 会发布第一个发布候选版，后缀为 -rc1，例如 1.20.2-rc1。目标是：如果没有发现新的问题，就可以直接将它作为正式版发布。如果发现意外错误，也可能像预发布版一样继续发布 -rc2、-rc3 等版本。

NeoForge

NeoForge 使用经过调整的 semver：主版本号对应 Minecraft 的次版本号，次版本号对应 Minecraft 的修订号，修订号才是 NeoForge 自身的构建序号。例如，NeoForge 20.2.59 是适用于 Minecraft 1.20.2 的第 60 个版本（编号从 0 开始）。Minecraft 编号开头的 1 被省略，原文理由见上文。

NeoForge 的一些配置还使用 Maven 版本范围，例如 neoforge.mods.toml 中的 Minecraft 和 NeoForge 版本范围。Maven 版本规则与 semver 大体兼容，但并不完全相同，例如不会按 Minecraft 的预期方式理解 pre 标签。

Mod

版本管理没有适用于所有项目的最佳方案。开发方式、项目规模等因素都会影响选择，有时也会组合多种编号方式。本节通过实际例子介绍几种常见方案。

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

提示版本编号方式是建议，并非强制规则。何时提升版本号、提升哪一部分，尤其取决于项目自身的约定。你也可以采用其他版本管理方式。

语义化版本

语义化版本（semver）由 major.minor.patch 三部分组成。代码库发生重大变更时提升主版本号，这通常意味着重要的新功能和错误修复；引入较小功能时提升次版本号；更新仅包含错误修复时提升修订号。

一般约定 0.x.x 表示开发中的版本，第一次完整发布时应将版本提升到 1.0.0。

实际项目经常不会严格遵守“次版本号用于功能、修订号用于修复”的规则。Minecraft 就是一个常见例子：它用次版本号承载主要功能，用修订号承载较小功能，并在快照中修复错误，见上文。

这些数字的大小取决于 Mod 的更新频率。例如，原文撰写时 Supplementaries 的版本是 2.6.31。出现三位甚至四位的数字也完全可能，尤其是修订号。

“精简”和“扩展”的 semver

有时可以看到只有两个数字的 semver，可称为“精简 semver”或“两段式 semver”，格式为 major.minor。只添加少量简单内容的小型 Mod 经常使用这种方式。这类项目除了适配 Minecraft 新版本外，很少需要更新，可能长期保持 1.0。

“扩展 semver”或“四段式 semver”包含四个数字，例如 1.0.0.0。具体格式可能是 major.api.minor.patch、major.minor.patch.hotfix，也可能另有约定，并没有统一标准。

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

major.minor.patch.hotfix 则进一步拆分了修订级别。Create 采用这种思路，原文撰写时的版本为 0.5.1f。注意，Create 使用字母表示热修复级别，而非第四个数字，以保持与常规 semver 的兼容性。

说明精简 semver、扩展 semver、两段式 semver、四段式 semver 都不是正式术语，也不是标准格式。

Alpha、Beta 与正式版

与 Minecraft 类似，Mod 开发也经常采用软件工程中常见的 alpha、beta、release 阶段。alpha 表示不稳定或实验版本，有时也称为 experimental 或 snapshot；beta 表示相对稳定的测试版本；release 表示稳定版本，有时直接使用 stable。

部分 Mod 通过主版本号表示所适配 Minecraft 版本的变化。例如 JEI 用 13.x.x.x 对应 Minecraft 1.19.2，14.x.x.x 对应 1.19.4，15.x.x.x 对应 1.20.1（没有针对 1.19.3 和 1.20.0 的版本）。另一些 Mod 会在名称末尾添加阶段标签，例如原文撰写时 Minecolonies 的版本是 1.1.328-BETA。

加入 Minecraft 版本

文件名中通常会包含 Mod 所适用的 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，其版本编号规则在一些细节上与 semver 不同，虽然整体仍然采用 major.minor.patch 模式。NeoForge 的部分配置使用相关的 Maven 版本范围（MVR），见上文。选择版本编号方式时，应确认它与 MVR 兼容，否则其他 Mod 将无法正确声明对你的 Mod 特定版本的依赖。

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