故障排查

当功能不如预期时，先在这里对照症状找原因，再决定是否需要向开发者反馈。每条按 现象 → 原因 → 操作 给出，Kabegame 的 UI 文案以「」标出。

查看日志

目前 Kabegame 没有持久化的日志文件，后端信息仅写入进程 stderr。若需要排查严重问题，可以：

从终端启动应用，观察 stderr 输出（Windows 下建议用 PowerShell / CMD 直接运行 exe）。
桌面端前端报错可在 WebView DevTools 中查看（右键「检查」或按 Ctrl+Shift+I）。

任务失败排查

现象：任务大量失败，详情显示「请求失败，重试（{attempt}/{max}）：{detail}」

原因：网络不稳，或并发过高导致站点限流。
操作：
1. 打开任务抽屉，进入失败任务详情查看「失败信息」。
2. 到「设置」降低「最大并发下载量」（1–10），或提高「网络失效重试次数」（0–10）。
3. 若需要把错误带给插件作者，点击「复制错误信息和运行参数」或「复制错误详情」按钮。

现象：任务详情显示「图片下载失败：{url} — {detail}」

原因：目标 URL 失效、站点返回错误，或插件解析逻辑出错。
操作：先对失败项重试；若持续失败，复制错误详情并反馈给对应插件作者。

现象：任务日志里出现「图片后处理失败：{detail}」或「入队失败 {url}：{detail}」

原因：落盘或入队阶段出错，通常与磁盘空间、权限或插件脚本相关。
操作：检查磁盘空间与保存目录权限；若错误来自插件脚本，复制详情反馈给插件作者。

网络与代理

Kabegame 跟随操作系统的网络配置，没有应用内的用户代理设置。如需走代理，请在操作系统层面配置代理或使用系统级代理工具。

现象：「加载商店失败（请检查商店源配置）」或「刷新失败」「加载商店源列表失败」

原因：商店源 URL 不可达。
操作：到插件源管理中确认源 URL 是否可达、切换或移除失效源；必要时在系统层面启用代理。详见插件商店。

权限与平台限制

macOS：拖入「图片」「桌面」「文稿」「下载」文件夹失败

原因：这些是 macOS 系统受保护目录，拖拽路径无权读取。
操作：
1. 优先使用「添加文件夹」按钮，通过系统选择器选中该文件夹后导入。
2. 若仍无法访问，打开「系统设置」→「隐私与安全性」→「文件与文件夹」，为 Kabegame 开启对应目录的访问权限。

详见画廊中的 macOS 导入章节。

Android：壁纸轮播停了、下载任务挂起

原因：系统省电优化把应用后台进程杀掉了。
操作：看到底部「后台运行受限，点击开启」提示时直接点击；或在弹窗「开启后台运行权限」中点「立即开启」，按引导到系统授权页允许后台运行。

Windows：提示「需要管理员权限」

原因：该设置（如系统级壁纸改写）需要启用 super 模式。
操作：按对话框提示，点击窗口左下角的开关启用 super 模式后再修改。

画册盘（虚拟盘）

画册盘依赖系统驱动：Windows 需 Dokan，macOS 需 macFUSE，Linux 需 FUSE。Android 与 Web 版本不包含虚拟盘。

现象：toast 提示「打开虚拟磁盘失败」或「打开虚拟磁盘文件夹失败」

原因：挂载点盘符被占用，或驱动状态异常。
操作：按提示「可以尝试在设置中关闭再重新开启画册盘。」；检查挂载点盘符未被其他软件占用；Windows 确认已安装 Dokan，macOS 确认已安装 macFUSE。

现象：提示「请先填写挂载点（例如 K:\）」

原因：挂载点为空。
操作：到设置中填写形如 K:\ 的挂载点后再开启。

现象：已开启画册盘但资源管理器里看不到盘符

原因：挂载点被其他软件占用，或画册盘实际未开启。
操作：先确认「画册盘」开关已打开，再检查挂载点盘符是否被占用，必要时换一个盘符。

现象：后端返回「当前模式不支持虚拟盘」

原因：你运行的是不含虚拟盘的版本（Android 或 Web）。
操作：在桌面版（Windows / macOS / Linux）使用虚拟盘。详见安装。

壁纸模式切换

现象：设置壁纸时弹窗「切换到插件模式将修改系统壁纸插件为 Kabegame 壁纸插件，是否继续？」或「该媒体需要窗口模式才能设置为壁纸。是否切换到窗口模式？」

原因：当前壁纸模式不支持所选媒体，前端会引导你切换。
操作：按需点确定由应用自动切换。

现象：「切换模式失败」或「切换模式超时：后端未在 30 秒内响应」

原因：壁纸后端挂起。
操作：重启应用。

现象：提示「该画册没有画哟，先去画廊添加进去吧！」

原因：轮播选中的画册是空的。
操作：先到画廊把图片加入该画册再开启轮播。

插件相关

现象：爬虫运行报错 `Failed to eval crawler script: ...`

原因：插件脚本执行异常。
操作：复制错误详情反馈给插件作者；必要时在插件商店切换到其他插件。

现象：Android 上选择某插件时提示安卓不支持

原因：该插件是 WebView 后端，需要真实浏览器窗口，安卓不支持。V8 后端插件在安卓可用。
操作：换一个同站点的 V8 后端插件；或改用桌面端运行该 WebView 插件。

现象：安装插件时报「Rhai 后端已停止支持」

原因：该插件是早期的 Rhai 插件，Rhai 后端自 4.3.0 起已移除。
操作：等待作者把插件迁移到 V8 / WebView 后端，或换一个同站点的现代插件。

现象：发起抓取时提示「当前应用版本过低：需要 Kabegame {required} 或更高，当前为 {current}。」

原因：该插件声明了最低 App 版本。
操作：升级 Kabegame 到提示的版本。

现象：安装或更新插件失败

原因：网络不可达或源配置错误。
操作：检查网络与商店源；见上文网络与代理。

畅游（Surf）

现象：Linux 下畅游只能浏览，无法下载图片/视频

原因：Linux WebKit 限制，属于系统能力约束，不是 bug。提示文案：「Linux 下因 WebKit 限制，畅游无法下载图片/视频，仅可浏览页面。」
操作：在桌面切到「开始收集」做本地导入，或改用 Windows/macOS 桌面端。

原因：会话或 Cookie 桥接异常。
操作：重试；必要时重启应用。

升级后大量功能失效

现象：升级到新版本后，「画廊数据加载失败」或多个按钮点了无反应、报「命令不可用/找不到」

原因：新版本的权限声明存在回归 bug，不是你能在客户端修复的。
操作：回滚到上一个稳定版本，并向开发者报告该版本号与复现步骤。

显示异常

若中日韩字符显示异常，请检查系统字体是否包含完整的 CJK 支持。

平台差异

故障类别	Windows	macOS	Linux	Android
日志仅 stderr	是	是	是	是
macOS 受保护目录	—	是	—	—
画册盘驱动	Dokan	macFUSE	FUSE	不支持
super / 管理员模式	是	—	—	—
后台运行权限	—	—	—	是
畅游下载受限	—	—	是	—
JS 爬虫插件	是	是	是	不支持