常见问题 FAQ

安装与环境

Q：运行 ./gradlew 时提示 Permission denied

# Linux/macOS
chmod +x gradlew
./gradlew build

Q：下载依赖很慢或超时

配置国内镜像（在 ~/.gradle/init.gradle 全局配置）：

allprojects {
    repositories {
        def ALIYUN = 'https://maven.aliyun.com/repository/public'
        all { ArtifactRepository repo ->
            if (repo instanceof MavenArtifactRepository &&
                repo.url.toString() == 'https://repo1.maven.org/maven2/') {
                remove repo
            }
        }
        maven { url ALIYUN }
    }
}

Q：Gradle 构建很慢，每次都要配置

启用守护进程和配置缓存：

# gradle.properties
org.gradle.daemon=true
org.gradle.configuration-cache=true
org.gradle.caching=true
org.gradle.parallel=true

Q：JAVA_HOME 未设置

# Linux/macOS
export JAVA_HOME=$(/usr/libexec/java_home -v 17)  # macOS
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64  # Linux

# 或使用 Toolchain（推荐）
java { toolchain { languageVersion.set(JavaLanguageVersion.of(17)) } }

---

依赖问题

Q：依赖下载失败，报 Connection refused

1. 检查网络连接
2. 配置代理：

# gradle.properties
systemProp.http.proxyHost=proxy.example.com
systemProp.http.proxyPort=8080
systemProp.https.proxyHost=proxy.example.com
systemProp.https.proxyPort=8080

Q：版本冲突：Multiple values found for artifact

# 查看冲突来源
./gradlew dependencyInsight --dependency conflicting-lib

# 强制指定版本
configurations.all {
    resolutionStrategy.force("com.example:conflicting-lib:2.0.0")
}

Q：SNAPSHOT 依赖没有更新

# 强制刷新依赖（不使用缓存）
./gradlew build --refresh-dependencies

# 或配置不缓存 SNAPSHOT
configurations.all {
    resolutionStrategy.cacheChangingModulesFor(0, TimeUnit.SECONDS)
}

Q：找不到依赖（Could not resolve）

1. 检查依赖坐标是否正确（可在 Maven Central 查找）
2. 检查仓库配置是否包含该依赖所在仓库
3. 尝试 ./gradlew build --refresh-dependencies

---

构建问题

Q：UP-TO-DATE 任务不应该被跳过

# 强制重新执行
./gradlew clean build

# 或单个任务
./gradlew test --rerun

Q：Out of memory（内存不足）

# gradle.properties
org.gradle.jvmargs=-Xmx4096m -XX:MaxMetaspaceSize=512m

Q：配置缓存不兼容

# 查看不兼容原因
./gradlew build --configuration-cache

# 报告位置
# build/reports/configuration-cache/*/configuration-cache-report.html

# 临时禁用
./gradlew build --no-configuration-cache

Q：编译时乱码

tasks.withType<JavaCompile> {
    options.encoding = "UTF-8"
}

---

多项目问题

Q：子项目找不到父项目的依赖

确保在 settings.gradle.kts 中正确 include 子项目：

include("core", "web")  // 确保子项目路径正确

Q：多项目并行构建时出现竞争

// 确保任务依赖声明正确
tasks.named("taskB") {
    mustRunAfter("taskA")
}

Q：子项目想使用不同的仓库

如果使用了 FAIL_ON_PROJECT_REPOS，子项目不能声明仓库，需在根 settings 中统一配置：

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)  // 子项目可以有自己的仓库，但优先用 settings 中的
}

---

Kotlin DSL 问题

Q：IDE 自动补全不工作

1. 刷新 Gradle 项目（File → Sync Project with Gradle Files）
2. 使配置缓存失效：删除 .gradle/configuration-cache/
3. 使 Kotlin DSL 缓存失效：删除 ~/.gradle/caches/modules-*/

Q：Kotlin DSL 编译错误：Unresolved reference

// 确保使用正确的类型转换
tasks.named<Test>("test") {   // ← 指定类型 <Test>
    useJUnitPlatform()
}

---

插件问题

Q：插件版本不一致

在 settings.gradle.kts 中统一管理：

pluginManagement {
    plugins {
        id("org.springframework.boot") version "3.2.0"
    }
}

子项目只需 id("org.springframework.boot")，不需要指定版本。

Q：插件无法下载（网络问题）

// settings.gradle.kts
pluginManagement {
    repositories {
        maven { url = uri("https://maven.aliyun.com/repository/gradle-plugin") }
        gradlePluginPortal()
    }
}

---

性能问题

Q：构建每次都很慢

运行构建扫描分析：

./gradlew build --scan

查看哪些任务耗时最长，然后针对性优化。

Q：内存溢出 GC overhead limit exceeded

org.gradle.jvmargs=-Xmx6g -XX:+UseG1GC -XX:MaxGCPauseMillis=200