Vue3+TypeScript实现Web端微信扫码登录：纯前端内嵌方案全解析

1. 项目概述：为什么要在Web端内嵌微信登录二维码？

最近在重构一个内部使用的CMS后台，用户反馈最多的就是登录流程太麻烦，每次都要记密码、输验证码。正好产品经理提了个需求，想接入微信扫码登录，让用户“扫一扫”就能进系统。这个需求很常见，但真动手做的时候，我发现网上很多教程要么是后端视角，要么是Vue2的，用Vue3 + TypeScript纯前端实现的完整方案并不多，而且细节坑不少。

所以，我决定把这次从零到一实现“Web端内嵌微信登录二维码”的全过程记录下来。核心目标很明确：在不依赖任何后端页面跳转或iframe嵌套的前提下，完全由前端（Vue3 + TypeScript）控制，在网站自己的登录页面上，渲染出微信官方的登录二维码，并处理整个扫码、授权、登录的状态流转。这不仅仅是调个API那么简单，它涉及到OAuth2.0授权码模式的理解、微信开放平台配置、前端状态机设计、以及如何优雅地处理各种边界情况。如果你也在为类似的需求头疼，或者想深入理解第三方登录在前端的完整闭环，这篇踩坑实录应该能帮到你。

2. 核心思路与方案选型：为什么是“纯前端”方案？

2.1 传统方案 vs 纯前端方案

在开始敲代码之前，我们先理清两种主流实现方式的区别，这决定了我们整个项目的架构。

传统后端跳转方案：这是最常见、文档也最多的方式。流程是：用户点击“微信登录” -> 前端跳转到一个后端路由（例如/auth/wechat） -> 后端向微信接口请求授权URL -> 后端302重定向到微信的授权页 -> 用户在微信页扫码授权 -> 微信回调到你的后端接口 -> 后端处理回调，建立会话，最后再重定向回前端页面。

这个方案的缺点是体验割裂。用户会被带离你的网站，跳到微信的域名下，授权完成后再跳回来。对于追求沉浸式体验的Web应用来说，这种跳转很打断用户操作。

纯前端内嵌方案：这正是我们要做的。核心思想是：由前端直接向微信接口发起请求，获取二维码所需的参数，并在当前页面（通常是一个弹窗或固定区域）渲染出二维码。用户扫码、确认授权的所有交互都在微信客户端内完成，授权成功后，微信会将授权码（code）回调到你预先配置的后端地址，而前端则通过轮询或WebSocket等方式，从自己的后端获取最终的登录态。

它的优势非常明显：

1. 用户体验无缝：登录流程完全在你的网站页面内完成，没有突兀的页面跳转。
2. 前端掌控力强：二维码的生成、展示、状态（等待扫码、已扫码、授权成功）提示都可以由前端精细控制，UI交互更灵活。
3. 符合现代SPA架构：状态变更通过API交互，更适合Vue/React这类前端框架。

2.2 技术栈选择：Vue3 + TypeScript的必然性

为什么是Vue3和TypeScript？这不仅仅是追新。

• Vue3的Composition API：对于登录这种带有复杂状态逻辑（等待、扫码、成功、失败）的组件，使用setup和ref、reactive、computed、watch来组织代码，比Vue2的Options API逻辑更清晰，尤其是需要封装自定义Hook（如useWechatLogin）时，代码复用和抽离非常方便。
• TypeScript的核心价值：第三方登录涉及大量的接口数据交互。微信返回的数据结构、前端传给后端的参数、后端返回的登录结果，如果没有类型约束，调试起来就是噩梦。TS能在编码阶段就帮你发现字段名拼写错误、类型不匹配等问题。例如，定义微信二维码接口的响应类型：

  interface WechatQRCodeResponse { errcode?: number; // 错误代码，0表示成功 errmsg?: string; // 错误信息 ticket: string; // 获取的二维码ticket，用于换取二维码图片 expire_seconds: number; // 二维码有效时间，单位秒 url: string; // 二维码图片解析后的地址，可用于生成二维码 }

  有了这个接口定义，你在调用接口后使用data.ticket时，编辑器会有智能提示，并且确保你不会误用data.ticket_id这种不存在的字段。

2.3 整体流程设计

整个流程可以拆解为以下几个关键阶段，理解这个时序图对后续编码至关重要：

1. 初始化阶段：前端加载登录页，用户点击“微信登录”按钮。
2. 获取二维码：前端调用自己的后端API（出于安全考虑，AppSecret绝不能暴露在前端）。该API向微信开放平台接口（https://api.weixin.qq.com/cgi-bin/qrcode/create）请求，生成一个临时的场景值（scene_id）和对应的二维码ticket。后端将ticket和场景值返回给前端。
3. 渲染与轮询：前端使用返回的ticket，拼接出二维码图片URL（https://mp.weixin.qq.com/cgi-bin/showqrcode?ticket=TICKET）并渲染到页面上。同时，前端开始以固定间隔（如2秒）轮询自己的后端，询问该场景值对应的登录状态（“是否已扫码并授权？”）。
4. 用户扫码授权：用户用微信扫描网页上的二维码。微信客户端会提示用户确认登录信息和授权范围。
5. 微信回调：用户确认后，微信服务器会携带授权码（code）和场景值（scene_id）回调到你预先在微信开放平台配置的“授权回调域名”下的后端API地址。注意，这一步是微信服务器对你后端服务器的直接调用，前端不参与。
6. 后端处理回调：你的后端接收到code和scene_id。用code、AppID、AppSecret去微信接口换取用户的唯一标识（openid）和访问令牌（access_token）。然后，后端需要将“该scene_id对应的用户已授权成功”这一状态更新到数据库或缓存（如Redis）中，并通常关联生成自己系统的用户令牌（如JWT）。
7. 前端获知成功：前端轮询的请求，在某一次会从后端得到“成功”的响应，并携带系统自身的登录令牌（如JWT）。
8. 前端完成登录：前端拿到令牌，存储到本地（如localStorage或Cookie），更新全局用户状态（Vuex/Pinia），并跳转到登录后页面或关闭登录弹窗。

关键安全提示：为什么不能从前端直接调微信API？因为获取二维码的接口需要access_token，而获取access_token需要AppSecret。这个密钥一旦泄露，攻击者就能以你的应用身份为所欲为。所以，所有涉及AppSecret的请求都必须由受信任的后端完成。

3. 前期准备：配置与基础搭建

3.1 微信开放平台配置（关键一步）

这是所有工作的基石，配置错了，后面代码写得再好也白搭。

1. 注册与创建网站应用：访问微信开放平台，注册开发者账号（如果已有则跳过）。在“网站应用”板块，创建一个新的应用。你需要准备一个ICP备案过的域名。
2. 获取关键凭证：创建成功后，你会得到AppID和AppSecret。把它们妥善保存，AppSecret尤其要保密，只能用于服务器端。
3. 配置授权回调域名：这是最容易出错的一步。在应用详情页找到“授权回调域”的配置项。这里填写的必须是你后端处理微信回调的API所在的域名，且不带http://或https://，也不带路径。
   • 正确示例：api.yourdomain.com
   • 错误示例：https://api.yourdomain.com(带协议),api.yourdomain.com/auth/callback(带路径),yourdomain.com(与前端域名混淆)。
   • 为什么：当用户扫码授权后，微信服务器会向这个域名下的一个固定路径（由你后端API的URL决定）发起GET请求。如果域名不匹配，回调会失败。
4. 确认网站应用域名：同时，你还需要在“网站应用”的“开发信息”里，设置“网站应用域名”。这里填写你前端页面所在的域名。例如www.yourdomain.com。这个配置会影响二维码生成时的一些安全策略。

3.2 前端项目初始化

我们使用Vite来快速搭建一个Vue3 + TypeScript项目，这是目前最主流和高效的选择。

# 使用 npm 7+, 需要额外的双横线 npm create vue@latest my-wechat-login-demo -- --typescript # 或使用 yarn yarn create vue my-wechat-login-demo --typescript

按照提示，选择需要的特性。为了项目简洁，除了TypeScript和Vue Router，其他如Pinia、ESLint等可按需选择。进入项目并安装基础依赖和我们将用到的UI库（这里以Element Plus为例）及HTTP客户端（Axios）。

cd my-wechat-login-demo npm install npm install axios element-plus # 安装Element Plus图标库（可选，用于美化按钮） npm install @element-plus/icons-vue

在main.ts中引入Element Plus和样式：

import { createApp } from 'vue' import App from './App.vue' import router from './router' import ElementPlus from 'element-plus' import 'element-plus/dist/index.css' const app = createApp(App) app.use(router) app.use(ElementPlus) app.mount('#app')

3.3 封装基础HTTP请求模块

一个健壮的HTTP模块是前后端交互的保障。我们使用Axios，并为其添加TypeScript类型和统一的错误处理。

创建src/utils/request.ts：

import axios, { type AxiosInstance, type AxiosRequestConfig, type AxiosResponse } from 'axios' // 定义后端返回数据的通用结构 export interface ApiResponse<T = any> { code: number message: string data: T } // 创建axios实例 const service: AxiosInstance = axios.create({ baseURL: import.meta.env.VITE_API_BASE_URL || '/api', // 从环境变量读取 timeout: 10000, // 10秒超时 }) // 请求拦截器 service.interceptors.request.use( (config) => { // 这里可以统一添加token等 // const token = localStorage.getItem('token') // if (token) { // config.headers.Authorization = `Bearer ${token}` // } return config }, (error) => { return Promise.reject(error) } ) // 响应拦截器 service.interceptors.response.use( (response: AxiosResponse<ApiResponse>) => { const res = response.data // 根据你的后端约定处理业务代码，例如 code 0 表示成功 if (res.code === 0) { return res.data // 直接返回后端定义的data数据 } else { // 业务错误，例如二维码过期、场景值无效等 console.error('业务错误:', res.message) return Promise.reject(new Error(res.message || 'Error')) } }, (error) => { // HTTP状态码错误或网络错误 console.error('请求错误:', error) return Promise.reject(error) } ) export default service

在项目根目录创建.env.development文件，配置开发环境的后端API地址：

VITE_API_BASE_URL=http://localhost:3000/api

4. 核心实现：登录组件与状态管理

4.1 构建登录弹窗组件

我们将创建一个独立的Vue组件WechatLoginModal.vue来管理整个登录流程。这个组件会处理二维码的获取、展示、状态轮询和用户交互。

首先，定义组件的核心状态和类型：

// src/types/wechat-login.ts export interface QRCodeInfo { ticket: string expireSeconds: number qrCodeUrl: string // 完整的二维码图片地址 sceneId: string // 场景值，用于轮询状态 } export type LoginStatus = 'init' | 'loading' | 'qrcode-generated' | 'waiting-scan' | 'scanned' | 'authorized' | 'error'

然后，开始编写组件：

<!-- src/components/WechatLoginModal.vue --> <template> <div class="wechat-login-modal"> <!-- 模态框头部 --> <div class="modal-header"> <h3>微信扫码登录</h3> <el-icon @click="handleClose"><Close /></el-icon> </div> <!-- 模态框内容区，根据状态动态显示 --> <div class="modal-body"> <!-- 初始/加载状态 --> <div v-if="status === 'init' || status === 'loading'" class="status-container"> <el-icon class="loading-icon" v-if="status === 'loading'"><Loading /></el-icon> <p>{{ status === 'loading' ? '正在获取二维码...' : '准备扫码登录' }}</p> </div> <!-- 二维码展示与轮询状态 --> <div v-else-if="status === 'qrcode-generated' || status === 'waiting-scan' || status === 'scanned'" class="qrcode-container"> <img :src="qrCodeInfo?.qrCodeUrl" alt="微信登录二维码" class="qrcode-img" /> <div class="status-hint"> <p v-if="status === 'qrcode-generated'">二维码已生成</p> <p v-else-if="status === 'waiting-scan'"> <el-icon><Search /></el-icon> 请使用微信扫描二维码 </p> <p v-else-if="status === 'scanned'"> <el-icon><Check /></el-icon> 扫码成功，请在手机上确认登录 </p> </div> <p class="expire-hint" v-if="qrCodeInfo"> 二维码有效期剩余：{{ Math.floor(expireCountdown / 60) }}分{{ expireCountdown % 60 }}秒 </p> <el-button type="primary" :loading="refreshing" @click="refreshQRCode" size="small">刷新二维码</el-button> </div> <!-- 授权成功 --> <div v-else-if="status === 'authorized'" class="success-container"> <el-icon class="success-icon"><CircleCheck /></el-icon> <p>登录成功！正在跳转...</p> </div> <!-- 错误状态 --> <div v-else-if="status === 'error'" class="error-container"> <el-icon class="error-icon"><CircleClose /></el-icon> <p>{{ errorMessage || '登录失败，请重试' }}</p> <el-button @click="initQRCode">重试</el-button> </div> </div> </div> </template> <script setup lang="ts"> import { ref, computed, onMounted, onUnmounted } from 'vue' import { Close, Loading, Search, Check, CircleCheck, CircleClose } from '@element-plus/icons-vue' import type { QRCodeInfo, LoginStatus } from '@/types/wechat-login' import { fetchQRCode, pollLoginStatus } from '@/api/login' // API函数稍后定义 const props = defineProps<{ visible: boolean }>() const emit = defineEmits<{ (e: 'update:visible', value: boolean): void (e: 'login-success', token: string): void }>() // --- 核心状态定义 --- const status = ref<LoginStatus>('init') const qrCodeInfo = ref<QRCodeInfo | null>(null) const errorMessage = ref('') const expireCountdown = ref(0) const pollTimer = ref<number | null>(null) const refreshing = ref(false) // --- 核心方法 --- // 初始化/获取二维码 const initQRCode = async () => { status.value = 'loading' errorMessage.value = '' try { const data = await fetchQRCode() qrCodeInfo.value = data status.value = 'qrcode-generated' expireCountdown.value = data.expireSeconds startCountdown() startPolling(data.sceneId) // 开始轮询这个场景值的状态 } catch (err: any) { status.value = 'error' errorMessage.value = err.message || '获取二维码失败' console.error('初始化二维码失败:', err) } } // 开始二维码有效期倒计时 const startCountdown = () => { const countdownInterval = setInterval(() => { if (expireCountdown.value > 0) { expireCountdown.value-- } else { clearInterval(countdownInterval) // 二维码过期，可以更新状态提示 if (status.value === 'qrcode-generated' || status.value === 'waiting-scan') { status.value = 'error' errorMessage.value = '二维码已过期，请刷新' } } }, 1000) } // 开始轮询登录状态 const startPolling = (sceneId: string) => { if (pollTimer.value) { clearInterval(pollTimer.value) } pollTimer.value = window.setInterval(async () => { // 如果状态已经是成功、失败或已授权，则停止轮询 if (['authorized', 'error'].includes(status.value)) { stopPolling() return } try { const pollResult = await pollLoginStatus(sceneId) // 根据后端返回的状态更新前端UI switch (pollResult.status) { case 'waiting': status.value = 'waiting-scan' break case 'scanned': status.value = 'scanned' break case 'authorized': status.value = 'authorized' stopPolling() // 假设后端返回了token emit('login-success', pollResult.token!) // 可以延迟关闭弹窗或跳转 setTimeout(() => handleClose(), 1500) break case 'expired': status.value = 'error' errorMessage.value = '二维码已过期' stopPolling() break } } catch (err) { // 轮询请求失败，可能是网络问题，不立即置为错误，继续轮询 console.warn('轮询请求失败:', err) } }, 2000) // 每2秒轮询一次 } // 停止轮询 const stopPolling = () => { if (pollTimer.value) { clearInterval(pollTimer.value) pollTimer.value = null } } // 刷新二维码 const refreshQRCode = async () => { refreshing.value = true stopPolling() // 刷新前停止旧的轮询 await initQRCode() refreshing.value = false } // 关闭弹窗 const handleClose = () => { stopPolling() emit('update:visible', false) // 重置状态，为下次打开准备 status.value = 'init' qrCodeInfo.value = null } // --- 生命周期 --- onMounted(() => { if (props.visible) { initQRCode() } }) onUnmounted(() => { stopPolling() // 组件卸载时务必清理定时器 }) // 监听visible prop变化，外部控制显示时初始化 watch(() => props.visible, (newVal) => { if (newVal) { initQRCode() } else { stopPolling() } }) </script> <style scoped> .wechat-login-modal { width: 320px; background: white; border-radius: 8px; box-shadow: 0 4px 20px rgba(0, 0, 0, 0.15); overflow: hidden; } .modal-header { display: flex; justify-content: space-between; align-items: center; padding: 16px 20px; border-bottom: 1px solid #eee; } .modal-header h3 { margin: 0; font-size: 18px; } .modal-header .el-icon { cursor: pointer; color: #999; } .modal-body { padding: 30px 20px; text-align: center; } .qrcode-img { width: 200px; height: 200px; display: block; margin: 0 auto 15px; border: 1px solid #eee; } .status-hint { margin: 15px 0; color: #666; } .expire-hint { font-size: 12px; color: #f56c6c; margin: 10px 0; } .loading-icon, .success-icon, .error-icon { font-size: 48px; margin-bottom: 15px; } .loading-icon { animation: rotating 2s linear infinite; } .success-icon { color: #67c23a; } .error-icon { color: #f56c6c; } @keyframes rotating { from { transform: rotate(0deg); } to { transform: rotate(360deg); } } </style>

4.2 封装API请求模块

组件中调用的fetchQRCode和pollLoginStatus需要对应的API函数。我们在src/api/login.ts中定义：

import request from '@/utils/request' import type { QRCodeInfo } from '@/types/wechat-login' // 获取微信登录二维码 export const fetchQRCode = (): Promise<QRCodeInfo> => { return request({ url: '/auth/wechat/qrcode', method: 'POST', // 可以根据需要传递参数，例如前端希望定义的场景值标识 data: { platform: 'web_admin' // 示例：标识是哪个平台在请求 } }) } // 轮询登录状态 export interface PollStatusResult { status: 'waiting' | 'scanned' | 'authorized' | 'expired' | 'error' token?: string // 授权成功时返回的系统令牌 userInfo?: any // 可选，用户信息 } export const pollLoginStatus = (sceneId: string): Promise<PollStatusResult> => { return request({ url: `/auth/wechat/poll/${sceneId}`, method: 'GET' }) }

4.3 在登录页中使用组件

最后，在登录页面中引入并使用这个弹窗组件。

<!-- src/views/LoginView.vue --> <template> <div class="login-container"> <!-- 你的其他登录表单... --> <el-form> <!-- 用户名密码登录 --> </el-form> <div class="divider">或</div> <!-- 微信登录按钮 --> <el-button type="primary" @click="showWechatLogin = true" :icon="Iphone"> 微信扫码登录 </el-button> <!-- 微信登录弹窗 --> <WechatLoginModal v-model:visible="showWechatLogin" @login-success="handleLoginSuccess" /> </div> </template> <script setup lang="ts"> import { ref } from 'vue' import { useRouter } from 'vue-router' import { Iphone } from '@element-plus/icons-vue' import WechatLoginModal from '@/components/WechatLoginModal.vue' const router = useRouter() const showWechatLogin = ref(false) const handleLoginSuccess = (token: string) => { // 1. 存储token localStorage.setItem('access_token', token) // 2. 更新全局状态（如果用了Pinia） // userStore.setToken(token) // 3. 跳转到首页或目标页 router.push('/dashboard') // 4. 可以显示一个登录成功的提示 ElMessage.success('登录成功') } </script>

5. 后端协作要点与接口设计

前端做得再漂亮，没有后端的正确配合也是徒劳。这里简要说明后端需要提供的两个核心接口，以及关键的安全逻辑。

5.1 生成二维码接口 (POST /api/auth/wechat/qrcode)

后端逻辑：

1. 接收前端请求（可附带一个自定义业务标识）。
2. 生成一个唯一的、临时的场景值（scene_id），例如使用UUID。这个scene_id将作为本次登录尝试的唯一标识。
3. 调用微信开放平台接口https://api.weixin.qq.com/cgi-bin/qrcode/create，参数中需要带上access_token（后端需自己维护获取和刷新）和场景值信息。微信会返回一个ticket和过期时间。
4. 将scene_id和ticket的对应关系，以及状态（初始化为waiting）存储到缓存（如Redis），并设置一个略短于二维码过期时间的TTL（例如590秒）。
5. 将ticket、scene_id、expire_seconds以及拼接好的二维码图片URL返回给前端。

接口响应示例：

{ "code": 0, "message": "success", "data": { "ticket": "gQH47joAAAAAAAAAASxodHRwOi8vd2VpeGluLnFxLmNvbS9xLzA...", "expireSeconds": 600, "qrCodeUrl": "https://mp.weixin.qq.com/cgi-bin/showqrcode?ticket=gQH47jo...", "sceneId": "550e8400-e29b-41d4-a716-446655440000" } }

5.2 微信授权回调接口 (GET /api/auth/wechat/callback)

这个接口的URL需要精确配置到微信开放平台的“授权回调域名”下。例如：https://api.yourdomain.com/api/auth/wechat/callback。

后端逻辑：

1. 微信服务器会携带code和state（如果生成二维码时传递了state参数）GET请求这个地址。
2. 后端解析出code。
3. 用code、AppID、AppSecret调用微信接口https://api.weixin.qq.com/sns/oauth2/access_token，换取openid和access_token。
4. （可选）用access_token和openid调用微信用户信息接口，获取用户昵称、头像等。
5. 关键一步：根据回调中可能携带的state参数（或在生成二维码时，将scene_id作为state传过去），找到缓存中对应的scene_id记录。
6. 将这条记录的状态更新为authorized，并关联上获取到的openid和用户信息。同时，生成自己系统的登录令牌（如JWT）。
7. 将令牌也存入缓存，与scene_id关联。
8. 按照微信要求，返回一个文本或JSON响应（如"success"或{"status":"ok"}），告知微信回调处理成功。注意：这个接口的响应是给微信服务器看的，不是给前端。

5.3 轮询状态接口 (GET /api/auth/wechat/poll/:sceneId)

后端逻辑：

1. 接收前端传来的scene_id。
2. 从缓存中查询该scene_id对应的记录。
3. 根据记录状态返回给前端：
   • waiting: 等待扫码。
   • scanned: 已扫码，等待用户确认（这个状态需要后端在收到微信的“用户扫码”事件推送时更新，如果没做事件推送，可以省略此状态）。
   • authorized: 已授权。此时将关联的系统令牌一并返回。
   • expired: 二维码过期或记录不存在。
   • error: 其他错误。
4. 一旦状态变为authorized或expired，后端可以考虑清理或短期保留该缓存记录。

接口响应示例：

{ "code": 0, "message": "success", "data": { "status": "authorized", "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "userInfo": { "nickname": "张三" } } }

6. 深度优化与高级特性实现

基础功能跑通后，我们可以从用户体验、稳定性和可维护性角度进行深度优化。

6.1 使用WebSocket替代轮询

轮询（Polling）简单但不够高效，且可能给服务器带来不必要的压力。对于实时性要求高的登录状态同步，WebSocket是更优选择。

前端改造：

1. 在WechatLoginModal组件中，建立WebSocket连接。
2. 在获取到scene_id后，通过WebSocket发送一个订阅消息，告知服务器“我开始监听这个scene_id的状态变化”。
3. 服务器在微信回调处理成功后，主动通过WebSocket向订阅了该scene_id的前端连接推送状态更新消息。
4. 前端收到消息后，更新UI状态并关闭连接。

优势：

• 实时性：状态变更毫秒级触达前端。
• 低开销：避免了大量无用的HTTP轮询请求。
• 体验好：状态切换更流畅。

实现要点：

• 需要处理WebSocket连接的重连、心跳、异常断开。
• 后端需要维护scene_id与WebSocket连接ID的映射关系。

6.2 二维码过期与自动刷新

微信二维码默认有效期为5分钟。我们需要在前端优雅地处理过期。

方案一：被动检测（推荐）如我们之前所做，在获取二维码时启动一个倒计时。倒计时结束，将状态置为“过期”，并提示用户刷新。同时，轮询或WebSocket连接也会收到后端返回的expired状态。

方案二：主动刷新在倒计时结束前（例如剩余30秒时），如果状态仍是waiting-scan，可以自动调用refreshQRCode方法，生成一个新的二维码并替换旧的。这需要修改startCountdown函数：

const startCountdown = () => { const countdownInterval = setInterval(() => { if (expireCountdown.value > 0) { expireCountdown.value-- // 剩余30秒且仍在等待扫码，自动刷新 if (expireCountdown.value === 30 && (status.value === 'waiting-scan' || status.value === 'qrcode-generated')) { ElMessage.info('二维码即将过期，自动刷新中...') refreshQRCode() clearInterval(countdownInterval) // 清除旧计时器 } } else { clearInterval(countdownInterval) if (status.value === 'waiting-scan' || status.value === 'qrcode-generated') { status.value = 'error' errorMessage.value = '二维码已过期，请刷新' } } }, 1000) }

6.3 状态管理的精细化与Hook封装

随着逻辑复杂，可以将所有微信登录相关的状态和方法封装成一个Composition API Hook，提高复用性。

创建src/composables/useWechatLogin.ts：

import { ref, computed, onUnmounted } from 'vue' import type { QRCodeInfo, LoginStatus } from '@/types/wechat-login' import { fetchQRCode, pollLoginStatus, type PollStatusResult } from '@/api/login' export default function useWechatLogin() { const status = ref<LoginStatus>('init') const qrCodeInfo = ref<QRCodeInfo | null>(null) const errorMessage = ref('') const expireCountdown = ref(0) const pollTimer = ref<number | null>(null) const isWaiting = computed(() => ['qrcode-generated', 'waiting-scan', 'scanned'].includes(status.value)) const isLoading = computed(() => status.value === 'loading') // ... 将所有之前组件中的方法移到这里，如 initQRCode, startPolling, stopPolling, refreshQRCode ... const handlePollResult = (result: PollStatusResult) => { switch (result.status) { case 'waiting': status.value = 'waiting-scan' break case 'scanned': status.value = 'scanned' break case 'authorized': status.value = 'authorized' stopPolling() return result.token // 返回token，由调用者处理 case 'expired': status.value = 'error' errorMessage.value = '二维码已过期' stopPolling() break } return null } // 清理函数 const cleanup = () => { stopPolling() status.value = 'init' qrCodeInfo.value = null } onUnmounted(cleanup) return { status, qrCodeInfo, errorMessage, expireCountdown, isWaiting, isLoading, initQRCode, refreshQRCode, cleanup } }

然后在组件中使用：

<script setup lang="ts"> import useWechatLogin from '@/composables/useWechatLogin' const { status, qrCodeInfo, errorMessage, expireCountdown, isWaiting, isLoading, initQRCode, refreshQRCode, cleanup } = useWechatLogin() // 组件逻辑变得更简洁 </script>

7. 常见问题排查与实战技巧

在实际开发和上线过程中，我遇到了不少坑。这里总结一下最常见的问题和解决方法。

7.1 二维码无法显示或显示错误

• 问题现象：图片裂图，或者控制台报错。
• 排查步骤：
  1. 检查ticket：确保后端返回的ticket是正确的，没有经过错误的编码或截断。前端拼接的URL格式必须是：https://mp.weixin.qq.com/cgi-bin/showqrcode?ticket=TICKET，其中TICKET需要经过URL编码。
  2. 检查网络：尝试直接在浏览器地址栏输入拼接好的URL，看是否能打开图片。如果不能，可能是ticket无效或已过期。
  3. 检查跨域：微信的二维码图片地址通常不会设置CORS头，如果前端项目是直接通过<img src=加载，一般没问题。但如果你的图片地址是通过CDN或代理，需要注意跨域问题。

7.2 扫码后无反应，状态不更新

这是最让人头疼的问题，可能的原因很多。

• 后端回调接口未正确触发：
  • 检查回调域名配置：这是重中之重！确保微信开放平台“授权回调域名”配置的，是你后端回调接口所在服务器的域名，且没有协议和路径。例如后端接口是https://api.mysite.com/auth/callback，那么回调域名就填api.mysite.com。
  • 检查服务器可访问性：确保微信服务器能通过公网访问到你的回调接口。可以在服务器上用curl命令测试接口是否正常响应。
  • 检查接口响应：微信要求回调接口在2秒内返回文本或JSON，否则会判定失败。确保你的接口逻辑高效，并且返回了正确的响应体（如"success"）。
• 后端状态未更新：
  • 检查scene_id映射：确保生成二维码时存储的scene_id，与微信回调时携带的state参数（如果你传了）能正确匹配，从而找到对应的缓存记录并更新状态。
  • 检查缓存：确认缓存（如Redis）服务工作正常，数据读写无误。
• 前端轮询问题：
  • 检查轮询参数：前端轮询时传的scene_id是否与后端返回的一致。
  • 检查轮询频率：频率不宜过高（建议2-5秒），避免给服务器造成压力。
  • 查看网络请求：打开浏览器开发者工具的Network面板，查看轮询请求是否正常发出，响应状态码和内容是什么。

7.3 安全性考量

• AppSecret保密：重申一遍，任何需要AppSecret的请求（如获取access_token、用code换openid）都必须在后端服务器进行。
• State参数防CSRF：在生成二维码时，后端可以生成一个随机的state字符串，与scene_id一起存储，并随二维码信息返回给前端。前端在轮询时带上这个state。后端在微信回调时，验证回调带来的state是否与存储的一致。这可以有效防止跨站请求伪造攻击。
• Token有效期：系统自身颁发的登录令牌（JWT）应设置合理的有效期，并考虑实现刷新令牌机制。
• 防重放攻击：确保一个code或一个scene_id只能使用一次，使用后立即失效。

7.4 用户体验优化点

• 多状态提示：除了“等待扫码”、“已扫码”、“授权成功”，还可以增加“二维码过期”、“网络异常”、“正在刷新”等状态，给用户明确的反馈。
• 扫码引导：在二维码旁边添加文字提示，如“打开微信扫一扫”或“使用手机微信扫描二维码”。
• 成功自动跳转：授权成功后，延迟1-2秒再跳转或关闭弹窗，让用户看到“登录成功”的提示，体验更完整。
• 错误友好提示：将后端返回的错误码（如errcode）转换为用户能看懂的文字提示，而不是直接显示技术错误。

整个实现过程，从配置到编码，再到调试上线，最深的体会就是：细节决定成败。尤其是微信开放平台的配置和前后端状态同步的逻辑，任何一个环节的小疏忽都可能导致流程走不通。把每个状态的变化、每个数据的流向都理清楚，画出流程图，编写代码时才能心中有数。这个纯前端的实现方案，虽然前期设计稍复杂，但换来的是无缝流畅的用户体验，对于现代Web应用来说，这份投入是值得的。