Vue 3 前端如何搭建可维护的 OAuth2 授权码流程？

在 Vue 3 单页应用中落地 OAuth2，核心并不是调用几个接口，而是把授权跳转、回调处理、令牌存储和刷新策略整合成一套稳定的工程化方案。授权码模式仍然是多数前后端分离项目的首选，它让前端只接触一次性的授权码，真正的访问令牌和刷新令牌可以通过后端代理来换取，从而减少浏览器拿到长期凭据的风险。如果项目采用纯前端模式直接向授权服务器交换令牌，则需要加入 PKCE 并严格限制令牌保存位置。本文按照一个常见的企业级前端流程展开。

一、工程化 OAuth2 的模块边界

很多前端项目最初接入 OAuth2 时，会把授权跳转写在登录按钮里，把回调解析写在 App.vue 的 onMounted 中，把令牌刷新塞进 axios 拦截器。功能虽然能跑通，但随着客户端 ID、重定向地址、权限范围等配置增多，维护成本会快速上升。更好的做法是将鉴权相关逻辑拆成独立模块，每个模块只承担一个明确职责。

推荐至少拆成四个模块。配置文件 oauth-config.ts 集中管理 authorizationEndpoint、tokenEndpoint、clientId、redirectUri 和 scopes；流程模块 oauth-flow.ts 负责构造授权 URL 和解析回调参数；token-store.ts 负责访问令牌、刷新令牌及过期时间的内存读写和 sessionStorage 持久化；refresh-queue.ts 负责解决并发请求同时触发刷新导致重复调用的问题。Vue 3 中还可以用 Pinia 暴露统一的 authStore 给组件使用，但 Pinia 不应该承担底层的令牌持久化和刷新队列逻辑。

// oauth-config.ts
export const oauthConfig = {
  authorizeEndpoint: 'https://auth.ipipp.com/oauth/authorize',
  tokenEndpoint: 'https://api.ipipp.com/oauth/token',
  clientId: 'spa-client',
  redirectUri: window.location.origin + '/callback',
  scopes: ['openid', 'profile', 'email'],
};

授权 URL 的构造也应该集中处理，避免每个组件自己拼接参数。构造时需要携带 response_type、client_id、redirect_uri、scope 和 state。state 用于回调时校验，防止跨站请求伪造。下面这个函数会在发起跳转前生成 state 并写入 sessionStorage，回调页面再读取比对。

// oauth-flow.ts
import { oauthConfig } from './oauth-config';

export function buildAuthorizeUrl() {
  const params = new URLSearchParams({
    response_type: 'code',
    client_id: oauthConfig.clientId,
    redirect_uri: oauthConfig.redirectUri,
    scope: oauthConfig.scopes.join(' '),
    state: generateState(),
  });

  sessionStorage.setItem('oauth_state', params.get('state'));

  return oauthConfig.authorizeEndpoint + '?' + params.toString();
}

function generateState() {
  return Math.random().toString(36).substring(2) + Date.now().toString(36);
}

二、回调解析与令牌交换

用户完成授权后会跳转回 redirectUri，地址栏通常携带 code 和 state。回调页面需要在挂载阶段完成三件事：校验 state、取出 code、调用后端交换接口。state 校验是为了防止跨站请求伪造，它的值应当在发起授权前写入 sessionStorage，并在回调后立刻清除。如果 state 不匹配或不存在，应直接终止流程并跳转到错误页。

在 Vue 3 中可以单独创建一个回调路由组件，而不是把逻辑耦合在路由守卫中。下面是一个使用组合式 API 的最小实现，交换令牌的请求由后端代理完成，浏览器不会接触客户端密钥。

// CallbackView.vue
import { onMounted } from 'vue';
import { useRouter } from 'vue-router';
import { exchangeCode } from '@/auth/oauth-flow';
import { useAuthStore } from '@/stores/auth';

export default {
  setup() {
    const router = useRouter();
    const authStore = useAuthStore();

    onMounted(async function () {
      const params = new URLSearchParams(window.location.search);
      const code = params.get('code');
      const state = params.get('state');

      if (!code || state !== sessionStorage.getItem('oauth_state')) {
        router.replace('/login?error=invalid_state');
        return;
      }

      sessionStorage.removeItem('oauth_state');

      const tokens = await exchangeCode(code);
      authStore.setTokens(tokens);
      router.replace('/dashboard');
    });
  },
};

exchangeCode 函数会调用后端接口，由后端携带客户端密钥向授权服务器发起令牌请求。返回体一般包括 access_token、refresh_token、expires_in 和 token_type。前端拿到令牌后，访问令牌可以放在 Pinia 或模块级变量中，刷新令牌则不建议长期写入 localStorage。localStorage 的读取权限太大，一旦发生 XSS 攻击，攻击者可以轻易窃取令牌。纯前端无法使用 HttpOnly Cookie 时，可将刷新令牌暂存 sessionStorage，并设置较短的有效期，或者优先使用后端会话保持登录状态。

还有一点容易被忽略：回调地址中的 query 参数会在刷新页面时再次触发回调处理。如果用户刷新某个携带 code 的回调页，可能因为 state 已被清除而报错，也可能重复调用交换接口。工程上可以在路由跳转到正式页面时使用 router.replace，而不是 router.push，这样浏览器历史记录中的回调地址会被替换，减少重复处理的概率。

三、令牌刷新与并发请求队列

访问令牌的有效期通常较短，刷新令牌用于在访问令牌过期后获取新令牌。如果在一个请求发出后令牌过期，服务端会返回 401。简单做法是在响应拦截器中捕获 401，然后调用刷新接口重试。但问题是，当页面上同时发出多个接口请求时，它们会同时收到 401，如果不做并发控制，前端会向刷新令牌接口发送多次请求，浪费资源甚至造成刷新令牌竞争。

处理方式是维护一个全局的刷新 Promise。当第一个 401 触发刷新后，后续 401 请求只需要等待同一个 Promise 完成，而不会再次发起刷新。下面这段代码展示了核心队列逻辑。

// refresh-queue.ts
let refreshPromise = null;

export function refreshAccessToken() {
  if (!refreshPromise) {
    refreshPromise = (async function () {
      const newToken = await requestNewAccessToken();
      refreshPromise = null;
      return newToken;
    })().catch(function (error) {
      refreshPromise = null;
      throw error;
    });
  }
  return refreshPromise;
}

async function requestNewAccessToken() {
  const response = await fetch('/api/auth/refresh', {
    method: 'POST',
    credentials: 'include',
  });
  const data = await response.json();
  return data.access_token;
}

在 axios 响应拦截器中接入该队列时，需要避免死循环：重试请求如果再返回 401，不应该继续刷新。可以通过给 originalRequest 增加一个自定义标记来实现，例如 _retry。当 _retry 已经为 true 时，直接返回错误，否则等待刷新完成并重试。

import axios from 'axios';
import { refreshAccessToken } from '@/auth/refresh-queue';

axios.interceptors.response.use(
  function (response) {
    return response;
  },
  async function (error) {
    const originalRequest = error.config;

    if (error.response) {
      if (error.response.status === 401) {
        if (!originalRequest._retry) {
          originalRequest._retry = true;
          const token = await refreshAccessToken();
          originalRequest.headers.Authorization = 'Bearer ' + token;
          return axios(originalRequest);
        }
      }
    }

    return Promise.reject(error);
  }
);

刷新令牌本身过期或失效时，刷新接口可能返回 401 或 400，此时 refreshPromise 会进入 catch 分支并清空队列。业务上应当清理本地会话并跳转登录页。建议把退出登录的处理放在 authStore.logout 中，由拦截器捕获异常后调用，而不是在请求工具函数里直接操作路由，这样可以避免循环依赖，也方便测试。

另外，刷新接口依赖的刷新令牌如果放在 HttpOnly Cookie 中，前端请求时需设置 credentials 为 include。如果使用 sessionStorage 保存刷新令牌，则需要在请求头中显式携带。两种方式没有绝对优劣，但团队需要在安全评审时明确令牌生命周期和可访问范围。

四、路由守卫与应用初始化恢复

路由守卫是保护页面权限的关键。Vue Router 4 的 beforeEach 可以在进入每个路由前检查 authStore 中是否有访问令牌。如果目标路由标记为 public，则直接放行；否则判断令牌是否存在。若令牌不存在，可以尝试调用恢复会话逻辑，从刷新令牌或后端会话中恢复访问令牌。

下面是一个基础实现。tryRestoreSession 内部会优先通过后端接口校验会话，成功后将令牌写入 authStore；如果失败则清理本地状态并返回 false，由守卫重定向到登录页。

// router.ts
import { createRouter, createWebHistory } from 'vue-router';
import { useAuthStore } from '@/stores/auth';

const router = createRouter({
  history: createWebHistory(),
  routes: [
    { path: '/callback', component: function () { return import('@/views/CallbackView.vue'); } },
    { path: '/dashboard', component: function () { return import('@/views/DashboardView.vue'); } },
    { path: '/login', component: function () { return import('@/views/LoginView.vue'); }, meta: { public: true } },
  ],
});

router.beforeEach(async function (to) {
  const authStore = useAuthStore();

  if (to.meta.public) {
    return true;
  }

  if (!authStore.accessToken) {
    const restored = await authStore.tryRestoreSession();
    if (!restored) {
      return { path: '/login', query: { redirect: to.fullPath } };
    }
  }

  return true;
});

export default router;

路由守卫里的 tryRestoreSession 不应每次导航都调用后端接口，否则会拖慢切换体验。可以在 authStore 中缓存恢复状态，例如增加一个 initialized 标记或 Promise 缓存，避免重复请求。应用初始化时先执行一次恢复，后续导航直接读取内存令牌即可。

权限控制还可以结合路由 meta 中的角色信息。比如某些页面只允许特定角色访问，守卫可以在恢复会话后比较用户角色和路由要求的权限，不满足则跳转 403 页面。这样的设计将身份认证和权限授权分开，后续接入 RBAC 会更自然。

五、安全边界与工程化检查清单

OAuth2 在前端的实现是否安全，很大程度上取决于工程化约束是否到位。以下几点可以作为团队自查清单。第一，授权请求必须携带 state，并在回调后严格校验和清除。第二，访问令牌不要长期放在 localStorage，优先内存态加 sessionStorage 的短期缓存。第三，刷新令牌应尽量放在 HttpOnly Cookie 或后端会话中，减少被脚本读取的风险。第四，回调路由使用 replace 方式清理历史记录。第五，刷新逻辑必须有并发队列和失败重试上限，防止重复刷新和死循环。

此外，如果项目使用纯前端 public client 直接向授权服务器交换令牌，务必启用 PKCE。授权码模式加 PKCE 可以防止授权码被截获后单独使用，因为即使拿到 code，缺少 code_verifier 也无法成功交换令牌。PKCE 的实现并不复杂，可以在发起授权时生成 code_verifier 和 code_challenge，将 challenge 随授权请求发送，回调后用 verifier 参与交换。

最后，工程化 OAuth2 不是一次性任务。随着授权服务器升级、安全策略变化或前后端职责调整，模块边界和令牌策略也需要持续演进。建议把 OAuth2 流程封装成独立的包或目录，通过清晰接口暴露给业务代码，并为核心模块编写单元测试，模拟令牌过期、刷新失败、state 不一致等异常场景。这样团队在后续迭代中才能真正把鉴权当作基础设施来维护，而不是每个页面各自为政。

Vue 3OAuth2授权码模式修改时间：2026-09-26 15:19:45