dukang/packages/weixin-sdk/GOTCHAS.md

@dukang/weixin-sdk · 踩坑

iOS 微信 H5：JSSDK 入场 URL（扫码 / 定位 / 选图）

症状

• 登录或 OAuth 后立刻调 scanQRCode / getLocation / chooseImage 失败
• 错误类似：permission value is offline verifying、invalid signature
• 业务文案常被写成「权限校验尚未完成，请等 1～2 秒」——多数情况下等无效
• 关掉 webview 再进（整页重载）立即恢复

原因

iOS 微信对 JS-SDK 验签使用的是本次 document 加载时的 URL（去掉 # 后的完整 URL，含 query）。
history.pushState / replaceState（含 React Router）不会更新微信内部用于验签的 URL。

典型错误链路：

1. OAuth 回跳：/login?code=xxx&state=yyy（入场 URL）
2. SPA：navigate('/')
3. 用当前页 / 或「去掉 code 后的 /login」去签名 → 与微信内部 URL 不一致 → 失败

正确做法

1. 业务跳转（登录成功 / 选店进首页）：iOS 微信内用 hardNavigateInWechat(path) / location.replace，让目标页成为新的入场 URL。
2. 签名 URL：getJssdkSignUrl() 在 iOS 上返回入场 URL；OAuth 的 code/state 必须保留参与签名；后端 jssdk-config 只去 #，不要删 query。
3. 先 captureIosJssdkEntryUrl()，再 stripOAuthParamsFromLocation()。
4. 失败恢复：引导用户刷新页面或重新走 OAuth，而不是无限「再点一次」。

相关 API

• captureIosJssdkEntryUrl / getJssdkSignUrl
• shouldHardNavigateForJssdk / hardNavigateInWechat
• stripOAuthParamsFromLocation