Wox 报错与错误代码详解：按症状定位故障的排查手册

先纠正一个误解

很多人搜索「Wox 错误代码」，是期待像系统蓝屏那样有个编号可以对照。但实际情况是：Wox 很少输出编号错误码，它更常表现为「某个功能不工作了」。

所以排查的正确入口不是「查代码」，而是「按症状定位环节」。这篇按故障发生的阶段分类整理，对着现象找即可。

如果你确实在日志里看到了一段异常信息，下面也列出了常见几类的含义。

按症状查：六类常见表现

这张表覆盖了绝大多数情况。先定位到环节，再看下面具体的日志线索。

日志里最常出现的几类信息

关于配置解析失败

关键词通常是 JSON 解析相关的异常。含义很直白：某个配置文件的结构不合法，程序读不进去。

常见诱因是手动编辑配置时多写或漏写了一个逗号、括号不配对，或者异常关机导致写入中断。处理方式是把可疑的配置文件改名备份，让程序重建默认配置。

关于文件或目录不存在

这类信息多半是在提示某个路径失效：插件目录被移动、Everything 的路径变了、索引目录被删除。

它通常不会直接导致程序崩溃，但会让对应功能静默失效。看到这类信息，去设置里核对路径即可。

关于依赖加载失败

出现 DLL 加载失败或模块找不到时，方向是运行库缺失。补齐 Visual C++ 运行库、.NET 运行时或 WebView2 运行时，多数情况能解决。

关于权限被拒绝

这类信息说明程序尝试访问某个路径或注册某个热键时被系统拒绝。可能是权限不足，也可能是被安全软件拦截。

处理方式：先确认是否需要管理员权限，再检查安全软件的拦截记录。

关于网络请求超时

只在使用联网类插件时出现。含义是插件访问外部服务失败，可能因为网络、代理或服务端不可用。

哪些报错可以忽略

不是所有日志里的红色信息都需要处理。以下几类通常无害：

• 启动时的主题或图标加载警告。资源文件找不到时会回退到默认样式，功能不受影响。
• 单次网络请求失败。联网插件偶发超时，下次调用会重试。
• 已卸载插件的残留引用。清理插件目录后可能出现，不影响主程序。
• 调试级别的信息输出。这类不是错误，只是详细日志。

判断标准很简单：对应功能是否真的不能用。功能正常就说明只是一条警告，不必处理。

哪些必须处理

反过来，这几类看到就要管：

1. 反复出现的崩溃记录。每次启动都崩，说明有稳定的触发条件。
2. 配置写入失败。这意味着你的设置改完不会保存，下次启动又回到旧状态。
3. 索引数据库损坏。表现为搜索结果异常缺失或重复，需要重建索引。
4. 权限被持续拒绝。会让某些功能永久失效，且不会自愈。

提交问题时应带上什么

如果排查后仍无法解决、需要向社区求助，把这几样带上，能大幅提高被回应的概率：

• Wox 的具体版本号（v1 还是 v2、完整版本号）
• Windows 版本与位数
• 是否安装了 Everything，以及它的版本
• 出错前你做了什么操作（这一步最关键）
• 日志里相关时间段的片段，而不是整份日志
• 已经试过哪些排查步骤、结果如何

只说「打不开」几乎无法得到有效回复，因为同样的症状可能对应五六种原因。把「我做了什么」和「试过什么」写清楚，别人才能帮你排除。

一个减少故障的预防清单

与其等出问题再排查，不如把这几个习惯养成：

• 定期备份 %APPDATA%\Wox\ 目录
• 不在同一时间做多项配置改动，出问题好定位
• 插件只装来源可追溯的，装完确认能正常加载
• 大版本升级前先导出插件清单
• 把安装目录与配置目录加入安全软件白名单

这五条能消掉大部分「突然坏了」的场景。启动器是每天要用的工具，稳定性值得花几分钟维护。

一个真实的排查路径示例

用一个具体场景把上面的方法串起来。症状是：Wox 能呼出，但搜文件永远是空的。

第一步，输入 calc。能调出计算器，说明主程序正常、程序索引正常。问题锁定在文件索引。

第二步，打开 Everything 自己的窗口，搜同一个关键词。能搜到——说明索引是好的，问题在「Wox 和 Everything 之间的连接」。

第三步，检查 Wox 设置里 Everything 的路径。发现指向的是 D 盘旧位置，而 Everything 已经重装到了 C 盘。这就是根因。

第四步，改正路径、重启 Wox，问题解决。

整个过程三步定位、一分钟解决。但如果一开始就去翻日志、重装程序、清缓存，可能要折腾半小时还找不到原因。