为什么选择了 cloudflared，而不是 ngrok
结论先行：我选择 cloudflared 不是因为它“更强”，而是因为 ngrok 免费版生成的回调地址太长，无法通过 WPS WebOffice 的回调校验；而要使用短子域名必须付费。
这是一篇真实踩坑后的工程实践总结，不是工具对比评测。
一、背景：WPS WebOffice 的「本地回调」调试场景
在对接 WPS WebOffice SDK（文档保存回调） 时，我遇到一个典型但容易被忽略的问题：
- WebOffice 的 保存、上传等接口是由 WPS 主动回调我的服务
- 我的服务运行在 本地（127.0.0.1）
- WPS 位于公网
👉 这意味着：本地调试 ≠ 不需要网络穿透
只要是「第三方主动调用你」，你就必须让你的接口 公网可达。
二、为什么一定要用网络穿透
很多文章会说：
“本地调试阶段不需要 ngrok / cloudflared”
这句话在 WPS 回调场景下是错误的。
原因很简单：
- 你的 Controller 在本地
- WPS 的服务器不可能访问你的 127.0.0.1
所以你必须满足三个条件：
- 公网 HTTPS 地址
- 能转发到本地服务
- URL 能被 WPS 平台接受
三、最开始我用的是 ngrok（问题从这里开始）
ngrok 是我最早尝试的工具，使用体验也确实很好：
- 安装简单
- 一条命令就能跑
- 稳定性不错
但在 WPS WebOffice 回调配置 这一步，问题暴露了。
1️⃣ ngrok 免费版的致命问题
ngrok 免费版生成的地址通常是：
https://xxxxxx-xxxx-xxxx-xxxx-xxxxxx.ngrok-free.app
这个地址：
- 非常长
- 不可控
- 每次重启都会变
而 WPS 对回调地址是有长度和格式校验的。
结果是：
- 在控制台配置时直接失败
- 或者回调时提示「参数无效 / 请求失败」
2️⃣ 那为什么不用 ngrok 的子域名？
因为：
ngrok 的自定义子域名是付费功能
对一个仅用于 本地联调 / SDK 调试 的场景来说，这个成本不合理。
四、转向 cloudflared：不是更强，而是“刚好能用”
后来我换成了 cloudflared 的 quick tunnel（trycloudflare）。
启动命令非常简单：
cloudflared tunnel --url http://127.0.0.1:8080
生成的地址类似：
https://matching-insights-known-importance.trycloudflare.com
cloudflared 为什么能通过 WPS？
关键不在于“技术先进”，而在于：
- URL 长度相对可控
- 域名结构简单
- 免费即支持 HTTPS
👉 刚好满足 WPS 的回调校验规则。
五、一个容易混淆但必须澄清的点
❌ 参数无效 ≠ 穿透工具问题
在调试过程中，我也遇到过：
- 404
- 参数无效
- 请求失败
但这些问题：
- 本地 Postman 直调也会出现
- 与 ngrok / cloudflared 无直接关系
真正的原因通常是：
- Controller 路径不匹配
- HTTP Method 不一致（GET / POST）
- PathVariable / RequestBody 解析错误
👉 穿透工具只负责“能不能打到你”，不负责“你写得对不对”。
六、最终选型总结
我最终选择 cloudflared 的原因只有一个，而且非常现实：
在不付费的前提下，它生成的回调地址能通过 WPS 的校验。
对比总结
| 项目 | ngrok 免费版 | cloudflared quick tunnel |
|---|---|---|
| HTTPS | ✅ | ✅ |
| 本地穿透 | ✅ | ✅ |
| URL 长度 | ❌ 过长 | ✅ 可接受 |
| 自定义子域 | ❌ 付费 | ❌ |
| WPS 回调可用 | ❌ | ✅ |
七、给后来者的建议
- 先本地把接口跑通（Postman 直调）
- 再解决公网可达问题
- 最后再看平台对 URL 的隐性限制
不要一上来就怀疑 SDK，也不要一上来就怀疑网络。
结语
这次踩坑让我意识到一件事：
很多技术选型，并不是“谁更好”，而是“谁在当前约束下活得下来”。
如果你也在做第三方 SDK、本地回调、内网穿透相关的调试，希望这篇文章能帮你少走一点弯路。
