故障排查
诊断和修复常见问题——部署失败、启动崩溃和运行时错误。
Last updated on
错误的三个阶段
Polymerium 将错误分为三个阶段，每个阶段有不同的原因和解决方案：
阶段 1：部署失败 → 游戏从未启动
阶段 2：启动失败 → Java 已启动但很快退出
阶段 3：运行时崩溃 → 游戏已加载但发生了崩溃确定错误阶段是解决问题的第一步。
阶段 1：部署失败
部署管道失败——Minecraft 从未启动。
网络问题
症状： 超时错误、校验和失败、"failed to resolve resource"。
解决方法：
- 检查网络连接。
- 如果资源仓库或下载请求无法连接，请检查代理设置。应用更新源不会影响游戏文件下载。
- 重试部署——网络问题通常是暂时性的。
符号链接权限问题（Windows）
症状： 部署时出现 "Failed to create symbolic link" 错误。
解决方法：
- 确认已启用开发者模式：设置 → 系统 → 面向开发者。
- 启用开发者模式后重启 Polymerium。
- 检查是否有杀毒软件或同步工具锁定了
build/目录。
文件系统冲突
症状： "File already exists" 或 "Unexpected file in build directory"。
解决方法：
- 关闭游戏及其他正在写入实例的程序，再重试部署。
- 使用重置或删除
build/前，请先备份仅存于运行目录中的存档、截图和配置。重置会永久清空运行目录；只有已经放入本地保留（persist/）的文件受到保护。参见目录模型。
安全软件
症状： 部署似乎卡住了，或者文件创建后被删除。
解决方法：
- 将 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 不可用，请移除覆盖项，并检查实例是否有兼容的内置运行时；原生 Patch 可能会收窄可接受的 Java 版本。
启动参数错误
症状： JVM 以错误码退出，Could not create the Java Virtual Machine。
解决方法：
- 检查设置中的内存分配——不要分配超过你实际拥有的 RAM。
- 移除你添加的自定义 JVM 参数。
- 尝试使用默认设置。
加载器/模组冲突
症状： NoSuchMethodError、ClassNotFoundException、加载器启动时崩溃。
解决方法：
- 验证加载器是否与 Minecraft 版本匹配。
- 检查模组版本冲突——为 1.21 构建的模组无法在 1.20.4 上运行。
- 尝试禁用一半的模组，然后分批重新启用以定位冲突。
阶段 3：运行时崩溃
游戏已加载但在游戏过程中发生了崩溃。
查看日志
- 打开实例的 Files 标签页。
- 导航到
build/logs/latest.log查看主日志。 - 检查
build/crash-reports/中的崩溃报告文件。
常见原因
| 症状 | 可能的原因 |
|---|---|
java.lang.OutOfMemoryError | 在设置中增加最大内存 |
| 光影包崩溃 | 更新或更换光影包；检查 Iris/Optimize 兼容性 |
| 特定模组崩溃 | 查看模组的问题追踪器；尝试不同版本 |
| 世界损坏 | 从单独的备份还原；快照不会自动保存仅位于 build/ 中的存档 |
诊断工具
崩溃报告弹窗
当托管启动崩溃时，Polymerium 会显示包含以下信息的崩溃报告：
- 退出代码
- Java 版本和路径
- 已分配的内存
- 操作系统信息
- 日志最后 50 行
- 崩溃报告文件（如已生成）
- 已安装模组数量
- 完整的命令行
诊断包
你可以导出包含所有相关信息的诊断包。在寻求帮助时这非常有用——将诊断包分享给开发者或社区。
AI 分析包
Polymerium 还可以导出 Markdown 格式的 AI 分析包。导出时会先将崩溃报告和最近的游戏日志上传到 mclo.gs（第三方日志分享服务）以生成可分享的链接，随后保存一份 Markdown 文件，其中包含这些链接、日志摘录、启动命令行与环境信息。Polymerium 会在上传前向你确认，并在本地对访问令牌和用户名脱敏。将文件内容粘贴到 AI 助手（Claude、ChatGPT 等）中即可进行引导式故障排查。请注意，上传的日志可通过其链接被公开访问，并由 mclo.gs 保留。
获取帮助
对于已记录的部署机制边界，请先查阅已知问题，再决定是否提交问题报告。
- 首先查看日志——大多数错误信息是不言自明的。
- 根据你的错误阶段尝试上述解决方法。
- 导出诊断包并分享到 GitHub Issues。
- 如果使用 AI 故障排查，导出 AI 分析包并粘贴到你的 AI 助手中。