常见问题

先定位失败发生在安装、打开页面、调用宿主还是后台请求，再核对对应声明。一次只调整与现象相关的配置。

#页面打不开或资源空白

检查扩展是否启用，contributes.views 与 webviews 是否使用同一个 View ID，入口文件是否真实存在于包内。

再检查 HTML 的脚本、样式和图片是否为包内相对路径。开发服务器可以访问的 /src/、绝对磁盘路径或在线 CDN，不代表安装后的扩展也可以访问。

页面在独立浏览器中预览时没有 Desktop Bridge。基础界面可以显示，依赖宿主的操作应明确提示环境不支持。

#桌面会话同步失败

先确认当前承载的是 .mipx 扩展还是普通 Web 应用。

• .mipx 扩展需要在 Manifest 中声明 identity.read。
• 普通 Web 应用需要由平台授予相应身份能力，不能通过添加扩展 Manifest 解决。
• 确认 Desktop 已登录、单位上下文有效，以及使用了适合承载环境的 SDK。

读取身份使用 公开身份接口，不要恢复读取 userInfo 或复制平台 Token 的旧方式。

#能力探测成功但调用失败

capabilities.has() 只说明接口存在。继续检查 Manifest 权限、当前登录状态、贡献点、依赖扩展与实际调用结果。

未授权、目标未启用、命令未声明、端点未配置和后台拒绝是不同问题，应保留明确的错误信息，不统一归为网络异常。

#命令返回值为什么多了一层

WebView 命令调用返回 ExtensionResponse，先检查外层 code，再读取 data。Host 命令调用返回业务值，失败通常通过 Promise 拒绝。

不要看到 code/data 就不断解包。业务值本身可能包含同名字段；后台 API 也应按各自返回契约处理。参见 命令返回值。

#应用入口、侧栏或卡片没有出现

确认贡献点已经被目标 Desktop 发行版支持，并核对入口、可见性与权限。应用入口、侧栏和工作台卡片需分别声明，一个贡献点不会自动生成其余位置。

确认扩展已启用、View 文件存在、声明属于当前扩展。参见 页面与贡献点。

#SDK 无法安装或导入

确认拿到了已构建 SDK 和匹配的协议包；当前不要假定公共 npm 上已发布这些包。使用交付文件安装时，以实际文件名和版本为准。

Host 导入 /host，页面导入 /webview，构建时将依赖内联到自己的资源。安装后不应解析开发机源码路径。

#打包成功但安装被拒绝

依次检查 ZIP 根目录、Manifest 格式、版本兼容、包内入口和签名要求。开发包与正式包的接收规则可能不同。

不要把压缩成功视为签名通过，也不要通过扩大权限或修改随机字段绕过错误。记录具体错误及目标宿主版本，再对照 发布检查。