wx-nodejs-sdk

面向 Node.js 的微信 SDK，当前聚焦两类能力：

• 公众号 OAuth / access_token / JS-SDK 签名
• 微信支付 v3 下单 / 请求签名 / 回调解密

它不是对旧社区包的简单封装，而是更适合做“一个微信主体代理多个项目”的基础 SDK。

使用说明

• 公众号接入说明
• 小程序接入说明
• 微信支付接入说明

安装

pnpm add wx-nodejs-sdk

本地联调也可以：

{
  "dependencies": {
    "wx-nodejs-sdk": "file:../../WxNodejs"
  }
}

发布前建议先跑：

npm test
npm run pack:check

OAuth 示例

import { MemoryCacheStore, WechatOfficialAccountClient } from 'wx-nodejs-sdk'

const oaClient = new WechatOfficialAccountClient({
  appId: process.env.WX_APP_ID!,
  appSecret: process.env.WX_APP_SECRET!,
  cache: new MemoryCacheStore(),
})

const authorizeUrl = oaClient.buildAuthorizeUrl({
  redirectUri: 'https://example.com/api/wechat/callback',
  scope: 'snsapi_userinfo',
  state: 'project-app-id=crm-web',
})

模板消息示例

await oaClient.sendTemplateMessage({
  touser: 'openid-xxx',
  template_id: 'template-id',
  url: 'https://example.com/order/1001',
  data: {
    title: { value: '支付成功', color: '#173177' },
    amount: { value: '100.00 元' },
  },
})

自定义菜单示例

await oaClient.createMenu({
  button: [
    {
      type: 'view',
      name: '开放平台',
      url: 'https://example.com/console',
    },
  ],
})

const menu = await oaClient.getMenu()
await oaClient.deleteMenu()

如果你要代理多个业务项目，可以直接用 SDK 的代理态：

const proxyAuthorizeUrl = oaClient.buildProxyAuthorizeUrl({
  redirectUri: 'https://example.com/api/wechat/callback',
  projectAppId: 'crm-web',
  redirectAfterLogin: '/dashboard',
  bizState: {
    inviteCode: 'A1001',
  },
})

微信支付示例

import { WechatPayV3Client } from 'wx-nodejs-sdk'

const payClient = new WechatPayV3Client({
  mchId: process.env.WX_MCH_ID!,
  appId: process.env.WX_PAY_APP_ID!,
  serialNo: process.env.WX_PAY_SERIAL_NO!,
  privateKey: process.env.WX_PAY_PRIVATE_KEY!,
  apiV3Key: process.env.WX_PAY_API_V3_KEY!,
  publicKeyId: process.env.WX_PAY_PUBLIC_KEY_ID,
  platformPublicKey: process.env.WX_PAY_PLATFORM_PUBLIC_KEY,
})

const result = await payClient.createJsapiTransaction({
  description: 'AI 服务充值',
  outTradeNo: 'order_202603170001',
  notifyUrl: 'https://example.com/api/pay/wechat/notify',
  payerOpenId: 'oUpF8uMuAJO_M2pxb1Q9zNjWeS6o',
  amount: {
    total: 100,
    currency: 'CNY',
  },
})

多项目代理时，可以把业务标识编码进 attach：

const attach = payClient.createProxyAttach({
  projectAppId: 'crm-web',
  orderId: 'order_202603170001',
})

统一回调处理示例

公众号登录回调：

import { resolveOfficialAccountProxyLogin } from 'wx-nodejs-sdk'

const result = await resolveOfficialAccountProxyLogin(oaClient, {
  code: req.query.code,
  state: req.query.state,
})

微信支付通知回调：

import { resolveWechatPayProxyNotification } from 'wx-nodejs-sdk'

const result = resolveWechatPayProxyNotification(payClient, {
  headers: req.headers,
  body: req.body,
  platformPublicKey: process.env.WX_PAY_PLATFORM_PUBLIC_KEY,
})

如果你想改成自动按微信平台证书序列号验签：

await payClient.downloadPlatformCertificates()

const result = resolveWechatPayProxyNotification(payClient, {
  headers: req.headers,
  body: req.body,
})

如果你已经切到“微信支付公钥”模式，可以这样配置：

const payClient = new WechatPayV3Client({
  mchId: process.env.WX_MCH_ID!,
  appId: process.env.WX_PAY_APP_ID!,
  serialNo: process.env.WX_PAY_SERIAL_NO!,
  privateKey: process.env.WX_PAY_PRIVATE_KEY!,
  apiV3Key: process.env.WX_PAY_API_V3_KEY!,
  publicKeyId: process.env.WX_PAY_PUBLIC_KEY_ID!,
  platformPublicKey: process.env.WX_PAY_PLATFORM_PUBLIC_KEY!,
})

说明：

• Authorization 里的 serial_no 仍然使用商户 API 证书序列号
• 请求头 Wechatpay-Serial 会优先发送你配置的 publicKeyId
• 回调验签时，如果 Wechatpay-Serial 是 PUB_KEY_ID_*，SDK 会优先走微信支付公钥验签
• 如果不是公钥 ID，则继续按平台证书 serial 验签

Express 中间件示例

公众号登录回调中间件：

import { createWechatOAuthCallbackHandler } from 'wx-nodejs-sdk'

app.get('/wechat/callback', createWechatOAuthCallbackHandler({
  client: oaClient,
  onSuccess: async (result, { res }) => {
    res.redirect(`${result.redirectAfterLogin}?project=${result.projectAppId}`)
  },
}))

微信支付通知中间件：

import { createWechatPayNotifyHandler } from 'wx-nodejs-sdk'

app.post('/wechat/pay/notify', createWechatPayNotifyHandler({
  client: payClient,
  onSuccess: async ({ resource, projectAppId }, { res }) => {
    // 在这里更新订单和业务项目状态
    res.json({ code: 'SUCCESS', message: '成功', outTradeNo: resource.out_trade_no, projectAppId })
  },
}))

Koa 中间件示例

import { createKoaWechatOAuthCallbackHandler, createKoaWechatPayNotifyHandler } from 'wx-nodejs-sdk'

router.get('/wechat/callback', createKoaWechatOAuthCallbackHandler({
  client: oaClient,
}))

router.post('/wechat/pay/notify', createKoaWechatPayNotifyHandler({
  client: payClient,
}))

适合你的代理模式

如果你要做“一个公众号 / 一个微信支付，对多个业务项目代理”，建议业务层再包一层：

• 外部请求额外传业务 projectAppId
• 登录回调用 state 带回业务标识
• 支付回调用 attach、out_trade_no 或你的订单表回查业务标识
• SDK 只负责微信协议本身，不耦合你的多项目路由策略

当前能力

• OAuth 授权地址生成
• OAuth 网页授权换 token
• OAuth 用户信息获取
• 公众号全局 access token 获取
• JS-SDK jsapi_ticket 获取
• JS-SDK 签名计算
• 公众号模板消息发送
• 公众号自定义菜单创建 / 查询 / 删除
• 代理登录 state 编解码
• 公众号登录统一回调处理
• 微信支付 v3 请求签名
• JSAPI / Native / H5 下单
• 查询订单
• 关闭订单
• 申请退款
• 平台证书下载
• 按平台证书 serial 自动验签
• 支付通知资源解密
• 支付通知签名验签
• 代理支付 attach 编解码
• 微信支付通知统一回调处理
• Express 登录回调中间件
• Express 支付通知中间件
• Koa 登录回调中间件
• Koa 支付通知中间件

发布建议

• npm version patch|minor|major
• 检查 CHANGELOG.md
• 执行 npm publish --access public

也可以直接用脚本发布：

.\scripts\publish.ps1 -Token "你的_npm_token"

或：

$env:NPM_TOKEN="你的_npm_token"
.\scripts\publish.ps1

后续可继续扩展

• 微信支付分账 / 转账
• 公众号素材管理
• 小程序登录 / 订阅消息