同一份build.gradle为何引入不同org.json:json版本？如何解决？

这种依赖版本冲突的坑我在团队协作中碰到过好多次——明明看着build.gradle一模一样，结果本地跑起来就因为某个方法的差异报错。咱们先搞清楚为啥会出现这种情况，再解决问题。

为什么会出现版本差异？ #

主要是Gradle的依赖解析机制和一些隐藏的配置差异导致的：

• 传递依赖冲突：你的项目里可能有其他第三方依赖，间接引入了2013版的org.json，而同事那边的依赖树里，要么没有这个间接依赖，要么某个依赖引入的是2010版。Gradle默认的冲突解决策略是选择最新的版本，所以如果你的依赖树里有更高版本的间接依赖，就会覆盖显式声明的版本（如果你们没指定具体版本的话）。
• 隐藏的配置差异：虽然根build.gradle看起来一样，但可能存在这些情况：
  • 子模块的build.gradle里单独声明了不同版本的org.json；
  • gradle.properties文件里有版本变量，你和同事的这个文件内容不一样；
  • 本地全局Gradle配置（比如~/.gradle/init.gradle）里有强制依赖版本的规则，和同事的配置不同。
• 仓库顺序或缓存问题：极少数情况下，不同仓库里的版本不同，Gradle解析时选了不同的；或者本地Gradle缓存里已经有2013版，而同事的缓存是2010版，导致下载的版本不一样。

怎么确保和同事用一样的版本？ #

这里有几个递进的解决办法，从快速解决到长期规范：

1. 强制指定目标版本（最快解决） #

直接在build.gradle里强制使用同事的2010版，不管其他依赖怎么引入，都统一用这个版本：

dependencies {
    // 如果显式声明了依赖，加force强制版本
    implementation('org.json:json:20100204') {
        force = true
    }

    // 更推荐用依赖约束，统一管控所有地方的依赖版本
    constraints {
        implementation('org.json:json:20100204') {
            because "与团队保持一致版本，避免JSONObject.getString()方法差异"
        }
    }
}

依赖约束的好处是，不管是显式声明还是间接引入的org.json，都会被强制改成指定版本，比单独给每个依赖加force更高效。

2. 找出冲突来源，精准排除 #

如果你想搞清楚到底是哪个依赖引入了2013版，可以运行Gradle的依赖树命令：

# macOS/Linux
./gradlew dependencies

# Windows
gradlew.bat dependencies

搜索org.json:json，就能看到所有引入这个依赖的路径，比如：

+--- some-third-party-lib:1.0.0
|    \--- org.json:json:20130218

找到这个第三方库后，就在依赖声明里排除它带来的org.json：

implementation('some-third-party-lib:1.0.0') {
    exclude group: 'org.json', module: 'json'
}

这样就能避免它引入的高版本覆盖你需要的2010版。

3. 清理本地缓存，重新下载 #

如果是本地缓存的问题，强制Gradle刷新依赖，重新下载正确的版本：

# macOS/Linux
./gradlew clean build --refresh-dependencies

# Windows
gradlew.bat clean build --refresh-dependencies

这个命令会清理本地缓存，重新从仓库拉取所有依赖，确保和同事的版本一致。

4. 统一团队的依赖管理（长期规范） #

为了避免以后再出现类似问题，建议团队统一依赖版本管理：

• 使用Gradle的Version Catalog（Gradle 7.0+支持）：把所有依赖版本定义在libs.versions.toml文件里，所有人共用这个文件，比如：

  [versions]
  json = "20100204"
  
  [libraries]
  json = { group = "org.json", name = "json", version.ref = "json" }
  

  然后在build.gradle里引用：

  implementation libs.json
  

• 把gradle.properties、libs.versions.toml这些配置文件都提交到Git仓库，确保所有人拉取的代码都有相同的依赖配置。

内容的提问来源于stack exchange，提问作者Ahmed Elkoussy