根本原因是Gradle Wrapper在用户主目录（~/.gradle）或项目根目录下写入缓存、解压分发包、生成守护进程锁文件时被系统拒绝权限，常见于路径只读、所有者不匹配或IDE以不同用户上下文运行。
Gradle Wrapper 启动时报 “Permission denied” 或无法创建 .gradle 目录
根本原因不是 Gradle 本身没装好，而是它尝试在用户主目录（~/.gradle）或项目根目录下写入缓存、解压分发包、生成守护进程锁文件时被系统拒绝。常见于 Windows 上用普通账户安装到 C:\Program Files，或 macOS/Linux 下用 sudo 安装后又切回普通用户运行 ./gradlew。
关键判断点：ls -la ~/.gradle（macOS/Linux）或 dir C:\Users\用户名\.gradle（Windows）能看到目录存在，但里面空或只有部分子目录；执行 ./gradlew --version 报错里含 Permission denied、Could not create parent directory 或 java.io.IOException: Unable to create directory。
- 不要用管理员/root 权限运行
./gradlew—— 守护进程和缓存会以 root 身份创建，后续普通用户无法读写 - 检查
~/.gradle所有者是否为你当前用户：ls -ld ~/.gradle；若显示root或其他用户，运行sudo chown -R $USER:$USER ~/.gradle（macOS/Linux） - Windows 用户重点看安装路径：如果 Gradle 解压到
C:\Program Files\gradle，且你没以管理员身份运行命令行，就别指望它能往那里写东西；改用%USERPROFILE%\gradle这类用户可写路径 - IDE（如 Android Studio）可能默认以不同用户上下文启动 Gradle，建议先在终端里用同一账户跑通
./gradlew --version，再回头配 IDE
gradle-wrapper.properties 指向的 distributionUrl 被下载到只读目录
Wrapper 机制会把 gradle-8.3-all.zip 下载并解压到 ~/.gradle/wrapper/dists/ 下某个 hash 命名的子目录中。如果该路径所在磁盘是只读挂载（比如某些企业终端策略），或父目录权限为 755 但组/其他无写权限，就会卡在“下载完成但无法解压”这一步，报错常含 Failed to create directory 或静默失败。
验证方式：手动执行 ls -la ~/.gradle/wrapper/dists/，看对应版本目录是否存在；若存在但为空，或提示 Permission denied，说明解压环节失败。
- 临时绕过：把
~/.gradle/wrapper/dists/软链接到一个你有完全权限的路径，例如ln -sf /tmp/gradle-dists ~/.gradle/wrapper/dists（macOS/Linux） - 永久修复：修改系统级 Gradle 缓存位置，在
~/.gradle/gradle.properties中添加org.gradle.user.home=/path/you/own，确保该路径可读写 - 不推荐直接改
gradle-wrapper.properties的distributionUrl为本地 file:// 路径——除非你已手动把 zip 放到目标位置且校验了distributionSha256Sum，否则容易因 hash 不匹配被拒绝
Android Studio 内置 Gradle 启动失败，实际是项目级权限问题
很多人以为是 Gradle 安装出问题，其实是 Android Studio 在打开项目时，试图在项目根目录下创建 .gradle 文件夹（用于存储构建缓存、任务输出等），而该目录所在分区或父路径被设为只读，或受公司策略限制（如 OneDrive 同步目录、加密卷、受限沙盒）。
典型现象：命令行里 ./gradlew build 成功，但 Android Studio 点击 Run 却卡住或报错；或者项目一打开就弹窗提示 “Gradle sync failed”，日志里出现 Cannot create directory 或 Access is denied（Windows）。
- 检查项目路径：避免放在
OneDrive、Google Drive、/Volumes/xxx（macOS 加密卷）、C:\Users\XXX\Documents（某些域策略限制）等路径 - 在 Android Studio 中，进入
File → Project Structure → Project，确认Gradle settings → Gradle user home指向的是你可控的路径（如C:\Users\YourName\.gradle），而不是默认的系统路径 - 右键项目根目录 → 属性 → 安全（Windows）或
getfacl（Linux/macOS），确认当前用户有Modify或rwx权限；若没有，手动赋予
最常被忽略的一点：权限问题往往不是“完全不能写”，而是“能建目录但不能建符号链接”或“能写文件但不能删锁文件”。Gradle 守护进程依赖文件锁和临时目录，哪怕只缺一项权限，也会导致启动后立即退出或构建中途崩溃。排查时别只盯着 Permission denied 字样，要结合 strace（Linux）、Process Monitor（Windows）或 Android Studio 的 Build → Toggle Tasks Execution View 查看具体哪一步失败。
