Wox 插件开发完全指南：用 JavaScript 写一个自己的插件

先理解插件在做什么

去掉所有脚手架之后，一个 Wox 插件只做一件事：接收用户输入的查询字符串，返回一组候选项。候选项包含标题、副标题、图标和一个「被选中时执行什么」的动作。

这条数据流是整个插件体系的核心。你不需要理解 Wox 的界面渲染、不需要处理键盘事件、不需要管窗口生命周期——那些都由主程序负责。你只要实现那个「输入字符串 → 输出列表」的函数。

插件目录长什么样

Wox 的插件存放在 %APPDATA%\Wox\Plugins\ 下，每个插件一个独立目录。一个最小可用插件通常只包含两个文件：

目录名建议和插件名一致，避免出现两个同名插件时难以分辨。开发阶段可以直接把目录建在 Plugins 下，改完代码重启 Wox 即可生效，不需要打包。

写一份最小可运行的清单文件

plugin.json 的核心字段只有几个：插件标识、显示名称、触发关键词、入口文件路径、以及运行时版本声明。

其中触发关键词最关键。它决定了用户在搜索框里输入什么前缀会激活你的插件。选词时注意两点：一是别和其他插件撞车，二是要短——最好两三个字符，长了就等于每次都要多敲几下。

如果你的插件是「无条件响应」（不需要特定前缀，任何输入都参与匹配），触发关键词可以留空或设为一个极短的符号。但这种做法会让插件对每次按键都执行一遍，性能开销较大，只适合逻辑极轻的场景。

实现入口函数

入口文件需要导出一个处理函数。它的职责分三步：

1. 解析参数——从查询字符串里取出真正需要的关键词。如果用户输入的是「前缀 + 空格 + 内容」，要先把前缀切掉。
2. 产出结果——把处理结果组装成候选项数组，每项包含标题、描述、图标和动作。
3. 返回——同步或异步返回数组都可以，异步适合需要网络请求的场景。

候选项里最重要的字段是「动作」。它决定了用户回车之后发生什么：打开一个网址、复制一段文本、启动一个程序、或者只是把结果展示出来让用户继续输入。

处理用户输入的几个实际坑

写插件时最容易踩的坑，几乎都出在参数处理上：

• 前后空格。用户输入经常带多余空格，切完前缀后务必再 trim 一次，否则匹配会失败。
• 中文输入法状态。中文输入时提交的字符串可能包含全角空格或未上屏的编码，需要做容错。
• 空参数。用户可能只输入前缀就回车，这时应该返回「用法提示」而不是空列表——空列表会让人误以为插件坏了。
• 超长输入。把整段文字当查询参数时要注意长度限制，过长的字符串可能导致匹配耗时暴增。

三个可以照着改的实例

实例一：内部系统直达

把公司内部常用系统的地址做成前缀加关键词的查询：输入前缀加项目编号，直接列出对应的工单页、文档页、监控面板。这类插件代码量极小，但对日常效率提升非常明显，是性价比最高的一个。

实例二：文本批量处理

把剪贴板里的文本做一次变换：转大写、转下划线命名、去除空行、格式化成 JSON。实现上只需要读剪贴板、做字符串处理、再写回剪贴板。适合经常在多种命名规范之间来回切换的人。

实例三：把查询结果当计算器用

接入一个汇率或单位换算接口，输入「100 usd」直接返回人民币金额。这类插件能体现异步请求的写法，也能让你熟悉「结果里带副标题说明」的展示方式。

调试与排错

插件不生效时，按这个顺序查，基本都能定位：

1. 插件是否出现在设置 → 插件列表里？不在，说明 plugin.json 格式有问题
2. 输入前缀后有没有任何反应？没有，说明触发关键词没对上
3. 有反应但结果为空？在入口函数里打日志，确认参数是否被正确接收
4. 报错但看不到信息？去看 %APPDATA%\Wox\Logs\ 下对应日期的日志

日志是排查插件问题最有效的手段，比反复改代码猜问题快得多。养成在关键分支打日志的习惯，能省掉大量时间。

要不要发布到社区

如果你的插件只服务于自己的内部系统，不必发布。如果做的是通用能力，可以考虑提交到社区仓库，好处是能被别人使用和反馈，也能促使你把文档和边界情况补全。

发布前至少要准备三样东西：一份说明用途和用法的 README、一张清晰的图标、以及一份写清已知限制的说明。这三样比代码质量更影响别人愿不愿意用。