本地调试 WPS WebOffice 的一次完整踩坑记录
在接入 WPS WebOffice SDK 的过程中，我没有一开始就上测试环境，而是选择先在本地把完整流程跑通。
结果发现，真正耗时的并不是接口本身，而是回调可达性、路径配置和调试方式。
这篇文章记录一次完整的本地调试过程，希望能帮到正在踩相同坑的人。
一、先在 WebOffice 平台创建测试应用
第一步是到 WPS WebOffice 控制台创建一个测试应用：
- 控制台地址：solution.wps.cn/console
- 创建测试应用即可
- 后续所有的回调配置、接口调试都在这里完成
这一阶段不用追求功能完整，目标只有一个：平台能打到你的接口。
二、本地准备最小可用环境
本地需要准备两样东西：
1️⃣ 后端接口
- 提供
getToken、wps回调需要的接口 - 用于接收 WebOffice 的回调请求
- 服务监听在本地端口（例如
8080）
2️⃣ 简单的测试 HTML 页面
- 页面中通过按钮触发接口请求
- 用来模拟「打开 / 编辑 / 保存文档」的流程
- 不需要复杂前端逻辑，能发请求即可
这一步的核心不是页面，而是接口链路是否真实可用。
三、解决“平台访问不到本地服务”的问题
WebOffice 的回调请求来自公网，
而本地服务默认只能在 127.0.0.1 访问，这一步是大多数人卡住的地方。
我的做法是通过内网穿透把本地服务暴露到公网。
启动本地服务后，执行：
cloudflared tunnel --url http://127.0.0.1:8080
命令执行成功后，会生成一个公网 HTTPS 地址，例如：
https://matching-insights-known-importance.trycloudflare.com
接下来需要：
- 将这个地址配置到 WebOffice 平台测试应用的回调地址
- 实际回调路径 = 公网地址 + Controller 路径
⚠️ 注意事项：
- 本地调试场景下
每次电脑重启，都需要重新启动穿透并更新回调地址 - 否则平台请求会直接失败，看起来像“接口没生效”
四、通过本地页面获取 token 和 file_id
完成回调配置后，就可以回到本地测试页面：
- 在浏览器中打开 HTML 文件
- 点击页面中的「上传 / 打开文档」按钮
- 页面请求本地
getToken接口
如果流程正常，你会拿到两个关键参数：
tokenfile_id
拿到这两个值，说明整条链路已经跑通。
五、开始调试平台侧接口
有了 token 和 file_id 之后，就可以：
- 在 WebOffice 平台的接口调试工具中
- 调试文档预览、编辑、保存、回调等接口
到这一步，其实已经完成了 80% 的接入难度。
总结
这次调试过程中，我最大的感受是：
- 问题不在接口
- 而在 回调是否可达、路径是否一致、环境是否真实
在第三方 SDK 接入时，先用本地调试跑通完整流程，比一开始就部署环境要高效得多。
如果你也在调 WebOffice，建议优先把这条链路跑通，再往下做功能扩展。
