Maven依赖解析失败：从sqljdbc4到mssql-jdbc的迁移与排障实践

最近连着两个项目碰到同一个报错：pom.xml 里明明写的是 com.microsoft.sqlserver:sqljdbc4:4.0，但 Maven 就是卡在 Cannot resolve com.microsoft.sqlserver:sqljdbc4:4.0，IDEA 中依赖列表红成一片，mvn compile 直接失败。这个报错看起来像网络问题，实际排查下来，大多数情况是坐标本身已经过时、写法有误，或者依赖根本没被正确放进仓库。这篇文章我把从报错现场到最终落地解决的各种路径都梳理一遍，给还在跟 SQL Server JDBC 驱动死磕的同学一个能直接照着做的参考。

1. 为什么一个看似合法的坐标会解析失败

1.1 先看看最常见的几种报错现场

同一个报错背后，实际的项目代码可能完全不一样。我归纳了三种高频现场，你可以先对号入座：

第一种，也是最常见的一种，pom.xml 里写了：

xml复制<dependency>
    <groupId>com.microsoft.sqlserver</groupId>
    <artifactId>sqljdbc4</artifactId>
    <version>4.0</version>
</dependency>

然后 IDEA 提示 Cannot resolve com.microsoft.sqlserver:sqljdbc4:4.0。

第二种，是把坐标拼错了。比如把 artifactId 写成 sqljdbc44、sqljdbc4.0，或者把 groupId 写成 com.microsoft.sqlserver.jdbc，又或者版本号写成 4.0.0。这类错字问题表面上看也是 Cannot resolve，但根子完全不一样。标题里那个 sqljdbc44.0 一眼就是书写错误，实际 Maven 坐标里不存在这个写法。

第三种，是公司用的私服或镜像没有同步过这个 artifact。本地 Maven 仓库里没有，私服也没有，中央仓库又因为网络配置访问不到，于是报错。

这三种情况的表象完全一样，但处理方式不同。所以遇到报错不要急着改配置，先把错误信息的上下文看全。Maven 在报 Cannot resolve 的同时，通常会给出完整的 groupId:artifactId:version 三段坐标，先确认你写的坐标和报错坐标是否一致，不一致就说明是拼写问题。

1.2 Maven 是如何找依赖的

要理解这个报错，得先搞清楚 Maven 找依赖的过程。Maven 坐标由 groupId:artifactId:version 三段组成，它定义了一个依赖的唯一身份。你可以把它理解成快递收件地址：国家、城市、街道都写对了，包裹才能送到。三段里任何一段不匹配，甚至大小写不对，都无法找到对应的 jar 包。

Maven 解析依赖的顺序是固定的：

1. 先在本地仓库找，默认是 ~/.m2/repository；
2. 本地没有，再看全局 settings.xml 里配置的 mirror 镜像仓库；
3. 再看项目 pom.xml 里声明的 <repository>；
4. 最后才会访问中央仓库。

Cannot resolve 的本质，就是这套顺序走完了，仍然没有在任何一个位置找到对应坐标的 jar 包和 pom 文件。

这里有个很容易忽略的点：如果本地 ~/.m2 里已经缓存了某个坐标的 _remote.repositories 元数据，并且它记录了"这个文件来自某个具体的仓库地址"，那么 Maven 在解析时会做仓库归属校验。私服地址变了、镜像变了，哪怕本地明明有 jar，也可能重新去远程拉，一旦远程拉不到就报 Cannot resolve。这属于比较隐蔽的情况，后面会专门讲。

1.3 sqljdbc4 4.0 的历史遗留属性

sqljdbc4 4.0 这个坐标之所以让人头疼，很大程度是因为微软 JDBC 驱动早期的命名和发布方式比较混乱。

早期微软发布的 SQL Server JDBC Driver 版本和 Java 版本强绑定。4.0 对应的是旧版的 sqljdbc4.jar，接着又有 4.1、4.2 等版本。不同 JDK 要使用不同 jar：

• sqljdbc4 4.0 支持 JDK 5、6、7；
• sqljdbc41 4.1 支持 JDK 7；
• sqljdbc42 4.2 支持 JDK 8。

后来微软统一改为 com.microsoft.sqlserver:mssql-jdbc 作为官方坐标，jar 包按 jre7、jre8、jre11、jre17 等后缀区分。也就是说，sqljdbc4:4.0 是一个已经被官方后续版本取代的旧坐标。

但问题在于，很多老教程和博客写的就是 sqljdbc4:4.0。新手照着复制，自然踩坑。而且旧坐标里的 4.0 这个版本非常老，即便能下载到，对于 JDK 8 以上的现代项目也未必适配。

这也是我在建议方案时，永远把"迁移到新版官方坐标"放在第一位的原因。你当然可以花时间让旧坐标在某个环境里能解析，但本质上是在给历史包袱买单。

2. 首选方案：切换到 mssql-jdbc 官方坐标

2.1 新旧坐标怎么选

直接说结论：如果条件允许，请把依赖换成官方推荐的新坐标。

以 JDK 8 为例，pom.xml 改成这样：

xml复制<dependency>
    <groupId>com.microsoft.sqlserver</groupId>
    <artifactId>mssql-jdbc</artifactId>
    <version>7.4.1.jre8</version>
</dependency>

这个坐标在 Maven 中央仓库是正常发布的，绝大多数网络环境都能直接解析。换完之后，原来的报错通常会消失。

2.2 根据 JDK 和 Spring Boot 版本挑驱动

mssql-jdbc 的版本号后面带 jre 后缀，本质是告诉你这个 jar 编译时针对哪个 Java 版本。选错后缀不会导致 Cannot resolve，但运行时可能报 UnsupportedClassVersionError，比如在 JDK 11 环境里用了 jre8 的旧版本，或者更极端地在 JDK 8 里用了 jre17 的类文件。

给一个实用的选择参考：

如果你用的是 Spring Boot，情况会更简单。Spring Boot 的 spring-boot-dependencies 已经帮你管理了 mssql-jdbc 的版本，你可以在 pom 里直接写：

xml复制<dependency>
    <groupId>com.microsoft.sqlserver</groupId>
    <artifactId>mssql-jdbc</artifactId>
    <scope>runtime</scope>
</dependency>

不写版本号，让 Spring Boot 的 BOM 决定。但要注意，不同 Spring Boot 版本管理的驱动版本差异很大。比如 Spring Boot 2.7.x 默认管理的是 10.2.0.jre8，Spring Boot 3.x 默认管理的是更高版本且需要 JDK 17 环境。如果项目 JDK 版本和 Spring Boot 默认管理的驱动版本不匹配，就需要显式覆盖版本号。

2.3 切换后代码需要改吗

这是大家最关心的问题。好消息是，从 sqljdbc4 切到 mssql-jdbc，绝大多数代码不需要改。

驱动类名还是 com.microsoft.sqlserver.jdbc.SQLServerDriver，JDBC URL 格式还是：

code复制jdbc:sqlserver://localhost:1433;databaseName=mydb;encrypt=true;trustServerCertificate=true

数据库连接池里配置的 driverClassName、url 都不变。如果你用的是 Spring Boot 的 spring.datasource 配置，更是只换依赖坐标即可：

yaml复制spring:
  datasource:
    driver-class-name: com.microsoft.sqlserver.jdbc.SQLServerDriver
    url: jdbc:sqlserver://127.0.0.1:1433;databaseName=test
    username: sa
    password: your_password

真正需要注意的反而是新版驱动对加密连接默认行为的改变。较新版本的 mssql-jdbc 驱动默认 encrypt=true，如果 SQL Server 实例没有配置 TLS 证书，会报连接错误。对于本地测试环境，可以在 JDBC URL 里加上 encrypt=true;trustServerCertificate=true 或者 encrypt=false。这一步和依赖解析无关，但很多人换完驱动后卡在这里，我特意提一下。

3. 兼容老项目的兜底方案：手动安装 jar 到本地仓库

3.1 保留旧坐标的动机

有些老项目短期内没法升级。比如项目里已经写死了 sqljdbc4:4.0，其他模块大量引用了这个坐标，或者业务代码里强制依赖旧 jar 的内部行为。这种情况下，可以先不切换，用"手动安装 jar 到本地仓库"的方式让 Maven 能解析到它。

我需要先提醒一句：这是一个兜底方案，不是首选。它的意义在于解决单机开发环境的问题，而不是消除依赖本身的历史债务。

3.2 install-file 命令的完整用法

操作分三步：拿到 jar 文件，执行 Maven 命令，验证本地仓库。

第一步，拿到正确的 sqljdbc4.jar。可以从微软官方下载历史版本的 JDBC 驱动包，也可以从本地已有的 Maven 仓库、旧项目 lib 目录里找。优先使用官方渠道，避免使用不明来源的 jar。下载完成后，确认 jar 包能够正常打开，里面存在 com/microsoft/sqlserver/jdbc/SQLServerDriver.class。

第二步，执行安装命令。打开命令行，在项目根目录运行：

bash复制mvn install:install-file \
  -Dfile=./lib/sqljdbc4.jar \
  -DgroupId=com.microsoft.sqlserver \
  -DartifactId=sqljdbc4 \
  -Dversion=4.0 \
  -Dpackaging=jar

执行成功后，控制台会输出类似 BUILD SUCCESS 的信息。此时去 ~/.m2/repository/com/microsoft/sqlserver/sqljdbc4/4.0/ 目录下，能看到 sqljdbc4-4.0.jar 和一个 sqljdbc4-4.0.pom 文件。

第三步，回到 pom.xml，原来的依赖坐标不用改，直接重新刷新 Maven 项目即可。

这里有个细节：-Dfile 后面可以写绝对路径，也可以写相对路径。建议把 jar 放到项目下的 lib 目录里，用 -Dfile=./lib/sqljdbc4.jar，这样命令的可读性和可维护性更好。

3.3 手动安装的坑：本地能用不代表团队能用

这个方案最大的问题，在于它只解决"你这一台机器"的编译问题。

你执行 install-file 后，jar 进入的是本地 ~/.m2/repository。换一台机器，或者持续集成环境（CI）跑构建时，本地仓库是全新的，依旧会报 Cannot resolve。如果说你提交代码到 Git 之后，同事拉下来还是会遇到一样的报错，大家需要各自手动执行一次安装命令，这是非常低效的团队协作方式。

如果团队决定保留 sqljdbc4:4.0 这个坐标，正确的做法应该是用 Nexus 或 Artifactory 这样的私服，通过 mvn deploy:deploy-file 将 jar 上传到私服仓库。然后团队成员统一从私服拉取。

举例，上传命令大致是：

bash复制mvn deploy:deploy-file \
  -Dfile=./lib/sqljdbc4.jar \
  -DgroupId=com.microsoft.sqlserver \
  -DartifactId=sqljdbc4 \
  -Dversion=4.0 \
  -Dpackaging=jar \
  -Durl=http://私服地址/repository/maven-releases/ \
  -DrepositoryId=私服认证id

上传后，pom.xml 无需改动，所有配置了私服镜像的机器都能解析到。这条路比每个开发者手动 install 要稳得多，但需要私服管理员权限，不是每个人都能做。

4. 再退一步的解法：本地 lib 与仓库镜像排查

4.1 用 system scope 指向 lib 目录

如果实在不想动私服、不想改坐标，还有一个"土办法"：用 <scope>system</scope> 指定 jar 的本地路径。

xml复制<dependency>
    <groupId>com.microsoft.sqlserver</groupId>
    <artifactId>sqljdbc4</artifactId>
    <version>4.0</version>
    <scope>system</scope>
    <systemPath>${project.basedir}/lib/sqljdbc4.jar</systemPath>
</dependency>

这样做的好处是立竿见影，项目里用到的 jar 直接放在 lib 目录，和源码一起进 Git。但坏处也很明显：

system scope 的依赖在打可执行 jar 包时，不会被 spring-boot-maven-plugin 默认打进 BOOT-INF/lib。也就是说，本地 IDEA 里运行没问题，打包部署到服务器后，运行时报 ClassNotFoundException: com.microsoft.sqlserver.jdbc.SQLServerDriver。

要解决打包问题，需要额外配置：

xml复制<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <configuration>
        <includeSystemScope>true</includeSystemScope>
    </configuration>
</plugin>

即便如此，这种方案依然会破坏 Maven 依赖管理的一致性。依赖的版本无法通过 Maven 传递、冲突检测也失效。我的建议是：system scope 只适合临时调试，不建议作为正式项目长期方案。

4.2 仓库源问题的排查：镜像和私服

有些时候 Cannot resolve 并不是坐标或版本的问题，而是仓库源本身有问题。

我在 1.2 节说了 Maven 的查找顺序，这里展开讲镜像配置。假设你的项目在公司的私服环境里，私服没有从中央仓库同步 mssql-jdbc，或者同步策略只允许白名单 groupId，那么改成新坐标后依然会报 Cannot resolve。

排查方式：

1. 看 ~/.m2/settings.xml 里的 <mirror> 配置。如果 mirrorOf 配的是 *，代表所有仓库请求都走这个镜像地址，此时中央仓库的访问被镜像接管；
2. 尝试直接访问镜像 URL，看对应坐标的目录是否存在。比如访问 http://私服地址/repository/maven-public/com/microsoft/sqlserver/，验证目录列表里有没有 mssql-jdbc；
3. 用 Maven 命令强制刷新并显示详细信息：

bash复制mvn clean compile -U -X

-U 强制更新远程快照和发布版本元数据，-X 输出调试级别的日志。在日志里搜索 mssql-jdbc 或 sqljdbc4，能看到 Maven 实际尝试访问的仓库地址和返回结果。

我遇到过一种情况：本地 ~/.m2/repository/com/microsoft/sqlserver/ 目录里已经有 sqljdbc4 的 jar，但 Maven 依然报 Cannot resolve。原因是 _remote.repositories 文件记录的仓库 ID 与当前镜像 ID 不一致，Maven 判定本地文件不可信，重新去远程拉取但拉不到。解决办法是删掉本地对应目录，重新执行依赖解析。

4.3 不建议长期使用本地依赖的原因

上面几种方案有一个共同问题：都在绕过 Maven 中央仓库的标准依赖管理。

依赖管理的本质是让构建可复现、可传递、可审计。你手动放置 jar、用 system scope、修改私服白名单，都会让"依赖从哪里来"这件事变得不透明。新同事入职、CI 环境构建、生产环境发版，一旦依赖获取链路不统一，就会出现"我本地编译是好的，但服务器上不行"的经典问题。

这也是我反复建议切换到 mssql-jdbc 的原因。新坐标在中央仓库直接可解析，不需要额外配置，行为可预期，后续升级也方便。

5. 从依赖解析到真正连上 SQL Server 的最后一公里

5.1 驱动类名、URL 格式和常见连接配置

依赖坐标修完，构建能通过了，接下来就是运行时连接。很多新手把精力花在依赖报错上，结果依赖好了又卡在连接上。这里我把连接配置的常见内容一起列出来。

JDBC 驱动类名：

code复制com.microsoft.sqlserver.jdbc.SQLServerDriver

JDBC URL 基础格式：

code复制jdbc:sqlserver://<host>:<port>;databaseName=<dbname>;<property>=<value>;[;<property>=<value>]

常见参数：

SQL Server 的默认端口是 1433。如果实例使用命名实例或动态端口，URL 需要单独处理，比如使用 host\instance 的写法。不过对绝大多数 Java 项目来说，上面的基础格式够用了。

5.2 Spring Boot 项目中容易踩的坑

Spring Boot 项目里除了依赖坐标本身，还有几个高频坑：

第一个，是依赖版本被 BOM 覆盖。你手动在 dependencies 里写了 mssql-jdbc 的某个版本，但 Spring Boot 的 spring-boot-dependencies 如果已经管理了这个 artifact，你写的版本号会被忽略（除非显式用 property 覆盖）。这通常不是坏事，但如果你不确定当前使用的是哪个版本，可以运行：

bash复制mvn dependency:tree -Dincludes=com.microsoft.sqlserver:mssql-jdbc

查看实际生效的版本。

第二个，是旧依赖传递导致的冲突。有些老项目的其它模块传递引用了 sqljdbc4 或 jtds 等旧驱动，导致运行时出现多个 SQL Server 驱动类。排除方法是在依赖声明里加 <exclusions>：

xml复制<dependency>
    <groupId>com.example</groupId>
    <artifactId>some-module</artifactId>
    <exclusions>
        <exclusion>
            <groupId>com.microsoft.sqlserver</groupId>
            <artifactId>sqljdbc4</artifactId>
        </exclusion>
    </exclusions>
</dependency>

第三个，是时区和日历相关的连接参数。SQL Server 的 datetime 类型和 Java 8 时间类型映射时，如果出现时区偏差，检查 JDBC URL 是否设置了 useBulkCopyForBatchInsert、sendTimeAsDatetime 等参数。虽然不是所有项目都会遇到，但我处理过不下三个因时区问题排查到驱动层面的案例。

5.3 快速自检清单

最后整理一个自检清单，报错的时候按顺序排查：

写在最后的一些实际操作体会

这个报错我断断续续处理过好几次，我的常规处理顺序是：先看坐标有没有拼错，然后确认项目 JDK 和 Spring Boot 版本，优先把依赖切到 mssql-jdbc。只有当地旧项目实在动不了的时候，才会用 mvn install:install-file 手动装到本地仓库。

排查过程中最耗时间的往往不是命令执行，而是环境差异。比如 CI 上报错而本地不报、同事不报而你不报，这类情况十有八九是仓库源或本地缓存不一致。遇到这种场景，先删本地 ~/.m2/repository 里对应 artifact 目录，再 mvn clean compile -U -X 看具体访问记录，基本都能找到根因。

另外提醒一句，换驱动版本后别急着跑业务逻辑，先写一个最简单的 JDBC 连接测试。用一个几行的 main 方法确认驱动类能加载、URL 能连通，再往上层接业务代码，排查边界就清晰很多。