公众号集成接入指南

在 CloudBase 控制台「集成中心」创建微信公众号集成后，平台会自动为你生成一个 HTTP 云函数，封装好网页授权、access_token 托管、JS-SDK、模板/订阅消息、客服消息、菜单、二维码、用户管理、素材等全部能力。本指南只介绍网页授权（OAuth 2.0）——也是公众号集成最常用、最高频的能力，用于在公众号场景下让网页拿到用户的 openid 与（可选的）昵称/头像等信息。

关于函数名的约定：集成中心生成的云函数名形如 <集成名>-<随机串>（例如 offiaccount-demo-rwmx67sc）。为方便讲解，本文统一称其为 offiaccount-common——你在自己的代码中替换为实际函数名即可。

其他能力（access_token 托管、JS-SDK、模板/订阅消息、客服消息、菜单、二维码、用户管理、素材等）由同一个 offiaccount-common 云函数提供，本指南不展开。

整体调用链路：

网页跳转 → 微信授权页 → 微信回跳带回 code
网页携带 code → CloudBase 云 API 网关（accessToken 鉴权）→ offiaccount-common HTTP 云函数 → 微信 sns/oauth2/access_token API
offiaccount-common 返回 { openid, access_token, ... } 给网页或业务后端

架构总览

公众号网页授权（OAuth2.0）换取 openid 的完整时序：

职责分工：

角色	职责
公众号网页	引导用户跳转微信授权页；回跳后把 `code` 发给后端
云 API 网关	校验 `Bearer {accessToken}`，将请求转发到 HTTP 云函数
`offiaccount-common` 云函数	持有 AppID + AppSecret，用 `code` 调微信换 `openid` 与 OAuth tokens；按需调用 `sns/userinfo` 拉用户资料
微信公众平台	颁发 `code`、`openid`，下发用户资料
集成中心	统一托管 AppID/AppSecret，作为环境变量注入云函数

前置条件

项	要求
公众号	服务号或已开通 `snsapi_base` 权限的订阅号；已通过微信认证
公众号 AppID + AppSecret	持有可用值，AppSecret 可在公众平台 → 基本配置中重置
网页授权域名	公众平台 → 设置与开发 → 公众号设置 → 功能设置 → 网页授权域名，已添加发起授权的页面域名并完成 MP_verify_xxx.txt 校验
CloudBase 环境	已开通；至少有一种认证登录方式可用（匿名登录不能调云函数，参见 4.3 节）

第一步 · 准备公众号凭证

登录微信公众平台 → 设置与开发 → 基本配置：

AppID：形如 wxc1546068399a59fc
AppSecret：点击「重置」生成，仅显示一次，妥善保存

AppSecret 不要泄露给前端，CloudBase 集成中心会把它托管并注入到云函数环境变量。

第二步 · 在 CloudBase 创建集成

前置说明 · 公众号 IP 白名单

CloudBase 调用公众号涉及两类来源 IP，需加入公众平台「设置与开发 → 基本配置 → IP 白名单」：

① 网关 IP（必配）：创建集成时平台会经云 API 网关校验凭证，网关出口 IP 必须先加入白名单，否则集成创建失败。务必在 2.2 填写集成信息提交前配置。

② 云函数固定 IP（按需）：若由云函数主动外呼公众号 API（如模板/订阅消息、客服消息、菜单等需全局 access_token 的接口），需补充配置，详见 2.4。

注：网页授权接口（sns/oauth2/access_token）本身不校验来源 IP，但 ① 网关 IP 仍是创建集成的必要条件。

2.1 进入集成中心

路径：云开发平台 → 模板与集成 → 集成中心 → 微信公众号 → 创建集成。

2.2 填写集成信息

控制台向导需填写：

集成名称（自定义，例如 offiaccount-demo）
公众号 AppID 与 AppSecret

⚠️ 提交前必做 · 配置网关 IP 白名单

创建集成时平台会用填写的 AppID/AppSecret 通过云 API 网关校验公众号凭证，网关出口 IP 未加入公众号白名单会导致集成创建失败。

创建集成的页面会直接提示云 API 网关的出口 IP，复制即可，先到微信公众平台 → 设置与开发 → 基本配置 → IP 白名单 粘贴保存，再回到本页提交创建。

集成中心将统一托管上述凭证。

2.3 自动生成云函数资源

创建成功后，系统自动完成两项操作：

按集成名称创建一个 HTTP 云函数（函数名形如 <集成名>-<随机串>，本文统称 offiaccount-common）。
将 AppID、AppSecret 作为环境变量注入到该云函数。

2.4 配置公众号 IP 白名单

公众号通过全局 access_token 调用的 API（模板/订阅消息、客服消息、菜单等）会校验调用来源 IP，需将相关 IP 配置到微信公众平台 → 设置与开发 → 基本配置 → IP 白名单。（仅做网页授权 sns/oauth2/access_token 不校验 IP，可跳过本节。）

① 网关 IP（必配）

即云 API 网关的出口 IP，已在 2.2 填写集成信息创建集成时配置。前端经网关转发到云函数的链路依赖该 IP。

② 云函数固定 IP（按需）

如果你在 offiaccount-common 云函数中直接调用公众号 API（即由云函数主动外呼微信接口），则该云函数的出口 IP 也必须在白名单内。云函数默认出口 IP 不固定，需先为其开启固定出口 IP，再把这个固定 IP 配置到公众号 IP 白名单：

进入云开发平台 → 云函数 → offiaccount-common → 配置，开启公网访问并启用固定出口 IP（详见云函数固定出口 IP）。
将得到的固定出口 IP 填入公众号「IP 白名单」。

仅经网关转发只需 ①（已在 2.2 配置）；当云函数主动调用公众号 API 时需补充 ②。两类 IP 都加入白名单后，公众号接口调用才不会被拦截。

第三步 · 了解 offiaccount-common 云函数

第二步创建集成时，平台已经把 AppID、AppSecret 作为环境变量注入到云函数。运行时通过 process.env 读取，业务代码中不会出现明文凭证。

如需修改配置，进入「集成中心 → 对应集成 → 编辑」，保存后平台将自动重新部署云函数。

3.1 网页授权相关路由

⚠️ 与「微信支付」集成的 pay-common 不同，offiaccount-common 不使用 _action 字段分发，而是直接使用 REST 路径。调用云函数时请使用完整路径，例如 POST /oauth/token。

云函数对外暴露的网页授权 5 个 REST 路由：

路由	用途	必填请求体
`POST /oauth/config`	返回当前集成配置的公众号 `appId`，便于前端拼授权 URL（避免在前端硬编码）	—
`POST /oauth/token`	用 `code` 换取 `openid` + OAuth `access_token` + `refresh_token`	`{ code }`
`POST /oauth/refresh`	刷新 OAuth `access_token`（30 天有效的 `refresh_token` 换新的 2 小时 token）	`{ refresh_token }`
`POST /oauth/userinfo`	用 OAuth access_token 拉取授权用户昵称/头像（仅 `snsapi_userinfo` scope 有效）	`{ access_token, openid }`
`POST /oauth/verify`	校验 OAuth `access_token` 是否仍有效	`{ access_token, openid }`

所有路由统一返回 { code: 0, msg: 'success', data: <业务数据> }，错误返回 { code: -1, msg, data: null }。

这里的 OAuth access_token 与公众号的全局 access_token（用于调菜单/消息接口）是两个不同的东西，前者只能用于拉取本用户的资料、不能调其他接口。

3.2 链路与鉴权

调用 offiaccount-common 的链路与 pay-common 完全一致：

前端登录 CloudBase 获取 accessToken → 携带 Authorization: Bearer {accessToken} 请求云 API 网关 → 网关分发至 offiaccount-common。

accessToken 必须来自「认证登录」——匿名登录拿到的 token 无权调用云函数，网关会直接返回 401。具体登录方式（邮箱、手机号、自定义登录等）请参考 CloudBase Web SDK · 认证登录。

第四步 · 接入网页授权

4.1 前置准备

配置网页授权域名

路径：微信公众平台 → 设置与开发 → 公众号设置 → 功能设置 → 网页授权域名。

下载 MP_verify_xxx.txt，放到 https://<你的域名>/MP_verify_xxx.txt 可访问的位置，再点击校验通过。

该域名必须是发起授权页的域名，不是回跳处理页的域名（虽然两者通常相同）。

理解两种 scope

scope	用户体验	能拿到什么
`snsapi_base`	静默授权，无弹窗	仅 `openid`（多数业务用这个）
`snsapi_userinfo`	弹出授权确认页	`openid` + 昵称 + 头像 + 性别等

4.2 完整网页授权流程

四步流程，前两步在前端完成，第三步走 offiaccount-common，第四步按需调用。

第 1 步：网页 → 跳转微信授权页
第 2 步：微信 → 回跳前端 redirect_uri，附带 ?code=xxx
第 3 步：前端 → POST /oauth/token { code } → 拿到 openid + access_token
第 4 步：前端 → POST /oauth/userinfo（仅 snsapi_userinfo 需要）

4.3 完整调用示例

适合微信内置浏览器中打开的公众号 H5 页面。

关键约束：

必须在微信内置浏览器中打开页面，外部浏览器（Chrome / Safari）打开微信授权页会跳到提示页
页面 URL 域名必须已配在公众号「网页授权域名」白名单
state 参数必填，用于防 CSRF（前端生成随机串，回跳后校验）
accessToken 必须来自认证登录，详见 3.2

<!-- oauth.html  发起授权页 -->
<!DOCTYPE html>
<html lang="zh-CN">
  <head>
    <meta charset="UTF-8" />
    <title>正在授权…</title>
  </head>
  <body>
    <script src="https://cdn.jsdelivr.net/npm/@cloudbase/js-sdk/dist/cloudbase.full.js"></script>
    <script>
      const ENV_ID = "your-env-id";
      const FN_NAME = "offiaccount-common"; // 集成创建后生成的实际函数名

      const app = cloudbase.init({ env: ENV_ID });
      const auth = app.auth({ persistence: "local" });

      // ⚠️ accessToken 必须来自「认证登录」，匿名登录无权调云函数
      // 完整登录方式见 https://docs.cloudbase.net/api-reference/webv3/authentication#%E8%AE%A4%E8%AF%81%E7%99%BB%E5%BD%95
      async function getAccessToken() {
        // 示例占位：业务方需实现真实登录后返回 accessToken
        throw new Error(
          "请按 CloudBase Web SDK 文档实现认证登录后返回 accessToken"
        );
      }

      async function callFn(token, path, body) {
        const res = await fetch(
          `https://${ENV_ID}.api.tcloudbasegateway.com/v1/functions/${FN_NAME}${path}?webfn=true`,
          {
            method: "POST",
            headers: {
              "Content-Type": "application/json",
              Authorization: `Bearer ${token}`,
            },
            body: JSON.stringify(body || {}),
          }
        );
        return res.json();
      }

      function unwrap(body) {
        // offiaccount-common 直接返回 { code, msg, data }，没有 wechatpay-node-v3 那层嵌套
        return body && body.code === 0 ? body.data : null;
      }

      (async () => {
        const token = await getAccessToken();
        const url = new URL(location.href);
        const code = url.searchParams.get("code");
        const state = url.searchParams.get("state");

        // —— 第 1 步：没有 code，发起授权 ——
        if (!code) {
          // 拿 AppID（也可直接在前端硬编码）
          const { appId } = unwrap(await callFn(token, "/oauth/config")) || {};
          if (!appId) {
            alert("未取到 appId");
            return;
          }

          const randomState = Math.random().toString(36).slice(2, 18);
          sessionStorage.setItem("oauth_state", randomState);

          // 当前页作为 redirect_uri，回跳后再次进入本脚本
          const redirectUri = encodeURIComponent(location.href.split("?")[0]);
          location.replace(
            `https://open.weixin.qq.com/connect/oauth2/authorize` +
              `?appid=${appId}` +
              `&redirect_uri=${redirectUri}` +
              `&response_type=code` +
              `&scope=snsapi_base` + // 改成 snsapi_userinfo 可拉昵称/头像
              `&state=${randomState}` +
              `#wechat_redirect`
          );
          return;
        }

        // —— 第 2 步：回跳带回 code，校验 state ——
        const expectedState = sessionStorage.getItem("oauth_state");
        if (state !== expectedState) {
          alert("state 校验失败，疑似 CSRF");
          return;
        }
        sessionStorage.removeItem("oauth_state");

        // —— 第 3 步：code 换 openid ——
        const tokenRes = unwrap(await callFn(token, "/oauth/token", { code }));
        if (!tokenRes || !tokenRes.openid) {
          alert("换取 openid 失败");
          return;
        }
        const { openid, access_token, refresh_token, scope } = tokenRes;
        console.log("已拿到 openid:", openid, "scope:", scope);

        // —— 第 4 步（可选）：snsapi_userinfo 才能拉资料 ——
        if (scope === "snsapi_userinfo") {
          const info = unwrap(
            await callFn(token, "/oauth/userinfo", {
              access_token,
              openid,
            })
          );
          console.log("用户资料:", info); // { nickname, headimgurl, sex, ... }
        }

        // 业务侧：把 openid 写入会话 / 跳转到业务页
        sessionStorage.setItem("openid", openid);
        location.replace("/home");
      })();
    </script>
  </body>
</html>

4.4 调用 `/oauth/refresh` 与 `/oauth/verify`

OAuth access_token 默认 2 小时过期。若要在长会话场景下复用 openid 关联的资料拉取能力，可：

// 续期：用 refresh_token 换新的 access_token（refresh_token 30 天有效）
const refreshed = unwrap(
  await callFn(token, "/oauth/refresh", {
    refresh_token,
  })
);
// refreshed = { openid, access_token, refresh_token, expires_in, scope }

// 校验：判断 token 是否仍有效
const { valid } = unwrap(
  await callFn(token, "/oauth/verify", {
    access_token,
    openid,
  })
);

大多数业务不需要持久化保存 OAuth access_token——拿到 openid 即可入库关联用户，其他公众号能力（消息/客服等）走全局 access_token（由 offiaccount-common 的 /token/* 路由托管）。

常见问题 FAQ

Q1：调用 /oauth/token 返回「微信接口错误 [40029]: invalid code」

code 有三种情况会拿到这个错误：

已被用过一次（code 只能消费一次，前端误重复调用，或刷新页面带 code 又跳一遍）
已过期（5 分钟内有效）
与发起授权时的 AppID 不一致（例如集成里填的是 A，授权 URL 用的是 B）

排查：清缓存重试，确认前端不会重入。

Q2：调用 /oauth/token 返回「invalid appsecret」或 40125

集成中心填写的 AppSecret 错误，或已被在公众平台重置。前往集成中心 → 编辑 → 重新粘贴 AppSecret。

Q3：授权页提示「该链接无法访问，请检查链接是否正确」/「redirect_uri 域名与后台配置不一致」

redirect_uri 的域名不在公众平台「网页授权域名」白名单。检查：

域名是否完整匹配（含子域；公众平台只允许填主域，子域会自动覆盖）
校验文件 MP_verify_xxx.txt 是否真的可以访问
配置后建议等 1–2 分钟生效

Q4：snsapi_base 拿不到昵称头像

这是设计如此。snsapi_base 只返回 openid，要拉资料必须用 snsapi_userinfo，会弹用户确认框。

Q5：网页在企业微信、QQ 浏览器中能跑吗

不能。open.weixin.qq.com/connect/oauth2/authorize 只在微信内置浏览器中生效；外部浏览器会跳到引导页。

Q6：能否直接在前端调 `https://api.weixin.qq.com/sns/oauth2/access_token`

不能也不该。该接口强制需要 AppSecret，前端调用会暴露 AppSecret，且微信对 IP 来源有校验。这正是 offiaccount-common 存在的价值——把 AppSecret 留在服务端。

Q7：能否复用 pay-common 的同一个 CloudBase 环境

可以。offiaccount-common 和 pay-common 是两个独立的集成，分别生成各自的 HTTP 云函数，互不影响。前端按需求分别调用即可。

延伸阅读

主题	链接
微信网页授权（官方文档）	https://developers.weixin.qq.com/doc/offiaccount/OA_Web_Apps/Wechat_webpage_authorization.html
`sns/oauth2/access_token` 接口说明	https://developers.weixin.qq.com/doc/offiaccount/OA_Web_Apps/Wechat_webpage_authorization.html#1
CloudBase Auth · 认证登录	https://docs.cloudbase.net/api-reference/webv3/authentication#%E8%AE%A4%E8%AF%81%E7%99%BB%E5%BD%95

架构总览​

前置条件​

第一步 · 准备公众号凭证​

第二步 · 在 CloudBase 创建集成​

2.1 进入集成中心​

2.2 填写集成信息​

2.3 自动生成云函数资源​

2.4 配置公众号 IP 白名单​

第三步 · 了解 offiaccount-common 云函数​

3.1 网页授权相关路由​

3.2 链路与鉴权​

第四步 · 接入网页授权​

4.1 前置准备​

4.2 完整网页授权流程​

4.3 完整调用示例​

4.4 调用 /oauth/refresh 与 /oauth/verify​

常见问题 FAQ​

Q1：调用 /oauth/token 返回「微信接口错误 [40029]: invalid code」​

Q2：调用 /oauth/token 返回「invalid appsecret」或 40125​

Q3：授权页提示「该链接无法访问，请检查链接是否正确」/「redirect_uri 域名与后台配置不一致」​

Q4：snsapi_base 拿不到昵称头像​

Q5：网页在企业微信、QQ 浏览器中能跑吗​

Q6：能否直接在前端调 https://api.weixin.qq.com/sns/oauth2/access_token​

Q7：能否复用 pay-common 的同一个 CloudBase 环境​

延伸阅读​