打包

开发完成后，把构建产物打包提交商店审核；上架后即可通过官方应用商店分发。本页说明产物结构与打包要求。

构建产物

npm run build

构建完成后，output/ 目录就是一个完整的微应用包：

output/
├── manifest.json        # 由工具链自动复制
├── index.html           # 页面入口
├── assets/              # 页面 JS / CSS / 图片等资源
└── events/              # 事件脚本（由 src/events/* 编译而来，如声明了事件）

安装的是什么

无论本地调试还是商店分发，安装的都是构建产物（output 目录或其打包结果），源码、node_modules、配置文件都不会进入微应用包。

开发与生产输出隔离

开发产物在 dist/、生产产物在 output/，两个目录互不覆盖：dev 服务运行期间也可以执行构建和打包。已有工程若把 vite.build.outDir 配置为 dist，请移除该配置（或改为独立的生产目录）；原来自定义开发路径的配置迁移到 dev.outDir。

打包 zip

使用工具链打包（自动构建、校验并生成 ZIP），ZIP 生成于 output/ 目录：

npm run package

打包成功后会清理本次构建文件，output/ 中默认只保留 ZIP；打包失败时保留构建文件便于排查。需要长期保存的 ZIP 请另行备份——下一次默认构建会清空 output/。

也可以只校验并打包已有产物（不清理已有文件）：

npm exec xunlei-miniapp package --no-build

顶层必须直接是微应用文件

zip 包解压后的第一层就必须是 manifest.json、index.html 等文件，不能外面再套一层目录：

✅ 正确                          ❌ 错误
payload.zip                     payload.zip
├── manifest.json               └── my-miniapp/
├── index.html                      ├── manifest.json
└── assets/                         └── index.html

直接使用 npm run package 生成的 ZIP 即可满足上述结构，不要手动重新压缩项目目录。

安装包下载与本地安装

上架后，可以在开发者后台下载该微应用的安装包（.xla 文件）。将 .xla 文件拖拽进迅雷客户端即可完成安装，方便在正式环境下验证上架效果。

包校验规则

安装时平台会校验安装包，以下情况会被拒绝：

问题	错误
zip 无法解压	MINIAPP_INSTALL_ZIP_INVALID
顶层结构不正确（缺少 manifest.json）	MANIFEST_NOT_FOUND / MINIAPP_INSTALL_SOURCE_INVALID
包内路径包含反斜杠等非法路径	MINIAPP_ZIP_ENTRY_INVALID
包内包含符号链接	MINIAPP_ZIP_ENTRY_INVALID

发布前检查清单

• [ ] manifest.json 字段完整：name / title / version（必填）
• [ ] version 已按 semver 递增
• [ ] entry.url 指向的文件存在于包内（如有UI 入口）
• [ ] scripts[].entry 指向的脚本存在于包内（如声明了事件）
• [ ] icon 图标文件存在，且为包内相对路径
• [ ] permissions 与 network.urls 符合最小权限原则
• [ ] 包内无源码、sourcemap、node_modules 等无关文件

下一步

• 提审与上架 — 提交商店审核
• 版本更新 — 版本号管理