故障排查

上次更新

错误的三个阶段

Polymerium 将错误分为三个阶段，每个阶段有不同的原因和解决方案：

阶段 1：部署失败  →  游戏从未启动
阶段 2：启动失败  →  Java 已启动但很快退出
阶段 3：运行时崩溃  →  游戏已加载但发生了崩溃

确定错误阶段是解决问题的第一步。

阶段 1：部署失败

部署管道失败——Minecraft 从未启动。

网络问题

症状： 超时错误、校验和失败、"failed to resolve resource"。

解决方法：

• 检查网络连接。
• 如果你在中国大陆，尝试在设置中将更新源切换为 Mirror酱。
• 重试部署——网络问题通常是暂时性的。

符号链接权限问题（Windows）

症状： 部署时出现 "Failed to create symbolic link" 错误。

解决方法：

• 确认已启用开发者模式：设置 → 系统 → 面向开发者。
• 启用开发者模式后重启 Polymerium。
• 检查是否有杀毒软件或同步工具锁定了 build/ 目录。

文件系统冲突

症状： "File already exists" 或 "Unexpected file in build directory"。

解决方法：

• 删除 build/ 目录并重新部署。
• 确保没有其他进程正在写入实例目录。

安全软件

症状： 部署似乎卡住了，或者文件创建后被删除。

解决方法：

• 将 Polymerium 的数据目录添加到杀毒软件的排除列表中。
• 暂时禁用实时保护进行测试。

阶段 2：启动失败

Java 已启动但游戏立即退出（通常在几秒内）。

Java 版本错误

症状： UnsupportedClassVersionError、"A JNI error has occurred"。

解决方法：

• 检查为此实例配置的 Java 版本（参见 Java 管理）。
• Minecraft 1.20.5+ 需要 Java 21。Minecraft 1.18–1.20.4 需要 Java 17。
• 移除手动设置的 Java 覆盖，让 Polymerium 自动部署正确的运行时。

启动参数错误

症状： JVM 以错误码退出，Could not create the Java Virtual Machine。

解决方法：

• 检查设置中的内存分配——不要分配超过你实际拥有的 RAM。
• 移除你添加的自定义 JVM 参数。
• 尝试使用默认设置。

加载器/模组冲突

症状： NoSuchMethodError、ClassNotFoundException、加载器启动时崩溃。

解决方法：

• 验证加载器是否与 Minecraft 版本匹配。
• 检查模组版本冲突——为 1.21 构建的模组无法在 1.20.4 上运行。
• 尝试禁用一半的模组，然后分批重新启用以定位冲突。

阶段 3：运行时崩溃

游戏已加载但在游戏过程中发生了崩溃。

查看日志

1. 打开实例的 Files 标签页。
2. 导航到 build/logs/latest.log 查看主日志。
3. 检查 build/crash-reports/ 中的崩溃报告文件。

常见原因

诊断工具

崩溃报告弹窗

当托管启动崩溃时，Polymerium 会显示包含以下信息的崩溃报告：

• 退出代码
• Java 版本和路径
• 已分配的内存
• 操作系统信息
• 日志最后 50 行
• 崩溃报告文件（如已生成）
• 已安装模组数量
• 完整的命令行

诊断包

你可以导出包含所有相关信息的诊断包。在寻求帮助时这非常有用——将诊断包分享给开发者或社区。

AI 分析包

Polymerium 还可以导出 Markdown 格式的 AI 分析包。你可以直接将其粘贴到 AI 助手（Claude、ChatGPT 等）中进行引导式故障排查。

获取帮助

1. 首先查看日志——大多数错误信息是不言自明的。
2. 根据你的错误阶段尝试上述解决方法。
3. 导出诊断包并分享到 GitHub Issues。
4. 如果使用 AI 故障排查，导出 AI 分析包并粘贴到你的 AI 助手中。