# 插件包

`.flyext` 是一个 ZIP 格式的插件包，根目录包含 `manifest.json`。安装时，飞块读取清单、展开文件，再根据 `main` 启动后台。

## 文件结构

```text
example.flyext
├── manifest.json
├── index.js
├── assets/
│   └── icon.png
├── node_modules/
└── widgets/
    ├── page.html
    └── config.html
```

如果把整个项目文件夹嵌进 ZIP，清单就不在包根目录，飞块无法识别。使用[打包工具](../../publishing/package.md)可以生成正确结构。

`main`、顶层 `icon`、`widgets[].page` 和 `configPage` 使用插件包内的相对路径。页面用相对路径加载同目录资源，例如 `./style.css`。包中的文件通过普通文件和目录组织，安装器会检查路径并拒绝符号链接。图标图片要随包分发，格式和显示规则见[插件图标与资源](../../reference/icons.md)。

## 插件身份

顶层 `id` 是插件的长期标识。用户保存的动作绑定、状态引用和服务依赖都包含它，更新插件时保留这个 ID。`version` 是插件发布版本，使用 SemVer，例如 `1.2.0`；`apiVersion` 当前填写 `1`。

在商店发布时，插件 ID 还对应开发者账号的命名空间，见[发布插件](../../publishing/marketplace.md)。

## 运行平台

顶层 `hostPlatforms` 声明插件可启动的平台。动作可通过同名字段声明其非空子集；其他贡献仍须支持整包声明。包含原生程序时，对应动作在已声明支持的平台上须具备相应工具及依赖。也可以按平台分别发布包。平台枚举和清单属性见 [manifest.json](../../reference/manifest.md)。

## 包大小

压缩包最多 256 MiB，单个文件最多 128 MiB，展开总量最多 512 MiB。安装器同时检查 ZIP 条目数量、目录深度和 CRC，以确认文件完整。