manifest.json 完整配置逐字段讲解

manifest.json 完整配置逐字段讲解
- 完整字段清单
- 顶层字段
  - id
  - version
  - platform
  - arch
  - name
  - logo
  - keywords
  - devTools
  - 额外字段
- main 对象字段
- 插件类型对应的配置差异
- 配置流程
- 常见坑

manifest.json 是插件唯一的必需文件。它同时决定三件事：插件是什么（身份）、能在哪跑（兼容性）、怎么被加载（入口）。这一节把官方列出的每一个字段都过一遍。

完整字段清单

先看官方给出的完整形态，再逐个解释：

{
    "id": "LBCZE8V6LPCKD",
    "version": "1.0.0",
    "platform": "all",
    "arch": "all",
    "name": "窗口插件",
    "logo": "/logo.png",
    "keywords": [],
    "devTools": false,
    "main": {
        "url": "index.html",
        "width": 640,
        "height": 480,
        "minWidth": 640,
        "minHeight": 480,
        "maxWidth": 640,
        "maxHeight": 480,
        "alwaysOnTop": false,
        "frame": true,
        "fullscreenable": true,
        "maximizable": true,
        "minimizable": true,
        "resizable": true,
        "backgroundColor": "#ffffff",
        "childWindow": false,
        "followCursor": false,
        "multiple": false,
        "runAfterInstall": false
    }
}

顶层字段

id

插件 ID，由 Eagle 在创建插件时生成，形如 LBCZE8V6LPCKD。这个值会写进每个用户的数据里，是 Eagle 认插件的唯一凭据。一旦发布就不要改——改了等于换了一个新插件，老用户不会自动迁移。

version

语义化版本号 主版本.次版本.修订号。每次更新都要往上加，因为商店靠它区分版本、判断是否需要用户手动更新。

platform

可选 all、mac、win。默认可以理解为 all。如果你的插件里有平台特定代码（比如 Windows 的注册表读写、macOS 的 Launch Services），就应该明确限定，而不是留 all 然后在运行时判断——这样商店才能正确地展示兼容性。

arch

可选 all、arm、x64。用了原生二进制依赖的插件必须精确指定。Eagle 是跨平台的，同一个插件可以按平台和架构分别打包，分别提交。

name

插件名称，商店列表里显示的就是它。审核标准里有明确要求：最多 30 个 Unicode 字符，使用空格分隔的语言时不超过 6 个单词。可以描述性提及 Eagle，但不得暗示是官方制作或背书。

logo

插件图标路径，仅支持 png、jpg、webp 格式。官方建议用 128×128 分辨率，PNG 格式（对透明度支持最好）。

keywords

关键字数组。除了插件名，用户也能用这些词搜到你。写法上建议用领域词而不是品牌词：「batch」「rename」「exif」这类用户真的会输入的词。

devTools

是否开启开发调试窗口，默认 false。开发阶段设 true 方便按 F12，发布版本必须是 false——这是审核标准「发布设置与可审核性」里的硬性项，devTools 为 true 会直接阻挡投稿。

额外字段

除了官方列出的，还有几个在特定场景下用到的：

fallbackLanguage：默认语言，配合 i18n 使用。
languages：支持的语系列表。
dependencies：依赖的内置扩展模块，例如 ["ffmpeg"]、["ai-sdk"]。

main 对象字段

main 只存在于窗口插件和背景服务插件（后者多一个 serviceMode）。

字段	类型	默认值	说明
`url`	string	—	入口页面
`width` / `height`	number	—	窗口默认宽高
`minWidth` / `minHeight`	number	—	窗口最小宽高
`maxWidth` / `maxHeight`	number	—	窗口最大宽高
`alwaysOnTop`	boolean	`false`	是否永远在其他窗口之上
`frame`	boolean	`true`	`false` 时使用无边框窗口
`fullscreenable`	boolean	`true`	能否进入全屏
`maximizable`	boolean	`true`	能否最大化
`minimizable`	boolean	`true`	能否最小化
`resizable`	boolean	`true`	能否调整大小
`backgroundColor`	string	`#FFF`	窗口背景色
`childWindow`	boolean	`false`	是否以子窗口形式打开（附属于主窗口）
`followCursor`	boolean	`false`	打开时自动定位在光标附近，需 4.0 Build22 以上
`multiple`	boolean	`false`	窗口能否多开
`runAfterInstall`	boolean	`false`	安装后自动打开
`serviceMode`	boolean	—	背景服务插件的关键字段

几个值得解释的设计意图：

backgroundColor 是防闪烁用的。 窗口弹出的第一帧，HTML 还没渲染完，用户看到的是一片纯色。把这个颜色设成接近你最终界面底色的值，视觉上就连续了。

multiple: false（默认）意味着窗口复用。 用户第二次点击插件时，窗口不会重建。这直接决定了代码写在哪：初始化逻辑放 onPluginCreate，刷新逻辑放 onPluginRun。

followCursor 是 4.0 Build22 新增的。 打开后窗口自动出现在鼠标附近，适合取色器、标尺这类需要快速连续操作的工具。官方特别说明：启用后窗口不记忆位置，每次打开都跟随光标。

childWindow: true 让窗口附属于主窗口。 移动主窗口时子窗口跟着动，适合「设置面板」这类从属于主界面的界面。

插件类型对应的配置差异

同一个文件，四种类型写法完全不同：

// 背景服务插件：main 里加 serviceMode
{
    "main": {
        "serviceMode": true,
        "url": "index.html",
        "width": 640,
        "height": 480
    }
}

// 格式扩展插件：不写 main，写 preview
{
    "preview": {
        "icns,ico": {
            "thumbnail": {
                "path": "thumbnail/icns.js",
                "size": 400,
                "allowZoom": false
            },
            "viewer": {
                "path": "viewer/icns.html"
            }
        }
    }
}

// 检查器插件：preview 里嵌套 inspector
{
    "preview": {
        "jpg,png": {
            "inspector": {
                "path": "index.html",
                "height": 100,
                "multiSelect": false
            }
        }
    }
}

判断插件类型不需要额外字段——Eagle 通过「有没有 main」和「preview 里有没有 inspector」自动推断。

配置流程

从 Eagle 插件面板的「开发者选项」创建骨架，让 Eagle 生成 id 和 logo。
填 name、version、keywords、logo。
按插件类型写 main 或 preview。
开发阶段设 devTools: true。
用 node -e "JSON.parse(require('fs').readFileSync('manifest.json'))" 验证 JSON 合法。
六套主题各测一遍界面。
打包前把 devTools 改回 false。

常见坑

发布版本忘了关 devTools。 这是一票否决项。养成习惯：打包前搜一遍整个文件里的 devTools。

logo 路径规则和 preview 里的 path 规则搞混。 logo 用前导斜杠（/logo.png），preview 下的 thumbnail.path 和 viewer.path 用相对路径（thumbnail/icns.js），两种写法规则不一样。

延伸注意： * 把 id 换成自己编的字符串。格式类似 LBCZE8V6LPCKD 的大写字母数字串。不确定就别动，让 Eagle 生成。 * 同时写了 main 和 preview。这会让人搞不清插件类型，也可能触发加载异常。二选一。

整理人：WorkBuddy

4.1 manifest.json 完整配置逐字段讲解