构建与依赖 / 系统课时
代理、认证与网络配置
代理、认证与网络配置
这节解决 Maven 在公司代理、私有仓库和 CI 环境里“能连网却拉不到依赖”的问题。完成后,你会把代理和仓库凭据放进 settings.xml,用仓库 ID 正确匹配认证信息,并能根据 401、403、407 和 TLS 错误快速定位故障。
学习目标
- 配置 Maven 3.9.x 的 HTTP 代理、镜像与私服认证,并避免把密码写进项目 POM。
- 理解
server.id、仓库或镜像id的匹配规则,能检查认证为什么没有生效。 - 在 CI 中使用批处理模式和秘密注入完成非交互式构建,并按错误类型排查网络问题。
把网络与凭据移出 POM
Maven 的用户级配置默认位于 ~/.m2/settings.xml,这里适合放代理、镜像和服务器认证。项目仓库地址可以由 POM 描述,但用户名、令牌和代理密码不应随源码分发。下面示例面向 Maven 3.9.x;仓库与代理域名使用示例域名,实际项目替换为自己的地址。
<settings>
<proxies>
<proxy>
<id>corp-http-proxy</id>
<active>true</active>
<protocol>http</protocol>
<host>proxy.corp.example</host>
<port>8080</port>
<username>${env.PROXY_USER}</username>
<password>${env.PROXY_TOKEN}</password>
<nonProxyHosts>localhost|127.*</nonProxyHosts>
</proxy>
</proxies>
<mirrors>
<mirror>
<id>corp-repo</id>
<name>Corporate Repository Manager</name>
<url>https://repo.corp.example/repository/maven-public/</url>
<mirrorOf>*</mirrorOf>
</mirror>
</mirrors>
<servers>
<server>
<id>corp-repo</id>
<username>${env.REPO_USER}</username>
<password>${env.REPO_TOKEN}</password>
</server>
</servers>
</settings>这个文件把四个敏感值留给环境变量注入;Maven 的 settings.xml 支持 ${env.NAME} 形式的环境变量插值。nonProxyHosts 使用 | 分隔,适合把本机或内网直连地址排除在代理之外。若代理不需要认证,直接删除代理里的 username 和 password。

让 ID 匹配后再谈认证
<servers> 不按 URL 选凭据,而是按 id 匹配。若 mirrorOf 为 *,中央仓库等请求会先被镜像替换,此时真正连接的是镜像 corp-repo,所以 <server><id> 也必须写 corp-repo;写成 central 往往会导致请求没有带上正确凭据。
| 连接方式 | 凭据应匹配的 ID | 常见错误 |
|---|---|---|
直接访问 POM 中的 <repository> |
该 repository 的 id |
server id 拼错,返回 401 |
通过 <mirror> 替换仓库 |
mirror 的 id |
仍给原 repository id 配凭据 |
| 经过认证代理 | <proxy> 自己的用户名和密码 |
把私服令牌误当代理密码 |
在 CI 已注入 PROXY_USER、PROXY_TOKEN、REPO_USER、REPO_TOKEN 后,可直接用同一份仅含占位符的配置验证。-B 是批处理模式,-ntp 关闭下载进度,-U 会要求 Maven 检查缺失的 release 和更新的 SNAPSHOT。
test -n "${REPO_USER:-}" && test -n "${REPO_TOKEN:-}" && test -n "${PROXY_USER:-}" && test -n "${PROXY_TOKEN:-}"
mvn -B -s ./ci/settings.xml -ntp -U verify预期结果:项目本身可正常构建且网络配置正确时,末尾应出现:
[INFO] BUILD SUCCESS如果公司代理无需用户名和密码,应同时从 settings.xml 和变量检查命令中移除 PROXY_USER、PROXY_TOKEN,不要为了“配置完整”保留空凭据。
在 CI 中做非交互式认证
非交互式认证的关键不是让 Maven 自动猜密码,而是让 CI 在进程启动前准备好凭据。推荐把 REPO_USER、REPO_TOKEN 等保存到 CI 的 Secret 管理中,运行时注入环境变量;提交到仓库的 settings.xml 只保留 ${env.REPO_TOKEN} 这类引用,并限制构建日志打印环境变量。
Maven 3 也支持服务器密码加密。首次配置时运行 mvn --encrypt-master-password,把结果保存到 ~/.m2/settings-security.xml;再运行 mvn --encrypt-password,把得到的加密值放入 settings.xml 的 <password>。这两条命令建议不带密码参数,让 Maven交互读取,避免明文进入 shell 历史。
本地 Linux 或 macOS 可把敏感配置权限收紧为 600;Windows 则应使用文件 ACL 只允许构建账户读取。CI 使用临时工作目录时,构建结束后还应删除动态生成的 settings.xml,避免工作区归档把凭据带走。
按错误类型定位网络问题
先看 HTTP 或 TLS 错误,再决定改代理、凭据还是证书;不要一上来删除整个 ~/.m2/repository。同一条 mvn -B -s ./ci/settings.xml -ntp -U verify 命令即可作为复现入口,必要时临时增加 -X 获取调试日志,但分享日志前要检查 URL、用户名和令牌是否被带出。
| 现象 | 优先检查 | 处理动作 |
|---|---|---|
407 Proxy Authentication Required |
代理用户名、密码、代理地址 | 修正 <proxy>,确认代理账号可用 |
401 Unauthorized |
<server><id> 与实际 repository 或 mirror id |
修正 ID 或仓库令牌 |
403 Forbidden |
账号权限、仓库路径策略 | 让仓库管理员确认读取权限 |
Unknown host / connect timeout |
DNS、代理 host/port、nonProxyHosts |
用同网络环境验证代理可达性 |
PKIX path building failed |
企业 TLS 代理或私有 CA | 把受信 CA 正确导入构建 JDK 的信任库 |
最终验收可以很具体:同一台构建机上,删除项目 target 后执行批处理构建,不出现凭据提示、不把密码写入 POM、网络请求经过预期代理,且依赖能从指定私服解析并得到 BUILD SUCCESS。