本文详解如何在 Android 项目中正确引入 Nextcloud 官方 Android Library（com.github.nextcloud:android-library），重点解决 Gradle 同步时因仓库配置冲突导致的 Failed to resolve 错误，并提供兼容 AGP 8.0+ 的标准化配置方案。
本文详解如何在 android 项目中正确引入 nextcloud 官方 android library（`com.github.nextcloud:android-library`），重点解决 gradle 同步时因仓库配置冲突导致的 `failed to resolve` 错误，并提供兼容 agp 8.0+ 的标准化配置方案。
在将 Nextcloud Android 客户端能力复用至自有应用时，开发者常通过 JitPack 引入其开源的 android-library 模块。但自 Android Gradle Plugin（AGP）7.2+ 起，Gradle 构建系统强制推行仓库声明分离策略：pluginManagement 仅用于插件解析，而实际依赖（如 implementation 'com.github.nextcloud:android-library:latest.release'）必须在 dependencyResolutionManagement 中声明仓库——否则会触发 Build was configured to prefer settings repositories over project repositories 等明确拒绝错误。
✅ 正确配置步骤（适配 AGP 8.0.2+）
1. 修正 settings.gradle —— 将 JitPack 移至依赖仓库区
// settings.gradle
pluginManagement {
repositories {
google()
mavenCentral()
gradlePluginPortal()
// ❌ 不要在此处添加 jitpack（它不托管插件）
}
}
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
google()
mavenCentral()
maven { url "https://jitpack.io" } // ✅ 正确位置：此处支持普通依赖解析
}
}
rootProject.name = "app"
include ':app'
⚠️ 注意：
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)表示禁止在各模块的build.gradle中重复声明repositories{}，所有仓库必须统一在settings.gradle中定义，否则构建将直接失败。
2. 确保模块级 build.gradle 无冗余仓库声明
删除 app/build.gradle 中任何 repositories{} 块（如有），仅保留依赖声明：
// app/build.gradle（精简后）
plugins {
id 'com.android.application'
}
android {
namespace 'com.example.app'
compileSdk 33
// ... 其他配置保持不变
}
dependencies {
implementation 'androidx.appcompat:appcompat:1.6.1'
implementation 'com.google.android.material:material:1.5.0'
implementation 'androidx.constraintlayout:constraintlayout:2.1.4'
// ✅ Nextcloud library（自动从 JitPack 解析）
implementation 'com.github.nextcloud:android-library:latest.release'
}
3. 验证 JitPack 版本可用性
latest.release 是 JitPack 提供的动态别名，但并非所有分支/Tag 都被自动索引。若同步仍失败，请显式指定稳定版本（推荐查阅 Nextcloud Android Library Releases）：
// 替换为实际发布的版本号（例如 v4.5.0） implementation 'com.github.nextcloud:android-library:v4.5.0'
4. 清理缓存并重试
执行以下操作确保配置生效：
- 在 Android Studio 中点击 File → Invalidate Caches and Restart → Invalidate and Restart
- 或终端执行：
./gradlew --stop && ./gradlew clean && ./gradlew build --refresh-dependencies
? 常见误区与补充说明
-
不要在
build.gradle（Project）中写repositories{}：AGP 8.0+ 已弃用该方式，所有仓库需集中管理。 -
JitPack 不是 Maven Central 的镜像：它专为 GitHub 仓库构建分发服务，因此
android-library必须通过https://jitpack.io解析，无法通过mavenCentral()获取。 -
版本兼容性提醒：Nextcloud
android-library当前主干基于 AndroidX 和 Material 3，若项目使用旧版 Support Library，请先完成 AndroidX 迁移。 -
安全提示：JitPack 构建过程透明可审计，但建议生产环境锁定具体 SHA 或 Tag（如
v4.5.0），避免latest.release引入意外变更。
按上述配置完成后，Gradle 同步将成功拉取 Nextcloud Android Library，并可在代码中直接使用其核心类（如 AccountManager, RemoteOperation, OCFile）。此方案已验证兼容 AGP 8.0.2、Gradle 8.0 及 JDK 17 环境，是当前维护 Nextcloud 集成项目的标准实践。
