---
title: "Mac 上的 npm error code ETIMEDOUT：解决 npm 网络超时 · Kilobat 指南"
url: "https://kilobat.app/zh-hans/guides/npm-etimedout.html"
description: "在 Mac 上运行 npm install 时出现 npm error code ETIMEDOUT 并中止。检查 registry、代理和网络连接，然后调整 npm 的设置。"
---

错误信息

# Mac 上出现“npm error code ETIMEDOUT”

ETIMEDOUT 表示对方没有及时响应。Node.js 文档的说法是：“the connected party did not properly respond after a period of time.”（连接方在一段时间后未正确响应。）

适用于：npm 10 及更高版本输出“npm error”，更早的版本输出“npm ERR!”。适用于所有当前 macOS 版本。 · 核查日期：2026年10月29日

## 症状

- `npm install` 中止并显示 `npm error code ETIMEDOUT`。
- npm 还会提示这是与网络连接有关的问题。
- 只在某个网络上失败，例如公司网络或热点。

## 可能的原因

- **npm 不知道的代理。**在需要代理的网络上，npm 需要设置 `proxy` 和 `https-proxy`。
- **无法访问的 registry。**旧的 `registry` 设置可能指向一台私有服务器。
- **连接缓慢或丢包。**在信号弱的 Wi-Fi 或热点上，大型包会超时。
- **IPv6 路径不通。**registry 有 IPv6 地址，而你的网络上 IPv6 无法使用。

## 如何检查

1. 显示 npm 的 registry 和代理设置。

   ```
   npm config get registry
   npm config get proxy
   npm config get https-proxy
   ```
2. 测试 registry 是否响应。

   ```
   npm ping
   ```
3. 用 curl 测试 registry，仅使用 IPv4。

   ```
   curl -4 -I https://registry.npmjs.org/
   ```
4. 测量连接质量。

   ```
   networkQuality
   ```

## 如何修复

1. 如果网络需要代理，为 npm 设置代理。

   ```
   npm config set https-proxy http://proxy.example.com:8080
   ```
2. 删除旧的 registry 设置，让 npm 使用默认值。

   ```
   npm config delete registry
   ```
3. 在慢速连接上增加 npm 的重试次数。

   ```
   npm config set fetch-retries 5
   ```
4. 如果可以，换到更快的网络上再次安装。

## 使用 Kilobat

1. Kilobat 的连接诊断会逐层测试 registry：网络、代理、DNS、规则、IPv4、IPv6、TLS 和服务器，并指出失败的是哪一层。

   ```
   kilobat why https://registry.npmjs.org/
   ```
2. 大型安装前，先检查网络是否按流量计费、是否在 VPN 上或速度较慢。

   ```
   kilobat conditions
   ```
3. Kilobat 的这些检查都是免费的。AI 智能体可以通过 MCP 用 `diagnose_connection` 和 `diagnose_network` 运行它们。请参阅[找出某个网站或 API 连不上的原因](https://kilobat.app/zh-hans/guides/recipes/why-cant-it-connect.html)。

## 常见问题

**npm 会等待多久？**

根据 npm 文档，`fetch-timeout` 默认为 300000 ms，即 5 分钟；`fetch-retries` 默认为 2。

## 参考资料

- [Node.js 文档：Common system errors](https://nodejs.org/api/errors.html#common-system-errors)
- [npm 文档：config](https://docs.npmjs.com/cli/v11/using-npm/config)
- curl(1) 和 networkQuality(8)，macOS 27.2 自带的手册页

参考资料核查于 2026年10月29日。man 手册页为 macOS 自带版本；在“终端”中用 `man <name>` 打开。

## 相关指南

- [Mac 上出现“npm error code ECONNRESET”](https://kilobat.app/zh-hans/guides/npm-econnreset.html): ECONNRESET 表示对方强行关闭了连接。
- [Mac 上 Homebrew 或 npm 下载失败](https://kilobat.app/zh-hans/guides/homebrew-npm-download-fails.html): Homebrew 通过 curl 和 Git 下载。
- [Mac 上代理设置导致 App 无法连接](https://kilobat.app/zh-hans/guides/proxy-settings-breaking-apps.html): 代理设置会让流量经由另一台服务器转发。
- [Mac 上公司代理证书导致“终端”工具出错](https://kilobat.app/zh-hans/guides/corporate-proxy-certificates.html): 一些公司网络会检查 HTTPS 流量。
- [智能体下载大文件前先检查网络](https://kilobat.app/zh-hans/guides/recipes/check-network-before-download.html): 智能体可以询问 Kilobat 现在是否适合进行大量传输。