Vercel/Netlify 部署国内访问指南:build 失败、拉依赖超时、控制台打不开全解

前端项目上线,Vercel 和 Netlify 几乎是默认选项:连上仓库、推一次代码、几十秒出预览地址,不用碰服务器。但在国内用它们,总有几件事反复发生——控制台打开一半卡住,部署列表一直转圈;`vercel login` 敲下去,浏览器跳出授权页却回调不回来;好不容易推上去,构建日志里满屏 `ETIMEDOUT`、`network timeout`,而同一份代码在本地 `npm run build` 一次就过;更让人困惑的是,有时候明明部署成功了,自己却打不开生成的预览地址。

把这些现象放在一起容易乱,但它们其实分属两层完全不同的问题。第一层是你到平台的访问:控制台、CLI 登录回调、预览地址,这些卡住是你这边的线路问题。第二层是平台构建机到外部资源的访问:构建时拉 npm 包、克隆子模块、下载二进制依赖,这些超时和你本地的网络毫无关系,构建机在海外,超时通常是源站限流、依赖地址不可达或者构建配置本身有问题。搞混这两层,就会出现「我挂了代理为什么 build 还是失败」这种典型误判。这篇按这两层分开讲。

Vercel 与 Netlify 的差异,以及两层问题的边界

这张表最有用的是最右边那一列。看到问题先问自己:这是我打不开,还是构建机拉不到?前者靠线路解决,后者要改构建配置、锁依赖版本或者换镜像源。两个平台在这方面的行为高度相似,选谁更多是看功能偏好而非网络表现。需要说明的是,两家的免费额度、构建时长限制与功能边界会不定期调整,以官方最新条款为准。

把访问与构建都配顺:分步操作步骤

• 第一步:先把线路准备好,连上刺猬VPN。安装后自定义用户名和密码即可匿名注册,不需要邮箱、也不需要手机号,免费节点永久免费、不限流量,连上后先确认浏览器能正常打开 Vercel 或 Netlify 的控制台;
• 第二步:挑一个延迟低、稳定的海外节点。控制台是重前端应用,资源请求多,延迟高的时候会表现成「加载一半卡住」;
• 第三步:CLI 登录前确认线路已生效。`vercel login` 与 `netlify login` 走的是浏览器回调授权,回调地址连不通就会一直卡在等待状态,授权页开着也没用;
• 第四步:如果回调始终失败,改用 token 方式登录。在控制台生成访问令牌后写进环境变量,CLI 就不再依赖浏览器回调,CI 环境里本来也该这么做;
• 第五步:把本地依赖锁死。提交 lockfile,确保构建机拿到的依赖树和你本地一致,很多「本地能过线上挂」其实是版本漂移而不是网络;
• 第六步:处理构建时的依赖超时。构建机在海外,拉不到某个包时优先检查依赖地址是否可达、是否指向了国内镜像源——构建机用不了你本地配的国内镜像,镜像源与官方源的取舍见 开发者镜像源与包管理访问;
• 第七步:检查构建配置里的仓库依赖。子模块、私有仓库、release 附件都要构建机能访问,GitHub 侧的常见问题见 GitHub 访问加速;
• 第八步:构建里如果要拉容器镜像或用自定义镜像环境,那是另一套问题,处理方式见 Docker Hub 拉取镜像指南;
• 第九步:部署成功后用线路打开预览地址验证。打不开不代表部署失败,先确认是访问问题还是构建产物问题;
• 第十步:手机上看部署状态的话,iOS 客户端需要外区 Apple ID 下载,中国大陆区 App Store 不提供 VPN 类应用,步骤见 iOS 安装教程。

按现象逐条排查:控制台、CLI、构建、访问产物

下面按现象分类。每条先说明它属于哪一层,再给动作——判断对了层,处理起来通常都不复杂。

• 控制台打开一半卡住、部署列表转圈:第一层问题,连稳定节点后强制刷新,控制台前端资源多,首次加载慢属正常;
• CLI 登录卡在等待授权:第一层问题,回调地址连不通,确认线路生效;反复失败就改用 token 登录,不依赖浏览器回调;
• 构建日志里 npm ERR! network timeout:第二层问题,构建机拉不到包,检查是否把国内镜像源写进了项目配置,构建机访问不了那些地址;
• 构建卡在克隆子模块:第二层问题,子模块地址构建机不可达或需要凭证,改用 HTTPS 地址并配置访问令牌;
• 本地 build 通过、线上失败:大概率不是网络,而是 Node 版本、环境变量或依赖版本不一致,先对齐这三样再怀疑网络;
• 构建超时被强制中断:构建耗时超过平台限制,精简构建步骤、开启缓存,限额口径以官方最新条款为准;
• 部署成功但预览地址打不开:第一层问题,先用线路访问验证,再判断是不是产物本身有问题;
• 环境变量在构建里读不到:与网络无关,检查变量作用域是否勾选了构建阶段,以及命名前缀是否符合框架要求;
• 自定义域名解析后长时间不生效:DNS 传播需要时间,先用平台分配的域名验证站点本身是否正常。

线路与登录方式怎么选

个人偶尔推个静态站,免费节点永久免费、不限流量就够;如果一天要部署十几次、还要盯实时构建日志,那就固定一个低延迟节点,并把 CLI 换成 token 登录,少一个环节就少一类故障。构建日志是长连接推送的,线路一抖日志就断,这也是很多人误以为「构建挂了」的原因。一个账号支持多设备同时在线,开发机、笔记本可以共用配置。实际可用性取决于当前网络环境。

和包管理、代码托管、镜像仓库的分工

部署平台只是整条链路的最后一环,前面还有三段各有各的最优解。依赖拉取这一段,本地开发用国内镜像源通常最快,但这个配置不能带到平台构建机上——构建机在海外,写死国内镜像反而可能拉不到或更慢,什么时候该切回官方源、lockfile 与镜像源怎么配合,见 开发者镜像源与包管理访问。

代码托管这一段,构建触发靠的是仓库的 webhook,而你本地推代码、拉 LFS 大文件、下载 release 附件又是另一类问题,处理方式见 GitHub 访问加速。如果项目用了自定义构建镜像或者在构建里跑容器,那就还要面对镜像拉取超时,思路见 Docker Hub 拉取镜像指南。把这四段按「各走各的最优路径」配置,而不是指望一条代理规则包治百病,整条流水线才会稳定。各平台的构建配额与功能边界随时可能调整,以官方最新条款为准。

常见报错速查表

高频问答

• 问:我挂了代理为什么构建还是失败?答:构建跑在平台的海外构建机上,和你本地线路无关,构建阶段的超时要从依赖地址和构建配置找原因;
• 问:项目里配了国内镜像源,线上为什么拉不到包?答:构建机访问不了那些镜像地址,项目配置里不要写死国内源,本地用环境变量或全局配置更合适;
• 问:CLI 登录一直卡住怎么办?答:改用控制台生成的访问令牌登录,不依赖浏览器回调,CI 环境本来就该用这种方式;
• 问:Vercel 和 Netlify 哪个在国内更好用?答:两者的访问表现接近,选择更多看功能偏好,免费额度与限制以官方最新条款为准;
• 问:免费节点够用吗?答:偶尔部署够用,免费节点永久免费、不限流量;频繁部署并盯实时日志建议换更稳的线路,日志走长连接,抖动会导致中断;
• 问:iPhone 上怎么装客户端?答:中国大陆区 App Store 不提供 VPN 类应用,需要外区 Apple ID 下载,步骤见 iOS 安装教程,实际可用性取决于当前网络环境。

深度补充:把两层问题分开治,部署才不会靠运气

Vercel 打不开、Netlify 后台访问慢、Vercel 部署失败、build 超时、拉依赖 ETIMEDOUT、Vercel CLI 登录失败、前端部署国内怎么配,这一串搜索词看似指向不同故障,实际只需要一个判断动作:先分清这是「我到平台」的问题还是「构建机到外部资源」的问题。前者靠一条稳定线路解决,后者靠依赖配置、lockfile 和构建缓存解决。绝大多数人卡很久的原因,就是拿第一层的办法去治第二层的病——挂上代理反复重试,而构建机那边其实一次都没变过。

第一层的线路值得一次配到位。刺猬VPN全程 HTTPS+AES 加密,严格零日志政策,不记录、不存储浏览记录;对于要在控制台里查看环境变量、部署日志、访问令牌的人来说,这一点很实际。服务器覆盖 20 多个国家、100 多台,可以挑一个延迟低、抖动小的节点常驻,专门给控制台与 CLI 用。注册是匿名的,自定义用户名和密码即可完成,不需要邮箱和手机号,也不用绑定支付方式;免费节点永久免费、不限流量,个人项目偶尔部署够用,团队协作、一天推十几次并长时间盯实时构建日志可以选时长套餐,期间不限流量、不限速,用得少则用流量包,按用量付费、用多少扣多少。客户端覆盖 Windows、macOS、Android 与 iOS,一个账号支持多设备同时在线,开发机、笔记本、临时用的机器可以共用一套配置。线路稳定之后,控制台、CLI、包管理源、代码托管、镜像仓库这几段就能各走各的最优路径,前端部署这条链路整体都会顺很多。实际可用性取决于当前网络环境。