Android gradlew 找不到命令不是环境变量问题

FreeGuideOnline 最新 2026-07-04

问题现象：`gradlew` 明明在眼前，终端却提示 command not found

你下载了 Android 开源项目，或者用 Android Studio 新建了工程，在项目根目录下执行 ./gradlew 或 gradlew 时，却收到类似“命令未找到”的错误：

bash: gradlew: command not found

但你又确认 %JAVA_HOME% 和 %ANDROID_HOME% 及相关路径都已正确配置，java -version 和 adb 都能正常调用。问题似乎不是出在环境变量上。
下面我们就从根源出发，系统地排查并解决这个问题。

第一步：确认 `gradlew` 文件是否存在

gradlew（Linux/Mac）或 gradlew.bat（Windows）是 Gradle Wrapper 的启动脚本，必须位于项目的根目录。
先在终端进入你的项目文件夹，然后查看文件列表：

# Linux / Mac
ls -la | grep gradlew

# Windows (PowerShell)
dir | Select-String "gradlew"

如果这里看不到 gradlew 或 gradlew.bat，那就不是执行权限的问题，而是文件缺失。

为何会缺失？

你 clone 的仓库没有提交 wrapper 脚本（.gitignore 中误排除了 gradlew 或 gradle/wrapper/ 下的文件）
项目是通过某种方式“半成品”下载的（比如只下载了源代码，没有包含 Gradle Wrapper）
你在错误的目录里执行了命令

解决方法：重新生成 wrapper 文件

如果你本地已经安装了 Gradle（或者暂时可以使用 gradle 命令），可以在项目根目录运行：

gradle wrapper --gradle-version 8.5

这会在项目根目录下创建 gradlew、gradlew.bat 和 gradle/wrapper/ 文件夹。

如果没有安装 Gradle，可以从其他可正常工作的 Android 项目中复制以下内容：

gradlew（Unix shell 脚本）
gradlew.bat（Windows 批处理）
gradle/wrapper/gradle-wrapper.jar
gradle/wrapper/gradle-wrapper.properties

将它们放入当前项目根目录和对应文件夹下即可。

第二步：检查脚本执行权限（Linux / Mac）

在 Unix 系统中，ls -la 的输出前面会显示权限位，例如 -rwxr-xr-x。
如果你看到了 gradlew，但它显示为 -rw-r--r--（没有 x 可执行标志），说明你缺少执行权限。系统就会把它当成普通文件，而不是可执行命令。

赋予执行权限：

chmod +x gradlew

之后再执行：

./gradlew tasks

如果正常，问题解决。

第三步：检查当前工作目录

很多初学者习惯在 IDE（如 VS Code、Android Studio）的终端里直接敲命令，却忘记切换到项目根目录。
用 pwd（Linux/Mac）或 cd（Windows）确认你当前的位置：

pwd   # 应该显示类似 /Users/yourname/AndroidProjects/MyApp 的路径

或者检查该目录下是否有 settings.gradle 或 build.gradle：

ls -la | grep build.gradle

若不存在，说明你不在项目根目录，请先用 cd 进入正确的文件夹。

第四步：正确调用 `gradlew`

即使环境变量没问题，调用方式出错也会导致 command not found。

Linux / Mac：必须使用 ./gradlew，因为当前目录通常不在 PATH 中。
Windows（命令提示符或 PowerShell）：直接使用 gradlew 或 .\gradlew.bat 均可。

如果你在 Mac 上只输了 gradlew（不包含 ./），系统就会去 PATH 目录里找，自然是找不到的。

第五步：检查 Gradle Wrapper 自身是否被破坏

即使 gradlew 文件存在且有权限，它也可能因为所依赖的 gradle-wrapper.jar 损坏或缺失而无法启动，某些错误信息可能被误报为“找不到命令”。

查看 gradle/wrapper/ 目录下是否包含 gradle-wrapper.jar：

ls gradle/wrapper/

如果该 jar 文件不存在或大小为 0，那么 gradlew 在执行时可能无法正确初始化，从而间接导致找不到命令的错误。

解决方法：

从 Gradle 官方发布包中下载对应版本的 gradle-wrapper.jar，或者使用 gradle wrapper 重新生成（如第一步所示）。

第六步：Java 环境是否可用（但不一定体现在环境变量上）

gradlew 启动时会调用 java 命令。如果系统虽然配置了 JAVA_HOME，但 java 命令在实际 shell 中仍找不到，也可能导致各种奇怪错误。此时单纯检查 echo $JAVA_HOME 可能无法发现问题。

验证：

java -version

如果该命令也提示 command not found，说明你的 PATH 并没有包含 Java 可执行文件。

快速修复：

# Mac/Linux 临时添加（假设 Java 安装在默认路径）
export PATH="/usr/bin/java/bin:$PATH"

# 或直接指向具体版本
export JAVA_HOME=$(/usr/libexec/java_home -v 17)
export PATH="$JAVA_HOME/bin:$PATH"

之后重新执行 ./gradlew。

第七步：Windows 下的常见额外陷阱

在 Windows 中运行 gradlew.bat 时，可能遇到：

.bat 关联错误
如果系统不认为 .bat 是可执行文件（例如被安全软件篡改），双击或命令行调用 gradlew 会被拒绝。可使用完整名称 gradlew.bat 尝试。
PowerShell 执行策略
在 PowerShell 中直接执行 .bat 一般不受限制，但如果你尝试执行 .ps1 脚本可能会被策略阻拦。gradlew.bat 是批处理，不受 PowerShell 执行策略影响，因此通常无碍。
使用 Git Bash 或 WSL
如果你在 Git Bash 中运行 gradlew（没有 .bat 后缀），它会寻找 gradlew 这个 shell 脚本（即 Linux 版本）。确保文件换行符为 LF，而不是 CRLF。可以使用 dos2unix gradlew 修复。

第八步：检查是否被杀毒软件或防火墙拦截

一些杀毒软件（如 Windows Defender 或第三方安全工具）可能会将 gradlew.bat 或 gradle-wrapper.jar 误判为威胁并静默删除或隔离。当你执行时，自然就会提示找不到文件。

去你的杀毒软件的隔离区中检查，如果有相关文件，请恢复并添加信任。或者临时停用杀毒软件再解压项目，确认文件完整性。

终极懒人排查脚本

把下面内容保存为 check_gradlew.sh（Linux/Mac）或 check_gradlew.bat（Windows），放到项目目录运行，可一键诊断。

Linux/Mac 版本（`check_gradlew.sh`）：

#!/bin/bash
echo "==== 检查 gradlew 是否存在 ===="
if [ -f ./gradlew ]; then
    echo "✅ gradlew 存在"
    if [ -x ./gradlew ]; then
        echo "✅ 具有可执行权限"
    else
        echo "❌ 没有可执行权限，执行 chmod +x gradlew"
    fi
else
    echo "❌ gradlew 不存在，使用 gradle wrapper 生成或复制文件"
fi

echo ""
echo "==== 检查 gradle-wrapper.jar ===="
if [ -f ./gradle/wrapper/gradle-wrapper.jar ]; then
    echo "✅  jar 文件存在"
else
    echo "❌ gradle-wrapper.jar 缺失"
fi

echo ""
echo "==== 检查 Java ===="
if command -v java &> /dev/null; then
    echo "✅ java 可用"
    java -version
else
    echo "❌ java 命令未找到"
fi

Windows 批处理版本（`check_gradlew.bat`）：

@echo off
echo ==== 检查 gradlew.bat ====
if exist gradlew.bat (
    echo [OK] gradlew.bat 存在
) else (
    echo [FAIL] gradlew.bat 缺失
)

echo.
echo ==== 检查 gradle-wrapper.jar ====
if exist gradle\wrapper\gradle-wrapper.jar (
    echo [OK] jar 文件存在
) else (
    echo [FAIL] gradle-wrapper.jar 缺失
)

echo.
echo ==== 检查 Java ====
java -version 2>nul
if %errorlevel% neq 0 (
    echo [FAIL] Java 不可用
) else (
    echo [OK] Java 工作正常
)
pause

运行脚本后根据输出逐一修复即可。

总结

gradlew 找不到命令，绝大多数情况下与环境变量无关，而是由以下原因造成：

文件缺失（Wrapper 未生成或未提交）
没有执行权限（仅 Mac/Linux）
目录错误（不在项目根目录）
调用方式错误（缺少 ./ 前缀）
Wrapper 损坏（jar 丢失或损坏）
Java 未在 PATH 中显现
安全软件拦截

按照上述步骤逐一排查，99% 的情况都能在几分钟内解决。如果所有方法都无效，可以尝试删除整个项目后重新 git clone，并确保 clone 时网络正常、文件完整，然后再用 ./gradlew 启动。

问题现象：gradlew 明明在眼前，终端却提示 command not found

第一步：确认 gradlew 文件是否存在