定位、扫码、微信支付一次讲透weixin-js-sdk高频业务接口实战清单【免费下载链接】weixin-js-sdk微信官方 JS-SDK 的 CommonJS 版本支持 TypeScript项目地址: https://gitcode.com/gh_mirrors/wei/weixin-js-sdkweixin-js-sdk 是微信官方 JS-SDK 的 npm 封装版支持 CommonJS 和 TypeScript 类型提示可被 Webpack、Browserify 等构建工具直接引用。本文这份微信 JS-SDK 实战清单将聚焦三个高频业务接口getLocation 定位、scanQRCode 扫码、chooseWXPay 微信支付带你一次搞懂参数含义与常见坑点。 先搞懂weixin-js-sdk 是什么在微信内置浏览器中打开的 H5 页面本身无法直接调用相机、定位、支付等系统能力需要借助微信客户端提供的 JS-SDK 来桥接。而官方提供的只是一个全局脚本直接使用有几个痛点无法通过require/import引入与现代前端工程化体系格格不入没有类型定义参数全靠查文档拼错字段名也不报错weixin-js-sdk 正是解决这两个问题的轻量封装核心价值一目了然特性说明npm 安装一条命令引入版本化管理CommonJS / ESM兼容require与import两种写法TypeScript 支持自带类型定义接口参数、回调字段全部可提示与官方同源内容对齐官方 jweixin-1.6.0能力完全一致项目核心文件非常简洁index.js—— CommonJS 入口文件index.original.js—— 官方 JS 源码原样保留index.d.ts—— TypeScript 类型定义本文三个接口的完整参数都可在此查阅package.json—— 包信息当前版本 1.6.5 3步完成 weixin-js-sdk 安装与初始化第1步安装依赖npm install weixin-js-sdk第2步引入 SDK// CommonJS 写法 var wx require(weixin-js-sdk); // ES Module 写法 import wx from weixin-js-sdk;第3步配置并等待就绪所有业务接口都必须先完成wx.config初始化然后在wx.ready回调中调用wx.config({ debug: true, // 调试阶段建议打开 appId: 公众号AppID, timestamp: 1234567890, nonceStr: 随机字符串, signature: 后端生成的签名, jsApiList: [getLocation, scanQRCode, chooseWXPay] }); wx.ready(function () { // 在这里调用定位、扫码、支付等接口 });⚠️ 两个关键点signature签名必须放在后端生成前端只负责传递jsApiList必须显式声明你要用的接口漏写会直接报没有权限。 接口一getLocation 定位——wgs84 与 gcj02 一文讲清适用于附近门店、打卡签到、收货地址推荐等场景。核心参数与返回值项目说明type坐标类型默认wgs84GPS 原始坐标传gcj02返回火星坐标success回调返回latitude纬度、longitude经度、speed速度、accuracy精度 新手最该记住的一点坐标系国内地图高德、腾讯、百度展示的坐标统一是gcj02而手机 GPS 芯片输出的是wgs84。如果你拿到 wgs84 坐标直接丢给地图展示位置会偏移几百米——这就是定位不准最常见的原因。经验法则拿坐标去地图上图、传给openLocation展示 → 传gcj02需要国际通用坐标系做距离计算 → 传wgs84定位成功后可紧接着调用openLocation接口用微信内置地图把位置可视化展示给用户底部还能挂一个超链接方便跳转。 接口二scanQRCode 扫码——二维码和一维码都能扫适用于会员码核销、门店扫码开门、设备绑定等场景。两个参数决定行为模式参数取值效果needResult0默认扫出的内容由微信直接处理比如扫到网址就直接跳转needResult1扫码结果原样返回给你的页面在success回调的res.resultStr中拿到scanType[qrCode]/[barCode]指定只扫二维码或只扫条形码默认两者都支持 实战建议核销会员码设needResult: 1把resultStr提交后端校验业务闭环完全可控扫内容跳转保持默认needResult: 0让微信自己处理少写一堆代码用户可能中途取消扫码记得在cancel回调中恢复页面状态避免按钮卡死 接口三chooseWXPay 微信支付——H5 支付五个关键参数适用于公众号 H5 页面内发起 JSAPI 支付。支付流程与参数来源微信支付不是前端独立完成的标准链路是后端调用微信统一下单接口 → 拿到 prepay_id → 前端组装签名参数 →chooseWXPay拉起收银台。chooseWXPay的五个必填参数全部来自后端参数含义易错点timestamp支付签名时间戳支付后台生成的字段名timeStamp中S 是大写与 JSSDK 的小写timestamp极易混淆nonceStr随机串不超 32 位必须与后端签名时使用的一致package统一下单返回的 prepay_id格式必须是prepay_idxxx不能漏前缀signType签名方式默认SHA1新版支付需传MD5与后端保持一致paySign支付签名签名错误会提示invalid signature优先检查参数拼写和签名范围 三条保命建议前端回调不可信success只用来刷新 UI是否支付成功必须以微信异步通知 后端查单为准签名报错先查大小写timeStamp/timestamp混用是新手第一大坑域名要备案JS 接口安全域名必须与页面实际域名一致否则 config 阶段就会失败 高频踩坑清单微信 JS-SDK 调试前对照一遍现象大概率原因解决方式接口调了没反应在wx.ready之前就调用了把所有业务调用挪进ready回调提示没有权限接口未加入jsApiList把接口名补进 config定位偏移几百米wgs84 / gcj02 坐标系混用展示地图的场景改传gcj02支付报 invalid signature签名参数大小写不一致或 package 格式错误按上表核对五个参数页面调试一片绿但生产报错签名过期或域名未配置时间戳控制在有效期内检查安全域名小技巧把debug设为true后所有接口的调用结果会在客户端直接弹出来是排查问题的第一手资料。✅ 总结weixin-js-sdk 让微信 JS-SDK 的接入从手贴脚本进化为工程化依赖安装npm install weixin-js-sdk配合 TypeScript 享受完整参数提示定位getLocation记住坐标系展示场景用gcj02扫码scanQRCode用needResult区分微信处理和自己处理支付chooseWXPay的参数交给后端生成前端只负责组装与回调兜底三个接口的完整参数定义都可以直接在index.d.ts中查阅IDE 悬停即可获得逐字段中文注释写代码时基本不用再去翻文档。【免费下载链接】weixin-js-sdk微信官方 JS-SDK 的 CommonJS 版本支持 TypeScript项目地址: https://gitcode.com/gh_mirrors/wei/weixin-js-sdk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
