parseJwtPayload

解析 JWT token payload 的纯函数工具，可用于任何运行环境。提供 parseJwtPayload 和 extractJwtSubject 两个方法：前者返回 payload JSON，后者直接提取 sub。

前置依赖

参数名	类型	说明
deps.base64Decode	(value: string) => string	base64 解码函数（需兼容 URL-Safe 格式）
deps.consoleError	Console['error']	可选，用于记录解析异常

在浏览器端可直接传入 window.atob，在 Node.js 环境可使用 Buffer.from(value, 'base64').toString('utf-8')。

函数签名

interface ParseJwtPayloadDeps {
  base64Decode: (value: string) => string
  consoleError?: Console['error']
}

function parseJwtPayload<TPayload extends Record<string, any> = Record<string, any>>(
  token: string,
  deps: ParseJwtPayloadDeps
): TPayload | null

function extractJwtSubject(
  token: string,
  deps: ParseJwtPayloadDeps
): string | null

参数

参数名	类型	必填	说明
token	string	是	JWT 字符串，例如 header.payload.signature
deps.base64Decode	Function	是	base64 解码函数（需支持 URL-Safe）
deps.consoleError	Function	否	捕获解析异常时的日志输出

返回值

• parseJwtPayload：payload 对象，解析失败返回 null
• extractJwtSubject：payload.sub 字段（字符串），不存在或解析失败时返回 null

工作原理

1. 拆分 JWT，读取第二段 payload
2. 将 URL-Safe base64 转换为标准 base64，并补齐 = 补位
3. 使用注入的 base64Decode 解码，再 JSON.parse 为对象
4. 解析失败时捕获异常，输出日志但不抛错
5. extractJwtSubject 在 payload 成功解析后直接返回 sub

使用示例

import { parseJwtPayload, extractJwtSubject } from 'zcw-shared/functions/auth/parseJwtPayload'

const deps = {
  base64Decode: window.atob,
  consoleError: console.error
}

const payload = parseJwtPayload(token, deps)
const userId = extractJwtSubject(token, deps)

最佳实践

• 解析失败时请结合缓存或后端接口降级（如 useAuth 中的用户资料缓存）
• 仅在受信任的上下文中使用，解析 payload 不等于 token 校验
• 如果需要支持 Node 环境，可使用 Buffer.from(value, 'base64').toString('utf-8') 并自行注入