@sud-web/utils

通用浏览器工具包，目前包含 CSRF Token 本地缓存工具、统一登录跳转工具和认证 code 常量。

安装

pnpm add @sud-web/utils

导出

import {
  AUTHKEYNAME,
  getCsrfToken,
  setCsrfToken,
  removeCsrfToken,
  redirectToLogin
} from '@sud-web/utils'

API	说明
AUTHKEYNAME	Auth 回跳 code 参数名，当前为 sud_auth_code
getCsrfToken	从 localStorage 读取 CSRF Token
setCsrfToken	写入 CSRF Token
removeCsrfToken	删除 CSRF Token
redirectToLogin	清理 Token 并跳转到统一认证系统

Token 工具

Token 默认存储在 localStorage 的 x-xsrf-token key 下。

setCsrfToken('token')

const token = getCsrfToken()

removeCsrfToken()

方法	参数	返回
getCsrfToken()	无	`string
setCsrfToken(token)	token: string	void
removeCsrfToken()	无	void

redirectToLogin

用于跳转到统一 Auth（SSO）系统。执行跳转前会调用 removeCsrfToken()，并清理回跳地址里的 sud_auth_code 参数，避免重复跳转时 code 堆积。

它有两种跳转方式，由 autoLogin 决定：

• autoLogin: true（走后端，form 探测）：创建隐藏 form，用 GET 提交到 redirectAction（后端接口）。本质是「探测用户是否已经在统一登录中心登录」——已登录就带 code 302 回来，未登录则进登录页。
• autoLogin 不传（走前端 location.href）：直接 location.href 跳到 authBaseUrl + authPath（auth 前端域名的某个路由），常用于主动退出。

实际使用（项目封装）

业务侧一般不直接调用包里的 redirectToLogin，而是按自己项目的 env / channel 再封装一层，对外暴露「登录」「退出」两个场景。下面是 customer 项目的真实封装：

// 对 SSO 跳转的二次封装：把项目固定的 env / channel 收口，对外只暴露 scene
import { redirectToLogin as redirectToSSO } from '@sud-web/utils'

interface IRedirectToLoginParams {
  /** auth 前端系统的指定路由，如 /logout */
  authPath?: string
  /** 默认 location.href，可指定回跳地址 */
  redirect_uri?: string
  /** 默认 login；logout 用于主动退出 */
  scene?: 'login' | 'logout'
}

export function redirectToLogin(props: IRedirectToLoginParams = {}) {
  const { authPath = '', redirect_uri, scene = 'login' } = props

  const baseParams = {
    authPath,
    authBaseUrl: import.meta.env.VITE_AUTH_BASE_URL, // auth 前端域名
    channel: 'official',
    redirect_uri
  }

  // 主动退出：跳 auth 前端域名的 /logout 路由，并关闭登录后的授权页
  if (scene === 'logout') {
    redirectToSSO({ ...baseParams, showLoginConfirm: '0' })
    return
  }

  // 登录态探测：走后端 redirectAction，用隐藏 form 提交
  redirectToSSO({
    ...baseParams,
    autoLogin: true,
    redirectAction: import.meta.env.VITE_PUBLIC_AUTH_REDIRECT_ACTION
  })
}

调用方只关心场景：

// 进入页面发现未登录 / token 失效：探测登录态
redirectToLogin()

// 用户点「退出登录」：跳 auth 前端 /logout 自动退出
redirectToLogin({ scene: 'logout', authPath: '/logout' })

redirectAction 是后端接口地址，按环境区分，通常配在 env 里（VITE_PUBLIC_AUTH_REDIRECT_ACTION）：

环境	redirectAction
dev	https://dev-auth.sud.tech/api/login/redirect
fat	https://fat-auth.sud.tech/api/login/redirect
prod	https://auth.sud.tech/api/login/redirect

直接调用（不封装）

不封装时，直接传包要求的参数。最小调用：

import { redirectToLogin } from '@sud-web/utils'

redirectToLogin({
  authBaseUrl: import.meta.env.VITE_AUTH_BASE_URL,
  channel: 'official'
})

默认使用当前 location.href 作为 redirect_uri。

authPath（主动退出）

authPath 指要进入 auth 前端系统的哪个路由。最终跳转地址是 authBaseUrl + authPath。主动退出时填 /logout，会跳到 auth 前端域名的 /logout 路由自动执行退出：

redirectToLogin({
  authBaseUrl: 'https://auth.sud.tech',
  authPath: '/logout',
  channel: 'official'
})
// → https://auth.sud.tech/logout?channel=official&redirect_uri=...

autoLogin + redirectAction（登录态探测）

autoLogin: true 时不走 location.href，而是创建隐藏 form，用 GET 提交到 redirectAction，探测用户是否已在统一登录中心登录：

redirectToLogin({
  authBaseUrl: 'https://auth.sud.tech',
  channel: 'official',
  autoLogin: true,
  redirectAction: 'https://auth.sud.tech/api/login/redirect'
})

autoLogin 场景下 redirectAction（后端接口地址）必填，否则报错返回。

tokenFailReturn

仅在 autoLogin: true（走后端探测）时使用。设为 true 时，不管用户是否已登录，都只会 302 回到原来的地址，不会强制进入登录页。一般用在非登录态也允许访问网站的场景（如官网）。

redirectToLogin({
  authBaseUrl: 'https://auth.sud.tech',
  channel: 'official',
  autoLogin: true,
  redirectAction: 'https://auth.sud.tech/api/login/redirect',
  tokenFailReturn: true
})

入参	最终参数
true	tokenFailReturn=1
'custom'	tokenFailReturn=custom
不传	不追加该参数

不设置时，则按登录态决定：已登录带 code 302 回来，未登录跳登录页。

showLoginConfirm

showLoginConfirm 控制登录成功后是否展示授权页面：

redirectToLogin({
  authBaseUrl: 'https://auth.sud.tech',
  channel: 'official',
  showLoginConfirm: '0'
})

入参	登录成功后行为
'0'	不展示授权页，直接回跳 redirect_uri
不传 / '1'	展示授权确认页

showLoginConfirm 只在 location.href 跳转分支生效（即不开 autoLogin，例如主动退出场景）。autoLogin 的 form 提交不会携带该参数。

debug

redirectToLogin({
  authBaseUrl: 'https://auth.sud.tech',
  channel: 'official',
  debug: true
})

debug: true 会完成参数计算和 Token 清理，但不会真正跳转，便于本地调试。

参数

interface IRedirectToLoginParams {
  channel: string
  authBaseUrl: string
  authPath?: string
  autoLogin?: boolean
  redirectAction?: string
  showLoginConfirm?: '0' | '1'
  redirect_uri?: string
  tokenFailReturn?: boolean | string
  debug?: boolean
}

参数	类型	必填	默认值	说明
channel	string	是	-	平台来源标识（如 official）
authBaseUrl	string	是	-	Auth 前端系统基础域名
authPath	string	否	''	要进入 auth 前端的路由，主动退出填 /logout
autoLogin	boolean	否	false	true 时用隐藏 form 提交到后端 redirectAction，探测登录态
redirectAction	string	条件必填	-	autoLogin=true 时的后端接口地址，按环境区分
showLoginConfirm	'0' | '1'	否	-	登录成功后是否展示授权页，'0' 不展示直接回跳；仅 location.href 分支生效
redirect_uri	string	否	location.href	登录完成后的回跳地址
tokenFailReturn	boolean | string	否	-	仅 autoLogin 时；true 则无论是否登录都 302 回原地址，用于允许未登录访问的站点
debug	boolean	否	false	只打印跳转地址，不执行跳转

校验与错误

场景	行为
authBaseUrl 为空	console.error('authBaseUrl must be has value') 后返回
channel 为空	console.error('channel must be has value') 后返回
autoLogin=true 且缺少 redirectAction	console.error('redirectAction must be has value when autoLogin is true') 后返回

测试

cd packages/utils
pnpm test