GitHub Actions 构建卡住怎么办？CI 依赖下载超时与海外网络排查指南

GitHub Actions 是很多团队的默认 CI/CD 平台。一次构建可能包含 checkout、安装依赖、下载浏览器、拉取 Docker 镜像、运行测试、上传制品、部署服务等多个步骤。只要其中某个外部资源访问慢，整个 workflow 就会表现为卡住、超时或失败。

CI 网络问题和本地开发不同。本地能成功，不代表 GitHub-hosted Runner、自建 Runner、容器 Runner 都能成功。排查时要把 Runner 区域、缓存命中、依赖源、Docker 构建、模型文件下载、API 调用和网络链路分开看。

本文排查路线

先定位 workflow 卡在哪一步：checkout、install、build、test、deploy。
检查缓存、依赖锁文件、Runner 类型和网络出口。
排查 npm、pip、Docker、GitHub Release、Hugging Face、OpenAI API 等外部资源。
自建 Runner 场景下，再优化 DNS、TLS、VPN 加速线路和出口稳定性。

一、先看卡住的 step

CI 阶段	常见表现	优先排查
checkout	拉仓库慢、submodule 超时	GitHub 链路、仓库体积、LFS、submodule
install	npm/pip/pnpm 下载依赖慢	缓存、依赖源、lockfile、网络出口
Docker build	基础镜像或 RUN 指令卡住	Docker Hub、apt、npm、pip、buildx
test	测试卡住或外部接口超时	测试依赖、API、数据库、模拟服务
deploy	上传制品或部署连接失败	云服务、SSH、对象存储、权限和网络

二、缓存命中决定 CI 速度下限

CI 里最常见的浪费，是每次从零下载依赖。前端项目的 node_modules、pnpm store，Python 项目的 pip cache，Docker 的 layer cache，Playwright 浏览器缓存，都会显著影响构建时间。缓存没命中时，网络问题会被放大。

CI 缓存检查清单

缓存 key 是否包含 lockfile hash，避免错误复用或永远不命中。
pnpm、yarn、npm、pip 是否缓存到正确目录。
Docker layer cache 是否在 buildx 或 registry cache 中启用。
Playwright、Cypress、Electron 等大文件是否重复下载。
自建 Runner 是否保留工作目录和依赖缓存。

三、AI 项目 CI 更容易遇到大文件下载

AI 应用的 CI 可能额外下载模型、向量库、测试数据集、浏览器、语音资源或图片处理依赖。Hugging Face 模型、OpenAI API 测试、Docker CUDA 镜像、Python 科学计算包，都会让 workflow 更依赖网络稳定性。

建议在 CI 日志里标记：
1. 哪一步开始变慢
2. 慢的具体资源：npm、pip、Docker、Hugging Face、API
3. 是否每次都慢，还是偶发慢
4. 是否只在某个 Runner 慢
5. 是否和缓存未命中有关

四、自建 Runner 要重点看出口网络

GitHub-hosted Runner 的网络环境由平台提供，自建 Runner 则完全依赖你自己的服务器或办公网络。如果自建 Runner 在国内网络环境里拉 Docker、npm、GitHub Release、Hugging Face 或 OpenAI API，跨境链路质量会直接影响 CI 成功率。

典型情况：本地跑测试快，自建 Runner 总是超时

这时要在 Runner 机器上单独测试 GitHub、npm、Docker、pip、Hugging Face、OpenAI API，而不是只看 workflow 配置。Runner 的 DNS、TLS、代理变量、系统证书和网络出口都可能和本地电脑不同。

五、稳如狗适合哪些 CI 场景

稳如狗加速器更适合自建 Runner、本地自动化构建机、开发者工作站和需要长期访问海外开发资源的环境。它可以帮助减少 GitHub 拉取慢、Docker 镜像下载中断、npm/pip 超时、AI API 测试失败和模型资源下载慢带来的 CI 不稳定。

如果 CI 是因为测试写得慢或缓存配置错误，先修 workflow；如果 Runner 上多个海外开发资源都慢，才需要重点优化 DNS、VPN 加速线路和网络出口。

六、推荐排查顺序

GitHub Actions / CI 网络排查：
1. 找到具体卡住的 step 和日志关键词
2. 检查缓存 key、lockfile、依赖安装目录
3. 区分 npm、pip、Docker、GitHub Release、Hugging Face、API
4. 对比本地、GitHub-hosted Runner、自建 Runner
5. 在 Runner 机器上单独测试外部资源
6. 自建 Runner 多资源都慢时，优化 VPN 加速线路