Version Adaptation

迈向 Minecraft 26.1.x：技术迁移实录

HSSkyBoy

深度解析 Java 25、Unobfuscated Loom 与 Mojang 官方对映的适配细节

由 Gemini 3.1 Pro 自我的 md 原稿重写为 html，换行好像都是问题///

序言

随着 Minecraft 26.1.x 的发布，Fabric 模组开发生态迎来了一次真正意义上的分水岭。

这不只是一次例行的版本升级——而是 26.1 Fabric 所代表的工具链、对映体系与开发流程的整体转向。

不仅 Java 版本跃升至 25，构建工具 Loom 的核心架构、对映机制与 GUI 系统都发生了根本性的重构。

本文将以 BoatFly 与 PetPhraseX 的完整适配过程为例，简单说下有关本次迁移的技术细节与踩坑经验。

第一部分：工具链与环境配置

1.1 Java 版本升级至

Minecraft 26.1.x 要求最低 Java 25 作为编译与运行环境，这不只是版本号上的递进，更涉及 JVM 的多项新特性与性能优化。

在 gradle.properties 中，我们需要明确指定目标版本，如：

Properties
org.gradle.jvmargs = -Xmx4096m -Dfile.encoding=UTF-8
target_java_version = 25
minecraft_version = 26.1.2

1.2 Fabric Loader 与 Loom 的版本对齐

Loom 1.15-SNAPSHOT 是适配 26.1.x 的关键版本。它引入了全新的编译流程，不再依赖 Yarn 对映的中间层转换。

同时也建议将 Fabric Loader升级至 0.18.6+，以支援新的模组加载机制。

Groovy
plugins {
    // 引入支援 Unobfuscated 流程的最新版 Loom 插件
    id 'net.fabricmc.fabric-loom' version '1.16-SNAPSHOT'
}
dependencies {
    // 指定目标 Minecraft 版本为 26.1.2
    minecraft "com.mojang:minecraft:26.1.2"

    // 引入支援新模组加载机制的 Fabric Loader 0.18.6+
    compileOnly "net.fabricmc:fabric-loader:0.18.6"
    }

1.3 fabric.mod.json 后设资料规范更新

伴随 Fabric Loader 0.18.6+ 的升级，模组后设资料档案的校验规则迎来了强约束更新，过往宽松的栏位宣告将直接导致模组无法载入，甚至出现启动器校验不透过的问题。

核心变更集中在依赖宣告、环境限定与 Java 版本约束三个维度，尤其针对 Minecraft 26.1.x 与 Java 25 的强制要求，必须在后设资料中明确宣告。

1.4 IDE 开发环境适配最佳化

针对 Java 25 与全新 Loom 工具链，主流 IDE 也需要完成对应的配置最佳化，才能避免同步失败、原始码对映错乱、除错断点失效等问题。

以 IntelliJ IDEA 为例，核心适配步骤如下：

  • 升级 IDEA 至 2025.3+ 版本，才能获得 Java 25 语法的完整支援与 Gradle 9.4+ 的原生相容
  • 在 专案结构 → SDK 中新增 Java 25 正式版 SDK，并将专案的 SDK、语言级别均设定为 Java 25
  • 在 Gradle 设定中，将「使用 Gradle 来自」设定为 gradle-wrapper.properties，并指定 Gradle JVM 为 Java 25

第二部分：对映机制迁移

2.1 从 Yarn 到 Mojang 的范式变革

本次 26.1.x 适配最核心的变革，莫过于 Loom 1.15+ 带来的 Unobfuscated 原生官方对映开发流程。

过往 Fabric 模组开发的标准流程，是基于社区维护的 Yarn 命名对映编写代码，编译时通过 Loom 转换为 Intermediary 中间对映，最终在运行时匹配游戏的混淆字节码。

而全新的 Unobfuscated 流程，直接基于 Mojang 官方发布的 deobfuscation 对映进行开发，彻底移除了 Yarn 中间层的依赖：

  • 编译流程大幅简化，无需执行对映转换，构建速度将会有所提升
  • 命名与官方源码完全对齐，避免了 Yarn 与官方对映的命名差异带来的理解成本
  • 与 Forge 生态的命名体系完全一致，跨加载器模组开发的适配成本大幅降低

在 build.gradle 中，无需再引入任何 Yarn 对映依赖，仅需保留 Minecraft 官方依赖即可完成对映配置，这也是本次工具链升级最具颠覆性的变化。

2.2 大规模包名与类名变更

官方对映的引入，导致了数百个类的重命名。以下是在我专案中常出现的变更对照：

Mapping Migration
// 文本
net.minecraft.text.Text → net.minecraft.network.chat.Component

// GUI
net.minecraft.client.gui.screen.Screen → net.minecraft.client.gui.screens.Screen
net.minecraft.client.gui.widget.ButtonWidget → net.minecraft.client.gui.components.Button

// 渲染
net.minecraft.client.gui.DrawContext → net.minecraft.client.gui.GuiGraphics

第三部分：GUI 系统重构

3.1 渲染生命周期的变更

在我的专案中，最重大的 API 变更发生在 Screen 类。

旧版本使用 render()，新版本则改为 extractRenderState()——必须重新适应新的图形提取模式。

Java
@Override
public void extractRenderState(GuiGraphicsExtractor graphics, int mouseX, int mouseY, float delta) {
    super.extractRenderState(graphics, mouseX, mouseY, delta);

    // 手动计算居中位置
    int titleWidth = this.font.width(this.title);
    int centerX = (this.width - titleWidth) / 2;
    graphics.text(this.font, this.title, centerX, 10, 0xFFFFFF, true);
}

第四部分：Mixin 注入体系适配要点

本次 26.1.x 版本升级中，Mixin 注入逻辑的调整，是多数模组启动崩溃的核心诱因。

除了前文提到的类名、方法名全量变更，游戏核心类的执行流程、位元组码结构也有深层重构，过往的注入点会出现无效异常，甚至直接阻断游戏启动。

以下为本次适配的核心规则，均来自 BoatFly 与 PetPhraseX 的实战验证。

4.1 注入目标的全量重定位

官方对映体系下，Mixin 注入的核心目标，必须完全替换为 Mojang 官方的命名规范，而非简单替换 Yarn 对映的名称。

核心调整包含三个维度：

其一，@Mixin 注解的目标类，需替换为官方对映的全限定类名，不可继续沿用 Yarn 体系的类路径。

其二，@At 注解中的注入目标，无论是方法呼叫还是栏位访问，都需同步更新为官方对映的命名与描述符。

其三，@Shadow 注解的栏位与方法，必须与官方对映的签名完全一致，否则会同时出现编译与执行期双重异常。

4.2 注入规范的强约束更新

伴随 Loom 1.15+ 的升级，Mixin 新增了编译期强校验机制，过往宽松的注入写法将直接导致构建失败。

最核心的变更，是要求所有注入点必须显式宣告 require 属性，推荐强制每个注入点必须匹配到对应目标以防止静默崩溃。

同时，介面注入、访问器的目标类与方法，也需同步完成官方对映的替换，并严格按客户端、服务端环境拆分配置，避免服务端载入客户端专属 Mixin 导致的崩溃。

4.3 配置档案的规范调整

Mixin 配置档案需同步完成两项核心调整，否则会直接导致 Mixin 无法载入。

第一，必须显式宣告 compatibilityLevel 为 JAVA_25，确保 Mixin 适配 Java 25 的位元组码版本。

第二，必须显式宣告 required 为 true，明确告知 Loader 该配置为模组必需，避免载入时的警告与潜在异常。

第五部分：Fabric API 核心体系变更

Fabric API 针对 26.1.x 同步完成了架构重构，大量常用事件、工具类被标记为弃用甚至移除，事件的触发时机、引数列表也有破坏性变更。

5.1 客户端生命周期事件重构

伴随 GUI 渲染系统的重写，客户端核心生命周期事件也同步完成了调整。

萤幕渲染相关事件，完全对应新的 extractRenderState 生命周期，替换了旧版本的 render 相关事件，触发时机与传入引数均有对应调整。

客户端 Tick、萤幕开启关闭等核心事件，也进行了名称空间与分类的重构，需按新的事件路径完成注册，否则会出现事件不生效的问题。

5.2 聊天与文本系统适配

除了前文提到的 Text 到 Component 的类名变更，聊天讯息的事件监听、文本元件构建 API 也有全量调整。

文本元件的构建方法，需替换为官方对映对应的静态方法，样式设定的流式 API 也有对应调整。

聊天讯息相关事件进行了强约束重构，新增了讯息取消机制，拦截或修改聊天讯息需按新的规范返回对应结果，否则会出现讯息重复传送、拦截失效的问题。

5.3 输入与按键系结系统调整

客户端输入处理的重构，也带来了按键系结、滑鼠键盘事件的对应变更。

按键系结需使用新的注册 API，而非旧版本的直接例项化注册。

按键按下/释放、滑鼠点选滚动等输入事件，也进行了名称空间重构，引数列表新增了视窗上下文资讯，需同步完成适配。

第六部分：常见踩坑与解决方案

在 BoatFly 与 PetPhraseX 的完整适配过程中，我们整理了多数开发者都会遇到的共性问题，对应的解决方案可大幅缩短适配周期。

6.1 编译与环境类问题

最常见的「无效的目标发行版: 25」报错，核心原因无非三点：Gradle 版本过低、IDE 配置的 Java SDK 版本不正确、目标版本宣告错误。

对应解决方案也很明确：升级 Gradle Wrapper 至 9.4.0+ 版本，在 IDE 中配置 Java 25 正式版 SDK，并将专案与 Gradle 的 JVM 均设定为 Java 25，同时确认配置档案中的目标版本号正确。

另一类常见的依赖同步失败问题，多是 Loom 版本与 Minecraft 版本不匹配，需使用 1.15-SNAPSHOT 及以上的 Loom 版本，才能完整支援 26.1.x 的官方对映流程。

6.2 执行与载入类问题

模组载入时提示「依赖约束不满足」，核心是 fabric.mod.json 中的依赖宣告不符合新规范。

必须在依赖中显式宣告 Java 25、对应的 Fabric Loader 与 Minecraft 版本范围，否则 Loader 会直接阻断模组载入，无任何容错空间。

游戏启动时的「模组访问许可权异常」，是 Java 25 强化了模组系统的访问控制，需在执行引数中新增对应的模组开放配置，解决反射访问的许可权问题。

6.3 功能与渲染类问题

GUI 渲染时文本错位、元件不显示，多是未迁移至新的渲染生命周期，仍沿用旧的 render 方法，或是文本坐标计算不符合新 API 的预设规则。

需将所有萤幕渲染逻辑迁移至 extractRenderState 方法，手动计算文本与元件的坐标，不再依赖旧版本的内建居中功能。

Mixin 注入失效、功能不生效，需先开启 Mixin 除错模式，检视详细的注入日志，核对注入目标的命名、描述符是否与官方对映完全一致，多数问题都来自命名的细微偏差。

总结

Minecraft 26.1.x 的适配虽然涉及深度的技术重构，但也为模组开发生态带来了长期的稳定性与可维护性。

透过采用官方对映、新的 GUI API 与改进的构建流程，我们现在能编写更清晰、更易维护的程式码。