跳到主要内容

常见问题

本节汇总集成中心使用过程中开发者最常问的问题，按 4 类组织。具体集成（如微信支付回调、域名校验等）的场景化问题请查看对应集成接入指南末尾的 FAQ。

分类适用读者问题列表
基础概念第一次使用，想了解集成是什么Q1 · Q2
使用与限制已开始使用，遇到边界场景Q3 · Q4 · Q5
集成调用正在写代码调用集成函数Q6 · Q7
常见报错接入或运行中遇到错误Q8 · Q9 · Q10

基础概念​

Q1：集成与模板有什么区别？​

「集成」和「模板」都是云开发的能力复用形式，但定位完全不同：

维度集成（Integration）模板（Template）
本质平台托管的运行时服务——平台帮你持续运行一个对接好第三方的 HTTP 云函数代码脚手架——给你一份可运行的初始工程，复制即拥有，后续完全自管
是否需要凭证✅ 需要在控制台填入第三方凭证（如商户号、AppSecret），平台用环境变量注入并妥善保管❌ 不涉及凭证托管，凭证由你自行写入代码或 .env
回调能力✅ 平台自动生成回调域名 + 验签解密链路，你只需关注业务逻辑❌ 需自行处理 HTTPS、域名备案、验签等基础设施
升级方式✅ 平台侧统一升级（修复安全问题、跟进第三方协议变化），你无需重新部署❌ 模板代码已是你的资产，第三方协议变化需自行跟进维护
改造空间集成函数源码可见、可二次开发，但回调链路与凭证注入由平台管控完全开源，所有代码可任意修改
典型场景微信支付、微信公众号、抖音支付等需要长期稳定 + 频繁回调的第三方对接多租户 SaaS 脚手架、AI Bot 起步工程、低代码起步包等需要快速起步的初始工程

怎么选？

  • 需要对接微信支付/公众号等第三方且想少操心凭证管理与回调验签 → 选集成
  • 想以一份成熟代码作为起点自由改造、不依赖平台侧任何托管 → 选模板

Q2：集成的云函数为什么有随机串后缀？可以改名吗？​

集成中心创建集成时，会按 <集成名>-<随机串> 规则生成云函数名。随机串是平台保留的标识符，不可修改，目的是：

  • 避免同环境下不同集成的命名冲突
  • 与回调域名子域、内置环境变量绑定，改名会破坏回调链路

如果你希望在代码中引用一个稳定的名字，建议把实际函数名作为常量配置在前端代码中（如本系列指南里的 FN_NAME），后续替换非常方便。

使用与限制​

Q3：我可以删除集成自动生成的云函数吗？​

不建议直接在云函数控制台删除——集成中心仍会保留集成记录与回调域名，但函数已不存在，导致回调失败。

正确做法是「集成中心 → 找到对应集成 → 点「删除集成」」：删除集成后，回调域名与回调路由会被释放（不可恢复）。

⚠️ 注意：删除集成只清理回调链路，不会自动删除已生成的云函数（云函数及其内的所有环境变量都是平台为你生成的资产，删除集成后会完整保留，你可以继续二次开发或自管，也可以前往「云函数控制台」手动删除）。如果不再需要该函数，请记得另行清理。

Q4：一个云开发环境可以创建多个相同类型的集成吗？​

可以。比如同一环境下你可以创建两个「微信支付」集成对接两个不同的微信商户号，集成名称互不冲突即可。每个集成独立生成各自的云函数和回调域名。

Q5：集成的云函数可以二次开发吗？​

可以。集成函数模板代码已开源在官方仓库，你可以参考源码进行业务侧扩展（例如下单前增加风控校验、回调后写入业务库等）。但有两点限制：

  • 环境变量注入逻辑由平台管控——请勿改动平台注入的凭证读取代码
  • 回调路由由平台预置（如 /wechatpay/order）——请勿修改路径，否则回调会 404

如果改造范围超过这些边界，建议改用「模板」方式从头自管。

集成调用​

Q6：集成函数能否被其他云函数调用？​

可以。集成函数本质是 HTTP 云函数，可通过 tcb.callFunction / tcb.callContainer 等方式从其他云函数互相调用。详见 云函数文档。

Q7：调用集成函数需要什么鉴权？​

集成中心为每个集成生成的是 HTTP 云函数——本质是一个对外暴露 HTTPS 入口的云函数，调用前需要获取访问令牌（access_token） 并以 Authorization: Bearer <token> 头部发起请求。

按调用方分两种典型方式：

调用方鉴权方式是否需要手动管理 token
小程序用 wx.cloud.callHTTPFunction，平台自动鉴权 + 注入 x-wx-openid❌ 无需
Web/H5、服务端、第三方系统走 HTTP API：先获取 access_token，再以 Authorization: Bearer <token> 调用✅ 需要

手动获取 access_token 的完整指引：

💡 Web/H5 场景如果已经接入 CloudBase Auth Web SDK，SDK 会自动维护 token 生命周期，业务代码可直接发起请求；只有在没用 SDK 的纯 HTTP 调用场景下才需要手动管理。

常见报错​

Q8：集成创建失败，提示凭证校验未通过​

通常是凭证字段填写错误。检查：

  • 字段值是否完整（特别是 PEM 格式：-----BEGIN ...----- 与 -----END ...----- 头尾完整、中间换行未被破坏）
  • 凭证类型是否匹配（如微信支付公钥模式与平台证书模式不能混用）
  • 关联应用（如小程序 AppID）是否已与商户号绑定

Q9：集成函数调用返回 401​

调用方未提供合法的 accessToken 或 openid：

  • 小程序场景：确认 wx.cloud.init 已执行、用户已登录微信
  • Web 场景：accessToken 必须来自认证登录（匿名登录的 token 无权调用云函数）
  • HTTP 场景：参考 Q7 鉴权指引 重新获取 access_token

Q10：第三方异步通知未触发业务函数​

按以下顺序排查：

  1. 第三方平台的回调 URL 是否填写为集成中心生成的地址
  2. 集成详情页「回调日志」中是否有对应记录
  3. 若回调日志显示验签失败：核对凭证一致性
  4. 若回调已转发到函数：查看函数日志确认业务代码是否报错