企业官网建设流程全解析

简介：这是一份专为uni-app开发者准备的微信H5授权登录解决方案，面向需要在小程序/H5端获取用户openId并实现注册登录的初学者与中级开发者。资源将微信网页授权流程封装为可直接调用的工具，包含2个核心文件（1个js工具函数、1个vue页面示例），压缩包仅4KB，轻量易懂。已有8158人学习下载，备受实战项目开发者关注。通过该资源可掌握组装授权URL、处理回调参数、解析用户openId与用户信息等关键步骤，js文件中封装了请求与参数处理逻辑，vue示例演示了从授权启动到登录态写入的完整页面流程，下载后替换配置即可快速接入项目，同时也可作为理解微信H5授权机制的教学笔记，适合边看边改、快速落地。

1. 微信H5授权与uniapp：为什么openId是移动端登录的基石

项目上线时甲方提了个需求：微信公众号菜单点进来，用户不用注册，直接用微信身份进入系统。这个需求落到技术上就是一件事——在uniapp打包的H5页面里拿到微信用户的openId，再拿它去自家后端换登录token。看起来简单，真正动手会发现微信H5授权和uni.login在小程序里的流程完全不同：H5端没有现成的code获取方法，必须自己完整走一遍微信OAuth2.0授权。下面基于一套已经封装好的utils工具类展开，从公众号后台配置、scope选型、授权URL拼接、后端换openId，到注册登录打通，五个环节按顺序拆开，每段代码都能直接复制进现有uniapp项目改造，适合正在做公众号H5嵌入、需要免登录进入的团队。

2. 授权前置：公众号配置、回调域名与scope选型

在写任何代码之前，先确认三件事，否则后面每一步都会出问题：公众号必须是已认证的服务号或已认证订阅号，页面必须在微信内置浏览器中打开，以及公众号后台至少配置了一个网页授权域名。这三条缺一条，整个OAuth2.0流程就起不来，报错还千奇百怪，比如redirect_uri参数错误或者干脆不跳转。

2.1 AppID与AppSecret：两个凭证各管什么

登录公众号后台，在「设置与开发-基本配置」页面拿到AppID和AppSecret。AppID是公开的，前端拼授权链接时要用；AppSecret只能出现在后端，用code换openId的请求必须由后端发起。很多demo把AppSecret直接写进uniapp的常量文件里，一旦前端代码打包上传到静态服务器，等于把公众号密钥公之于众。拿到AppSecret的人可以调微信接口拉取粉丝数据、发模板消息，这是比较严重的权限泄漏，生产环境不能这么干。

如果AppSecret真的泄漏了，补救手段是在后台重置，重置后旧密钥立即失效，新密钥从后端配置中心同步，不需要发版前端。这个操作是即时的，用户无感知。

2.2 网页授权域名与回调域名：少配一个都会报错

在「设置与开发-公众号设置-功能设置」里配置网页授权域名。微信要求这个域名必须是已ICP备案的完整域名，不能是IP地址，也不能带http://或https://前缀。配置完成后，这个域名下所有页面路径都可以发起网页授权。实际开发里最容易遇到「本地能跑、线上白屏」，根源大多是本地用了localhost，它不在授权域名单里。

我的做法是本地起一个和线上同域名的映射：线上用yourdomain.com，本地就在hosts里把dev.yourdomain.com指向127.0.0.1，nginx反代到uniapp的devServer端口，然后把dev.yourdomain.com也加进授权域名。这样本地调试和线上行为一致，不会出现「本地随便跳、线上一个错」的割裂感。

表：网页授权配置项说明

回调redirect_uri不一定非要单独做一个落地页，直接把uniapp H5首页地址作为回调地址是常见做法。比如https://yourdomain.com/h5，用户授权完成后微信会跳到https://yourdomain.com/h5/?code=xxx&state=xxx，H5自己在onLoad里解析当前URL的code。这种方式省掉一个中间页，打包资源也不需要为授权单独配路由。

这里还要提醒一个公众号后台规则：同一个网页授权域名在同一时间只能关联一个公众号。新项目申请出现「该域名已被使用」时，需要先在原公众号后台解绑再重新绑定，这个操作即时生效，不需要联系微信审核。

2.3 snsapi_base 还是 snsapi_userinfo：按业务场景选型

微信网页授权有两种scope，选型直接影响用户体验和数据维度。snsapi_base是静默授权，用户无感，微信直接带着code跳回，后端拿这个code只能换到openId，拿不到昵称头像。大多数登录注册场景这个就够了，因为openId就是用户在你们业务体系里的唯一标识。

snsapi_userinfo授权时会弹窗，用户必须点「允许」才能继续。code换到access_token后，多了调用sns/userinfo接口的能力，可以拉取微信头像、昵称、性别和地区。需要默认头像和昵称的注册页，才值得付出多一次弹窗的代价。

表：两种scope的差异对比

一个容易被忽略的细节：snsapi_userinfo模式下拿到的access_token有效期是2小时，而openId是永久的。头像昵称只在注册那一刻需要，拿到后应存入自己的用户表，后续登录直接用openId匹配，不需要再走一遍userinfo流程。如果项目将来要嵌入企业微信h5做免登，那还需要同时采集unionId，因为企业微信环境里的用户标识体系和公众号是两套，openId不通用。

3. utils.js封装：uniapp侧微信授权工具的三个函数

微信侧配好之后，开始写前端。整套授权在uniapp里就是一个工具文件的几个函数，对应项目里的utils/utils.js。我把它拆成三步：拼链接、取参数、换openId。三个函数独立暴露，任何页面要用，直接引入即可。

3.1 授权URL拼接：getWxAuthorizeUrl的实现与参数说明

第一步生成授权链接。这个URL指向open.weixin.qq.com的OAuth2.0授权端点，参数必须按微信文档的键名拼，一个都不能少。

// utils/utils.js const WX_CONFIG = { appId: 'wx1234567890abcdef', redirectUri: 'https://yourdomain.com/h5', scope: 'snsapi_base' } // 生成每次唯一的state，防CSRF function makeState() { return 'h5_' + Date.now() + '_' + Math.random().toString(36).slice(2, 8) } // 第一步：拼接微信授权URL export function getWxAuthorizeUrl() { const state = makeState() // state先存起来，回调时比对，防止第三方伪造授权请求 uni.setStorageSync('oauth_state', state) return 'https://open.weixin.qq.com/connect/oauth2/authorize' + '?appid=' + WX_CONFIG.appId + '&redirect_uri=' + encodeURIComponent(WX_CONFIG.redirectUri) + '&response_type=code' + '&scope=' + WX_CONFIG.scope + '&state=' + state + '#wechat_redirect' }

这里三个细节别动错。第一，redirect_uri必须用encodeURIComponent编码，不编码时微信解析链接会把后续参数截断，报redirect_uri参数错误。第二，#wechat_redirect是微信H5授权链接的固定后缀，没有它微信不跳转。第三，state每次生成随机值并写入本地缓存，回调时比对URL里的state是否一致，这是防止CSRF的标准做法，很多项目的遗漏点就在这里。

表：OAuth2.0授权链接核心参数

3.2 取code与换openId：调用链路的完整拼装

用户在微信里打开授权链接后，会跳转到redirect_uri并携带code和state。第二步是从当前页面URL里把这两个参数解析出来，然后把code发给后端。

因为uniapp H5默认是hash路由，授权完成后的完整URL是https://yourdomain.com/h5/?code=xxx&state=xxx#/。微信追加的参数落在#之前，路由hash在#之后，所以解析window.location.search就能拿到。下面的函数没有直接用URLSearchParams，原因是部分低版本安卓内置浏览器的WebView支持不完整，手动拆分query字符串兼容性最稳。

// 第二步：从当前URL解析code与state export function getWxAuthParams() { const query = window.location.search.substring(1) const params = {} query.split('&').forEach(item => { const [key, value] = item.split('=') if (key) params[key] = decodeURIComponent(value || '') }) return params // { code: 'xxx', state: 'xxx' } } // 第三步：用code向后端换取openId export function requestOpenId(code) { return new Promise((resolve, reject) => { uni.request({ url: 'https://yourdomain.com/api/wx/openid', method: 'POST', data: { code }, success: (res) => { if (res.data.code === 0) { resolve(res.data.data) // { openId, unionId? } } else { reject(new Error(res.data.msg)) } }, fail: (err) => reject(err) }) }) }

requestOpenId请求的是自家后端接口，不是直接请求微信，因为AppSecret不能暴露在前端，前端直连微信接口还有跨域限制。后端接口返回统一结构{code: 0, data: {openId}}，前端只关心code是否为0。

还要注意，code是一次性的，有效期约5分钟，长度约128字节，微信文档没有固定长度。前端不要在业务代码里对code做长度硬编码，后端收到40029 invalid code时应当作不可重试错误处理，而不是直接发起重试。

3.3 页面级调用：pages/clue中的授权逻辑

项目里pages/clue页面是实际使用这套工具的地方。典型场景是公众号菜单跳转进来，先判断URL里有没有code，有就直接换openId，没有就跳授权。

// pages/clue/index.vue import { getWxAuthorizeUrl, getWxAuthParams, requestOpenId } from '@/utils/utils.js' export default { onLoad() { const params = getWxAuthParams() if (params.code) { const localState = uni.getStorageSync('oauth_state') if (localState && params.state !== localState) { console.error('state校验失败，疑似CSRF攻击') return } this.handleLogin(params.code) } else { // 没有code，说明第一次进，跳授权 window.location.href = getWxAuthorizeUrl() } }, methods: { async handleLogin(code) { try { const data = await requestOpenId(code) // data.openId 是当前微信用户在业务体系里的身份标识 uni.setStorageSync('openId', data.openId) } catch (err) { console.error('openId获取失败', err) } } } }

state校验有个边界情况要处理好：用户手动清空微信缓存后，微信侧的静默授权关系还在，但本地oauth_state已经没了。此时本地没有oauth_state就别阻断流程，跳过一次校验只记录warning，保证老用户不被卡在登录页。模板里用if (localState && ...)而不是直接比，就是这个原因。

还要区分一个概念：uni.login()返回的是小程序端的code，只能在微信小程序环境里换openId。H5页面内调用uni.login不会走网页授权链路，拿到的code对公众号H5完全无效。从App或小程序项目转过来做H5的团队最容易在这里绕弯，H5端只认从URL里解析出来的这个code。

4. 注册与登录：openId打通用户体系的完整实现

openId拿到后，进入核心业务环节：怎么把它映射成用户登录态。常规做法是后端用openId反查用户绑定表，查不到就新建用户，查到就复用老用户，然后签发一个自定义token返回，前端后续请求带着token走。

4.1 后端接口设计：code换openId再换token

前端把code发给后端后，后端要做的事是拿code去请求微信的sns/oauth2/access_token接口，拿到openid。这个请求只能由后端发起，因为需要AppSecret。下面以Node.js/Express为例：

// routes/wx.js const express = require('express') const axios = require('axios') const router = express.Router() // POST /api/wx/openid —— 用code换openId router.post('/wx/openid', async (req, res) => { const { code } = req.body const wxUrl = 'https://api.weixin.qq.com/sns/oauth2/access_token' + '?appid=' + process.env.WX_APPID + '&secret=' + process.env.WX_SECRET + '&code=' + code + '&grant_type=authorization_code' const { data } = await axios.get(wxUrl) if (data.errcode) { return res.json({ code: 1, msg: data.errmsg }) } // openid是最核心的返回，unionid需公众号绑定开放平台才有 return res.json({ code: 0, data: { openId: data.openid, unionId: data.unionid || '', accessToken: data.access_token, expiresIn: data.expires_in } }) })

响应里把access_token和expires_in透传给前端，是为了在需要调snsapi_userinfo拿头像昵称时，可以由前端或后端缓存后继续使用。注意data.unionid只有公众号绑定微信开放平台后才返回，没绑定就是空字符串。openId一次获取后永久有效，access_token有效期2小时，refresh_token有效期30天，设计缓存时要把这些有效期差异考虑清楚。

表：微信access_token接口返回字段

4.2 首次授权是注册、再次授权是登录

拿到openId后，后端业务逻辑就简单了：查user_oauth_bind表。没有记录说明首次授权，此时插入一条用户记录和一条绑定记录；有记录说明是老用户，直接走登录更新逻辑。代码示意如下：

// routes/auth.js —— 注册/登录合一 router.post('/auth/login', async (req, res) => { const { openId, unionId } = req.body if (!openId) return res.json({ code: 1, msg: '缺少openId' }) let bind = await db.query('SELECT * FROM user_oauth_bind WHERE open_id = ?', [openId]) let userId let isNewUser = false if (!bind) { // 首次授权：同时创建users记录和绑定记录 const userResult = await db.query( 'INSERT INTO users (nickname, avatar, status) VALUES (?, ?, 1)', ['微信用户', ''] ) userId = userResult.insertId await db.query( 'INSERT INTO user_oauth_bind (user_id, open_id, union_id, channel) VALUES (?, ?, ?, ?)', [userId, openId, unionId || '', 'wechat_h5'] ) isNewUser = true } else { userId = bind.user_id // 老用户，更新最后登录时间 await db.query('UPDATE users SET last_login_at = NOW() WHERE id = ?', [userId]) } // 签发自定义token，后续请求带token即可 const token = jwt.sign({ userId }, process.env.JWT_SECRET, { expiresIn: '7d' }) return res.json({ code: 0, data: { token, userId, isNewUser } }) })

这段逻辑用user_oauth_bind中间表而不直接把openId当用户主键，是为了以后多端接入做准备。如果以后接入小程序、或公司再开一个公众号，同一个真实用户会有多个不同openId，但通过user_id关联回同一条users记录，用户数据不会裂成几个账号。channel字段记录来源渠道，运营要分析公众号H5和App转化率时，这个字段是唯一口径。

isNewUser返回给前端后，由前端决定注册流程是否继续。比如业务要求注册必须绑定手机号，前端看到isNewUser === true就跳手机号绑定页；业务不强制就先进首页，用户后续需要手机号时再触发绑定。

4.3 前端登录状态管理：从授权到进入业务页面

前端把两个接口串起来，一条调用链完成注册或登录。核心代码在pages/clue里扩展：

// pages/clue/index.vue 完整登录方法 async handleLogin(code) { try { // 1. code换openId const { openId, unionId } = await requestOpenId(code) // 2. openId换token const loginRes = await new Promise((resolve, reject) => { uni.request({ url: 'https://yourdomain.com/api/auth/login', method: 'POST', data: { openId, unionId }, success: resolve, fail: reject }) }) if (loginRes.data.code === 0) { const { token, userId, isNewUser } = loginRes.data.data uni.setStorageSync('token', token) uni.setStorageSync('userId', userId) uni.setStorageSync('openId', openId) // 3. 按新老用户分流 if (isNewUser) { uni.showToast({ title: '注册成功', icon: 'none' }) } uni.reLaunch({ url: '/pages/index' }) } } catch (err) { console.error('登录链路失败', err) } }

所有关键登录态都通过uni.setStorageSync写入本地。后续发起业务请求时，在uni.request拦截器里统一带token请求头，后端按token解析用户身份，不需要前端每次手动传openId。注意，openId在本地存储只是方便调试和展示，不能作为后端鉴权凭证，服务端只认token。

这里解释一下为什么用setStorageSync而不是setStorage。同步方法调用后立刻能读到值，异步方法存在时序问题，登录成功后马上要跳页，用同步方法可以避免「跳转完成但token还没写完」的竞态。本地存储容量上限10MB，token和openId加起来几十字节，不存在容量问题。

5. 高频授权问题的排查现场：redirect_uri、code复用与授权恢复

最后把实际项目里最容易碰到的三个问题列一下，每一个都有明确的排查手段和修复方案。

5.1 redirect_uri参数错误：域名与编码的双重检查

这个报错出现频率最高。排查按两条线走：先打开公众号后台「网页授权域名」，把它和代码里redirect_uri的域名做对比，必须是同一个主域名，比如后台配了yourdomain.com，redirect_uri就不能是www.otherdomain.com；再检查授权链接里redirect_uri有没有经过encodeURIComponent。微信对参数拼接很严格，redirect_uri里只要有一个&或?没编码，微信解析时就会截断后续参数。实际项目里这两种情况同时存在的也不少，先域名后编码，一步步排除。排查时可以把完整授权链接贴到浏览器地址栏，用Network面板看最终跳转URL的结构，一眼就能看出微信把redirect_uri解析成了什么。

5.2 code已被使用：一次性凭证的幂等处理

微信的code只能用一次，有效期5分钟。前端如果因网络抖动导致请求超时后点了一次重试，同一个code被提交两次，后端第二次请求微信接口时会收到40029 invalid code。修复分前后端两层：前端在会话里记录已处理过的code，重复点击直接忽略；后端也记录最近处理过的code，命中缓存时直接返回第一次结果，不再请求微信。两层各加一个防重判断，这个错误基本能压到零。

还要注意，微信授权链接每访问一次就生成一个新code，旧code立即失效。页面里不要用浏览器前进后退去还原授权页，很容易拿到过期code，正确做法是重新走一次授权链接获取新code。

5.3 用户拒绝授权后的交互恢复

只有snsapi_userinfo会触发拒绝授权。用户拒绝后，微信会跳回redirect_uri，但URL里没有code，而是带一个error参数。前端判断逻辑要覆盖这层分支，不能只写「有code走登录，没code跳授权」，否则用户拒绝后会被反复弹授权框，体验很差。

推荐交互是：检测到URL里有error或code为空时，显示一行说明文案，再放一个自定义按钮，用户点击时重新调用getWxAuthorizeUrl()跳授权。要注意微信对重复授权请求有频率限制，连续多次拒绝后再点授权可能不再弹窗而是直接返回错误，此时提示用户「请过几分钟再试」，不要无脑跳转。

最后补一个容易被忽略的边界：整个授权流程依赖微信内置浏览器。如果用户用系统浏览器打开H5，微信会跳到提示页显示「请在微信客户端打开链接」。遇到这种反馈，先引导用户从公众号菜单入口进入，普通浏览器地址栏访问在微信授权体系里走不通，这是微信H5授权与App内WebView授权最大的行为差异，排查问题时优先确认这一点。

本文还有配套的精品资源，点击获取