Sa-Token 的 token-prefix 和 token-style，到底谁管谁？

我前阵子给一套 Sa-Token 鉴权做接口标准化时，就把这两个配置混过一次。 后来才彻底想明白：token-prefix 管的是“怎么提交”，token-style 管的是“怎么生成”，它们压根不是一回事。

一、问题背景：看起来都在配 token，其实不是同一个层面

很多项目做前后端分离后，都会顺手做两件事：

• • 对外统一成 Authorization: Bearer xxx
• • 对内把 token 生成规则改成更短、更随机，或者更符合公司规范

这时候最容易犯的错就是： 把“请求头格式”和“token 内容格式”混在一起配。

结果通常很典型：

• • 前端已经带了 Bearer
• • 后端还是读不到 token
• • 改了 token-style 之后，问题没有任何改善

我一开始就走过一条弯路：

• • 先去改 token-style
• • 看到 token 长相变了，以为方向对了
• • 结果一抓包才发现，请求头里真正出问题的还是 Bearer

这不是 Sa-Token 有问题。 本质上是配置职责没分清。

二、先把概念掰开：一个管提交，一个管生成

💡 先记住一句话：prefix 是输入协议，style 是输出策略。

1）token-prefix：解决“前端怎么带 token”

如果前端提交的是这种格式：

{
  "satoken": "Bearer xxxx-xxxx-xxxx-xxxx"
}

后端如果不做处理，Sa-Token 会把 Bearer 当成 token 值的一部分。 这样一来，框架自然匹配不到真实 token，鉴权就会失败。

所以这时候你要配的是：

sa-token:
  token-prefix: Bearer

它的作用很明确：

• • 告诉框架：请求里可能会带固定前缀
• • 读取 token 时，先把这个前缀裁掉
• • 最终真正参与鉴权的，还是后面的 token 值

这里有个特别容易漏掉的细节：前缀和 token 之间必须有一个空格。

也就是说，正确的是：

Bearer xxxxx

不是：

Bearerxxxxx

2）token-style：解决“token 长什么样”

token-style 跟请求头格式没关系。 它控制的是 Sa-Token 生成 token 时采用哪种风格。

内置常见选项包括：

• • uuid
• • simple-uuid
• • random-32
• • random-64
• • random-128
• • tik

比如你想把默认 uuid 改成 64 位随机串，可以直接这么配：

sa-token:
  token-style: random-64

这一步只会改变 token 的生成样式。 它不会帮你处理 Bearer，也不会决定前端该怎么传。

3）想完全自定义，就改生成策略

如果内置风格都不满意，可以直接重写 SaStrategy.instance.createToken。

@Configuration
public class SaTokenConfigure {

    @PostConstruct
    public void rewriteSaStrategy() {
        SaStrategy.instance.createToken = (loginId, loginType) -> {
            return SaFoxUtil.getRandomString(60);
        };
    }
}

这时候你做的是“生成策略定制”。 和 token-prefix 一样，仍然不是一个层面的问题。

三、工程里怎么配最稳

我现在更推荐把这件事拆成两步做，职责非常清楚。

1）先统一提交协议：Header + Bearer

如果你希望接口对接更标准，建议直接统一成：

sa-token:
  token-name: Authorization
  is-read-header: true
  is-read-cookie: false
  token-prefix: Bearer

前端统一拦截器注入：

axios.interceptors.request.use((config) => {
  const token = localStorage.getItem('token');

  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }

  return config;
});

然后用命令先自测一遍：

curl http://localhost:8080/user/info \
  -H "Authorization: Bearer 这里替换成真实token"

这样你能很快确认一件事： 后端到底是“没收到”，还是“收到了但没识别”。

2）再决定 token 长相：内置风格优先

如果你只是觉得默认 uuid 太长，或者不符合团队习惯，先用内置风格就够了。

sa-token:
  token-style: random-64

我自己的经验是：

• • 对接系统多，优先追求兼容性，用 uuid 或 simple-uuid
• • 更偏向随机串风格，用 random-64
• • 没有明确需求时，不要一上来就自定义算法

先把协议跑通，再追求个性化。

3）Cookie 场景单独看，不要顺手混进去

这个坑很多人第一次都会踩。

因为 Cookie 里不能存空格字符。 而 Bearer xxx 中间偏偏就有一个空格。

所以你一旦配了 token-prefix，Cookie 模式就可能直接失效。 如果你确实还要继续走 Cookie，可以再加：

sa-token:
  cookie-auto-fill-prefix: true

它的作用是： 在 Cookie 模式下自动补齐提交前缀。

四、我踩过的 4 个高频坑

⚠️ 坑 1：把 token-style 当成 Bearer 兼容开关

• • 现象：前端已经传了 Bearer xxx，后端仍然未登录
• • 原因：改的是 token 生成样式，不是 token 提交格式
• • 修复：配置 token-prefix=Bearer

这个误会最常见。 因为两个配置名字里都有 token，看起来很像一类功能。

⚠️ 坑 2：前缀和 token 之间没空格

• • 现象：请求头看起来没问题，但始终读不到 token
• • 原因：传成了 Bearerxxxxx
• • 修复：改成 Bearer xxxxx

这个空格不是装饰，是协议的一部分。

⚠️ 坑 3：配了前缀之后，Cookie 登录态突然不生效

• • 现象：Header 模式正常，Cookie 模式异常
• • 原因：Cookie 无法直接存带空格的前缀格式
• • 修复：开启 cookie-auto-fill-prefix=true，或者直接禁用 Cookie 读取

如果项目本来就是前后端分离，我更建议直接走 Header。 这样链路更透明，排查也简单。

⚠️ 坑 4：自定义了生成策略，但看起来没生效

• • 现象：代码已经改了，生成出来的 token 还是老样子
• • 原因：Redis 里还躺着旧 token 数据，当前会话没有重新生成
• • 修复：清理旧数据，或者至少重新登录再验证

这个问题文档里其实已经点得很明确了。 你改的是“新 token 的生成规则”，不是“把历史 token 批量重写”。

五、我现在的固定方案

如果是标准前后端分离项目，我现在基本固定这套配置：

sa-token:
  token-name: Authorization
  is-read-header: true
  is-read-cookie: false
  token-prefix: Bearer
  token-style: random-64
  timeout: 2592000

这套方案的好处很直接：

• • 对外协议统一，前端和网关都好理解
• • 后端读取逻辑稳定，不靠猜
• • token 样式和提交协议彻底解耦
• • 后续真要自定义，也只动生成策略，不碰传输协议

🚀 这也是我现在最推荐的一套默认组合。

如果你必须兼容 Cookie，再按需补：

sa-token:
  cookie-auto-fill-prefix: true

别把所有模式揉在一起配。 认证链路最怕的不是功能少，而是职责不清。

六、工程总结

👇 最后提炼 3 条我认为最值钱的认知：

• • 认知 1：token-prefix 解决的是“请求如何提交”，token-style 解决的是“token 如何生成”。
• • 认知 2：先统一协议，再调整样式，排障成本会低很多。
• • 认知 3：凡是改 token 生成规则的操作，都要带着“旧会话是否还在”这个问题一起检查。

如果你最近也在折腾 Sa-Token，先别急着改一堆配置。 先问自己一句：

你现在要解决的，到底是“前端怎么带”，还是“后端怎么造”？

参考文档：

• • https://github.com/BNTang/Sa-Token-Demo/tree/main/sa-token-demo-prefix-style

相关文章推荐：

• • 智谱 GLM-4.7 编程第一
• • LangChain4j 结构化输出实战
• • 让 AI 不再失忆
• • Claude Code 免费指南
• • Agent Skills，让 AI 像老员工一样靠谱

如果这篇文章帮到了你，不妨点个分享给同样需要的朋友吧！ 你的每一次支持，都是我持续创作的动力！💪