自动刷新访问令牌：基于Axios拦截器的实现指南

新闻中心 NEWS CENTER

您当前位置：首页 > 新闻中心 > 网络学院

自动刷新访问令牌：基于Axios拦截器的实现指南

2025-10-15

浏览次数：次

返回列表

自动刷新访问令牌：基于Axios拦截器的实现指南

本文旨在提供一个全面的教程，指导开发者如何利用axios拦截器实现访问令牌（access token）的自动化刷新机制。通过捕获http 403未授权错误，并在后台静默刷新过期令牌，确保用户会话的连续性，避免频繁的登录操作，从而提升用户体验和应用的安全性。

理解访问令牌与刷新机制

在现代Web应用中，为了保护API资源，通常采用基于令牌的认证机制。用户成功登录后，服务器会颁发一个访问令牌（Access Token）和一个刷新令牌（Refresh Token）。访问令牌用于授权用户访问受保护的资源，但其通常具有较短的有效期（例如一小时），以降低令牌泄露的风险。当访问令牌过期时，客户端需要获取一个新的访问令牌。手动要求用户重新登录不仅体验差，也效率低下。因此，实现访问令牌的自动化刷新变得至关重要。

刷新令牌通常具有较长的有效期，并用于在访问令牌过期后，向认证服务器请求新的访问令牌。这个过程应该对用户透明，即在不打断用户操作的情况下完成。

利用Axios拦截器实现自动刷新

Axios作为一款流行的HTTP客户端库，提供了强大的拦截器功能，允许我们在请求发送前或响应返回后进行处理。这使得Axios拦截器成为实现自动令牌刷新机制的理想选择。

核心思路

响应拦截： 监听所有HTTP响应。
错误捕获： 当接收到HTTP 403（未授权）状态码时，表明当前访问令牌可能已过期或无效。
令牌刷新： 在后台使用刷新令牌向认证服务器请求新的访问令牌。
重试请求： 使用新的访问令牌重新发起原始失败的请求。
错误处理： 如果刷新令牌也失效，或者刷新过程失败，则引导用户重新登录。

实现步骤与代码示例

我们将通过一个Axios响应拦截器的具体实现来展示这一过程。

AI Surge Cloud

低代码数据分析平台，帮助企业快速交付深度数据

87 查看详情 AI Surge Cloud

首先，确保你已经配置了Axios实例，并可能在请求头中设置了默认的Authorization字段。

import axios from 'axios';

// 创建一个Axios实例，便于管理和配置
const axiosApiInstance = axios.create({
  baseURL: 'YOUR_API_BASE_URL', // 替换为你的API基础URL
  headers: {
    'Content-Type': 'application/json',
    // 初始时可能没有Authorization头，或者从本地存储加载
  },
});

// 模拟一个用于刷新访问令牌的函数
// 实际应用中，此函数会使用refresh token向认证服务器请求新的access token
async function refreshAccessToken() {
  try {
    // 假设你的刷新令牌存储在某个地方，例如localStorage
    const refreshToken = localStorage.getItem('refreshToken');
    if (!refreshToken) {
      throw new Error('No refresh token found');
    }

    // 实际的API调用，用于获取新的access token
    // 例如：
    const response = await axios.post('YOUR_AUTH_REFRESH_ENDPOINT', {
      refreshToken: refreshToken,
    });

    const { accessToken: newAccessToken, refreshToken: newRefreshToken } = response.data;

    // 更新本地存储的令牌
    localStorage.setItem('accessToken', newAccessToken);
    if (newRefreshToken) { // 如果刷新令牌也可能更新
      localStorage.setItem('refreshToken', newRefreshToken);
    }

    return newAccessToken;
  } catch (error) {
    console.error('Failed to refresh access token:', error);
    // 在这里可以处理刷新失败的情况，例如清除所有令牌并重定向到登录页
    localStorage.removeItem('accessToken');
    localStorage.removeItem('refreshToken');
    window.location.href = '/login'; // 重定向到登录页
    throw error; // 抛出错误以便拦截器后续处理
  }
}

// 响应拦截器
axiosApiInstance.interceptors.response.use(
  (response) => {
    // 如果响应成功，直接返回
    return response;
  },
  async function (error) {
    const originalRequest = error.config;

    // 检查是否是403错误，并且该请求之前没有被重试过
    // _retry 标志用于防止无限循环重试
    if (error.response && error.response.status === 403 && !originalRequest._retry) {
      originalRequest._retry = true; // 标记为已重试

      try {
        const newAccessToken = await refreshAccessToken();
        // 更新Axios实例的默认Authorization头，以便后续请求使用新令牌
        axiosApiInstance.defaults.headers.common['Authorization'] = 'Bearer ' + newAccessToken;
        // 更新原始请求的Authorization头，然后重新发送该请求
        originalRequest.headers['Authorization'] = 'Bearer ' + newAccessToken;
        return axiosApiInstance(originalRequest); // 使用更新后的配置重新发送原始请求
      } catch (refreshError) {
        // 刷新令牌失败，可能是刷新令牌也过期了，或者其他错误
        // 此时应重定向用户到登录页面
        console.error('Token refresh failed, redirecting to login:', refreshError);
        // refreshAccessToken函数内部已经处理了重定向，这里可以再次确认
        // 或者抛出错误，让调用方处理
        return Promise.reject(refreshError);
      }
    }

    // 对于其他错误，或者已经重试过的403错误，直接拒绝Promise
    return Promise.reject(error);
  }
);

// 导出Axios实例供应用使用
export default axiosApiInstance;

// 在应用启动时，可以从localStorage加载access token并设置到axiosApiInstance
const storedAccessToken = localStorage.getItem('accessToken');
if (storedAccessToken) {
  axiosApiInstance.defaults.headers.common['Authorization'] = 'Bearer ' + storedAccessToken;
}

代码解析

axiosApiInstance.interceptors.response.use(...): 这是Axios响应拦截器的入口。它接收两个函数：一个用于处理成功响应，另一个用于处理错误响应。
originalRequest = error.config: 在错误处理函数中，我们可以访问到原始请求的配置对象，这对于重试请求至关重要。
if (error.response.status === 403 && !originalRequest._retry): 这是核心逻辑。我们检查：
- 响应状态码是否为403（未授权）。
- originalRequest._retry 标志是否为false。这个自定义标志非常重要，它确保一个请求只会被重试一次，防止在刷新令牌失败时陷入无限循环。
originalRequest._retry = true: 在尝试刷新令牌之前，将_retry标志设置为true。
await refreshAccessToken(): 调用refreshAccessToken函数来获取新的访问令牌。这个函数应该负责：
- 使用存储的刷新令牌向认证服务器发送请求。
- 成功后，更新本地存储中的访问令牌和刷新令牌（如果刷新令牌也更新了）。
- 返回新的访问令牌。
- 失败时，清除所有令牌并重定向到登录页。
axiosApiInstance.defaults.headers.common['Authorization'] = 'Bearer ' + newAccessToken;: 更新Axios实例的默认Authorization头。这确保了后续的所有请求都会使用新的访问令牌。
originalRequest.headers['Authorization'] = 'Bearer ' + newAccessToken;: 更新原始请求的Authorization头。这是为了确保即将被重试的那个特定请求能够携带新的令牌。
return axiosApiInstance(originalRequest);: 使用更新后的配置重新发送原始请求。由于这是一个异步操作，我们返回axiosApiInstance(originalRequest)的结果，它会是一个Promise。
return Promise.reject(error);: 如果不是403错误，或者已经是重试过的请求，或者刷新令牌失败，则直接拒绝Promise，将错误传递给调用方处理。

注意事项与最佳实践

刷新令牌的安全性： 刷新令牌通常具有较长的有效期，因此需要妥善保管。不应将其直接暴露在客户端代码中，应考虑使用HTTP-only cookie或更安全的存储机制。
并发请求处理： 如果在刷新令牌的过程中，有多个请求同时收到403错误，可能会导致多次尝试刷新令牌。这可以通过引入一个锁机制（例如，使用一个Promise来存储正在进行的刷新操作，所有需要刷新令牌的请求都等待这个Promise完成）来优化，确保只有一个刷新请求在执行。
用户体验： 在刷新令牌期间，可以显示一个加载指示器，告知用户正在处理中，避免用户误以为应用卡死。
错误处理粒度： refreshAccessToken函数内部应包含详细的错误处理逻辑，例如当刷新令牌本身也过期时，清除所有认证信息并强制用户重新登录。
登录页面的处理： 确保登录请求（/auth/login或其他认证端点）不会被拦截器误判为需要刷新令牌，通常可以在拦截器中排除这些特定路径。
服务器端配合： 确保认证服务器提供一个专门的刷新令牌端点，并且该端点能够正确验证刷新令牌并颁发新的访问令牌。