公众号菜单里放一个H5活动页，用户点进去却提示需要手机号登录，这种割裂体验很容易造成流失。微信内置浏览器不会把粉丝身份直接带给H5页面，H5应用也没有微信生态的会话凭证，因此需要在菜单跳转这一层设计单点登录，打通公众号粉丝与H5应用账号。下面从原理、流程、代码三个层面拆解实现。
一、为什么公众号菜单里的H5拿不到用户身份
公众号自定义菜单本质上是微信客户端里配置的一个入口，它只负责打开一个URL，不会附加上下文用户参数。H5页面运行在微信内置浏览器中，虽然可以记录自己的cookie，但这个cookie与公众号粉丝身份没有关联，也和微信登录态不是一回事。很多业务方误以为在菜单设置里能选择会员卡或用户标签，但实际上菜单事件只对关键词和跳转动作有意义，不会把openid传给网页。
微信生态里要拿到用户身份，必须走网页授权。对于静默识别用户，通常使用snsapi_base，用户无感知，只能获取openid；如果需要昵称头像等资料，才使用snsapi_userinfo并弹出确认。单点登录场景优先选择snsapi_base，避免打扰用户，同时也减少因授权弹窗造成的流失。
所以打通的核心不再是菜单配置如何传用户，而是在菜单跳转的URL里先指向微信授权地址，让微信在回调中把code带给后端，后端完成身份解析后再跳到H5前端。这个链路一建立，后续每次从菜单进入H5都可以静默识别，不再需要用户重新登录。
二、OAuth2.0网页授权与单点登录的流程设计
微信网页授权基于OAuth2.0协议，整体流程可以分成五步：用户点击菜单触发跳转；H5入口检测到没有本地登录态，跳转到微信授权URL；微信回调业务服务器并携带code；后端用code换取access_token和openid；后端绑定用户并生成业务token，再把token重定向回前端。
授权URL的格式如下：
public String buildAuthUrl(String redirectUri, String state) {
String appId = "你的公众号AppID";
String scope = "snsapi_base";
String encodedRedirect = URLEncoder.encode(redirectUri, StandardCharsets.UTF_8);
String url = "https://open.weixin.qq.com/connect/oauth2/authorize?appid=" + appId
+ "&redirect_uri=" + encodedRedirect
+ "&response_type=code"
+ "&scope=" + scope
+ "&state=" + state
+ "#wechat_redirect";
return url;
}
state参数非常重要，它应当由后端生成并保存在服务端或签名校验，回调时比对。强烈不建议在redirect_uri中透传用户ID、手机号等敏感信息，因为回调地址可能出现在日志或浏览器历史中。redirect_uri必须使用https，且域名要与公众号后台配置的网页授权域名一致，否则微信会报redirect_uri参数错误。
授权范围snsapi_base与snsapi_userinfo的选择也要根据业务。snsapi_base只能拿到openid，无法获取用户资料；如果需要展示头像昵称，可以单独设计升级授权入口，而不是在菜单跳转时强制用户确认。单点登录的目标是静默，因此推荐先落openid，资料用其他业务接口补齐。
三、后端实现：处理回调并绑定本地用户
后端回调接口会收到两个参数：code和state。先校验state防止CSRF，然后用code请求微信接口获取openid。这里使用Spring Boot示例：
@GetMapping("/wechat/callback")
public void wechatCallback(@RequestParam String code,
@RequestParam String state,
HttpServletResponse response) throws Exception {
if (!checkState(state)) {
response.sendError(HttpServletResponse.SC_BAD_REQUEST, "state无效");
return;
}
String appId = "你的公众号AppID";
String secret = "你的公众号AppSecret";
String tokenUrl = "https://api.weixin.qq.com/sns/oauth2/access_token?appid="
+ appId + "&secret=" + secret + "&code=" + code + "&grant_type=authorization_code";
String result = httpGet(tokenUrl);
JSONObject json = JSON.parseObject(result);
String openid = json.getString("openid");
String accessToken = json.getString("access_token");
User user = userService.findOrCreateByOpenid(openid);
String token = jwtService.generateToken(user.getId());
String frontUrl = "https://你的域名/index.html?token=" + token;
response.sendRedirect(frontUrl);
}
这里假设httpGet、checkState、userService、jwtService已经存在。实际项目中要把access_token也缓存起来，虽然snsapi_base拿到的access_token一般只用于获取用户信息，但后续如果要调用用户信息接口，需要同时保存openid和access_token。
获取到openid后，先查本地user表是否存在该openid。若不存在，创建一个新的本地用户，用户资料可以先用占位，后续再通过手机号绑定或snsapi_userinfo授权来补充。若存在，则直接复用，保持同一用户在不同设备、不同场景下的身份一致。然后生成JWT或自定义token返回前端。JWT中可以带用户ID、openid、应用标识和过期时间，不建议把openid直接暴露到前端，使用内部ID更安全。
重定向回前端页面时，token放在URL参数里。这会短暂出现在浏览器地址栏，但页面可以立即把token存入localStorage并清理URL。也可以采用设置HttpOnly Cookie的方案，但微信浏览器对跨域Cookie限制较多，URL参数方案更直观稳定。无论哪种方案，都要保证token有效期合理，并支持续期。
四、前端接收token与菜单配置细节
前端H5页面加载时从URL读取token，保存到localStorage。之后所有异步请求都由拦截器统一带上Authorization头。示例：
function getTokenFromUrl() {
const params = new URLSearchParams(window.location.search);
return params.get('token');
}
const token = getTokenFromUrl();
if (token) {
localStorage.setItem('h5_token', token);
window.history.replaceState({}, document.title, window.location.pathname);
}
axios.interceptors.request.use(config => {
const savedToken = localStorage.getItem('h5_token');
if (savedToken) {
config.headers.Authorization = 'Bearer ' + savedToken;
}
return config;
});
清除URL参数是为了防止用户复制地址分享出去，导致token泄露。分享出去的链接如果没有token，接收者打开后会重新走授权流程，获取自己的身份。这是合理行为，但要注意如果分享链接里带了旧token，可能造成越权。因此URL清理步骤必须尽早执行，最好在应用启动阶段完成。
公众号自定义菜单配置也有关键点。菜单类型选择跳转网页，菜单的URL要填后端暴露的登录入口地址，而不是直接填H5页面的静态地址。这个入口会检查登录态：如果已经登录，直接重定向到H5页面；如果未登录，则重定向到微信授权URL。比如菜单URL配置为 https://你的域名/auth/entry，入口接口负责整个调度。
回调域名配置在微信公众平台设置与开发中的接口权限里，找到网页授权获取用户基本信息，填写业务域名，不包含协议和路径。如果有测试环境，需要使用内网穿透或配置测试公众号，不要在生产公众号上随意修改回调域名，以免影响线上用户。
五、容易踩的坑与优化建议
单点登录链路里最常出现的问题是redirect_uri参数错误。这个错误的直接原因是回调地址与后台配置的网页授权域名不一致，或者编码方式不对。建议把回调地址规范化：所有回调统一走 https://你的域名/wechat/callback，不要带多余参数和路径。state参数要生成后放在服务端缓存，设置过期时间，回调时只校验一次，防止重放。
另一个问题是用户在微信外打开H5页面。微信网页授权只能在微信客户端内执行，如果用户在系统浏览器或第三方浏览器直接访问 https://你的域名/auth/entry，会无法拉起授权。这时要做环境判断，提醒用户使用微信打开，或者降级为手机号验证码登录。
性能方面，不要把微信API的access_token与网页授权access_token混淆。前者是公众号调用接口的全局凭证，由公众平台统一管理；后者是网页授权后针对单个用户的凭证，两者接口地址和作用完全不同。代码里不要用同一个token去调不同的接口，否则会报40001或无效凭证错误。
最后，可以对登录态续期做优化。JWT设置过期时间不宜过长，例如2小时。用户每次打开H5页面时，如果后端判断token即将过期，可以在入口调度中刷新token，或者通过refresh_token机制延长会话。不要依赖微信网页授权每次重新获取，因为频繁授权虽然静默，但也会增加请求链路耗时。