问【鸿蒙二开】WPS SDK 常见错误码与处理速查

集成 WPS Open SDK 后，文档打开、关闭回传与应用注册均通过 WPSApi.sendRequest 异步返回 Result。不少 HarmonyOS 二开项目只写 .then() 不判断 code，或忽略 .catch()，导致鉴权失败、打开失败与回传失败混在一起，测试阶段表现为「偶发打不开」「保存了但上传旧文件」。本文把鸿蒙统一版常见 ResultCode 与处理建议浓缩成帖，便于联调时快速对照，适合已能拉起 WPS、需要完善错误分支的开发者。

Result 结构

属性	说明
`code`	状态码，见下表
`msg`	可读说明，建议打日志
`data`	关闭回传成功时有 `ResultData`
`requestType`	区分注册/打开等请求

ResultCode 速查

code	常量	场景	处理
0	OK	成功	无回传时 `data` 空仍正常
-2	ERROR	打开/参数	查沙箱路径、参数
1013	ERROR_CODE_AUTH_FAILURE	registerApp	查 key/secret、包名
>0	—	回传失败	勿用旧 filePath
异常	—	未注册就 sendRequest	先 registerApp

三类高频问题与处理

1013 鉴权失败

包名与申请凭据不一致最常见；换包名需邮件重新申请。appKey、appSecret 勿硬编码提交到公开仓库。调试包与上架包包名不同时，凭据不能混用，否则 registerApp 永远 OK 不了。

ERROR 打开失败

文件应先拷贝到应用沙箱再 OpenFileRequest；enableEdit = true 才可编辑。结合 result.msg 定位。若从系统文件选择器直接传 URI，极易触发 ERROR；建议统一走 filesDir 下副本路径。

回传与 OK 混淆

开启 wpsTransferType 后须用户关闭 WPS 窗口；OK 无 data 表示尚未回传或未开回传。回传失败时 code 可能为正整数，此时不要用打开前的 filePath 走上传，否则业务侧会误以为同步成功。

时序与 Promise 异常

registerApp 成功之前调用 sendRequest 会抛异常，不会进入 result.code 分支。冷启动时用户快速点击「打开」即可复现。建议在 UI 层增加 wpsReady 状态，注册完成前禁用打开入口；或在打开函数开头 await ensureRegistered()。

专业版须在 registerApp OK 后调用 setWpsFileToken；个人版无此步骤。排错时先用 SdkConstants.isPersonalSdk() 确认当前 HAR 类型，避免用 ToC 流程去套 ToB 环境。

工程化与代码骨架

- 封装 handleWpsResult(result)，按 code 映射 UI 文案

- 日志保留 requestType、code、msg 三要素

- 联调时 Mock 1013、ERROR、回传正整数等分支

- 与 extraOptions、水印、不落地配置变更隔离测试

- 回传场景在测试用例中明确「关闭 WPS 窗口」为触发条件

ToB 政企项目可将错误码上报到运维平台，按机型与 ROM 聚合 ERROR 率，便于发现特定环境下的路径权限问题。ToC 场景则更注重用户可读提示，避免直接展示 1013 等内部码。

// 注册
const reg = await WPSApi.sendRequest(new RegisterAppRequest(ctx, key, secret));
if (reg.code === ResultCode.ERROR_CODE_AUTH_FAILURE) { /* 鉴权 */ }
if (reg.code !== ResultCode.OK) { /* 其他失败 */ }

// 打开
try {
  const open = await WPSApi.sendRequest(new OpenFileRequest(ctx, path));
  if (open.code === ResultCode.ERROR) { /* 参数/路径 */ }
  if (open.code !== ResultCode.OK) { /* 含回传失败码 */ }
} catch {
  /* 未注册 */
}

若同时开启水印、修订模式与回传，建议分阶段启用，否则 ERROR 或回传正整数时难以判断是哪个参数组合导致。HarmonyOS 上 WPS 与应用生命周期不同步，测试时务必区分「切回应用」与「关闭文档窗口」。注册完成前禁用打开按钮；专业版在 registerApp OK 后 setWpsFileToken。

小结

ResultCode 是鸿蒙 WPS 二开排错的主线：注册看 1013，打开看 ERROR，回传看 OK 与正整数，时序问题看 Promise 异常。统一版 SDK 专业版与个人版 API 一致，便于一套错误处理复用。

更多参数见官方对接文档：https://365.kdocs.cn/l/clQl5cek2NoT

申请 SDK HAR 与凭据：m_open_sdk@wps.cn（注明包名与专业版/个人版需求）。

技术交流 QQ 群：628436767

基于 WPS Open SDK 鸿蒙版实践整理，仅供开发者交流参考。

WPS移动办公鸿蒙WPS

2天前湖北省

3 +1

问 【鸿蒙二开】WPS SDK 常见错误码与处理速查