오류 메시지

Mac에서 “npm error code ETIMEDOUT” 발생

ETIMEDOUT은 상대방이 제때 응답하지 않았다는 뜻입니다. Node.js 문서는 “연결된 상대방이 일정 시간 후에도 제대로 응답하지 않았습니다”라고 설명합니다.

적용 대상: npm 10 이상은 “npm error”를 출력합니다. 이전 버전은 “npm ERR!”를 출력합니다. 현재 지원되는 모든 macOS 버전.확인일: 2026년 10월 29일

증상

  • npm install이(가) npm error code ETIMEDOUT 메시지와 함께 중단됩니다.
  • npm은 이 문제가 네트워크 연결과 관련되어 있다고 덧붙입니다.
  • 회사 네트워크나 핫스팟 같은 특정 네트워크에서 실패합니다.

가능한 원인

  • npm에 설정되지 않은 프록시. 프록시가 필요한 네트워크에서는 npm의 proxy 및 https-proxy 설정이 필요합니다.
  • 연결할 수 없는 레지스트리. 오래된 registry 설정이 개인 서버를 가리킬 수 있습니다.
  • 느리거나 패킷 손실이 있는 연결. Wi-Fi 신호가 약하거나 핫스팟을 사용하면 큰 패키지의 다운로드 시간이 초과될 수 있습니다.
  • 작동하지 않는 IPv6 경로. 레지스트리에 IPv6 주소가 있지만 네트워크에서 IPv6가 작동하지 않습니다.

확인 방법

  1. npm의 레지스트리 및 프록시 설정을 표시합니다.

    npm config get registry
npm config get proxy
npm config get https-proxy

  2. 레지스트리에 응답을 요청하세요.

    npm ping

  3. curl을 사용하여 IPv4만으로 레지스트리를 테스트하세요.

    curl -4 -I https://registry.npmjs.org/

  4. 연결을 측정합니다.

    networkQuality

해결 방법

  1. 네트워크에 프록시가 필요하면 npm에 설정하세요.

    npm config set https-proxy http://proxy.example.com:8080

  2. npm이 기본값을 사용하도록 이전 레지스트리 설정을 제거합니다.

    npm config delete registry

  3. 느린 연결에서 npm의 재시도 횟수를 늘립니다.

    npm config set fetch-retries 5

  4. 가능하면 더 빠른 네트워크에서 설치를 다시 실행하세요.

Kilobat 사용

  1. Kilobat 연결 진단은 네트워크, 프록시, DNS, 규칙, IPv4, IPv6, TLS 및 서버 순으로 레지스트리를 테스트합니다. 실패한 계층을 알려줍니다.

    kilobat why https://registry.npmjs.org/

  2. 대규모 설치 전에 네트워크의 데이터 제한, VPN 연결 및 속도를 확인합니다.

    kilobat conditions

  3. 이 Kilobat 검사는 무료입니다. AI 에이전트는 MCP를 통해 diagnose_connection 및 diagnose_network(으)로 실행합니다. 특정 사이트나 API에 연결되지 않는 이유 찾기를 참조하세요.

질문

npm은 얼마나 기다리나요?

npm 문서에 따르면 기본 fetch-timeout은 300000 ms, 즉 5분이며 fetch-retries은 2입니다.

프록시 설정이 npm 다운로드에 영향을 줄 수 있나요?

예. npm에는 프록시 구성이 있으며, 접근할 수 없거나 잘못된 프록시는 레지스트리 연결을 방해할 수 있습니다.

출처

2026년 10월 29일 확인했습니다.