启动白屏或无法运行——常见启动失败场景排查

官方 FAQ 里的启动问题

Chaldea 官方文档的 FAQ 里专门列了这个问题，以下是整理：

情况一：下载了 zip 直接双击运行

这是 Windows / Linux 用户最常见的错误。

• ❌ 不要在 zip 文件里直接双击 exe
• ✅ 先解压再运行

Windows 会允许你在 zip 压缩包里"看起来可以"直接双击文件，但实际上是临时解压到系统临时目录。程序运行过程中需要访问同目录的其他文件（如 Flutter 的 dll 文件），这些文件还在 zip 里读不到。

正确做法：右键 zip → 全部提取 → 选一个普通用户目录（如 D:\Apps\Chaldea\）→ 解压 → 双击 chaldea.exe。

情况二：解压到了需要管理员权限的目录

Windows 用户常见：

• ❌ 不要解压到 C:\ 根目录
• ❌ 不要解压到 C:\Program Files\
• ❌ 不要解压到 C:\Program Files (x86)\
• ❌ 不要解压到系统隐藏的 ProgramData 目录

这些目录需要管理员权限才能读写。Chaldea 是普通用户程序，不需要管理员权限运行。如果数据目录（userdata/、backup/）创建失败，程序就会启动白屏。

正确做法：解压到用户目录下的普通文件夹：

• C:\Users\<你的用户名>\Apps\Chaldea\
• D:\Apps\Chaldea\
• 桌面新建一个文件夹也行

情况三：放在了网络 / 映射盘符

• ❌ 不要放在 FTP / SMB / NFS 网络盘
• ❌ 不要放在 OneDrive / 百度网盘 / 坚果云的同步文件夹里
• ❌ 不要放在映射盘符（Z:\ 这种指向网络路径的盘符）

原因：Chaldea 需要频繁读写本地文件（userdata.json、backup/、game/）。网络盘的延迟和同步行为会干扰文件读写，导致白屏或数据损坏。

正确做法：解压到本地硬盘的普通文件夹。

情况四：Windows 7

Chaldea 不支持 Windows 7。 最低要求 Windows 10 x64。

如果你还在用 Windows 7：

• 升级到 Windows 10 / 11（推荐）
• 或使用 Web 版（但 Web 版在 Windows 7 的浏览器上可能也有兼容性问题，因为需要现代浏览器）

情况五：Firefox 隐私模式

Web 版在 Firefox 的隐私模式或"关闭 Firefox 时清除历史"设置下，会因为 IndexedDB 被禁用而无法启动。

解决：退出隐私模式、关闭"清除历史时禁用 IndexedDB"的相关设置。

情况六：只有 32 位系统

• ❌ Windows 32 位不支持
• ❌ Linux 32 位不支持
• ✅ 必须 64 位系统

下载安装包时注意文件名里的 x64。如果你是从旧版本升级，确认新安装包也是 _x64.zip。

情况七：杀毒软件拦截

杀毒软件可能把解压后的 Chaldea 目录隔离或删除关键文件。

解决：

• 查看杀毒软件的"隔离区"（可能有被删的文件）
• 把整个解压目录加入信任 / 白名单
• 重新解压一次

快速排错清单

按这个顺序排查，90% 的启动问题能解决：

1. ✅ 确认已经完全解压（不是在 zip 里运行）
2. ✅ 确认解压到了本地硬盘普通目录（不是 C 盘根、不是网络盘）
3. ✅ 确认系统版本符合最低要求（Win10+、64 位）
4. ✅ 确认杀毒软件没拦截
5. ✅ 换个目录试试（比如从 D:\Apps 换去 C:\Users\<你>\Documents）
6. ✅ 下载最新版本重新解压
7. ✅ 看日志文件（root_path/logs/ 下有运行日志，能看到具体报错）