Wox插件开发入门：为Windows快速启动器创建你的第一个效率工具

开发环境准备

Wox v2支持Node.js和Python两种主流开发语言，开发者可根据技术栈选择：

Node.js开发环境

• Node.js LTS版本（推荐v18+）
• pnpm包管理器（npm/yarn也可）
• Wox v2主程序（官网下载）

Python开发环境

• Python 3.8+
• pip包管理器
• Wox v2主程序

插件架构解析

一个标准的Wox插件包含以下核心组件：

my-wox-plugin/
├── plugin.json          # 插件元数据与配置
├── main.js (或 main.py) # 主逻辑入口
├── icons/               # 图标资源
│   └── app.png
└── README.md            # 使用说明

plugin.json配置文件

这是Wox识别插件的关键文件，定义了插件的基本信息和入口：

{
  "Name": "MyFirstPlugin",
  "Version": "1.0.0",
  "Author": "YourName",
  "Description": "我的第一个Wox插件",
  "Website": "https://github.com/yourname/my-wox-plugin",
  "Entry": "main.js",
  "Icon": "icons/app.png",
  "Commands": [
    {
      "Command": "my",
      "Description": "触发词：输入my激活插件"
    }
  ]
}

实战：开发一个"快速打开项目"插件

假设你是开发者，经常需要在不同项目间切换。我们将创建一个插件，输入项目名称关键词即可快速打开对应文件夹。

Step 1: 初始化项目

# 创建项目目录
mkdir wox-project-launcher
cd wox-project-launcher

# 初始化Node.js项目
pnpm init

# 安装Wox插件SDK（如需要额外依赖）
pnpm add @wox-launcher/wox-plugin

Step 2: 编写主逻辑 (main.js)

const { WoxPlugin } = require('@wox-launcher/wox-plugin');
const path = require('path');
const fs = require('fs');

// 项目路径映射（实际应用中可从配置文件读取）
const projects = {
  'website': 'D:\\Projects\\company-website',
  'api': 'D:\\Projects\\backend-api',
  'docs': 'D:\\Projects\\documentation',
  'wox': 'C:\\Users\\YourName\\Projects\\wox-plugin'
};

class ProjectLauncher extends WoxPlugin {
  async query(query) {
    const keyword = query.toLowerCase();
    const results = [];
    
    // 模糊匹配项目
    for (const [name, projectPath] of Object.entries(projects)) {
      if (name.includes(keyword) || keyword === '') {
        results.push({
          Title: `打开项目: ${name}`,
          SubTitle: projectPath,
          Icon: 'icons/folder.png',
          Action: () => {
            // 使用系统默认方式打开文件夹
            require('child_process').exec(`start "" "${projectPath}"`);
          }
        });
      }
    }
    
    return results;
  }
}

module.exports = ProjectLauncher;

Step 3: 本地调试

Wox v2提供热重载功能，极大提升开发效率：

1. 在Wox设置中添加"本地插件目录"，指向你的项目文件夹
2. 在项目目录运行pnpm run dev启动开发模式
3. 修改代码后保存，Wox自动重新加载插件并显示通知
4. 在Wox搜索框输入触发词（如"my"）测试功能

进阶功能实现

1. 上下文菜单

为结果项添加右键菜单选项：

results.push({
  Title: `打开项目: ${name}`,
  SubTitle: projectPath,
  ContextMenu: [
    {
      Title: '在VS Code中打开',
      Action: () => exec(`code "${projectPath}"`)
    },
    {
      Title: '在终端中打开',
      Action: () => exec(`wt -d "${projectPath}"`)
    },
    {
      Title: '复制路径',
      Action: () => clipboard.writeText(projectPath)
    }
  ]
});

2. 异步数据处理

对于耗时操作（如API调用），使用异步避免阻塞主线程：

async query(query) {
  // 显示加载状态
  this.showLoading();
  
  // 异步获取数据
  const data = await fetchProjectData(query);
  
  return data.map(item => ({
    Title: item.name,
    SubTitle: `最后修改: ${item.lastModified}`,
    Icon: item.icon
  }));
}

3. 配置持久化

允许用户自定义项目路径：

// 读取用户配置
const settings = await this.loadSettings();
const projects = settings.projects || defaultProjects;

// 在plugin.json中定义设置UI
"Settings": [
  {
    "Name": "projects",
    "Type": "textarea",
    "Label": "项目列表(JSON格式)",
    "DefaultValue": "{}"
  }
]

打包与发布

本地打包

# 打包为.wox文件（实际为zip格式）
zip -r MyProjectLauncher.wox plugin.json main.js icons/

# 或直接拖放文件夹到Wox窗口安装

发布到社区

1. 在GitHub创建开源仓库，上传源码
2. 编写详细的README，包含安装说明和截图
3. 提交到Wox官方插件仓库（需遵循贡献指南）
4. 在社区论坛分享，收集用户反馈

调试技巧与常见问题

• 查看日志：Wox设置中开启开发者模式，查看详细运行日志
• 语法错误：使用VS Code等IDE的Lint工具提前发现错误
• 性能优化：避免在query函数中进行同步文件IO操作
• 跨平台注意：Windows路径使用双反斜杠或path.join处理