定位、扫码、微信支付一次讲透：weixin-js-sdk高频业务接口实战清单-平芜编程栈

定位、扫码、微信支付一次讲透：weixin-js-sdk高频业务接口实战清单

【免费下载链接】weixin-js-sdk微信官方 JS-SDK 的 CommonJS 版本，支持 TypeScript项目地址: https://gitcode.com/gh_mirrors/wei/weixin-js-sdk

weixin-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`	坐标类型，默认`wgs84`（GPS 原始坐标）；传`gcj02`返回火星坐标
`success`回调	返回`latitude`（纬度）、`longitude`（经度）、`speed`（速度）、`accuracy`（精度）

💡 新手最该记住的一点：坐标系

国内地图（高德、腾讯、百度）展示的坐标统一是gcj02，而手机 GPS 芯片输出的是wgs84。如果你拿到 wgs84 坐标直接丢给地图展示，位置会偏移几百米——这就是"定位不准"最常见的原因。

经验法则：

拿坐标去地图上图、传给openLocation展示 → 传gcj02
需要国际通用坐标系做距离计算 → 传wgs84

定位成功后，可紧接着调用openLocation接口，用微信内置地图把位置可视化展示给用户，底部还能挂一个超链接方便跳转。

🔍 接口二：scanQRCode 扫码——二维码和一维码都能扫

适用于：会员码核销、门店扫码开门、设备绑定等场景。

两个参数决定行为模式

参数	取值	效果
`needResult`	`0`（默认）	扫出的内容由微信直接处理，比如扫到网址就直接跳转
`needResult`	`1`	扫码结果原样返回给你的页面，在`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_id=xxx`，不能漏前缀
`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 格式错误	按上表核对五个参数
页面调试一片绿但生产报错	签名过期或域名未配置	时间戳控制在有效期内，检查安全域名