---
title: 故障排查
description: 诊断和修复常见问题——部署失败、启动崩溃和运行时错误。
---

## 错误的三个阶段

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 管理](/docs/managing/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/` 中的崩溃报告文件。

### 常见原因

| 症状 | 可能的原因 |
|---------|-------------|
| `java.lang.OutOfMemoryError` | 在设置中增加最大内存 |
| 光影包崩溃 | 更新或更换光影包；检查 Iris/Optimize 兼容性 |
| 特定模组崩溃 | 查看模组的问题追踪器；尝试不同版本 |
| 世界损坏 | 从备份或快照恢复 |

---

## 诊断工具

### 崩溃报告弹窗

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

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

### 诊断包

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

### AI 分析包

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

---

## 获取帮助

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