Gradle 本机私服配置

后端依赖 wuli3 的 Gradle 约定插件、BOM 和 starter。私服配置放在用户级 Gradle 目录，项目不负责读取或解析 ~/.m2/settings.xml。同一台机器上的 Gradle 项目可复用这份配置。

本文对应 2026-11-09 验证过的本机配置。后端使用 JDK 21 和项目提交的 Gradle Wrapper。

配置文件

默认 Gradle 用户目录为 ~/.gradle。若设置了 GRADLE_USER_HOME，下文的安装路径应改为该目录； IDE 和命令行也应使用同一个 Gradle 用户目录。

文件	用途
`~/.gradle/init.d/company-maven.gradle.kts`	注入插件仓库和业务依赖仓库
`~/.gradle/init.d/snapshot-revalidation.gradle.kts`	每次解析 SNAPSHOT 时检查仓库更新
`~/.gradle/gradle.properties`	保存本机私服用户名和密码

仓库地址已写入初始化脚本，认证信息通过 Gradle 属性读取，不写入项目。

仓库名	用途	已核实的 wuli3 插件与 BOM 版本
`companyReleases`	正式制品	`1.0.0`
`companySnapshots`	开发快照	`1.0.1-SNAPSHOT`

当前后端的 wuli3 约定插件和 BOM 使用 1.0.1-SNAPSHOT，需要 snapshot 仓库访问权限。版本分别声明在 packages/service/build.gradle.kts 和 packages/service/gradle.properties，以仓库实际声明为准。 release 仓库继续用于正式制品；初始化脚本同时配置两个仓库。

安装

以下命令在 alang-mono 根目录执行。已有同名初始化脚本时先比较内容，再决定是否替换。

bash

mkdir -p ~/.gradle/init.d
cp -i docs/public/gradle/company-maven.gradle.kts ~/.gradle/init.d/
cp -i docs/public/gradle/snapshot-revalidation.gradle.kts ~/.gradle/init.d/
touch ~/.gradle/gradle.properties
chmod 600 ~/.gradle/gradle.properties

编辑 ~/.gradle/gradle.properties，合并以下属性并替换占位值。保留已有的其他配置；同名属性只保留一份。snapshot 和 release 可以使用不同账号。

ini

# 合并到本机 ~/.gradle/gradle.properties，替换占位值；不要提交真实凭据。
companySnapshotsUsername=YOUR_SNAPSHOT_USERNAME
companySnapshotsPassword=YOUR_SNAPSHOT_PASSWORD
companyReleasesUsername=YOUR_RELEASE_USERNAME
companyReleasesPassword=YOUR_RELEASE_PASSWORD

用户名和密码使用制品仓库提供的访问凭据。不要把填写后的文件复制回仓库。属性文件中的反斜杠应写成 \\，避免被当作转义符。

可下载：私服初始化脚本、 SNAPSHOT 更新检查脚本、认证属性示例。

私服初始化脚本

以下代码与可下载的初始化脚本使用同一份文件。

kts

// 本机私服配置：同时支持 Gradle 插件与业务依赖。
fun addCompanyRepositories(
    settings: org.gradle.api.initialization.Settings,
    repositories: org.gradle.api.artifacts.dsl.RepositoryHandler,
) {
    val companyRepositories = mapOf(
        "companySnapshots" to "https://packages.aliyun.com/62ac9a6364c8a06be2d5db5d/maven/2242408-snapshot-clz7gf",
        "companyReleases" to "https://packages.aliyun.com/62ac9a6364c8a06be2d5db5d/maven/2242408-release-qbh2fh",
    )
    companyRepositories.forEach { (repositoryName, repositoryUrl) ->
        if (repositories.findByName(repositoryName) == null) {
            repositories.maven {
                name = repositoryName
                setUrl(repositoryUrl)
                credentials {
                    username = settings.providers.gradleProperty("${repositoryName}Username").get()
                    password = settings.providers.gradleProperty("${repositoryName}Password").get()
                }
            }
        }
    }
}

gradle.beforeSettings {
    pluginManagement.repositories {
        gradlePluginPortal()
        mavenCentral()
    }
    addCompanyRepositories(this, pluginManagement.repositories)
}

gradle.settingsEvaluated {
    addCompanyRepositories(this, dependencyResolutionManagement.repositories)
}

beforeSettings 在 settings 脚本求值前接入插件仓库，供根构建脚本的 plugins 解析使用。 settingsEvaluated 在 settings 脚本求值后向 dependencyResolutionManagement 添加业务依赖仓库，兼容后端的 FAIL_ON_PROJECT_REPOS 约束。

脚本按仓库名避免重复添加；如果项目已声明同名仓库，会沿用项目配置。它保留公共仓库，并为私服按仓库名读取对应的 Username 和 Password 属性。用户级脚本会作用于使用该 Gradle 用户目录的所有构建；CI、容器和其他开发机器需要分别安装。脚本使用 Kotlin DSL，文件后缀保持 .gradle.kts。

SNAPSHOT 更新检查

Gradle 将 Maven -SNAPSHOT 版本视为 changing modules，默认缓存其元数据和制品 24 小时。本机脚本将 changing modules 的缓存有效期设为 0 秒，使每次在线解析都向仓库检查更新。仓库元数据或制品未变化时继续复用本地缓存，固定 release 版本的缓存策略保持原状。具体机制见 Gradle 依赖缓存文档。

kts

// 本机开发约定：每次解析 SNAPSHOT 都检查仓库元数据，未变化的制品继续复用缓存。
// Maven SNAPSHOT 自动属于 changing modules；固定 release 版本缓存不受影响。
// 离线模式仍由 Gradle 使用已有缓存。
fun revalidateSnapshots(configurations: org.gradle.api.artifacts.ConfigurationContainer) {
    configurations.configureEach {
        resolutionStrategy.cacheChangingModulesFor(0, "seconds")
    }
}

gradle.beforeSettings {
    revalidateSnapshots(buildscript.configurations)
}

gradle.beforeProject {
    revalidateSnapshots(buildscript.configurations)
    revalidateSnapshots(configurations)
}

脚本覆盖以下配置：

settings 构建脚本依赖：在 beforeSettings 阶段设置。
各工程的构建脚本、插件依赖：在 beforeProject 阶段设置 buildscript.configurations。
各工程的普通业务依赖：设置 configurations，包括 BOM 和 starter。

脚本只改变当前 Gradle 用户目录下构建的解析策略，安装后下一次 Gradle 调用自动加载，无需修改项目文件。 IDE 重新加载 Gradle 项目时也使用该配置；启用 IDE 离线模式或使用 --offline 时，仍从已有缓存解析。若 mavenLocal() 优先且已有同版本制品，Gradle 可能继续选中本地制品；可通过依赖报告确认来源，必要时调整仓库优先级。

验证

在 monorepo 根目录执行：

bash

cd packages/service
./gradlew help --console=plain
./gradlew :alang-common:dependencies --configuration compileClasspath --console=plain
./gradlew :alang-bootstrap:dependencyInsight --dependency wuli3-aliyun-spring-boot-starter --configuration runtimeClasspath --console=plain --info

第一条验证构建配置及插件解析，成功时输出 BUILD SUCCESSFUL。第二条检查 BOM 和 starter 的依赖解析，确认 wuli3 为项目声明的 1.0.1-SNAPSHOT，并检查报告中是否有 FAILED。 dependencies 任务即使存在未解析项也可能成功退出，因此不能只看退出码。第三条确认实际选中的阿里云 starter 快照，并观察 --info 日志中 maven-metadata.xml 的下载或 Cached resource ... is up-to-date 记录，后者表示已检查仓库且缓存仍有效。 2026-11-09 本机验证时，插件快照和业务依赖元数据均进行了检查，阿里云 starter 解析到时间戳快照 20261109.073050-7。该时间戳仅为验证证据，后续以仓库最新快照为准。以上检查不代表完整编译或测试通过。

如果单独使用相邻的 alang-service 仓库，在该仓库根目录执行相同的 Wrapper 命令即可。 IDE 中将 Gradle JVM 设置为 JDK 21，确认 Gradle 用户目录一致，然后重新加载 Gradle 项目。

常见问题

现象	检查方式
`Plugin ... was not found`	确认脚本位于实际 Gradle 用户目录的 `init.d` 中；检查对应 snapshot / release 仓库权限及版本，必要时加 `--info` 查看搜索仓库
HTTP 401 / 403	检查用户级属性中的账号、访问凭据及对应仓库权限
缺少 `companyReleasesUsername` 等属性	按示例补齐实际 Gradle 用户目录下的 `gradle.properties`；两个仓库共需四个属性
命令行正常，IDE 失败	对齐 IDE 的 Gradle 用户目录与 JDK，重新加载项目
更换仓库或凭据后仍命中旧失败记录	执行 `./gradlew help --refresh-dependencies --console=plain` 重新解析
SNAPSHOT 已发布但仍使用旧内容	确认更新检查脚本已安装、IDE 未开启离线模式；检查 `mavenLocal()` 是否先命中本地同版本制品，再用 `dependencyInsight --info` 核实

停用

将用户目录中的 snapshot-revalidation.gradle.kts 改名为 snapshot-revalidation.gradle.kts.disabled，然后重新加载 Gradle，即可恢复项目或 Gradle 默认的 changing modules 缓存策略。

若要停用私服注入，将 company-maven.gradle.kts 改名为 company-maven.gradle.kts.disabled。私服注入停用后，原项目若仅配置公共仓库且 Maven Local 没有 wuli3 制品，会再次无法解析私服依赖。

Gradle 本机私服配置 ​

配置文件 ​

安装 ​

私服初始化脚本 ​

SNAPSHOT 更新检查 ​

验证 ​

常见问题 ​

停用 ​

Gradle 本机私服配置

配置文件

安装

私服初始化脚本

SNAPSHOT 更新检查

验证

常见问题

停用