微信 JS-SDK 的始注注册流程卡了三天，最后发现是始注 URL 编码多写了一个斜杠。这事说起来挺蠢的始注，但如果你也在调 JSAPI，始注大概率能懂那种“明明照文档抄了却死活调不通”的始注崩溃感。

JSAPI 注册的始注本质就一件事：让当前页面拿到调用微信原生能力的权限。没有注册，始注wx.chooseImage、始注wx.scanQRCode 这些接口连报错都懒得给你，始注直接静默失败。始注我第一次踩坑是始注在一个活动页，用户点了上传按钮毫无反应，始注控制台干干净净，始注后来才知道是始注 wx.config 根本没通过。

config 之前，始注先把签名拿到手

签名不是前端算的。后端用 AppSecret 换 access_token，再用 access_token 换 jsapi_ticket，最后把 ticket、noncestr、timestamp、url 拼起来做 SHA1。听起来步骤多，但真正容易出错的是那个 url 参数。

它必须是当前页面的完整 URL，不包含 # 后面的 hash 部分。iOS 上微信会忽略 hash，Android 上部分机型会把 hash 也带进去算签名。我遇到过一个诡异情况：同一个页面，iOS 能调起相机，Android 死活不行。排查半天，发现 Android 端传的 url 带了 #/detail，后端签名时没去掉，前端校验自然失败。

所以注册前先干一件事：location.href.split('#')[0]，把这个值传给后端，别自作聪明加参数或去掉什么。

wx.config 到底在验什么

调用 wx.config 时，微信客户端会拿你传的 appId、timestamp、nonceStr、signature 跟它自己算的做比对。四个参数任何一个不对，config:fail 就来了。但微信的报错信息出了名的模糊，invalid signature 四个字背后可能是十几种原因。

我的经验是：先确认 jsapi_ticket 有没有过期。它有效期 7200 秒，但微信不保证到点才失效，有时候提前几分钟就废了。如果后端做了缓存，缓存时间设 7000 秒比较稳妥。再确认签名用的 url 跟当前页面 url 完全一致——包括协议、域名、端口、路径、查询参数，一个字符都不能差。

有个细节很多人忽略：wx.config 里的 jsApiList 必须把你要用的接口都列进去。漏写一个，那个接口就调不了。我见过有人只写了 chooseImage，结果 previewImage 用不了，还以为是图片路径问题。

ready 和 error 才是真正干活的

wx.config 本身不执行任何操作，它只是注册。真正的业务逻辑要写在 wx.ready 回调里。这个设计挺合理，但新手容易把代码直接写在 config 后面，然后发现接口时好时坏——因为 config 是异步的，没 ready 就调用，等于没注册。

wx.config({  debug: false, appId: '...', timestamp: ..., nonceStr: '...', signature: '...', jsApiList: ['chooseImage', 'previewImage'] }); wx.ready(function() {  // 这里才能安全调用 wx.chooseImage({  count: 1 }); }); wx.error(function(res) {  console.log('注册失败', res); });

调试阶段把 debug 设为 true，微信会弹出 alert 显示每一步的校验结果。虽然烦，但比对着 invalid signature 干瞪眼强。

SPA 路由切换后的坑

单页应用里，pushState 改变 URL 后，之前注册的 config 就失效了。微信只认第一次注册时的 URL，后面路由变了，签名对不上，接口全部罢工。解决办法是在路由变化后重新走一遍签名和 config 流程。Vue 项目里可以在 router.afterEach 里做这件事，React 就在 history.listen 里处理。

但别每次路由变都重新注册，微信对 config 调用频率有限制。我的做法是判断新 URL 跟上次注册的 URL 是否同源同路径，变了才重新签。这样既不会频繁触发限制，也不会漏掉必要的重新注册。

说到底，JSAPI 注册就是个细心活。参数别写错，URL 别乱传，异步别搞混，基本就能跑通。剩下的就是跟微信那套不太友好的错误提示斗智斗勇了。