快速上手
本节从零创建一个带 UI 页面的微应用，安装到迅雷中运行，并在页面上创建第一个下载任务。
准备环境
| 依赖 | 要求 |
|---|---|
| Node.js | 22.18+ |
| 包管理器 | npm（也支持 pnpm / yarn） |
| 迅雷客户端 | 支持微应用的桌面端版本（Windows） |
创建项目
使用官方脚手架创建微应用工程：
bash
npm create @xunlei-open/miniapp@latest脚手架会依次询问：
- 项目名称；
- 框架：
Vanilla/Vue/React三选一； - 语言：
TypeScript/JavaScript； - 代码检查：
ESLint + Prettier或Biome（可选，二选一）； - 单元测试：
Vitest（可选）； - 是否立即安装依赖并启动。
认识项目结构
以 Vue + TypeScript 模板为例，生成的工程结构如下：
text
my-first-miniapp/
├── manifest.json # 微应用清单文件（应用信息、入口、权限等）
├── miniapp.config.ts # 开发与构建配置（框架模块、Vite 配置）
├── index.html # 页面入口 HTML
├── src/
│ ├── main.ts # 页面源码入口
│ ├── App.vue # 页面组件（内置创建下载任务示例）
│ └── assets/ # 样式等静态资源
├── dist/ # 开发产物（npm run dev 生成），在迅雷中加载的就是这个目录
└── output/ # 生产构建与 ZIP 安装包（npm run build / package 生成）模板自带示例页面
模板页面内置了一个「创建下载任务」表单：输入地址、点击按钮即可调用 xunlei.tasks.create 创建任务，跑通它就完成了微应用与迅雷能力的第一次串联。
工程依赖 @xunlei-open/miniapp-types 类型包，全局对象 xunlei 有完整的 TypeScript 类型提示，直接使用即可。
安装到迅雷
1. 启动开发服务
bash
npm run dev保持开发服务运行——迅雷中的微应用页面由它提供，页面代码改动可热更新。
2. 加载本地应用
在迅雷客户端的「微应用」页面，点击 「加载本地应用」 按钮，在弹出的目录选择器中 选择 dist 目录（终端中有路径提示）即可完成安装。
3. 打开微应用
安装成功后，微应用会出现在已安装列表中，点击即可打开第一个微应用窗口。
创建下载任务
模板已内置示例：在微应用窗口的输入框中填入一个下载地址（如 https://example.com/file.zip），点击「创建任务」——迅雷主界面就会出现这个下载任务。
核心代码只有几行（见模板的 src/App.vue）：
ts
const task = await xunlei.tasks.create({
req: { url: 'https://example.com/file.zip' },
opts: { name: '示例文件.zip' },
});
xunlei.logger.info('任务已创建:', task.id);TIP
- 调用
xunlei.tasks.create需要在manifest.json的permissions中声明"tasks.create"，模板已默认包含，权限机制详见平台能力； - 在普通浏览器中打开页面时没有
xunlei对象，模板代码已做判空降级，平台能力请在迅雷中验证。
日常开发工作流
本地加载后，开发体验与常规前端开发一致：
- 保持
npm run dev运行，页面改动通过 HMR 即时生效； manifest.json变更（入口、窗口、权限、设置项等）时，需要重启开发服务，并在迅雷的微应用管理中重新加载应用；- 常用命令：
| 命令 | 用途 |
|---|---|
npm run dev | 开发与热更新（产物在 dist/） |
npm run build | 构建并校验生产产物（output/） |
npm run package | 构建、校验并生成 ZIP（output/） |
开发产物（dist/）与生产产物（output/）相互隔离：dev 服务运行期间也可以执行构建和打包，两者互不覆盖。
更多调试技巧见本地调试。