Wox插件开发完全指南：用JavaScript打造你的专属效率工具

Wox的真正威力在于其开放的插件架构。作为一款支持JavaScript和Python开发的跨平台启动器，Wox允许开发者通过简单的代码扩展实现个性化功能 。本文将带你从零开始开发第一个Wox插件，无论你是想实现内部工具集成，还是计划发布到社区，这份指南都是你的最佳起点。

为什么选择开发Wox插件？

在深入技术细节前，先了解Wox插件生态的独特优势：

• 低门槛高上限：基于Node.js开发，前端开发者可快速上手，同时支持复杂后端功能
• 实时热重载：开发模式下自动重新加载，无需重启Wox即可看到代码变更效果
• 跨平台兼容：一次开发，Windows/macOS/Linux三端通用
• 丰富的API支持：支持剪贴板操作、浏览器URL获取、文件系统访问等系统级功能

开发环境准备

开始编码前，确保你的环境满足以下要求 ：

1. Node.js：建议v16+版本
2. pnpm：作为包管理器（Wox官方推荐）
3. Wox主程序：安装v2版本以获取完整插件支持
4. 代码编辑器：VSCode配合JavaScript/TypeScript插件

插件核心架构解析

每个Wox插件由三个核心组件构成 ：

1. plugin.json - 插件的配置身份证

这是Wox识别插件的入口文件，包含关键元数据 ：

• Id：全局唯一标识符（建议使用GUID）
• TriggerKeywords：触发关键词数组，支持多别名如["calc", "calculator", "计算"]
• Runtime：指定运行环境（Nodejs/Python/Dotnet）
• EntryFile：主入口文件路径

2. 查询处理器（Query Handler）

处理用户输入并返回结构化结果。Wox支持两种查询类型 ：

• QueryTypeInput：用户手动输入的常规查询
• QueryTypeSelection：基于选中文本的上下文查询（效率神器）

3. 结果渲染器（Result Renderer）

定义搜索结果的展示样式，包括图标、标题、子标题和操作按钮。

实战：开发一个"IP查询"插件

以下是一个最小可运行的插件示例结构：

// 目录结构
my-ip-plugin/
├── plugin.json      # 插件配置
├── main.js          # 入口逻辑
├── node_modules/    # 依赖包
└── icon.png         # 插件图标（建议64x64）

在plugin.json中定义基础配置 ：

{
  "Id": "com.example.ipquery",
  "Name": "IP查询",
  "Description": "快速查询本机IP和公网IP地址",
  "Author": "YourName",
  "Version": "1.0.0",
  "MinWoxVersion": "2.0.0",
  "Runtime": "Nodejs",
  "EntryFile": "main.js",
  "TriggerKeywords": ["ip", "地址"],
  "Icon": "icon.png"
}

调试与发布流程

1. 本地开发模式：在插件目录运行pnpm run dev启动热重载
2. Wox配置：在插件管理设置中添加"Local Plugin Directories"指向你的开发目录
3. 实时测试：在Wox中输入触发词查看效果，修改代码后自动刷新
4. 日志排查：通过Wox日志系统查看运行时错误和调试信息

学习资源推荐

虽然Wox v2官方文档仍在完善中，但社区已提供丰富的参考资源：

• DeepL翻译插件：学习外部API调用和异步处理
• Spotify控制插件：了解如何与本地应用交互
• 基础编码插件：掌握Base64/URL编码等工具类插件开发