重新启动器

重新启动器

基于Java的应用程序的JVM重新启动库。

基础库

Relauncher

适用于基于 Java 的应用程序的 JVM 重启动库。将单个 JAR 放入你的 mods 文件夹中,它应该能从 Minecraft 1.6.4 一直到最新版本工作,或者作为早期插件或常规插件在 Hytale Server 上工作。

它的作用

Relauncher 会在游戏加载之前透明地使用附加参数重启 JVM 进程。这适用于:

  • 添加 JVM 标志 - GC 调优、-XX:+AlwaysPreTouch、系统属性等,无需修改启动器设置
  • 整合包工具 - 其他模组可以在安装依赖或配置环境(javaagents、模块层等等)后以编程方式触发重启动

重启动发生在启动过程的非常早期,在任何重要的游戏状态初始化之前。外部启动器看到的是一个连续的进程,没有额外的窗口,也没有孤立的进程。

支持的版本

加载器 Minecraft 版本 入口点
Forge (LaunchWrapper) 1.6.4 - 1.12.2 通过 manifest 的 ITweaker
Forge (ModLauncher) 1.13.2+ 通过 SPI 的 ITransformationService
NeoForge (ModLauncher) 最高到 1.21.1 通过 SPI 的 ITransformationService
NeoForge (FancyModLoader) 1.21.3+ 通过 SPI 的 IModFileCandidateLocator
Fabric 1.14+ 通过 fabric.mod.json 的 PreLaunchEntrypoint
Quilt 1.14+ 使用 Fabric 的 PreLaunchEntrypoint
Hytale Server (early) - ClassTransformer SPI
Hytale Server (plugin) - 通过 manifest.json 的 JavaPlugin

Java 版本:8 到 25

平台:Linux、Windows 和 macOS,均支持 x86_64 和 aarch64。

安装

  1. 下载通用 JAR(relauncher-universal-<version>.jar)
  2. 将其放入你的 mods/ 文件夹
  3. 启动游戏一次,它会在 config/relauncher/config.cfg 创建配置文件
  4. 编辑配置以添加你的 JVM 参数并设置 enabled = true
  5. 重新启动游戏

配置

配置文件位于 <game directory>/config/relauncher/config.cfg:

# Relauncher Configuration
# Extra JVM arguments to add when relaunching, one per line.
# Lines starting with # are comments, blank lines are ignored.

# Set to false to disable relaunching without removing your arguments.
enabled = true

# Add extra JVM arguments below, one per line:
-XX:+UseG1GC
-XX:+AlwaysPreTouch
-Dsome.java.property=true

配置中的 enabled 标志仅控制配置文件自身的参数。如果另一个模组提供了 CommandLineProvider SPI 实现,则无论此标志如何,重启动都会发生。

工作原理

Relauncher 尝试三种策略来重启 JVM,按优先级顺序:

  1. POSIX exec(Linux / macOS)- 通过原生 Rust 库调用 execvp() 来原地替换当前进程。相同的 PID,零开销,最干净的重启。

  2. Windows DLL - 挂钩 DllMain(DLL_PROCESS_DETACH) 以便在 JVM 完全关闭之后生成子进程。stdin/stdout/stderr 会事先复制,以便它们在拆卸后仍然存在。父进程等待子进程并转发其退出代码。

  3. 回退方案(纯 Java)- 启动一个具有继承 I/O 的子进程,等待其完成,然后停止。到处都能用,但原始进程会在整个游戏会话期间保留。

启动器兼容性

启动器 状态
Vanilla 完全支持
PrismLauncher 完全支持(系统属性变通方案)
CurseForge 完全支持(委托给 Vanilla)
Modrinth 完全支持(theseus 包装器变通方案)
ATLauncher 完全支持
MultiMC 不支持 - 依赖于一种 stdin 协议,该协议在重启动后无法重放。会记录警告并跳过重启动。考虑切换启动器或手动应用参数。

面向模组开发者

API 依赖

将 relauncher-core 添加为仅编译依赖项 - 通用 JAR 将在运行时存在:

dependencies {
    compileOnly 'com.juanmuscaria:relauncher-core:<version>'
}

编程式重启动

如果你的模组需要重启 JVM(例如,在安装 javaagent 之后),直接调用 Relauncher.relaunch():

import com.juanmuscaria.relauncher.Relauncher;
import com.juanmuscaria.relauncher.RelaunchResult;

List<String> extraArgs = Arrays.asList("-Dfoo=bar", "-XX:+AlwaysPreTouch");
RelaunchResult result = Relauncher.relaunch(extraArgs);

// If we get here, the relaunch didn't happen
if (result.isFailed()) {
    logger.error("Relaunch failed: " + result.reason());
} else if (result.isSkipped()) {
    logger.warn("Relaunch skipped: " + result.reason());
}

SPI 提供者

你也可以在不直接调用 API 的情况下注入 JVM 参数,只需实现 CommandLineProvider 并通过 ServiceLoader 注册它。 Relauncher 会自行扫描 mods 文件夹中的服务文件,因此你的模组甚至不需要在类路径上。

import com.juanmuscaria.relauncher.CommandLineProvider;

public class MyProvider implements CommandLineProvider {
    @Override
    public List<String> extraJvmArguments() {
        return Collections.singletonList("-Dmy.mod.installed=true");
    }

    @Override
    public int priority() {
        return 0; // lower = runs first
    }
}

在 META-INF/services/com.juanmuscaria.relauncher.CommandLineProvider 中注册它:

com.example.mymod.MyProvider

检查重启动状态

Relauncher.isRelaunched()  // true if we're inside a relaunched JVM
Relauncher.getDepth()      // 0 = original, 1 = first relaunch, etc.

调试

将 -Drelauncher.debug=true 添加到你的启动器的 JVM 参数中。这会记录完整的命令行提取、参数组装和策略选择过程。对于弄清楚重启动为何未按预期工作很有用。

从源代码构建

./gradlew build                           # Full build
./build-natives.sh                        # Cross-compile native libraries

你需要 Java 17+(用作工具链;输出仍以 Java 8 为目标)和 Gradle 9。 对于交叉编译原生 Rust 库,你还需要 cross、cargo-xwin、cargo-zigbuild,以及 Zig 工具链。

许可证

Mozilla Public License 2.0