一、前言

目前绝大多数 H5、微信小程序项目均需对接微信三大核心能力：微信分享（朋友圈 / 好友）、扫一扫功能、微信支付。两者开发载体分为微信公众号 H5、微信小程序两套环境，底层调用微信官方 JS-SDK、小程序 API 实现能力。本文分两大场景，梳理完整接入流程、代码示例、踩坑解决方案，方便前端开发直接落地对接。

二、前置公共基础：微信 JS-SDK 授权配置（公众号 H5 通用）

2.1 必备配置项

1. 公众号后台配置「JS 接口安全域名」：项目线上域名，本地localhost、IP 无法调试；

2. 后端提供签名接口：传入当前页面 URL，返回timestamp、noncestr、signature、appId；

3. 引入微信官方 JS 文件：https://res.wx.qq.com/open/js/jweixin-1.6.0.js

2.2 前端基础 wx.config 初始化代码

// 引入wx js文件后执行 async function initWxSdk() {  // 1、获取当前不带#的页面地址  const url = window.location.href.split('#')[0];  // 2、请求后端获取签名信息  const res = await fetch(`/api/wx/sign?url=${encodeURIComponent(url)}`);  const { appId, timestamp, noncestr, signature } = await res.json();  wx.config({    debug: false, // 上线关闭，调试开启true打印日志    appId,    timestamp,    nonceStr: noncestr,    signature,    // 一次性注册需要使用的所有接口权限    jsApiList: [      "updateAppMessageShareData", // 分享好友      "updateTimelineShareData", // 分享朋友圈      "scanQRCode", // 扫一扫      "chooseWXPay" // 微信支付    ]  });  wx.ready(() => {    // SDK加载完成，统一初始化分享配置    setWxShare();  })  wx.error((err) => {    console.error("wx配置失败：", err);  }) }

三、功能一：微信分享（分享好友 / 朋友圈）

3.1 业务说明

使用updateAppMessageShareData（分享给好友）、updateTimelineShareData（分享到朋友圈），废弃旧版onMenuShareTimeline等废弃 API。

3.2 完整分享封装函数

function setWxShare() {  const shareInfo = {    title: "国防兵器科普暑期实践活动", // 分享标题    desc: "沉浸式兵器体验，国防教育亲子实践", // 分享描述（朋友圈不展示）    link: "https://xxx.com/activity", // 分享落地页域名需和JS安全域名一致    imgUrl: "https://xxx/share.jpg" // 分享图标，建议32*32以上线上图片  };  // 分享给微信好友  wx.updateAppMessageShareData({    ...shareInfo,    success() {      console.log("分享好友配置成功");    }  })  // 分享到朋友圈  wx.updateTimelineShareData({    ...shareInfo,    success() {      console.log("分享朋友圈配置成功");    }  }) }

3.3 常见踩坑

1. 分享图片必须 HTTPS 线上地址，本地 / 内网图片不生效；

2. 页面 URL 带#哈希值签名会失效，签名必须截取 #前地址；

3. 域名未配置 JS 安全域名，直接报签名错误；

4. wx.config 必须在 wx.ready 内执行分享注册。

四、功能二：微信扫一扫（扫码核销 / 登录）

4.1 接口：scanQRCode 参数说明

• needResult：1 直接返回扫码结果；0 跳转对应小程序 / 链接

• scanType：扫码类型 ["qrCode","barCode"] 二维码、条形码

4.2 扫码调用代码

// 页面扫码按钮点击事件 function openScan() {  wx.scanQRCode({    needResult: 1, // 扫描完成返回内容给前端    scanType: ["qrCode"],    success: (res) => {      // res.resultStr 扫码获取的内容      const code = res.resultStr;      console.log("扫码结果：", code);      // 业务逻辑：核销券、登录、跳转页面等    },    fail: (err) => {      console.log("扫码失败", err);    }  }) }

4.3 使用限制

仅微信内置浏览器可调用，外部浏览器、小程序无法使用 JS-SDK 扫码；小程序需使用专属wx.scanCodeAPI。

五、功能三：公众号 H5 微信支付（chooseWXPay）

5.1 整体流程

1. 前端下单请求后端订单接口；

2. 后端调用微信支付统一下单 API，返回支付参数timeStamp、nonceStr、package、signType、paySign；

3. 前端调用wx.chooseWXPay唤起微信支付弹窗。

5.2 支付完整代码

// 点击下单支付 async function createOrder() {  // 1、请求后端创建订单，获取支付签名参数  const payParams = await fetch("/api/wx/createOrder", {    method: "POST",    body: JSON.stringify({ goodsId: 1 })  }).then(res => res.json());  // 2 唤起微信支付弹窗  wx.chooseWXPay({    timestamp: payParams.timeStamp,    nonceStr: payParams.nonceStr,    package: payParams.package, // 固定格式 prepay_id=xxxx    signType: "RSA2", // 推荐RSA2加密    paySign: payParams.paySign,    success(res) {      // 支付成功，跳转订单/核销页面      location.href = "/order-success";    },    fail(res) {      // 用户取消支付、支付失败      console.log("支付取消/失败", res);    }  }) }

5.3 支付关键注意点

1. 支付权限需要公众号开通微信支付商户号；

2. package 参数格式固定，不可自定义修改；

3. 签名算法前后端必须统一（MD5/RSA2）；

4. 支付结果以商户后台回调通知为准，前端 success 仅作页面跳转展示，不可作为订单核销依据。

六、微信小程序端对应实现（补充对比）

很多项目同时配套小程序，附上对应简易 API，区分 H5 JS-SDK：

1、小程序分享

Page({  onShareAppMessage() {    return {      title: "国防兵器科普暑期实践活动",      path: "/pages/index",      imageUrl: "xxx.jpg"    }  },  onShareTimeline() {    return { title, imageUrl }  } })

2、小程序扫一扫

wx.scanCode({  success: res => { console.log(res.result) } })

3、小程序微信支付

wx.requestPayment({  timeStamp, nonceStr, package, signType, paySign,  success() {} })

七、通用问题排查方案

1. wx.config 签名报错 复制页面完整 URL（去除 #），使用微信官方签名校验工具核对后端生成的 signature；

2. 分享不显示自定义图片 / 标题 图片地址 HTTPS、无防盗链，清除微信缓存重新进入页面；

3. 扫一扫按钮点击无反应 检查 jsApiList 是否注册 scanQRCode，确认在微信内置浏览器打开；

4. 支付弹窗调不起 核对商户号权限、统一下单接口返回参数是否完整、signType 前后端一致；

5. 本地开发无法调试 JS-SDK 仅支持线上已配置域名，本地可使用内网穿透工具映射线上域名测试。

八、总结

1. 微信公众号 H5 统一基于JS-SDK，需后端提供签名、支付订单两项接口支撑；

2. 分享、扫码、支付三大能力必须在 wx.ready 就绪后调用；

3. 数据真实性（支付、核销）全部依赖后端接口校验，前端仅做交互展示；

4. 小程序内置原生 API，无需 JS-SDK 签名，开发流程更简单，但能力限制与 H5 有差异。