【鸿蒙二开】WPS Open SDK 接入 FAQ 与排查清单

社区里关于 WPS Open SDK 鸿蒙版的提问，很多最后都会落到同一条链路：申请的 HAR 和客户端是否匹配、registerApp 是否成功、文件是否在业务沙箱、OpenFileRequest 是否开启了预期能力。下面按接入顺序整理一份 FAQ，方便在联调页直接对照。具体字段和版本行为以官方对接文档为准。

一、版本、HAR 和凭据怎么配

统一版保留了专业版的完整能力，同时新增个人版支持。两个版本 API 一致，但申请 HAR 和凭据时要明确所需版本，不能混用。凭据与三方应用 Bundle 包名绑定，变更包名后需要重新确认申请记录。

运行时可使用 SdkConstants.isPersonalSdk() 判断当前 SDK，不要通过 WPS 包名或设备外观猜测。申请时建议在邮件中写清应用名称、Bundle 包名、所需版本、联系人和用途，避免拿到不匹配的 HAR。

二、registerApp 要放在哪里

WPSApi.registerApp(appKey, appSecret, callback) 是应用级初始化。回调返回 ResultCode.OK 之前，sendRequest 不具备执行条件。把注册写在每个“打开文档”按钮里，容易出现重复注册和时序竞态，建议收口到应用启动或共享模块。

import { WPSApi, Result, ResultCode, SdkConstants } from '@wps/wps_sdk';

let ready = false;
let booting: Promise<void> | null = null;

export function prepareWps(
  appKey: string,
  appSecret: string,
  proSn: string
): Promise<void> {
  if (ready) return Promise.resolve();
  if (booting) return booting;

  booting = new Promise<void>((resolve, reject) => {
    WPSApi.registerApp(appKey, appSecret, {
      onCallback: (result: Result) => {
        if (result.code !== ResultCode.OK) {
          booting = null;
          reject(new Error(`register ${result.code}: ${result.msg ?? ''}`));
          return;
        }
        if (!SdkConstants.isPersonalSdk() && proSn) {
          WPSApi.setWpsFileToken(proSn);
        }
        ready = true;
        resolve();
      },
    });
  });

  return booting;
}

日志保留 code 和 msg 即可，不要输出完整 appSecret。注册失败后清空 booting，允许用户下一次操作重试；不要用定时器无限重发。

三、序列号与请求字段怎么处理

需要激活序列号的场景，推荐在注册成功回调中调用一次 WPSApi.setWpsFileToken(token)，后续请求自动携带。不要在每次构造 OpenFileRequest 时重复写 wpsToken，也不要让业务页面决定当前版本是否需要序列号。

如果全局设置与请求字段同时存在，排查时很难判断采用哪一个值。全仓检索 wpsToken，把旧写法清理掉，配置只留在初始化模块。

四、文件为什么打不开或只能预览

待打开文件应先复制到本应用可访问的沙箱目录。外部选择器的临时 URI 可能在页面切换或应用重启后失效，直接传给 OpenFileRequest 会出现打开失败，也可能导致后续编辑结果无法保存。

enableEdit 不传或为 false 时按只读处理，需要编辑必须显式设为 true：

const request = new OpenFileRequest(context, sandboxPath);
request.enableEdit = true;
const result = await WPSApi.sendRequest(request);

如果 sendRequest 直接进入 Promise 的 catch，先检查注册是否完成；如果返回 Result 但 code 非零，再检查文件路径、权限和请求参数。两种错误分开记录，现场定位会快很多。

五、Result.data 为空是不是失败

没有开启关闭回传时，WPS 成功拉起就会返回 ResultCode.OK，此时没有编辑结果，data 为空属于正常语义。开启回传后，用户关闭文档并成功回传，才应检查 URI、FD、文件名和大小。

回传得到的 URI 属于 WPS 沙箱临时路径，业务必须复制到自己的沙箱后再长期使用。拷贝完成前不要删除临时文件；用户取消、WPS 崩溃或业务超时也不能假设一定会收到回调，需要保留失败状态。

六、1013 与常见错误怎么分层

1013 对应 ERROR_CODE_AUTH_FAILURE，表示接入凭据校验失败。出现时先对表：

如果 appKey 或 appSecret 为空，常见结果是 ResultCode.ERROR；1013 更偏向身份不一致。不要用修改水印、修订或回传参数的方式排查认证问题。

七、上线前排查清单

1. 确认 HAR、凭据、Bundle 和所需版本匹配。

2. 冷启动 registerApp 返回 ResultCode.OK。

3. 专业版在成功回调里设置序列号，个人版不额外注入。

4. 文件先进入业务沙箱，只读和可编辑各验证一次。

5. 开启回传后，关闭文档并完成业务侧文件转存。

6. 更换 HAR 或包名后，从注册环节重新回归。

把注册、路径、请求和回传拆开验收，大部分“文档打不开”的问题都能快速定位。欢迎在社区补充具体机型、HAR 批次与错误码组合，方便大家对齐排查口径。