Unknown host 'services.gradle.org'：代理设置问题解析

Question

**问题描述：** 在使用 Gradle 构建项目时，出现错误提示：“Unknown host 'services.gradle.org'”，导致依赖无法下载。该问题通常发生在使用代理网络环境下，Gradle 无法正确访问官方仓库。请解析该问题的常见原因，并提供可行的解决方案，包括但不限于配置 `gradle.properties` 文件中的代理设置、检查网络连接、切换镜像源等方法。要求步骤清晰，适用于不同操作系统平台（Windows/Linux/macOS）。

Answer 1

一、问题背景与现象描述

在使用 Gradle 构建项目时，开发者可能会遇到如下错误提示：

Unknown host 'services.gradle.org'

该错误通常出现在网络受限或使用代理服务器的环境中。Gradle 在构建过程中会尝试从官方仓库（如 https://services.gradle.org）下载依赖库和插件，若无法解析域名或访问目标地址，就会导致构建失败。

二、常见原因分析

1. 本地网络环境限制，例如公司内网或校园网限制了对外访问。
2. 未正确配置代理设置，导致 Gradle 无法通过代理访问外部资源。
3. DNS 解析异常，无法将 services.gradle.org 解析为 IP 地址。
4. 系统 hosts 文件中存在错误配置，覆盖了正常的 DNS 解析。
5. 防火墙或杀毒软件拦截了 Gradle 的网络请求。

三、解决方案详解

1. 检查基础网络连接

首先确保你的机器可以正常访问互联网，并尝试手动访问以下网址：

• https://services.gradle.org
• https://repo1.maven.org/maven2/

如果无法打开上述页面，请检查是否需要设置浏览器代理或联系网络管理员。

2. 配置 Gradle 代理设置

编辑或创建 gradle.properties 文件，添加如下代理配置：

# HTTP Proxy
systemProp.http.proxyHost=your.proxy.host
systemProp.http.proxyPort=your.proxy.port
systemProp.http.proxyUser=your.username
systemProp.http.proxyPassword=your.password

# HTTPS Proxy
systemProp.https.proxyHost=your.proxy.host
systemProp.https.proxyPort=your.proxy.port
systemProp.https.proxyUser=your.username
systemProp.https.proxyPassword=your.password

位置说明：

• 项目根目录下的 gradle.properties：仅影响当前项目。
• 用户目录下的 ~/.gradle/gradle.properties（Linux/macOS）或 C:\Users\用户名\.gradle\gradle.properties（Windows）：全局生效。

3. 使用镜像源替代官方仓库

修改项目的 build.gradle 或 settings.gradle 文件，替换默认仓库地址为国内镜像源，例如阿里云：

// settings.gradle (for Gradle 7+)
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        maven { url 'https://maven.aliyun.com/repository/public' }
        mavenCentral()
    }
}

或者旧版 build.gradle：

repositories {
    maven {
        url "https://maven.aliyun.com/repository/public"
    }
    jcenter()
}

4. 检查 hosts 文件配置

某些情况下，hosts 文件可能屏蔽了 Gradle 官方域名。检查并删除相关条目：

操作系统	路径
Windows	C:\Windows\System32\drivers\etc\hosts
Linux/macOS	/etc/hosts

查找是否有类似如下内容：

127.0.0.1 services.gradle.org

如有，请删除或注释掉。

5. 禁用防火墙或杀毒软件临时测试

部分安全软件会拦截 Gradle 的网络请求。可尝试暂时关闭防火墙或杀毒软件进行测试。

四、流程图展示解决思路

graph TD
            A[开始] --> B{能否访问 services.gradle.org ?}
            B -- 是 --> C[检查 Gradle 代理配置]
            B -- 否 --> D[检查本地网络或代理设置]
            C --> E{代理配置正确?}
            E -- 是 --> F[切换镜像源]
            E -- 否 --> G[重新配置代理]
            F --> H[构建成功]
            G --> H
            D --> I[尝试更换网络环境]
            I --> J{是否成功?}
            J -- 是 --> H
            J -- 否 --> K[检查 hosts 文件或防火墙]
            K --> L{修正后是否有效?}
            L -- 是 --> H
            L -- 否 --> M[联系网络管理员]