代码一提交,平台就会自动帮你安装依赖、编译、测试——这套自动流程在自己电脑上跑得好好的,放到平台上却卡在下载依赖那一步,最后超时失败。
多数时候,是跑这套流程的那台机器没有走代理。
这篇讲三处可以配置代理的地方,再讲两件在自己电脑上不存在、上了自动流程才会暴露的问题:密码不能写进配置文件,以及每次运行的出口地址可能都不一样。
一、先确认:你真的需要代理吗
用 GitHub 官方提供的运行机,大多数公开的依赖源本来就能直接访问,不一定需要代理。CI 是「持续集成」的缩写,就是代码提交后自动运行构建和测试的流程;运行机就是实际执行这些步骤的那台机器。
通常需要代理的是这几种情况:
- 运行机是你们自己搭建、放在公司网络里的,公司网络要求所有外部访问走代理。
- 流程里有一步需要从特定地区访问某个服务,比如测试网站在某个国家的表现。
- 某个依赖源从运行机所在的网络访问很慢或不稳定。
如果都不是,先查依赖源本身是否故障,再考虑代理。
二、第一步:把代理地址存进密钥
代理地址里通常带着账号密码,绝不能直接写进工作流文件,也不能提交进仓库。工作流文件就是仓库里描述自动流程的那个配置文件,仓库的读者都能看到它。
正确做法是存进平台的「密钥」里,流程运行时再读取。步骤:
- 打开 GitHub 上的仓库页面,点 Settings。
- 左侧选 Secrets and variables → Actions。
- 点 New repository secret。
- 名称填
PROXY_URL,值填http://用户名:密码@代理地址:端口。 - 点保存。
存进去之后,值在运行日志里会被自动隐藏。密码里有 @ 等符号的,先按URL 编码转写。团队里凭据怎么管,见代理账号密码怎么管。
三、三处可以配的地方
按影响范围从大到小:整个工作流、单个任务、单个步骤。
整个工作流都走代理:在工作流文件顶部设置环境变量。下面这段的作用是让这个工作流里所有步骤都带上代理设置:
env:
HTTP_PROXY: ${{ secrets.PROXY_URL }}
HTTPS_PROXY: ${{ secrets.PROXY_URL }}
NO_PROXY: localhost,127.0.0.1
只让某一步走代理:把环境变量写在那一步下面。下面这段的作用是只在安装依赖这一步走代理,其他步骤不受影响:
- name: 安装依赖
env:
HTTPS_PROXY: ${{ secrets.PROXY_URL }}
run: npm ci
环境变量的大小写规则和各程序的读取差异,见HTTP 代理环境变量相关文章。
四、不读环境变量的工具要单独配
有些工具不读 HTTP_PROXY 这类环境变量,要在流程里给它们单独生成配置。
| 工具 | 读不读环境变量 | 怎么配 |
|---|---|---|
| npm、pip、curl 等 | 读 | 第三节的环境变量即可 |
| Maven | 不读 | 在流程里先生成一份带代理的 settings.xml |
| Gradle | 不读 | 通过 -D 参数传入,或生成 gradle.properties |
| Docker 拉镜像 | 由后台服务决定 | 要配的是 Docker 服务本身,不是这一步的环境变量 |
Maven 和 Gradle 的具体写法见Maven、Gradle、Composer 怎么配代理,注意生成的配置文件里的密码同样要从密钥读取;Docker 见Docker 怎么设置代理;集群环境见Kubernetes 怎么配代理。
五、CI 特有的问题:出口地址不固定
平台官方提供的运行机,每次运行可能都是一台新机器,对外的地址也可能每次都不同。
这在自己电脑上不会遇到,却会直接影响两件事:
- 按来源地址认证会反复失效:如果代理或某个外部服务是靠「登记你的机器地址」来放行的,运行机地址一变,就进不去了。这种情况要改用账号密码认证。
- 对方需要登记你的地址时,登记不了:比如某个合作方的接口只允许指定地址访问。
需要固定出口时,有两种做法:
- 用自己搭建的运行机,放在出口固定的网络里。
- 让流程统一通过一个出口固定的代理访问外部,对方只需要登记这个代理出口。
六、用 Jenkins 的情况
Jenkins 自己的代理设置只管下载插件,构建任务里还要另外配。Jenkins 是另一种常用的自动构建工具。
- 插件下载:在管理页面的插件管理里,找到高级设置中的代理配置,填代理地址。不同版本菜单位置略有不同。
- 构建任务:在任务配置或流水线脚本里设置环境变量,做法和第三节相同;凭据用 Jenkins 自带的凭据管理来存,不要写在脚本里。
七、边界与产品对应
必须说清楚:依赖拉不下来,不一定是代理的问题。依赖源本身故障、版本号写错、缓存损坏,都会导致失败。先看错误信息是连接超时,还是找不到某个版本。
需要给自动流程一个长期固定的出口,方便对方登记时,可以用静态住宅 IP(按条数计费,出口长期不变)。再次提醒:账号密码一律放在密钥里,不要写进工作流文件或提交进仓库。配置示例均为通用占位写法,具体连接信息以后台为准。我们提供免费试用。
八、常见问题
Q1. GitHub Actions 怎么设置代理?
A. 先把代理地址存进仓库的 Actions 密钥,再在工作流文件里用环境变量 HTTP_PROXY、HTTPS_PROXY 引用它。
Q2. 设置了代理,Maven 还是拉不到依赖?
A. Maven 不读环境变量,要在流程里单独生成一份带代理的 settings.xml。
Q3. 代理密码可以写在工作流文件里吗?
A. 不可以。工作流文件在仓库里,能看到仓库的人都能看到。一律存进密钥。
Q4. 为什么按地址认证在 CI 里总是失效?
A. 平台提供的运行机每次可能是新机器,出口地址会变。改用账号密码认证,或使用出口固定的运行机。
先测,再谈采购
先确认真的需要代理,再把地址存进密钥、按工具逐个配好。
(本文基于 2026 年 10 月 GitHub Actions 与 Jenkins 的通用做法整理,界面名称以实际版本为准;示例中的地址与凭据均为占位写法。)