Gradle Wrapper加载gradle-wrapper.properties失败：Windows环境根因与修复指南

先说一个很多人都经历过的场景：你正在终端里敲 ./gradlew assembleDebug，或者打开 IDE 让它 Sync，屏幕突然飘红，前端显示一行 java.lang.RuntimeException: Could not load wrapper properties from 'C:\Users\Administrator\project\gradle\wrapper\gradle-wrapper.properties'。如果你是在 Windows 上做 Java / Android 开发，遇到这个异常的频率比想象中高得多。表面上看，这像是 Gradle “抽风”了；实际上，这行报错背后是整个 Gradle Wrapper 启动链路中某个环节出了问题。这篇文章不打算只给你一个“删了重建”的万能答案，而是把这条异常从源头到修复完整拆开讲清楚，包括它会在哪些环节出现、哪些根因最隐蔽、以及 Windows 平台上有哪些特有的坑。

这套排查思路不仅适用于 Gradle 项目，也适用于任何依赖“启动脚本 + 配置文件”的构建工具。无论你是刚接触 Gradle 的新人，还是被这个错误反复折磨过几次的开发老手，文中的命令和检查顺序都值得照着敲一遍。尤其是那些“删了 gradle 文件夹再 Sync 一次”的土办法，往往治标不治本，下次换台电脑或者换个分支又会冒出来。

1. 先拆异常：Wrapper 加载链路上到底哪里出了岔子

1.1 Wrapper 机制：为什么 Gradle 非要一个“启动器”

要理解这个报错，先得知道 Gradle 为什么设计了一个“多余的” wrapper 层。Gradle 本身是一个需要下载和安装的构建工具，不同项目的 Gradle 版本如果不一样，构建结果和行为就可能出现差异。Wrapper 的思路很简单：项目里放一套“启动脚本 + 小体积 jar + 配置文件”，由它来决定到底调用哪个版本的 Gradle，并且自动下载到本地。这样一来，团队里每个人都不需要手动安装 Gradle，只要执行 gradlew.bat 或 ./gradlew，构建工具版本就自动统一了。

这套机制包含四个关键文件：

• gradlew（Linux / macOS 下的 Shell 启动脚本）
• gradlew.bat（Windows 下的批处理启动脚本）
• gradle/wrapper/gradle-wrapper.jar（负责下载和执行真正 Gradle 的迷你程序）
• gradle/wrapper/gradle-wrapper.properties（记录下载地址、存储位置等参数的配置文件）

报错信息里的 wrapper properties 指的就是第四个文件——gradle-wrapper.properties。这个文件虽然名字带 “properties”，但它加载失败时抛出的却是 RuntimeException，也就是文章标题里的那句 java.lang.RuntimeException: Could not load wrapper properties from 'C:\Users\...'。

1.2 启动链路上的三个环节，逐个确认

当你在 Windows 命令提示符里执行 gradlew.bat 时，实际发生的加载链路可以简化为：

text复制gradlew.bat
  └─ 查找 JAVA_HOME / java 命令
      └─ 执行 java -classpath gradle/wrapper/gradle-wrapper.jar org.gradle.wrapper.GradleWrapperMain
          └─ GradleWrapperMain 定位到项目目录
              └─ 读取 gradle/wrapper/gradle-wrapper.properties
                  └─ 解析 distributionUrl 等属性
                      └─ 根据 URL 下载 / 使用本地缓存的 Gradle 发行版

这条链路的任何一个环节出错，都会让构建直接终止。而 Could not load wrapper properties 这一句，恰恰发生在“读取并解析 gradle-wrapper.properties”的步骤。所以当看到这个异常时，第一反应不应该去检查你的业务代码，也不应该去查 build.gradle，而应该顺着这条链路检查。

一个很常见的误解是：报错里出现了 C:\Users\...，有人就以为是 Gradle 在下载发行版时找不到本地缓存的目录。实际上，如果 distributionUrl 指向的下载地址访问不了，或者本地缓存目录损坏，报错通常会包含类似 Could not download Gradle distribution 或 Could not HEAD ... 的信息，而不是 Could not load wrapper properties。出现 Could not load wrapper properties 时，说明 Gradle 在很早期就读不到、或者读不懂这个 properties 文件本身了。

1.3 别只盯着第一行，真正的线索在 “Caused by” 里

Java 异常最容易被忽略的就是 “Caused by” 部分。同一个 Could not load wrapper properties，背后的底层异常可能完全不同：

如果你在 IDE 里看到完整堆栈，把鼠标滚到最下面，找到 Caused by 那一行，基本就能判断问题方向。比如常见的是：

text复制java.lang.RuntimeException: Could not load wrapper properties from 'C:\Users\Administrator\workspace\demo\gradle\wrapper\gradle-wrapper.properties'.
    at org.gradle.wrapper.WrapperExecutor...
Caused by: java.io.FileNotFoundException: C:\Users\Administrator\workspace\demo\gradle\wrapper\gradle-wrapper.properties (系统找不到指定的文件。)

看见 FileNotFoundException，事情就清晰了：文件缺失。这也正是我要在下一节重点展开的场景——绝大多数人的问题都出在目录不完整，而不是文件内容写错了。

2. gradle/wrapper 目录状态：九成问题的第一现场

2.1 一个完整的 wrapper 目录应该有三个文件

在排查之前，先看看项目里 gradle/wrapper 目录到底有什么。Windows 下用命令：

bat复制dir gradle\wrapper

一个正常的、可以被 Gradle 读取的目录，至少应该包含：

text复制gradle\wrapper\
    gradle-wrapper.jar
    gradle-wrapper.properties

注意，gradlew.bat 和 gradlew 在项目根目录，不在 gradle/wrapper 里。如果你打开目录后发现只有 gradle-wrapper.jar，没有 gradle-wrapper.properties，那么恭喜你，问题直接找到了。很多情况下，gradle-wrapper.properties 是在拷贝项目、切换分支、团队协作中被误删的，而 gradle-wrapper.jar 因为体积小、不常被.gitignore 命中，反而幸存了下来。

2.2 拷贝项目与 git 操作：最容易踩的坑

这个错误在我接触的项目里，出现频率最高的一种场景，是从 Git 仓库 clone 或下载压缩包后，直接跑构建。常见原因有：

• 项目的 .gitignore 里误写了 *.properties，导致 gradle-wrapper.properties 从未被提交到仓库。你本地跑得好好的，换一个人 clone 下来就报错。
• 用网盘、聊天软件传项目压缩包时，某些文件被安全软件静默拦截，压缩包里偏偏少了 properties 文件。
• 从旧分支切到新分支时，Git 工作区里文件状态异常，properties 文件消失或变成未跟踪状态。

这种情况下，最快的确认方法是在项目根目录执行：

bat复制git status

观察是否有 deleted: gradle/wrapper/gradle-wrapper.properties 之类的提示。如果你怀疑是 .gitignore 把文件排除掉了，可以用：

bat复制git check-ignore gradle/wrapper/gradle-wrapper.properties

如果这条命令输出了路径，说明文件确实被忽略规则踢出了版本库。正确的做法是修正 .gitignore，把 gradle/wrapper/gradle-wrapper.properties、gradle-wrapper.jar、gradlew、gradlew.bat 这几项强制加入版本管理，而不是手动拷贝文件糊弄过去。

2.3 “文件存在但内容为空”的隐藏炸弹

还有一种情况比文件缺失更隐蔽：文件在，大小却是 0 字节，或者只有几行空行。IDE 或某些文本编辑器在异常退出时，可能把文件内容清空；Git 合并冲突解决不当，也可能生成一个残废的空文件。用命令查看文件大小：

bat复制dir gradle\wrapper\gradle-wrapper.properties

如果大小显示 0 或者内容只有几个字节，那它跟文件不存在没什么区别。Gradle 读取一个空 properties 文件时，拿不到任何参数，通常也会直接抛出加载失败相关异常。

2.4 为什么“先删掉 .gradle 再 Sync”很多时候没用

网上很多答案会让你删除项目根目录下的 .gradle 文件夹，以及用户目录下的 C:\Users\你的用户名\.gradle，再重新 Sync。这个操作在某些缓存损坏的场景下确实有效，但它解决的是“Gradle 发行版下载了一半、缓存校验失败”一类问题，对 gradle-wrapper.properties 本身缺失或损坏是无能为力的。因为在删除缓存之前，Gradle 压根还没走到下载发行版那一步，它就卡在读取 properties 文件上了。所以，先检查 wrapper 目录是否存在且完整，永远比盲目清缓存更高效。

3. gradle-wrapper.properties 内容排雷：字段、编码与保存姿势

3.1 一份正常可用的文件长什么样

确认文件存在、内容不是 0 字节之后，下一步就是把内容打开看看。正常情况下，一个典型的 gradle-wrapper.properties 长这样：

properties复制distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-8.7-bin.zip
networkTimeout=10000
validateDistributionUrl=true
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

注意 distributionUrl 那一行里的冒号前面有一个反斜杠转义：https\://。这是因为 Java properties 格式里，冒号是键值分隔符，虽然 Gradle 生成的默认文件会自动把 // 之后的内容当作 value 的一部分，但为了稳妥，官方模板保留了转义。如果你手工修改时不小心把反斜杠删掉，变成：

properties复制distributionUrl=https://services.gradle.org/distributions/gradle-8.7-bin.zip

大多数情况下 Gradle 也能正确解析，因为 = 之后的所有内容都会被当作 value，冒号不再产生歧义。但如果你习惯用空格或 Tab 作为键值分隔符，那就很容易出问题。例如：

properties复制distributionUrl https://services.gradle.org/distributions/gradle-8.7-bin.zip

这种写法在 Java properties 规范里是合法的，但一旦你手动编辑时多加了一个空格，或者把 URL 拆成了两行，解析结果就会变得不可控。

3.2 每个字段到底负责什么

我把这些字段的含义整理成一张表，方便你排查时对照：

GRADLE_USER_HOME 代表的是 Gradle 用户主目录，Windows 上默认是 C:\Users\你的用户名\.gradle。也就是说，发行版最终会被解压到类似 C:\Users\Administrator\.gradle\wrapper\dists\gradle-8.7-bin\xxxx\ 的位置。那个 xxxx 是一段根据 distributionUrl 计算出来的哈希目录名。这意味着，即使你只是把 URL 里的版本号从 8.7 改成 8.6，Gradle 也不会复用旧目录，而是重新下载一份。

3.3 编码问题：为什么中文注释会成为定时炸弹

这是我认为最值得单独拿出来的细节。很多开发者喜欢在 properties 文件里加中文注释，比如：

properties复制# 这里配置 Gradle 版本
distributionUrl=https\://services.gradle.org/distributions/gradle-8.7-bin.zip

如果你的文本编辑器保存时用的是 UTF-8 编码，那么这个文件在 Gradle 解析时可能不会立即报“编译错误”，但会在某些 JDK 版本和 Gradle 版本组合下出现异常。最典型的是 Windows 自带的“记事本”保存文件时默认添加 BOM 头（文件开头有一串不可见字节）。BOM 会让 properties 解析器把第一个键名读取成带有乱码前缀的字符串，导致 Gradle 找不到它认识的 distributionUrl 键。

我自己就遇到过一起非常诡异的问题：gradle-wrapper.properties 看起来一切正常，文件在、内容完整、键值对也没写错，但构建就是报 Could not load wrapper properties。最后用十六进制编辑器打开文件，发现文件头部多出了 EF BB BF 三个字节——正是 UTF-8 BOM。把文件另存为“无 BOM 的 UTF-8”，或者干脆改成纯 ASCII 编码重新保存，问题立刻消失。

建议：gradle-wrapper.properties 保持纯 ASCII 内容，注释尽量不要写中文，更不要在 Windows 记事本里编辑它。要用就用 VS Code、Notepad++ 这类可控制编码的编辑器，并且确认右下角编码是 UTF-8 而不是 UTF-8 with BOM。

3.4 值里包含反斜杠时的转义陷阱

另一个容易被忽略的问题是反斜杠。Java properties 格式里，反斜杠是转义字符。如果一个 distributionUrl 的值里包含 Windows 路径风格的反斜杠，比如：

properties复制distributionUrl=D:\software\gradle-8.7-bin.zip

那么 \s、\g 这些组合在解析时会产生不可预料的转义效果。正确的写法是用正斜杠，或者对每个反斜杠再加一个反斜杠转义：

properties复制distributionUrl=D:/software/gradle-8.7-bin.zip

大部分支持 file:// 协议的 Gradle 版本都能接受正斜杠路径。如果你是离线环境，需要把发行版 zip 放到本地磁盘，最好统一用正斜杠。

4. Windows 独有的隐性陷阱：用户名、权限、路径长度与安全软件

4.1 用户名里的中文、空格和括号，引出的连锁反应

回到标题里的 C:\Users\，这个路径前缀其实已经暗示了问题的高发区——Windows 用户主目录。我自己在实际项目里遇到过不止一次，因为 Windows 用户名是中文（比如 C:\Users\张三），导致 Gradle 在某些环节表现异常的情况。

虽然现代 JDK 对 Unicode 路径的支持已经不错，但 Gradle 的下载、解压、缓存校验等环节会调用大量底层文件操作和第三方库。个别库对非 ASCII 路径处理不完善，就会在构建链路深处报出各种莫名其妙的错。除了中文，用户名里的空格和括号在某些脚本解析时也容易引出问题。比如 C:\Users\John Doe 这类路径，用 gradlew.bat 执行时如果脚本没有给路径加引号，就会出现“找不到命令”或“文件无法访问”的异常。

遇到这种情况，最稳妥的处理方式不是去修改 Windows 用户名，而是把项目工程移动到没有空格、没有中文的路径下，比如 D:\dev\demo。同时，可以通过设置环境变量 GRADLE_USER_HOME，把 Gradle 的缓存目录也迁移到安全路径：

bat复制set GRADLE_USER_HOME=D:\gradle-cache

这样 Gradle 下发的发行版和构建缓存都会放在 D:\gradle-cache，绕开用户名带来的路径问题。

4.2 权限和 Windows 安全中心的“受控文件夹访问”

Windows 10 / 11 自带的安全中心里有一项“受控文件夹访问”，默认会对某些目录（如“文档”“图片”等）做额外的写入保护。如果你的项目恰好放在这些受保护目录下，并且 Gradle 需要写入 .gradle 缓存，就可能被安全策略拦截。更常见的是，项目团队使用 OneDrive 同步“桌面”或“文档”目录，文件被 OneDrive 锁定或同步冲突，构建工具读取 properties 文件时可能抛出共享冲突。

排查这类问题，一是看 Caused by 是不是 AccessDeniedException；二是把项目从 OneDrive 同步目录、桌面、文档里挪出来。如果确实需要在原位置开发，可以临时关闭“受控文件夹访问”再试一次，但更推荐的做法是在安全中心的“允许应用通过受控文件夹访问”里，把 JDK 的 java.exe 加入白名单，或者干脆把项目迁移到普通目录。

4.3 安全软件与“文件被占用”场景

很多企业办公电脑会预装杀毒软件，它们对 Java 进程读取或写入 .gradle 目录的行为相当敏感。我见过一种很有意思的情况：杀毒软件把 gradle-wrapper.jar 临时隔离了，导致 gradlew.bat 在执行时找不到主类；用户重新下载文件后能跑通，但下次又被查杀。如果你的项目在团队内大面积遇到 wrapper 相关异常，而其他人没有问题，优先检查本机安全软件的隔离记录。

此外，Windows 上文件被占用是个经典问题。如果你用文本编辑器打开了 gradle-wrapper.properties，并且编辑器进程没有释放文件锁，某些情况下 Gradle 读取文件会失败。排查办法很简单：关掉所有可能打开该文件的编辑器、IDE 窗口，然后再执行构建命令。

4.4 路径过长：Window 260 字符的隐形上限

这不算一个高频问题，但一旦碰上就非常难排查。Windows 传统上对路径长度有 260 个字符的限制，虽然新版系统可以通过注册表开启长路径支持，但很多程序默认没有启用。Gradle 的缓存目录会拼接用户主目录、哈希目录、发行版解压路径，路径本身就长。如果你的项目又嵌套在很深的目录里，比如：

text复制C:\Users\Administrator\AndroidStudioProjects\MyCompany\Modules\Feature\Pay\checkout-service

再加上 gradle\wrapper\dists\gradle-8.7-bin\xxxx\gradle-8.7\... 那一串，很容易触碰到路径上限。报错可能千奇百怪，但本质都是文件系统操作失败。

遇到这种情况，最好的方案是整体缩短项目根路径，例如放到 C:\code\pay-service 这种层级下，同时避免使用超长目录名。如果你的项目确实结构很深，建议在 Windows 设置中开启长路径支持，并统一团队开发环境的配置。

5. 修复实操：从备份到重建 Wrapper 的完整链路

5.1 修复前的完整诊断流程

动手修复之前，建议按下面的顺序做一遍诊断，避免反复“删了又建”浪费时间：

1. 记录完整堆栈，找到 Caused by 指向的底层异常。
2. 检查 gradle/wrapper/ 目录是否存在 gradle-wrapper.properties 与 gradle-wrapper.jar。
3. 用文本编辑器打开 properties 文件，确认节操内容不是空文件，编码无 BOM。
4. 执行 gradlew --version，观察是否复现同样的异常。
5. 检查 distributionUrl 指向的版本能否正常访问（离线环境和内网环境尤其要注意）。
6. 确认本机 JAVA_HOME 指向的 JDK 版本可用：java -version。

其中第 6 步很容易被忽略。如果 JAVA_HOME 配置不对，gradlew.bat 可能连 JVM 都启动不了，或者启动后因为 JDK 版本过低，在读取 properties 之外的环节先崩掉。所以每次排查构建问题，我都会先确认 JDK 环境，再继续往下走。

5.2 方案 A：手动补齐 properties 文件

如果目录里只是缺少 gradle-wrapper.properties，但 gradle-wrapper.jar 和 gradlew.bat 都还在，那么你可以新建一个文件，手动写入内容：

properties复制distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-8.7-bin.zip
networkTimeout=10000
validateDistributionUrl=true
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

这里的关键是让 distributionUrl 指向的版本和你项目期望的版本一致。如果不确定项目原本用哪个版本，可以看看 build.gradle 或 build.gradle.kts 里有没有相关注释，或者去仓库历史里找 git log 恢复旧文件：

bat复制git checkout HEAD -- gradle/wrapper/gradle-wrapper.properties

如果你的项目根本没有 git 历史可以参考，那就选择一个与本项目兼容的 Gradle 版本。Android 项目通常对 Gradle 版本有最低要求，比如 Android Gradle Plugin 8.x 需要 Gradle 8.x。保守的做法是先选一个较新的稳定版，然后根据实际构建报错再调整。

5.3 方案 B：用本机安装的 Gradle 重新生成 Wrapper

手动写 properties 文件虽然能应急，但没有 gradle-wrapper.jar 配合的话，后续的下载逻辑也可能出问题。更标准、更可靠的做法，是用本机已安装的 Gradle 重新生成整套 Wrapper。

如果你本机已经有可用的 Gradle，直接执行：

bat复制gradle wrapper --gradle-version 8.7

Gradle 会在项目里重新生成 gradlew、gradlew.bat、gradle/wrapper/gradle-wrapper.jar 和 gradle/wrapper/gradle-wrapper.properties。如果本机没有 Gradle，可以找一个你信任的同事，让他从自己的健康项目里拷贝整套 gradle/wrapper 目录和根目录下的 gradlew.bat、gradlew 过来，再根据项目实际需求修改 distributionUrl 里的版本号。

这里有一个细节：gradle-wrapper.jar 和 gradle-wrapper.properties 是对应的。不同 Gradle 版本生成的 wrapper jar 对 properties 文件的解析行为基本一致，但为了减少不必要的兼容问题，最好整套目录一起拷贝，不要只拷贝其中一个文件。

5.4 清理本地缓存并重新构建

如果确认文件内容没错，但构建依然失败，那问题可能出在本地缓存目录。Gradle 的缓存位置有两层：

• 项目根目录的 .gradle 文件夹：存放该项目的构建状态。
• 用户目录下的 C:\Users\你的用户名\.gradle\wrapper\dists：存放下载的 Gradle 发行版。

处理方式分两步。第一步删除项目根的 .gradle 缓存：

bat复制rmdir /s /q .gradle

注意这个目录删除后，项目下一次构建会重新解析所有依赖和任务，耗时会更长，但通常不会导致不可恢复的问题。第二步，如果确认发行版缓存损坏，可以只删除 wrapper\dists 下的对应版本目录：

bat复制rmdir /s /q C:\Users\你的用户名\.gradle\wrapper\dists\gradle-8.7-bin

如果不确定是哪个目录损坏，也可以临时把 wrapper\dists 整个改名备份，让 Gradle 全部重新下载。这样至少能保证不是缓存文件残缺导致的问题。

清理完后，执行：

bat复制gradlew.bat --version

正常情况会看到类似输出：

text复制------------------------------------------------------------
Gradle 8.7
------------------------------------------------------------

如果你的 distributionUrl 指向的是外部网络地址，而本机处于内网或离线环境，下载这一步会卡住或报超时。解决办法是把下载地址换成内网镜像，或者用 file:// 指向本地已有的 zip 包。比如：

properties复制distributionUrl=file\:///D:/gradle-dist/gradle-8.7-bin.zip

这里 file:/// 后面跟的是本地绝对路径，建议用正斜杠表示。

5.5 IDE 场景下的额外一步：清 IDE 缓存

IntelliJ IDEA 和 Android Studio 都内置了 Gradle 缓存机制。有时候命令行 gradlew.bat 已经恢复正常，但 IDE 里依然报错。这时候除了项目本身的 wrapper 文件，还需要让 IDE 关闭旧的 Gradle daemon：

• 在 IDEA / Android Studio 的 Settings -> Build, Execution, Deployment -> Build Tools -> Gradle 中，点击 Invalidate Caches。
• 如果你设置了自定义的 Gradle user home，检查它是否指向了不存在或不可写的目录。
• 检查 IDE 使用的 JDK 是否正确，避免 IDE 自带的低版本 JDK 和项目要求不匹配。

做完这些，再让 IDE 重新 Sync 项目，通常就能恢复正常。

5.6 一张问题定位速查表

把上面这些场景整理成速查表，方便你日后直接用：

6. 之后的日子里怎么避坑：团队与 CI 实践

6.1 Wrapper 四个文件必须提交到版本库

这是我认为最值得强调的一条建议。很多新项目模板默认会把 .gradle 文件夹排除，但 gradle-wrapper.jar、gradle-wrapper.properties、gradlew、gradlew.bat 这四样东西是必须提交的。你可以检查一下项目的 .gitignore，确认没有把 *.properties、*.jar 这类通配规则误伤到 gradle/wrapper 目录。

在 Git 仓库里查看跟踪状态：

bat复制git ls-files gradle/wrapper

如果输出为空，说明整个 wrapper 配置都没有纳入版本管理。这就是为什么其他同事 clone 项目后总是报 java.lang.RuntimeException 的根源。你本地之所以没事，是因为 Gradle 缓存里已经存在对应发行版，构建时被 wrapper 脚本略过了某些检查，但换一台干净机器立刻暴露。

6.2 固定 Gradle 版本，避免“顺手升级”

Wrapper 的核心价值就是让项目与 Gradle 版本强绑定。某个分支上的构建脚本依赖 Gradle 8.2 的特性，另一个分支却要用 8.7，Wrapper 会自动在本地下载两套不同版本，互不干扰。但要注意，一旦有人手动修改了 distributionUrl 里的版本号，又没有跑完整构建验证，可能就会在团队里引入不一致。

正确升级 Gradle 版本的方式，不是直接编辑 properties 文件，而是运行：

bat复制gradlew wrapper --gradle-version 8.7

这会让 Gradle 同时更新 gradle-wrapper.jar 和 gradle-wrapper.properties，并保持两者兼容。升级后，把四个文件一起提交到版本库，并且跑一遍干净的构建，确认没有遗漏。

6.3 CI 上的复现与缓存策略

如果你是在 CI 环境（如 Jenkins、GitLab CI）遇到同样的报错，排查思路有些不同。CI 通常每次从仓库拉取最新代码，在干净的 runner 上构建。如果仓库里确实包含了正确的 wrapper 文件，但 CI 依然报 Could not load wrapper properties，优先级最高的是排查 CI 的缓存目录。

很多 CI 服务为了加速，会把 Gradle 用户主目录做成缓存，比如挂在 /root/.gradle 或 Windows runner 的 C:\Users\runneradmin\.gradle。如果缓存里的目录结构或文件权限异常，就会导致 properties 文件读取失败。这时可以尝试：

• 清空 CI 项目里的 Gradle 缓存并重新构建。
• 检查 runner 上是否有旧版本 Gradle daemon 占用文件锁。
• 确认 CI 环境的 GRADLE_USER_HOME 环境变量没有指向异常位置。

给 CI 配置里加上“每次构建前删除项目内 .gradle 缓存”的步骤，虽然会牺牲一点构建速度，但能有效规避很多莫名其妙的缓存问题。更精细的做法，是在 CI 配置里把 gradle-wrapper.jar 这类小文件单独设为不缓存，每次都从仓库读取。

6.4 一点个人经验：遇到“反复出现”时，先怀疑工具链而不是项目代码

最后分享一个我自己的排查习惯：类似 Could not load wrapper properties 这类发生在构建工具启动阶段的异常，每次出现时我都会强烈怀疑“文件状态、环境路径、缓存完整性”三个方向，而不是急着去改业务代码或依赖配置。很多开发者花了大量时间在网上搜索解决方案，结果把项目里各种配置文件改得面目全非，最后发现只是 .gitignore 多写了一行。

如果你严格按照这篇文章的顺序排查一遍，大多数情况都能在五分钟内定位根因。少部分特殊情况，比如公司统一推送的安全策略、特殊的磁盘加密软件干扰，可能确实需要借助本机日志进一步分析。但无论如何，先掌握 Wrapper 的加载链路，再带着 Caused by 指向的底层异常去搜索解决方案，才能少走弯路。构建工具的快乐，往往就藏在这些“读懂异常背后的机制”的瞬间里。