错误码
平台 API 与安装流程使用统一的错误结构：
jsonc
{
"code": "PERMISSION_DENIED",
"message": "permission denied: tasks.list",
"details": {
"permission": "tasks.list",
"api": "xunlei.tasks.list"
}
}开发者最常遇到的是平台 API 类与事件执行类错误；安装类错误多发生在打包结构不正确时。
平台 API 错误
| 错误码 | 含义 | 处理建议 |
|---|---|---|
PERMISSION_DENIED | 调用了未声明权限的 API | 在 manifest.permissions 中补充对应权限；页面与事件脚本调用 xunlei.tasks.* 均受权限校验 |
PLATFORM_API_INVALID_INPUT | API 参数不合法 | 对照任务 API 检查入参结构（如 create 需要 { req, opts }） |
PLATFORM_API_FAILED | 平台 API 调用失败 | 查看 message 与日志定位；多为宿主侧能力暂不可用 |
事件执行错误
| 错误码 | 含义 | 处理建议 |
|---|---|---|
EVENT_NOT_REGISTERED | 脚本未在时限内注册回调 | 脚本加载后立即调用 xunlei.events.<event>(handler)，注册前不要做耗时操作 |
EVENT_TIMEOUT | 单次事件处理超出时限 | 精简脚本逻辑，网络请求设置超时，复杂解析并发化；时限说明见钩子事件 |
EVENT_EXECUTION_FAILED | 脚本执行抛错 | 查看日志中的错误堆栈；用户可见的错误用 MessageError |
导航与资源拦截
| 错误码 | 含义 | 处理建议 |
|---|---|---|
NAVIGATION_BLOCKED | 尝试跳转到被禁止的地址 | 页面不能跳转外部地址 / window.open；站外页面用辅助 WebView |
RESOURCE_BLOCKED | 尝试加载被禁止的资源 | 远程 JS / CSS / 字体 / 媒体被拦截，改为打包进包内 |
安装与清单错误
| 错误码 | 含义 | 处理建议 |
|---|---|---|
MANIFEST_NOT_FOUND | 包根目录缺少 manifest.json | 检查 zip 顶层结构是否正确 |
MANIFEST_INVALID_JSON | manifest 不是合法 JSON | 用 JSON 校验工具检查（注意多余逗号、注释） |
MANIFEST_INVALID | manifest 字段不符合规范 | 对照清单文件检查必填字段、类型与路径规则 |
MANIFEST_READ_FAILED | manifest 无法读取 | 检查文件权限 |
PACKAGE_FILE_NOT_FOUND | entry.url 或 scripts[].entry 指向的文件不存在 | 确认文件已构建进包内、路径为包内相对路径 |
PACKAGE_PATH_INVALID | 路径不是合法的包内相对路径 | 不允许绝对路径、../、带协议路径 |
MINIAPP_INSTALL_SOURCE_NOT_FOUND | 安装源路径不存在 | 检查安装来源 |
MINIAPP_INSTALL_SOURCE_INVALID | 安装源不是合法的微应用目录或安装包 | 确认安装的是构建产物（dist）或符合规范的安装包 |
MINIAPP_INSTALL_ZIP_INVALID | zip 无法解压 | 重新打包，确认 zip 文件完整 |
MINIAPP_INSTALL_ZIP_DEV_UNSUPPORTED | zip 不支持开发者模式安装 | 本地调试请安装目录而非 zip |
MINIAPP_ZIP_ENTRY_INVALID | zip 内含非法条目（反斜杠路径、符号链接） | 用标准工具重打包；避免在打包过程中创建符号链接 |
MINIAPP_INSTALL_COPY_FAILED | 复制到安装目录失败 | 检查磁盘空间与文件权限 |
MINIAPP_NOT_INSTALLED | 目标微应用未安装 | 确认安装状态 |
MINIAPP_DISABLED | 微应用已被停用 | 在微应用管理中重新启用 |
MINIAPP_ENTRY_NOT_FOUND | 微应用未声明 UI 入口 | manifest 中补充 entry 字段 |
MINIAPP_IN_APP_WEBVIEW_UNAVAILABLE | 宿主不支持 in_app_webview 入口 | 改用包内页面入口 |