@gulibs/wechat-open-api

微信生态服务端接口封装：小程序、公众号、服务号，基于官方文档实现，TypeScript 类型完整。

• 小程序：登录校验、access_token、订阅消息、内容安全、URL Link 等
• 公众号：凭证、二维码、用户 / 标签、自定义菜单
• 服务号：在公众号基础上增加网页授权、模板消息、订阅通知

支付能力请使用 wechat-pay-v3，本包仅导出支付配置类型供参考。

安装

pnpm add @gulibs/wechat-open-api
# 或
npm i @gulibs/wechat-open-api

要求：Node.js >= 16。

配置

所有客户端均使用统一配置 IWechatConfig：

| 字段 | 类型 | 说明 | |--------|--------|----------| | appid | string | 应用 ID（小程序 / 公众号 / 服务号 AppID） | | secret | string | 应用密钥（AppSecret） |

小程序、公众号、服务号若为不同应用，请分别使用对应的 appid/secret。

快速开始

import {
  MiniprogramClient,
  OfficialAccountClient,
  ServiceAccountClient,
  type IWechatConfig,
} from '@gulibs/wechat-open-api'

const config: IWechatConfig = { appid: 'your_appid', secret: 'your_secret' }

// 小程序：登录校验、access_token、订阅消息、内容安全、URL Link
const miniprogram = new MiniprogramClient(config)
const session = await miniprogram.code2Session('wx_login_code_from_frontend')
const token = await miniprogram.getAccessToken()

// 公众号：凭证、二维码、用户信息、标签、自定义菜单
const officialAccount = new OfficialAccountClient(config)
const userInfo = await officialAccount.getUserInfo(token.access_token, 'openid')
const menus = await officialAccount.getMenu(token.access_token)

// 服务号：公众号能力 + 网页授权、模板消息、订阅通知
const serviceAccount = new ServiceAccountClient(config)
const oauthToken = await serviceAccount.getOAuthAccessToken('code_from_redirect')
await serviceAccount.sendTemplateMessage({
  access_token: token.access_token,
  touser: 'openid',
  template_id: 'template_id',
  data: { first: { value: 'Hello' } },
})

公共类型

IWechatConfig

| 字段 | 类型 | 说明 | |--------|--------|----------| | appid | string | 应用 ID | | secret | string | 应用密钥 |

用于小程序、公众号、服务号的初始化。

IStateResponse

| 字段 | 类型 | 说明 | |---------|----------------|----------| | errcode | number | string | 错误码 | | errmsg | string | 错误信息 |

IAccessTokenResponse

继承 IStateResponse，并包含 access_token: string、expires_in: number。

小程序（MiniprogramClient）

• 类：MiniprogramClient
• 基础 URL：https://api.weixin.qq.com
• 构造：new MiniprogramClient(config: IWechatConfig, apiUrl?: string)

登录与凭证

| 方法 | 说明 | 参数 | 返回 | |------|------|------|------| | code2Session(code) | 登录凭证校验，获取 openid、session_key、unionid | code: string | ICode2SessionResponse | | getAccessToken() | 获取 access_token（普通版） | - | IAccessTokenResponse | | getStableAccessToken() | 获取 access_token（稳定版） | - | IAccessTokenResponse |

用户与手机号

| 方法 | 说明 | 参数 | 返回 | |------|------|------|------| | getPhoneNumber(accessToken, code) | 获取用户手机号 | accessToken: string, code: string | IGetPhoneNumberResponse |

消息

| 方法 | 说明 | 参数 | 返回 | |------|------|------|------| | sendSubscribeMessage(params) | 发送订阅消息 | ISendSubscribeMessageParams | IStateResponse |

内容安全

| 方法 | 说明 | 参数 | 返回 | |------|------|------|------| | checkText(options) | 文本内容安全检测 | ICheckTextOptions | ICheckTextResponse | | checkImageAndMedia(options) | 图片 / 音视频异步安全检测 | ICheckImageAndMediaOptions | ICheckImageAndMediaResponse |

URL Link

| 方法 | 说明 | 参数 | 返回 | |------|------|------|------| | generateUrlLink(options) | 生成 URL Link | IGenerateUrlLinkOptions | IGenerateUrlLinkResponse |

公众号（OfficialAccountClient）

• 类：OfficialAccountClient
• 基础 URL：https://api.weixin.qq.com
• 构造：new OfficialAccountClient(config: IWechatConfig, apiUrl?: string)

凭证

| 方法 | 说明 | 参数 | 返回 | |------|------|------|------| | getAccessToken() | 获取 access_token（普通版） | - | IAccessTokenResponse | | getStableAccessToken() | 获取 access_token（稳定版） | - | IAccessTokenResponse |

二维码

| 方法 | 说明 | 参数 | 返回 | |------|------|------|------| | createQrcode(params) | 创建带参数临时二维码 | IQrcodeParams | IQrcodeResponse |

展示二维码地址：QRCODE_DISPLAY_URL + '?ticket=' + ticket（常量 QRCODE_DISPLAY_URL 为 https://mp.weixin.qq.com/cgi-bin/showqrcode）。

用户管理

| 方法 | 说明 | 参数 | 返回 | |------|------|------|------| | getUserInfo(accessToken, openid) | 获取用户基本信息 | accessToken: string, openid: string | IUserInfoResponse | | setUserRemark(params) | 设置用户备注名 | IRemarkParams | IStateResponse |

标签

| 方法 | 说明 | 参数 | 返回 | |------|------|------|------| | getTags(accessToken) | 获取已创建标签列表 | accessToken: string | ITagsResponse | | batchTagUsers(params) | 批量为用户打标签 | IUsersAddTagParams | IStateResponse |

自定义菜单

| 方法 | 说明 | 参数 | 返回 | |------|------|------|------| | createMenu(params) | 创建自定义菜单 | ICreateMenuParams | IStateResponse | | getMenu(accessToken) | 获取自定义菜单配置 | accessToken: string | unknown |

服务号（ServiceAccountClient）

• 类：ServiceAccountClient（继承 OfficialAccountClient）
• 基础 URL：https://api.weixin.qq.com
• 构造：new ServiceAccountClient(config: IWechatConfig, apiUrl?: string)

在公众号能力基础上增加以下接口。

网页授权

| 方法 | 说明 | 参数 | 返回 | |------|------|------|------| | getOAuthAccessToken(code) | 通过 code 换取网页授权 access_token | code: string | IOAuthAccessTokenResponse | | refreshOAuthAccessToken(refreshToken) | 刷新网页授权 access_token | refreshToken: string | IOAuthAccessTokenResponse | | checkOAuthAccessToken(accessToken, openid) | 检验网页授权凭证是否有效 | accessToken: string, openid: string | { errcode, errmsg } | | getOAuthUserInfo(accessToken, openid, lang?) | 获取网页授权用户信息 | accessToken, openid, lang? | IOAuthUserInfoResponse |

模板消息与订阅通知

| 方法 | 说明 | 参数 | 返回 | |------|------|------|------| | sendTemplateMessage(params) | 发送模板消息 | ISendTemplateMessageParams | IStateResponse | | sendSubscribeNotify(params) | 发送订阅通知 | ISendSubscribeNotifyParams | IStateResponse |

支付（pay 模块）

微信支付能力请使用 wechat-pay-v3（或 @gulibs/wechat-pay-v3）。本包仅从 pay 模块导出配置类型 IWechatPayConfig，供类型参考；具体支付 API 请直接依赖 wechat-pay-v3。

开发与测试

# 安装依赖
pnpm install

# 构建
pnpm run build

# 使用 .env 中的 WATCHAT_APP_ID / WATCHAT_APP_SECRET 跑接口测试（非企业权限）
pnpm run test:env

公众号单独测试时，可在 .env 中配置 WATCHAT_OFFICIAL_APP_ID 与 WATCHAT_OFFICIAL_APP_SECRET，详见 scripts/test-with-env.mjs 注释。

官方文档

• 小程序服务端 API
• 公众号 API
• 服务号 API

License

MIT