企业官网建设流程全解析

Sa-Token 最新版本说明与 Maven 依赖引入实战指南

【免费下载链接】Sa-Token✨ 开源、免费、一站式 Java 权限认证框架，让鉴权变得简单、优雅！—— 登录认证、权限认证、分布式 Session 会话、微服务网关鉴权、SSO 单点登录、OAuth2.0 统一认证、jwt 集成、API Key 秘钥授权、API 参数签名项目地址: https://gitcode.com/GitHub_Trending/sa/Sa-Token

本篇技术指南以 Sa-Token 官方版本发布信息为准，系统梳理当前正式版 v1.46.0 的 Maven 坐标、不同框架下的依赖引入方式、BOM 统一版本管理方案，以及 Maven 依赖拉取失败时的完整排查流程。读者读完本篇后，将能够在 Spring Boot 2.x/3.x/4.x、WebFlux、Solon、JFinal 等环境中正确引入并锁定 Sa-Token 版本，并独立解决依赖下载相关的常见问题。

当前最新版本总览

Sa-Token 采用"正式版 + 内测版"双轨发布机制：正式版经过完整测试、可稳定上生产；内测版为正在开发中的特性版本，稳定性不作保证，仅在开发者需要提前体验新功能时使用。

依据 sa-token-doc-new/docs/start/new-version.md 的版本说明，当前状态如下：

该版本号与仓库源码保持严格一致：根目录 pom.xml 中通过<revision>1.46.0</revision>统一声明版本，sa-token-bom/pom.xml 以及示例项目 sa-token-demo-springboot/pom.xml 中的<sa-token.version>1.46.0</sa-token.version>均指向同一版本，可从源码层面验证版本信息的准确性。

Maven 引入：基础坐标与版本选择

Sa-Token 的 Maven 坐标格式为cn.dev33:sa-token-xxx:<version>。以 Spring Boot（Servlet API）环境为例，在pom.xml中添加如下依赖即可：

<!-- Sa-Token 权限认证 --> <dependency> <groupId>cn.dev33</groupId> <artifactId>sa-token-spring-boot-starter</artifactId> <version>1.46.0</version> </dependency>

需要注意：不同基础框架需要引入不同的 starter 包，版本号必须保持一致。下表根据 sa-token-doc-new/docs/start/download.md 与仓库 sa-token-starter 模块结构整理：

从仓库 sa-token-starter 目录可以看到，sa-token-spring-boot-starter、sa-token-spring-boot3-starter、sa-token-spring-boot4-starter、sa-token-servlet、sa-token-jakarta-servlet等均以独立 Maven 模块存在，各环境按需取用即可，互不冲突。

使用版本属性的推荐写法

为避免项目中多处硬编码版本号导致升级遗漏，建议像官方示例项目 sa-token-demo-springboot/pom.xml 那样，先用<properties>定义版本号，再在依赖中引用：

<!-- 定义 Sa-Token 版本号 --> <properties> <sa-token.version>1.46.0</sa-token.version> </properties> <dependencies> <!-- Sa-Token 权限认证 --> <dependency> <groupId>cn.dev33</groupId> <artifactId>sa-token-spring-boot-starter</artifactId> <version>${sa-token.version}</version> </dependency> </dependencies>

这样在升级版本时只需修改一处属性即可。

配套插件依赖

除了启动器之外，Sa-Token 还提供大量功能插件，引入时同样使用cn.dev33坐标与同一版本号，例如：

• Redis 集成：sa-token-redis-jackson（jackson 序列化）、sa-token-redisson（Redisson 集成）
• JWT 集成：sa-token-jwt
• SSO 单点登录：sa-token-sso
• OAuth2.0 统一认证：sa-token-oauth2
• 注解鉴权（AOP）：sa-token-spring-aop
• API Key 秘钥授权：sa-token-apikey

这些插件模块均可在仓库 sa-token-plugin 目录下找到对应源码，且所有模块版本统一由根 POM 的<revision>属性管理。

使用 BOM 统一管理所有 Sa-Token 版本

当项目中同时引入多个 Sa-Token 模块（如 starter + Redis + JWT）时，逐个写版本号不仅繁琐，还容易造成版本不一致。官方提供了 BOM（Bill of Materials）包sa-token-bom来解决该问题。

参考官方示例 sa-token-demo-bom-import/pom.xml 的写法：通过dependencyManagement的import方式导入 BOM 后，所有 Sa-Token 依赖都无需再写版本号：

<properties> <sa-token.version>1.46.0</sa-token.version> </properties> <dependencies> <!-- Sa-Token 权限认证 --> <dependency> <groupId>cn.dev33</groupId> <artifactId>sa-token-spring-boot-starter</artifactId> </dependency> <!-- Sa-Token 整合 Redis (使用jackson序列化方式) --> <dependency> <groupId>cn.dev33</groupId> <artifactId>sa-token-redis-jackson</artifactId> </dependency> <!-- Sa-Token 整合 jwt --> <dependency> <groupId>cn.dev33</groupId> <artifactId>sa-token-jwt</artifactId> </dependency> </dependencies> <!-- 依赖管理 (不会真正的引入依赖，只会限定其版本) --> <dependencyManagement> <dependencies> <!-- Sa-Token 所有包的版本定义 --> <dependency> <groupId>cn.dev33</groupId> <artifactId>sa-token-bom</artifactId> <version>1.46.0</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement>

BOM 包本质上是一个只做版本管理、不引入任何实际依赖的 POM 工程。查看 sa-token-bom/pom.xml 可以看到，其全部内容位于dependencyManagement中，为sa-token-core、各 starter 与插件统一声明版本；正如示例中注释所言，"不会真正的引入依赖，只会限定其版本"。

Gradle 项目的引入方式

对于使用 Gradle 构建的项目，在build.gradle中引入 Sa-Token 同样简单（以 Spring Boot 环境为例）：

implementation 'cn.dev33:sa-token-spring-boot-starter:1.46.0'

其它环境的 Gradle 写法与 Maven 坐标一一对应：

// WebFlux 环境 implementation 'cn.dev33:sa-token-reactor-spring-boot-starter:1.46.0' // Solon 集成 implementation 'cn.dev33:sa-token-solon-plugin:1.46.0' // JFinal 集成 implementation 'cn.dev33:sa-token-jfinal-plugin:1.46.0' // 裸 Servlet 容器环境 implementation 'cn.dev33:sa-token-servlet:1.46.0' // 其它环境（core 核心包） implementation 'cn.dev33:sa-token-core:1.46.0'

引入后版本号同样替换为当前正式版1.46.0。

Maven 依赖一直拉取失败？完整排查手册

即使 Maven 坐标完全正确，实际开发中仍可能遇到依赖无法下载的问题。根据官方排查文档 sa-token-doc-new/docs/start/maven-pull.md，可按以下顺序依次排查：

方法 1：先重启构建

依赖拉取失败有时只是 IDE 缓存或网络瞬断导致，先重启一下 IDE / 重新构建项目试试，这是成本最低的排查手段。

方法 2：检查构建进度

可能依赖还没有下载完毕，请观察编辑器下方是否有正在构建项目的进度条，等待构建完成后再次检查。

方法 3：清理本地仓库的残碎文件

网络不稳定时，Maven 可能只下载了部分残碎文件（.lastUpdated文件），这些残留会导致后续重试始终失败。此时应删除本地仓库中的 Sa-Token 相关目录后重新构建：

C:\Users\你的电脑用户名\.m2\repository\cn\dev33

打开该目录，把其中文件全部删除即可（如果你自定义过 Maven 本地仓库路径，请按修改后的路径操作）。

方法 4：排查阿里云镜像配置

很多开发者会在settings.xml中配置阿里云镜像加速下载，但部分 jar 包无法通过阿里云镜像加载成功，从而造成"坐标正确却始终拉不下来"的现象。打开 Maven 的settings.xml，检查是否存在以下配置：

<mirror> <id>nexus-aliyun</id> <mirrorOf>central</mirrorOf> <name>Nexus aliyun</name> <url>http://maven.aliyun.com/nexus/content/groups/public</url> </mirror>

如果有，先将其注释掉（注释掉即直连 Maven 中央仓库），或替换为其它镜像，例如腾讯云镜像：

<mirror> <id>tencent</id> <name>tencent maven</name> <url>http://mirrors.cloud.tencent.com/nexus/repository/maven-public/</url> <mirrorOf>central</mirrorOf> </mirror>

修改完成后重启代码编辑器，重新构建项目。

方法 5：父子 Maven 项目的依赖识别问题

如果使用的是父子 Maven 项目，在父项目中导入该依赖后出现 POM 无法识别的情况，需要先在子项目中引用该依赖，再进行重新加载。

若依然不行，可以新建一个小的 Maven 项目，先尝试将该依赖下载成功，再返回原父子项目中将该依赖导入。

最后手段：寻求社区反馈

若上述方法均无法解决，可以在 Sa-Token 社区群中反馈问题，附上你的构建日志与 Maven 配置，便于快速定位。

从源码验证版本与模块结构

以上所有说明均可在当前仓库中得到验证：

• 版本号：根 pom.xml 的<revision>1.46.0</revision>与 sa-token-doc-new/docs/start/new-version.md 中"正式版本 v1.46.0"一致；
• Starter 模块：sa-token-spring-boot-starter、sa-token-spring-boot3-starter、sa-token-spring-boot4-starter、sa-token-reactor-spring-boot-starter等均在 sa-token-starter 下以独立模块存在，sa-token-bom/pom.xml 的dependencyManagement为其统一锁定版本；
• 插件模块：Redis、JWT、SSO、OAuth2 等插件位于 sa-token-plugin 目录，与 BOM 中声明一一对应；
• 官方示例：sa-token-demo-springboot 展示了最基础的引入方式，sa-token-demo-bom-import 展示了 BOM 统一版本管理方式，均可直接作为新项目配置的参照模板。

小结

Sa-Token 当前正式版本为v1.46.0，无内测版。引入时只需记住三点：一是按运行环境选择正确的 starter 依赖（Servlet / Reactor / Solon / JFinal / core 等）；二是保持所有 Sa-Token 模块版本号一致，多模块项目优先通过sa-token-bom统一管理；三是遇到依赖拉取失败时，按"重启 → 清理本地仓库 → 排查镜像 → 处理父子工程"的顺序排查，绝大多数问题都可迎刃而解。

【免费下载链接】Sa-Token✨ 开源、免费、一站式 Java 权限认证框架，让鉴权变得简单、优雅！—— 登录认证、权限认证、分布式 Session 会话、微服务网关鉴权、SSO 单点登录、OAuth2.0 统一认证、jwt 集成、API Key 秘钥授权、API 参数签名项目地址: https://gitcode.com/GitHub_Trending/sa/Sa-Token