四种插件类型怎么选

Eagle 有四种插件类型。它们的差异不在技术难度，而在运行时机、触发方式和能用什么 API。选错类型会导致后面大量返工——比如你给一个需要后台常驻的功能写成了窗口插件，用户不点它它就永远不工作。

四种类型速览

怎么选：一个决策问题

问自己一个问题：这个功能需要「用户主动触发」还是「持续生效」？

需要用户主动触发、做完就结束 → 窗口插件。一键抠图、批量重命名、转格式、导出导入都属于这一类。官方文档说得很直接：绝大部分插件都应该用这种方式开发。默认选它，不会错。

需要在软件启动后一直生效 → 背景服务插件。后台同步、缩略图批量分析、定时检查更新属于这一类。它和窗口插件的开发方式几乎一样，唯一的差别是一个字段。

需要让 Eagle「能打开一种新文件」→ 格式扩展插件。注意它的能力边界最窄：官方文档明确写了目前格式扩展插件不支持 Eagle Plugin API 和 DevTools 调试功能。你的代码被扔进一个几乎裸奔的沙箱，只能用 Node 原生 API 解析文件、生成缩略图。

需要「选中某类文件时，右侧多出一块信息」→ 检查器插件。给 JPG 显示 EXIF、给音频显示波形、给设计稿显示尺寸和色板都属于这一类。检查器插件本质上是格式扩展插件的变体，定义方式非常像，但它能拿到 Eagle API。

三个决策要点

第一，格式扩展插件的能力限制要提前评估。 它拿不到 eagle.item，也就无法读取素材的其他元数据。如果你的缩略图生成逻辑需要「读取这个文件的标签来决定用什么风格渲染」，那这条路走不通，只能改做检查器插件。

第二，检查器插件需要 Eagle 4.0 Beta 17 以上版本。 这是硬性门槛，虽然现在早已满足，但如果你要给企业客户做兼容性说明，得提一句。

第三，背景服务插件必须处理资源库切换。 因为它随应用启动，如果用户中途切换了资源库，缓存里的路径就失效了。官方明确建议：需要依赖相对资源库路径时，透过 eagle.onLibraryChanged 做出对应调整。

四类插件的配置对照

四种类型在 manifest.json 里的写法完全不同，一眼就能分辨：

// 窗口插件
{
    "id": "LBCZE8V6LPCKD",
    "version": "1.0.0",
    "name": "窗口插件",
    "logo": "/logo.png",
    "keywords": [],
    "main": {
        "url": "index.html",
        "width": 640,
        "height": 480
    }
}

// 背景服务插件：唯一差别是 serviceMode
{
    "id": "LBCZEHP8BBO94",
    "version": "1.0.0",
    "name": "Service Plugin",
    "logo": "/logo.png",
    "keywords": [],
    "main": {
        "serviceMode": true,
        "url": "index.html",
        "width": 640,
        "height": 480
    }
}

// 格式扩展插件：不写 main，写 preview
{
    "id": "LARSKLB8OTOC2",
    "version": "1.0.0",
    "platform": "all",
    "arch": "all",
    "name": "Preview Plugin",
    "logo": "/logo.png",
    "keywords": ["icns"],
    "devTools": false,
    "preview": {
        "icns,ico": {
            "thumbnail": {
                "path": "thumbnail/icns.js",
                "size": 400,
                "allowZoom": false
            },
            "viewer": {
                "path": "viewer/icns.html"
            }
        }
    }
}

// 检查器插件：preview 里只嵌套 inspector
{
    "id": "cc41e899-5fc3-445c-a113-2d9573d6edcc",
    "version": "1.0.0",
    "platform": "all",
    "arch": "all",
    "name": "Inspector Plugin",
    "logo": "/logo.png",
    "keywords": [],
    "devTools": true,
    "preview": {
        "jpg,png": {
            "inspector": {
                "path": "index.html",
                "height": 100,
                "multiSelect": false
            }
        }
    }
}

对比这四段能发现一个规律：能拿到 Eagle API 的类型（窗口、背景服务、检查器）都在 HTML 页面里跑代码，用 eagle.onPluginCreate 启动；拿不到的类型（格式扩展）在独立的 js 与 html 文件里跑，通过回调参数接收数据。

格式扩展插件的回调契约

格式扩展插件的缩略图脚本导出一个 async 函数，参数由 Eagle 传入：

// thumbnail/icns.js
const fs = require('fs');

module.exports = async ({ src, dest, item }) => {
    return new Promise(async (resolve, reject) => {
        try {
            // 1. 解析源文件，把缩略图写到 dest
            // 2. 校验结果是否正确
            if (!fs.existsSync(dest)) {
                return reject(new Error(`icns file thumbnail generate fail.`));
            }
            // 3. 顺带回写尺寸信息
            item.height = 512;
            item.width = 512;
            // 4. resolve(item) 表示成功
            return resolve(item);
        }
        catch (err) {
            return reject(err);
        }
    });
};

src 是源文件路径，dest 是缩略图输出路径，item 是对应素材对象——你可以在生成过程中顺手修正它的 width 与 height，然后 resolve(item) 把修正结果带回去。reject 会让 Eagle 记录失败原因，这也是格式扩展插件唯一的错误反馈渠道（因为它不支持日志 API）。

快速验证清单

1. 你的功能是一次性操作吗？是 → 窗口插件。
2. 需要开机自动运行吗？是 → 背景服务插件。
3. 目标是让 Eagle 支持新文件格式吗？是 → 格式扩展插件，并确认不依赖 eagle.* API。
4. 目标是选中文件后展示额外信息吗？是 → 检查器插件。
5. 如果同时符合多个条件，选限制更少的那一类：窗口插件能力最全，放不下才考虑下沉到背景服务。
6. 拿不准就先做窗口插件。窗口插件随时可以加 serviceMode 变成背景服务，反过来却不行。

混用的可能性

四类不是互斥的。一个项目完全可以同时提交窗口插件和检查器插件：窗口插件负责复杂配置界面，检查器插件负责日常快速查看。Eagle 插件中心的每个条目独立安装独立审核，你也可以先发布窗口插件验证需求，再补检查器版本。

常见坑

为了「功能更持续」把窗口插件改成 serviceMode: true。 这会让插件在每次启动 Eagle 时都自动运行，占用内存、拖慢启动，而用户可能根本不需要它。只有真正需要后台常驻的功能才开这个开关。

在格式扩展插件里调用 eagle.item.getSelected()。 会在运行时直接报错。这类插件只能通过回调参数拿到 src、dest、item 这些信息，且不能调用 Eagle API。设计之初就要把逻辑和数据来源想清楚。

延伸注意： * 检查器插件设 multiSelect: true。 官方建议非特殊情况一律 false。多选时语义往往不明确，性能压力也大。

整理人：WorkBuddy