常见问题与故障排查

ArkPets 桌宠在运行、渲染、联网下载模型等环节可能出现的一系列典型故障现象，以及官方文档 (docs/FAQ.md) 中给出的诊断思路与解决方案汇总。本页面向 ArkPets 的普通用户与排障工程师，将症状归类、给出排查路径，并串联调试热键、命令行参数与日志导出等排障工具。

Purpose and Scope

本页覆盖以下内容：

• ArkPets 官方 FAQ 中记录的全部 7 类典型问题及其解决方法（游戏引擎冲突、悬空站立、窗口黑背景、模型下载失败、缝合线/伪影、启动器乱码、日志获取）。
• 排障工具链的使用：日志等级、命令行启动参数、调试热键、配置文件 app/ArkPets.cfg。
• 版本兼容性矩阵（桌宠版本 × 模型库版本）及其对缝合线/伪影问题的影响。

以下相关主题有意留给兄弟页面，不在本页展开：

• 命令行参数的完整语义与用例：参见 命令行启动 类页面。
• 自定义模型的制作与接入：参见自定义模型相关页面。
• 模型库结构、下载镜像等模型仓库细节：参见模型库管理相关页面。
• 程序遥测与崩溃上报机制：参见遥测（Telemetry）相关页面。

Overview

ArkPets 是基于 Java/LWJGL（LibGDX 渲染栈）构建的桌面宠物程序，其故障来源可以归纳为四类：

排障时的总体策略是：先定位类别 → 应用对应解决方法 → 如仍失败则导出日志（必要时开启 DEBUG 等级）→ 借助调试热键或命令行参数复现与取证。

Architecture

故障排查决策流

下面的流程图展示了用户遇到问题后的官方推荐排查路径，节点均对应 docs/FAQ.md 中的实际条目：

图中"Angle原生渲染""下载策略""网络代理""导出日志"等操作均位于启动器的"选项"页面，是 ArkPets 内建的排障入口。

排障工具链

ArkPets 提供的排障工具彼此配合：日志等级决定信息量，命令行参数控制启动方式，调试热键提供运行时可视化取证，配置文件提供 JVM 级别的兜底开关。

问题详解

1. 启动桌宠后某些软件（游戏）崩溃

在打开桌宠的情况下，基于某些特定游戏引擎的游戏可能无法正常运行。官方调查显示该问题源于这些游戏引擎与桌宠游戏引擎 LWJGL 之间的冲突。规避方式是避免桌宠与受影响的游戏同时运行。

来源：docs/FAQ.md 第 15–17 条目。

2. 桌宠悬空站立 / 卡在桌面上

官方给出三种常见原因，按排查优先级如下：

1. 桌面装饰类软件干扰：例如 WallpaperEngine 等壁纸软件、桌面整理软件，会干扰桌宠的窗口检测，导致"窗口站立"等功能异常。
2. 透明边界：桌宠站立在了某些软件窗口不可见的透明边界上方。
3. 重力加速度被设置为零：可在启动器"行为"页面重新调整。

来源：docs/FAQ.md 第 19–24 条目。

3. 桌宠的窗口背景是黑色的

该问题（Issue #7 的调查结果）主要与 NVIDIA GeForce 系列显卡有关，尤其涉及显卡驱动与 OpenGL 的图形设备接口（GDI）。FAQ 给出四种方法，按推荐顺序：

• 方法一（推荐）：启动器 →"选项"页面 → 渲染设置 - 其他 → 勾选"Angle原生渲染" → 重启桌宠。让渲染走 ANGLE（OpenGL over D3D）路径，绕开 NVIDIA 驱动的 GDI 兼容性问题。
• 方法二：在 Windows 图形设置中将程序目录中的 ArkPets.exe 和 runtime/bin/java.exe 一并设为 [节能] 模式；如仍失败则改为 [高性能]，再进入 NVIDIA 控制面板 →"管理3D设置" → 将 OpenGL GDI 兼容性 设为 [优先兼容性]。Win7 用户不适用此法。
• 方法三：在 NVIDIA 控制面板的"程序设置"中为 ArkPets.exe 与 runtime/bin/java.exe 将"首选图形处理器"改为 [集成图形]。
• 方法四：设备管理器 →"显示适配器" → NVIDIA 显卡属性 →"驱动程序"选项卡 → 若"回退驱动程序"按钮可用则执行回退。

设计意图：同一个进程实际由 ArkPets.exe（启动器）与 runtime/bin/java.exe（桌宠 JVM）两部分组成，因此所有 GPU 相关设置必须同时覆盖这两个可执行文件，否则只改一半可能无效。

4. "无法建立神经连接" / 网络异常导致模型下载失败

按官方给出的顺序依次尝试：

1. 多重试几次下载操作。
2. 在启动器"选项"页面中更换"下载策略"（切换下载镜像/通道）。
3. 如果使用了 VPN，在启动器"选项"处设置其"网络代理"地址。
4. 在启动器"模型"页面点击"模型库管理"按钮 → 点击"下载时遇到问题？"链接，按链接指引操作。
5. 更换到其他网络（例如移动热点）。
6. 关闭反病毒软件（例如卡巴斯基）和网络防火墙。

5. 缝合线与伪影（版本兼容性问题）

缝合线（透明线条）与伪影（异常色块或条纹）的直接原因是桌宠程序版本与模型库版本不一致。解决方式是尽可能将桌宠和模型库都更新到最新版本。官方兼容性矩阵如下（- 表示无问题，+ 表示部分模型出现问题，++ 表示所有模型都会出现问题）：

问题发生的历史原因与完整调查过程见 Issue #76。

6. 桌宠启动器所有文字乱码

调查显示该问题主要与系统本地安装了**思源黑体（Source Han Sans）**有关。可以通过强制让程序使用系统字体来规避乱码：

1. 进入程序所在目录中的 app 文件夹（或右键启动器桌面快捷方式 →"打开文件所在的位置" → 再打开 app 文件夹）。
2. 用记事本打开 ArkPets.cfg 文件。
3. 在文件最后一行下添加：

Source: FAQ.md

4. 保存文件，然后重启桌宠。

这是 JVM 级别的系统属性开关（-D 参数），通过 ArkPets.cfg 的 java-options 行注入到桌宠 JVM，属于启动器 UI 未暴露的兜底配置入口。

7. 如何获取程序日志文件

获取日志的标准流程：

1. 在启动器"选项"中点击"导出日志"。
2. 在日志对话框中点击"选择最近日志"，然后点击"导出所选的日志"。
3. 某些日志信息需要将"日志等级"设置为 DEBUG 之后才会被记录。

Source: FAQ.md

Core Flow：一次完整的排障流程

流程要点：

• 先配置后取证：多数渲染/网络类问题可以通过启动器"选项"页面的设置解决，无需日志。
• DEBUG 是取证门槛：只有 DEBUG 日志等级（或命令行 --debug）会记录完整调试信息并启用调试热键。
• 截图热键是渲染类问题的直接证据：S 键截图保存到工作目录下 temp/snapshot-<当前时间戳>.png，可直接附在 Issue 中。

Usage Examples

示例一：命令行以调试模式直接启动桌宠

当需要完整调试信息（含调试热键）时，将工作目录切换到程序目录后执行：

Source: CmdLine.md

注意：必须将命令行工作目录设置为程序文件所在目录，否则可能发生各种奇怪的错误。如果使用的是 .jar 版本，命令应以 java -jar ArkPets.jar 或 ArkPets.jar 开头（注意写完整文件名）。

示例二：加载外部渲染调试库

渲染类问题（如黑背景、伪影）可以用 RenderDoc 等工具捕获帧进行深入分析：

Source: CmdLine.md

其中 <path> 是外部库文件的绝对路径；--load-lib 需与 --direct-start 同时使用（v3.5.0+）。

示例三：通过配置文件强制系统字体（乱码修复）

Source: FAQ.md

调试热键参考

启用调试（日志等级 DEBUG 或启动参数 --debug）后可用：

Source: Debug.md

Configuration Options（排障相关）

Failure Modes, Edge Cases & Concurrency

• 双进程特性（最重要的边界情况）：ArkPets 实际由启动器 ArkPets.exe 与桌宠 JVM runtime/bin/java.exe 两个可执行文件构成。所有显卡/GPU 相关设置（Windows 图形设置、NVIDIA 控制面板）必须同时应用到两者，只设置其一往往无效。
• 工作目录依赖：命令行启动必须 cd 到程序目录，否则会出现"各种奇怪的错误"——这类错误容易被误判为程序缺陷，实际是相对路径（如 app/ArkPets.cfg、temp/ 截图目录）解析失败所致。
• 版本不匹配的隐性故障：缝合线/伪影并非"损坏"，而是桌宠版本与模型库版本的兼容性矩阵问题；升级桌宠而不同步更新模型库，会落入 >=2.4.2 且 <=3.6.0 × 2025 年 3 月或更晚 的 ++（所有模型都出现问题） 区间。
• 杀软与防火墙拦截：网络类故障的最后排查项；卡巴斯基等反病毒软件会静默拦截模型下载，表现为"无法建立神经连接"。
• 本地字体污染：系统本地安装的思源黑体会导致启动器全部乱码，这是外部环境而非程序自身缺陷。
• 日志等级门槛：默认 INFO 等级不会记录调试级信息，反馈 Issue 前若未切到 DEBUG，导出的日志往往缺少关键线索。

Performance / Operational Notes

• 渲染类问题（黑背景）优先尝试代价最小的方案：勾选"Angle原生渲染"比重装驱动、回退驱动等方法风险低得多。
• --quiet（ERROR 等级）适合无人值守长期运行场景，可减少日志写入量；排障时应临时切换到 --debug，取证完成后再切回。
• 调试热键 D（帧率 + JVM 堆内存）可用于定位性能/内存问题；W（系统窗口列表）可用于诊断"窗口站立"类物理行为异常，直接观察桌宠能检测到哪些窗口。
• 截图文件落在工作目录 temp/ 下，长期运行时注意清理磁盘占用。

Extension Points

• app/ArkPets.cfg 的 java-options 行是官方认可的 JVM 级扩展入口：任何 -D 系统属性（如 arkpets.usesystemfont）都可以从这里注入，无需修改程序。
• 命令行 --load-lib 允许挂载任意外部本地库（RenderDoc 等 GPU 调试器），为渲染问题提供第三方取证途径。
• --config <path>（v3.11.0+）支持以指定配置文件启动，便于在多套配置间切换以隔离问题。

Related Links

• FAQ.md（官方常见问题解答源文档）
• Debug.md（调试模式与热键）
• CmdLine.md（命令行启动）
• Issue #7（黑背景问题调查）
• Issue #76（缝合线/伪影问题调查）