本地调试

本页介绍如何把开发中的微应用安装到迅雷里调试，以及常用的排查手段。

安装本地微应用

先在项目里启动开发服务：

bash

npm run dev

然后在迅雷客户端的「微应用」页面，点击 「加载本地应用」，在目录选择器中选择 dist 目录（构建产物，内含 manifest.json），无需其它前置操作。

本地加载后即以开发者模式运行，开发体验与常规前端开发一致：页面改动通过 HMR 即时生效；仅当 manifest.json 变更（入口、窗口、权限、设置项等）时，需要重启开发服务，并在微应用管理中执行一次重载。

浏览器中预览页面

本地加载使用的就是 npm run dev 的开发服务，同一个地址也可以直接在浏览器里打开，调试布局与交互。但浏览器里没有 xunlei 对象，调用平台能力前需要判空：

if (typeof xunlei !== 'undefined') {
  await xunlei.tasks.create({ req: { url } });
} else {
  console.warn('浏览器预览环境，平台能力不可用');
}

平台相关的逻辑（任务、存储、事件）仍需回到迅雷中验证。

查看日志

在代码中使用 xunlei.logger 输出日志（见数据与日志）。日志由迅雷统一收集持久化，并带微应用标识前缀便于过滤；debug 级别日志只在本地加载（开发者模式）的微应用中输出，调试期可以放心使用。

调试面板

在迅雷客户端的 应用中心 → 我的应用 中打开应用的详细信息，通过 开发工具 → 打开 进入调试面板查看日志：

应用详细信息中的「开发工具」入口

调试面板支持两种筛选方式：

按日志级别：debug / info / warn / error；
按微应用运行时：页面、事件脚本等各运行时的日志分开展示，便于定位输出来源。

入口仅限本地加载的应用

「开发工具」入口只在通过「加载本地应用」方式安装的应用中提供，其它方式安装的应用不显示该入口。排查非本地来源应用的日志时，可先在本地以加载本地应用的方式复现。

排查清单

打开微应用后页面空白

确认 npm run dev 开发服务正在运行；
检查 manifest.json 的 entry.url 是否指向正确的入口文件；
若刚修改过 manifest.json，先在微应用管理中执行重载再打开。

资源加载失败（样式 / 图片 / 脚本丢失）

远程 URL 资源会被拦截（RESOURCE_BLOCKED），改为包内引用；
检查资源引用路径是否正确。

网络请求失败 / 被拦截

manifest.permissions 是否声明了 "network"，且 network.urls 覆盖了目标地址？见网络白名单；
network.urls 只接受主机／路径规则，例如 wss://example.com/*；*://example.com/* 可同时匹配该主机的 HTTP(S) 与 WS(S) 请求。<all_urls> 和 wss:* 不能用于网络授权；
tasks.create 的下载地址、辅助 WebView 打开的页面不受白名单约束，无需为它们声明规则。

调用 API 报 PERMISSION_DENIED

对应 API 是否已在 manifest.permissions 中声明？对照权限对照表；
页面和事件脚本调用 xunlei.tasks.* 都需声明对应任务权限；事件上下文中的控制方法无需额外任务权限。

事件脚本不触发

scripts[].match 是否声明？urls / labels 都未声明时脚本不参与匹配；
匹配规则是否写对？对照URL 匹配规则；
脚本是否在加载后立即注册了回调（如 xunlei.events.onResolve(...)）？事件脚本有时限约束（见钩子事件），超时会以 EVENT_TIMEOUT 失败；
修改事件源码后，dev 服务会自动重建事件产物（公共依赖、Worker 变更也会触发重建），产物就绪后在宿主中重载应用再试。

下载行为没反应

浏览器原生下载（<a download> 等）被禁用，必须走 xunlei.tasks.create（见下载规则）。

更多错误码见错误码。

下一步

钩子事件 — 调试事件脚本
打包 — 调试完成后准备发布

本地调试 ​

安装本地微应用 ​

推荐工作流 ​

浏览器中预览页面 ​

查看日志 ​

调试面板 ​

排查清单 ​

下一步 ​