清单文件 manifest.json

每个微应用包的根目录必须包含一个 manifest.json 清单文件，它描述了微应用的基本信息、UI 入口、窗口尺寸、权限声明、事件脚本和设置项。

一个完整的示例：

json

{
  "manifest_version": 1,
  "name": "my-miniapp",
  "author": "your-name",
  "title": "我的微应用",
  "description": "一个示例微应用",
  "version": "1.0.0",
  "homepage": "https://example.com",
  "icon": "assets/icon.png",
  "entry": {
    "url": "index.html"
  },
  "window": {
    "width": 900,
    "height": 700
  },
  "permissions": ["network", "tasks.create", "tasks.list"],
  "network": {
    "urls": ["https://api.example.com/*"]
  },
  "scripts": [],
  "settings": [
    {
      "name": "quality",
      "title": "默认画质",
      "description": "解析视频时优先选择的画质",
      "type": "string",
      "value": "high",
      "options": [
        { "label": "高清", "value": "high" },
        { "label": "标清", "value": "standard" }
      ]
    }
  ]
}

字段总览

字段	类型	必填	说明
`manifest_version`	`1`	否	清单版本，当前固定为 `1`
`name`	`string`	是	微应用内部名称
`title`	`string`	是	展示名称，显示在微应用管理界面与商店中
`description`	`string`	否	简介，最多 1024 个字符
`version`	`string`	是	版本号，遵循 semver 规范
`author`	`string`	否	作者名
`homepage`	`string`	否	主页地址
`repository`	`object`	否	源码仓库信息 `{ url, directory? }`
`icon`	`string`	否	图标，包内相对路径（如 `assets/icon.png`）
`entry`	`object`	否	UI 入口，未声明则不支持打开页面
`window`	`object`	否	桌面端窗口尺寸配置 `{ width, height }`
`permissions`	`string[]`	否	平台权限声明，默认 `[]`
`network`	`object`	否	网络白名单 `{ urls: [...] }`，见下方 network
`scripts`	`array`	否	事件脚本声明，默认 `[]`
`settings`	`array`	否	设置项声明，默认 `[]`

基本信息

name 与 author

name 是微应用的内部名称；author 为作者名，两者用于标识微应用的来源。

name 与 author 不能包含路径分隔符、控制字符、系统保留字符、.、..，也不能以空格或点结尾。

title 与 description

title 是面向用户的展示名称；description 会展示在管理界面与商店详情页。

version

版本号用于更新判断，必须遵循 semver 规范并严格递增（见版本更新）。

repository（可选）

源码仓库信息，便于溯源与展示：

json

{
  "repository": {
    "url": "https://github.com/your-name/my-miniapp",
    "directory": "packages/my-miniapp"
  }
}

directory 用于微应用位于仓库子目录的场景。

entry（UI 入口）

json

{
  "entry": {
    "url": "index.html"
  }
}

url：页面入口，必须是包内相对路径，指向的文件必须存在于构建产物中。打开微应用时，迅雷创建独立窗口并从本地加载该页面。

页面开发的细节见页面与窗口。

window（窗口配置）

json

{
  "window": {
    "width": 900,
    "height": 700
  }
}

仅对 miniapp 入口类型且桌面端生效。width / height 指窗口内容可视区的初始宽高（单位 px），不包含标题栏和边框；窗口标题始终使用 manifest 的 title，页面修改 document.title 不会改变它。

permissions（权限声明）

声明微应用会使用的受保护能力：

json

{
  "permissions": ["network", "tasks.create", "tasks.list", "tasks.detail", "blob", "webview"]
}

当前支持的权限：network / tasks.create / tasks.list / tasks.detail / tasks.file.access / tasks.update / tasks.delete / blob / webview。

不支持 tasks、tasks.* 等通配写法。权限与能力的对应关系及校验语义见平台能力 · 权限模型。

只声明用到的权限

权限声明会展示给用户，也会在商店审核时检查。申请与功能无关的权限可能导致审核被拒，请遵循最小权限原则。

network（网络白名单）

network 声明微应用允许直接访问的远程地址。页面与事件脚本中发起的网络请求（fetch / XMLHttpRequest / WebSocket / EventSource / sendBeacon）必须同时满足两个条件才会放行：

permissions 中声明了 "network"；
请求 URL 命中 network.urls 中的至少一条规则。

json

{
  "permissions": ["network"],
  "network": {
    "urls": ["https://api.example.com/*"]
  }
}

字段	类型	必填	说明
`urls`	`string[]`	否	允许直接访问的 URL 匹配规则列表，默认 `[]`

规则说明：

多条规则之间为或关系，命中任意一条即放行；network.urls 只支持 协议://主机/路径 形式及省略路径的写法，例如 https://* 匹配任意 HTTPS 主机和路径；
*:// 匹配任意协议，*://example.com/* 可同时放行该主机的 HTTP(S) 与 WS(S) 请求。也可写 ws://example.com/* / wss://example.com/* 限定协议；
事件匹配支持的 <all_urls> 和 协议:* 不授予网络访问权限，写在 network.urls 中不会命中；
只声明 network 权限但 urls 为空、或请求未命中任何规则时，请求会被拦截（不影响安装，只在运行时生效）。

network 不管理的范围

任务下载 URL（tasks.create 的 req.url）与辅助 WebView 不受 network 约束。页面引用的远程资源（脚本、样式等）仍然禁止——声明 network 不会放开资源加载限制。

scripts（事件脚本）

声明在下载任务生命周期中自动执行的脚本：

json

{
  "scripts": [
    {
      "event": "onResolve",
      "match": {
        "urls": ["*://example.com/*"]
      },
      "entry": "events/onResolve.js"
    }
  ]
}

字段	说明
`event`	事件名：`onResolve` / `onStart` / `onError` / `onDone`
`match.urls`	URL 匹配规则（Chrome match pattern 风格）
`match.labels`	请求标签匹配条件（可选）
`entry`	脚本文件，包内相对路径

match 未声明或没有任何匹配条件时，该脚本不参与事件匹配。详见钩子事件。

settings（设置项）

声明微应用的设置项，迅雷会根据声明自动渲染设置界面，无需自行开发设置页面：

json

{
  "settings": [
    { "name": "autoStart", "title": "自动开始下载", "type": "boolean", "value": true },
    { "name": "maxConnections", "title": "最大连接数", "type": "number", "value": 8 },
    {
      "name": "quality",
      "title": "默认画质",
      "description": "解析视频时优先选择的画质",
      "type": "string",
      "value": "high",
      "options": [
        { "label": "高清", "value": "high" },
        { "label": "标清", "value": "standard" }
      ]
    }
  ]
}

Setting 字段

字段	类型	必填	说明
`name`	`string`	是	设置项唯一名称，运行时通过 `xunlei.settings.<name>` 读取
`title`	`string`	是	展示标题
`description`	`string`	否	设置项说明
`type`	`string` / `number` / `boolean`	否	值类型，默认 `string`
`value`	同 `type`	否	默认值
`options`	`array`	否	选项列表 `{ label, value }`，声明后渲染为下拉选择

控件映射

声明	渲染控件
`type: "string"` 且无 `options`	文本输入框
`type: "number"` 且无 `options`	数字输入框
`type: "boolean"`	开关
声明 `options`	下拉选择器

用户保存的设置值优先于 value 默认值；微应用内通过 xunlei.settings.<name> 读取当前生效值（只读），见数据与日志。

路径规则

icon、entry.url 和 scripts[].entry 必须是相对微应用包根目录的路径：

路径	是否允许
`index.html`	✅ 包内相对路径
`assets/icon.png`	✅ 包内相对路径
`events/onResolve.js`	✅ 包内相对路径
`/Users/example/index.html`	🔴 绝对路径
`../outside.js`	🔴 跳出包根目录
`https://example.com/index.js`	🔴 远程资源
`file:///tmp/index.html`	🔴 带协议的本地文件

下一步

页面与窗口 — 入口类型与窗口详情
平台能力 — 权限模型与 API 总览

清单文件 manifest.json ​

字段总览 ​

基本信息 ​

name 与 author ​

title 与 description ​

version ​

repository（可选） ​

entry（UI 入口） ​

window（窗口配置） ​

permissions（权限声明） ​

network（网络白名单） ​

scripts（事件脚本） ​

settings（设置项） ​

Setting 字段 ​

控件映射 ​

路径规则 ​

下一步 ​

清单文件 manifest.json

字段总览

基本信息

name 与 author

title 与 description

version

repository（可选）

entry（UI 入口）

window（窗口配置）

permissions（权限声明）

network（网络白名单）

scripts（事件脚本）

settings（设置项）

Setting 字段

控件映射

路径规则

下一步