sionrui/frontend/utils/TOKEN_STORAGE.md

Token 存储位置说明

📍 Token 存储位置总览

Token 在项目中有 3 个存储位置，按读取优先级排序：

1. Dev Token（开发手动输入的 token）

• 存储位置：sessionStorage
• 键名：DEV_MANUAL_TOKEN
• 设置方式：setDevToken(token)
• 特点：
  • 优先级最高（读取时优先使用）
  • 关闭浏览器标签页后自动清除
  • 用于开发测试

浏览器查看方式：

// 在浏览器控制台执行
sessionStorage.getItem('DEV_MANUAL_TOKEN')

2. 正式登录的 Token（主要存储）

• 存储位置：localStorage（通过 WebStorageCache 封装）
• 键名：
  • ACCESS_TOKEN 或 access_token（访问令牌）
  • REFRESH_TOKEN 或 refresh_token（刷新令牌）
• 设置方式：setToken({ accessToken, refreshToken })
• 特点：
  • 持久化存储（关闭浏览器后仍然存在）
  • 使用 WebStorageCache 库管理
  • 支持大小写不同的键名变体（兼容性）

浏览器查看方式：

// 在浏览器控制台执行
localStorage.getItem('ACCESS_TOKEN')
localStorage.getItem('REFRESH_TOKEN')
// 或者
localStorage.getItem('access_token')
localStorage.getItem('refresh_token')

实际存储结构：

localStorage:
  ├── ACCESS_TOKEN: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  └── REFRESH_TOKEN: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

3. 环境变量 Token（兜底）

• 存储位置：代码中（不存储在浏览器）
• 变量名：VITE_DEV_TOKEN
• 设置方式：.env 文件或环境变量
• 特点：
  • 只在代码中读取，不写入浏览器存储
  • 优先级最低（前两者都没有时才使用）
  • 用于开发环境默认配置

🔄 Token 读取优先级

当调用 getToken() 时，按以下顺序查找：

1. sessionStorage['DEV_MANUAL_TOKEN']  ← 最高优先级
   ↓ (如果没有)
2. localStorage['ACCESS_TOKEN'] 或 localStorage['access_token']
   ↓ (如果没有)
3. import.meta.env.VITE_DEV_TOKEN  ← 最低优先级

📝 代码示例

设置 Token

import { setToken, setDevToken } from '@gold/utils/token-manager'

// 设置正式登录的 token（存储到 localStorage）
setToken({
  accessToken: 'xxx',
  refreshToken: 'yyy'
})

// 设置开发 token（存储到 sessionStorage）
setDevToken('dev-token-123')

读取 Token

import { getToken } from '@gold/utils/token-manager'

// 自动按优先级读取
const token = getToken()

清除 Token

import { clearAllTokens } from '@gold/utils/token-manager'

// 清除所有位置的 token
clearAllTokens()
// 会清除：
// 1. sessionStorage['DEV_MANUAL_TOKEN']
// 2. localStorage['ACCESS_TOKEN'] 和 'access_token'
// 3. localStorage['REFRESH_TOKEN'] 和 'refresh_token'

🔍 在浏览器中查看

Chrome DevTools

1. 打开 DevTools (F12)
2. Application 标签页
3. Storage 部分：
   • Local Storage → 查看 ACCESS_TOKEN、REFRESH_TOKEN
   • Session Storage → 查看 DEV_MANUAL_TOKEN

控制台命令

// 查看所有 token
console.log('Dev Token:', sessionStorage.getItem('DEV_MANUAL_TOKEN'))
console.log('Access Token:', localStorage.getItem('ACCESS_TOKEN'))
console.log('Refresh Token:', localStorage.getItem('REFRESH_TOKEN'))

// 查看所有 localStorage
console.table(localStorage)

// 查看所有 sessionStorage
console.table(sessionStorage)

⚠️ 注意事项

1. WebStorageCache 封装：

   • useCache() 默认使用 localStorage
   • 通过 WebStorageCache 库管理，支持过期时间等功能
   • 实际存储位置仍然是 localStorage

2. 键名大小写：

   • 代码中统一使用 ACCESS_TOKEN 和 REFRESH_TOKEN（大写）
   • 但为了兼容，也支持 access_token 和 refresh_token（小写）
   • 读取时会尝试所有变体

3. 清除逻辑：

   • clearAllTokens() 会清除所有位置的 token
   • 包括 sessionStorage、localStorage 的所有变体键名
   • 确保完全清除，避免残留

📊 存储位置总结表

Token 类型	存储位置	键名	持久化	优先级
Dev Token	sessionStorage	DEV_MANUAL_TOKEN	❌ 关闭标签页清除	1 (最高)
Access Token	localStorage	ACCESS_TOKEN / access_token	✅ 持久化	2
Refresh Token	localStorage	REFRESH_TOKEN / refresh_token	✅ 持久化	2
Env Token	代码中	VITE_DEV_TOKEN	N/A	3 (最低)