企业官网建设流程全解析

Sa-Token Maven 依赖拉取失败排查指南：从本地缓存、镜像源到父子工程的完整解决方案

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

本篇以 Sa-Token 官方文档《Maven 依赖一直无法拉取成功？》为骨架，结合仓库内真实的 Maven 工程结构与依赖坐标，系统梳理 Maven 拉取 Sa-Token 依赖失败的五大排查方向：重启与等待、清理本地残碎缓存、镜像源排查、父子工程依赖识别问题，以及最后的兜底手段。读完你不仅能独立解决"依赖一直拉不下来"的日常问题，还能理解 Sa-Token 的坐标体系（cn.dev33下的 Starter、Core、Plugin 各模块）与本地仓库布局，从而在 Maven 构建时少走弯路。

一、先搞清楚你要拉取的到底是什么：Sa-Token 的 Maven 坐标体系

排查依赖问题之前，先确认坐标本身没有写错。Sa-Token 所有制品统一以cn.dev33为 groupId，版本号由仓库根 POM 统一管理。当前仓库根 pom.xml 声明了groupId=cn.dev33、artifactId=sa-token-parent，并在 pom.xml 中通过revision属性将当前版本定义为1.46.0；sa-token-doc-new/docs/start/new-version.md 也确认 v1.46.0 为当前正式版本，可直接上生产。

常见的引入方式（以 Spring Boot 项目为例）：

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

需要注意 artifactId 会随宿主框架变化：Spring Boot 2.x 用sa-token-spring-boot-starter，3.x 用sa-token-spring-boot3-starter，4.x 用sa-token-spring-boot4-starter（见 sa-token-doc-new/docs/start/example.md）。全部可用坐标（Core、Starter、Plugin 各模块）统一定义在 sa-token-bom/pom.xml 的<dependencyManagement>中；官方示例 sa-token-demo/sa-token-demo-springboot/pom.xml 展示了真实的引入写法。

确认坐标无误后，如果依赖依然拉取失败，按下面的方法逐一排查。

二、方法 1：先重启你的代码编辑器

这是成本最低的一步。IDE 的 Maven 索引、本地缓存模型可能停留在上一次失败的状态，导致即便依赖已经下载成功，编辑器依然显示"找不到依赖"。重启编辑器会强制其重新读取pom.xml并触发重新导入，许多"假性拉取失败"在这一步就解决了。

三、方法 2：检查编辑器下方是否正在构建项目

首次引入依赖（或切换了版本号）时，Maven 需要解析整个依赖树并逐个下载 jar，这一过程可能持续数十秒甚至更久。此时编辑器底部通常会出现"正在构建 / Resolving dependencies"之类的进度条。只要进度条还在走，就说明依赖尚未下载完毕，请耐心等待构建完成再判断是否真的失败，避免误删缓存导致重复下载。

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

网络不稳定时，Maven 可能只下载了 jar 的一部分（典型的.lastUpdated残片或半截文件）就中断了。这些残碎文件不会被自动覆盖，Maven 看到"已存在"就会跳过重新下载，从而表现为"永远拉不下来"。

Sa-Token 相关制品的本地路径一般位于：

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

打开该目录，把其中内容全部删除，然后重新构建项目。之所以能精确定位到这个目录，是因为 Sa-Token 的 groupId 就是cn.dev33，本地仓库会按groupId/artifactId/version三级目录组织，例如cn\dev33\sa-token-core\1.46.0\、cn\dev33\sa-token-spring-boot-starter\1.46.0\等。

注意：如果你修改过 Maven 的本地仓库目录（例如在settings.xml中自定义了<localRepository>），就按你配置的路径去清理，而不一定是上述默认路径。

Linux/macOS 下对应路径为~/.m2/repository/cn/dev33（Windows 下~即C:\Users\你的电脑用户名）。清理后可用以下命令强制刷新并重新解析依赖，验证是否恢复：

mvn -U clean compile

-U参数强制检查远程仓库的最新快照，可帮助绕过本地缓存的"坏味道"。

五、方法 4：排查 Maven 镜像源配置

这是国内开发者最常踩的坑。很多人为了加速依赖下载，在settings.xml中配置了阿里云镜像，但部分 jar 包（尤其是较新的版本或冷门制品）在阿里云镜像上同步不及时或加载异常，就会导致"明明配置了镜像反而拉不下来"。

打开 Maven 的settings.xml（全局配置通常在 Maven 安装目录的conf\settings.xml，用户级配置在C:\Users\你的电脑用户名\.m2\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>

如果有，有两种处理方式：

1. 将其注释掉——<mirrorOf>central</mirrorOf>表示该镜像接管了 Maven 中央仓库（central）的所有请求，注释掉后即恢复直连 Maven 中央仓库；
2. 替换为其它镜像，例如腾讯云镜像：

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

修改完成后，重启代码编辑器并重新构建项目。需要说明的是：镜像配置是 Maven 的通用能力，与 Sa-Token 本身无关；当前仓库的所有制品都发布在 Maven 中央仓库，直连中央仓库或使用同步及时的镜像均可正常拉取。

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

如果你使用的是父子（多模块）Maven 工程，可能出现"在父项目pom.xml中声明了 Sa-Token 依赖，但子模块却报找不到依赖"的情况。这通常不是下载失败，而是 IDE 的 Maven 模型没有正确传播依赖。

处理步骤如下：

1. 先在子项目中显式引用该依赖，再执行"重新加载 / Reload All Maven Projects"，让 IDE 以子模块为粒度重新解析依赖；
2. 如果仍然不行，新建一个最小的单模块 Maven 项目，先单独把该依赖下载到本地仓库，再回到原父子项目中导入该依赖。由于依赖已经存在于本地仓库cn/dev33目录下，父项目再次解析时就会命中本地缓存，从而绕过解析失败的问题。

这一做法利用了 Maven 本地仓库的"命中即用"特性：一旦某个坐标（如cn.dev33:sa-token-core:1.46.0）在本地仓库中完整存在，任何项目的解析都会直接复用，不再发起网络请求。

七、验证与兜底：如何确认依赖真正就绪

完成上述任意一步后，可通过以下方式验证依赖是否真正就绪：

• 观察 IDE 的依赖树：展开项目依赖（如 IntelliJ IDEA 的 External Libraries），确认sa-token-*相关 jar 已出现；
• 命令行确认解析结果：

mvn dependency:resolve

• 直接检查本地仓库：确认cn/dev33下对应坐标的目录中存在完整的.jar文件，且不存在*.lastUpdated残片。

如果以上五种方法全部尝试后依然无法解决，可以在 Sa-Token 的社区群里反馈，附上你的pom.xml依赖声明、Maven 版本与settings.xml镜像配置，方便快速定位问题。

八、进阶建议：用官方 BOM 统一版本管理

排查完问题后，为避免不同模块版本不一致引发的二次麻烦，可考虑引入官方 BOM sa-token-bom（它统一约束了 Core、Starter、Plugin 各模块的版本）：

<dependencyManagement> <dependencies> <dependency> <groupId>cn.dev33</groupId> <artifactId>sa-token-bom</artifactId> <version>1.46.0</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement>

之后引入各模块时即可省略<version>，由 BOM 统一接管，从根源上减少"版本写错导致拉取不到"的排查成本。最新版本号以 sa-token-doc-new/docs/start/new-version.md 为准。

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