前端通用 Token 全流程操作指南（常见常用版）
前端通用 Token 全流程操作指南（常见常用版）
本文梳理 所有前端框架通用 的 Token 操作逻辑，剥离具体项目/技术栈细节，聚焦「获取→存储→使用→过期→清除」的核心生命周期，每个步骤均标注「通用场景+通用方案+注意事项」，适合所有前端开发场景，可直接作为开发速查表。
前置说明：Token 的核心定位
Token 是后端签发的临时访问凭证，核心作用是：
- 证明“当前用户是谁”（身份认证）；
- 证明“当前用户有权限访问”（权限校验）。
一、第一步：登录成功获取 Token
通用场景
用户通过账号密码/验证码/第三方登录等方式，向后端发起登录请求，后端验证通过后，在响应体中返回 Token。
通用方案
- 解析登录接口的响应数据；
- 根据后端接口文档，从响应体中提取 Token 字段（常见字段名：
token、access_token、data.token）； - 获取到 Token 后，立即执行「存储」操作。
注意事项
- 必须以后端接口文档为准，不要硬猜字段名；
- 获取到 Token 后，不要只打印在控制台，必须立即存储；
- 若接口同时返回
refresh_token（刷新 Token），需一并存储。
二、第二步：存储 Token（核心是选对存储方式）
通用场景
将获取到的 Token 保存到前端，确保刷新页面后不丢失，且全局页面/组件都能读取。
通用方案（三种常见存储方式对比）
| 存储方式 | 特性 | 适用场景 | 通用代码示例（原生 JS） |
|---|---|---|---|
| localStorage | 永久存储（关闭浏览器/重启电脑不丢失），容量约 5MB，仅客户端可读。 | 绝大多数 Web 应用（需求为“记住登录状态，下次打开不用重登”）。 | localStorage.setItem('token', '你的token值')const token = localStorage.getItem('token') |
| sessionStorage | 会话存储（关闭标签页/浏览器后立即清空），容量约 5MB，仅客户端可读。 | 安全性要求极高的应用（需求为“关闭浏览器就自动登出”，如银行、政务系统）。 | sessionStorage.setItem('token', '你的token值')const token = sessionStorage.getItem('token') |
| Cookie | 可设置过期时间，容量约 4KB，支持自动携带在请求头中，服务端可读取。 | 需服务端直接读取 Token 的场景，或有跨域/SSO（单点登录）需求的场景。 | document.cookie = 'token=你的token值; expires=过期时间; path=/' |
注意事项
- 推荐优先选 localStorage：是目前最通用、最方便的存储方式；
- 不要同时用多种方式存储（如同时存 localStorage 和 Cookie），易导致数据不一致；
- 不要在 Token 中存储敏感信息（如密码、身份证号）：Token 仅作为凭证，不承载业务数据。
三、第三步：请求接口时自动携带 Token
通用场景
每次向后端发起业务请求（如获取列表、提交数据）时，都需在请求头（Header） 中带上 Token，供后端验证身份。
通用方案
使用主流 HTTP 请求库的「请求拦截器」（如 Axios、Fetch 封装、umi-request），在请求发送前自动读取 Token 并添加到请求头，无需每次手动添加。
通用请求头格式（两种最常见）
自定义 token 头：
token: <你的token值> 标准 Authorization 头（推荐）：
Authorization: Bearer <你的token值> 注意事项
- 必须以后端接口文档为准，不要写错请求头字段名；
- 只有 Token 存在时才添加请求头，避免空 Token 导致接口报错；
- 不要在请求体（Body）中传递 Token（除非后端强制要求），请求头是标准做法。
四、第四步：处理 Token 过期
通用场景
Token 有有效期（常见为 2 小时/24 小时/7 天），过期后后端会拒绝请求并返回特定状态码（通常为 401 Unauthorized）。
通用方案
使用主流 HTTP 请求库的「响应拦截器」，统一处理 Token 过期逻辑：
- 判断响应状态码是否为
401（或后端约定的其他过期标识）； - 若确认过期：
- 给用户友好提示（如“登录已过期，请重新登录”）；
- 清除所有存储的 Token（及用户信息）；
- 强制跳转到登录页。
注意事项
- 不要忽略
401错误：Token 过期后用户无法继续操作，必须重新登录； - 清除 Token 时要彻底：删除所有存储介质中的 Token（如同时删 localStorage 和全局状态）；
- 跳转登录页时建议替换当前历史记录（避免用户点击“回退”回到过期页面）。
五、第五步：用户主动登出清除 Token
通用场景
用户点击“退出登录”按钮时，需清除所有登录相关数据，恢复到未登录状态。
通用方案
- 触发登出操作时，先给用户二次确认（如“确定要退出登录吗？”）；
- 确认后执行清除操作：
- 清除所有存储介质中的 Token（localStorage/sessionStorage/Cookie）；
- 清除全局状态中的用户信息（如头像、昵称）；
- 强制跳转到登录页。
注意事项
- 不要省略二次确认：避免用户误触登出按钮；
- 登出后不要保留任何登录痕迹：确保下次打开应用是完全的未登录状态；
- 若后端有“登出接口”，建议先调用接口（通知后端销毁 Token），再执行前端清除操作。
六、第六步：路由/页面权限控制（进阶但常用）
通用场景
未登录的用户不能访问需要登录的页面（如首页、个人中心），已登录的用户不能访问登录页。
通用方案
使用路由守卫/权限拦截（如 Vue Router 的 beforeEach、React Router 的路由拦截），在页面跳转前统一校验：
- 定义「白名单」：不需要登录就能访问的页面（如登录页、注册页、404 页）；
- 跳转前读取 Token，判断用户是否登录；
- 根据判断结果决定“放行”还是“跳转登录页”。
注意事项
- 不要忘记定义白名单：登录页本身不需要登录，否则会导致“无限重定向”；
- 权限控制仅做“前端拦截”：真正的权限校验必须在后端做（前端拦截防君子不防小人）；
- 不要在权限拦截中做复杂的异步操作（如调接口验证 Token）：会导致页面加载卡顿。
总结：Token 全流程核心逻辑
- 获取：登录接口返回 → 提取 Token；
- 存储：选对存储方式（推荐 localStorage）→ 全局可读取、刷新不丢；
- 使用：请求拦截器自动带 Token → 放在请求头里；
- 过期：响应拦截器处理 401 → 清除 Token、跳登录页；
- 清除：用户登出 → 彻底清除所有数据、跳登录页；
- 控制：路由守卫 → 未登录用户不能访问受保护页面。
避坑总览（新手必看）
- ❌ 不要只存全局状态不存本地存储：刷新页面后数据会清空；
- ❌ 不要在每个请求里手动加 Token：用请求拦截器统一处理；
- ❌ 不要忽略 Token 过期的 401 错误：必须强制用户重新登录；
- ❌ 不要在 Token 里存敏感信息：Token 仅作为凭证；
- ❌ 不要省略登出的二次确认：避免用户误操作。
