npm에서 레지스트리 차단 시 프록시 설정 방법: 미러, .npmrc 및 제한 우회

```html

npm 레지스트리에 접근할 수 없어서 프로젝트 빌드가 중단되었습니다. 이는 기업 네트워크, 접근이 제한된 지역 또는 엄격한 방화벽을 통해 작업할 때 개발자들이 자주 겪는 상황입니다. 이 가이드에서는 미러로 전환하는 것부터 .npmrc에서 프록시를 세밀하게 조정하는 방법까지 모든 작동 가능한 방법을 다룰 것입니다. npm install이 다시 오류 없이 작동하도록 합니다.

npm 레지스트리가 차단되는 이유와 그 과정

공식 npm 레지스트리는 https://registry.npmjs.org에 위치해 있습니다. 이는 글로벌 CDN이지만 여러 가지 이유로 접근할 수 없게 될 수 있으며, 각 경우마다 다른 접근 방식이 필요합니다.

레지스트리 접근 불가의 주요 원인

• 기업 방화벽 — 회사가 외부 리포지토리에 대한 직접 요청을 차단하고 내부 프록시 서버를 통해서만 트래픽을 허용합니다. 이는 은행, 정부 기관, 대형 IT 회사에서 일반적인 관행입니다.
• 지리적 차단 또는 지역 제한 — 일부 국가 및 지역에서는 npmjs.org에 대한 접근이 인터넷 서비스 제공업체나 정부 방화벽 수준에서 제한됩니다.
• 인터넷에 직접 연결되지 않은 사무실 네트워크 — 격리된 네트워크 세그먼트의 작업용 컴퓨터는 외부 리소스에 직접 접근할 수 없으며, 모든 트래픽은 기업 게이트웨이를 통해 전달됩니다.
• 강제 프록시가 있는 VPN 터널 — 기업 VPN이 모든 트래픽을 리디렉션하여 npm이 레지스트리에 직접 접근할 수 없습니다.
• SSL 검사 문제 — 기업 프록시가 HTTPS 트래픽을 가로채고 인증서를 변경하여 SELF_SIGNED_CERT_IN_CHAIN 또는 UNABLE_TO_VERIFY_LEAF_SIGNATURE와 같은 오류를 발생시킵니다.

차단된 레지스트리에서의 일반적인 오류

npm ERR! code ECONNREFUSED
npm ERR! errno ECONNREFUSED
npm ERR! network request to https://registry.npmjs.org/react failed

npm ERR! code ETIMEDOUT
npm ERR! network This is a problem related to network connectivity.

npm ERR! code CERT_HAS_EXPIRED
npm ERR! code SELF_SIGNED_CERT_IN_CHAIN

각 오류 코드는 다른 문제를 나타냅니다: ECONNREFUSED — 방화벽에 의해 연결이 거부됨, ETIMEDOUT — 요청이 응답 없이 차단됨, 인증서 오류 — SSL 검사 문제입니다. 원인을 이해하면 해결책의 범위를 즉시 좁힐 수 있습니다.

npm 레지스트리 미러: 프록시 없이 빠르게 우회하기

차단을 우회하는 가장 간단한 방법은 npm을 대체 레지스트리 미러로 전환하는 것입니다. 미러는 공식 레지스트리와 동일한 패키지를 포함하지만 다른 서버와 도메인에 위치합니다. 이는 registry.npmjs.org 도메인만 차단되고 전체 HTTPS 트래픽이 차단되지 않을 때 작동합니다.

인기 있는 npm 미러

레지스트리 전환 방법

한 번의 명령으로 전환하기 (전역 설정 변경 없이):

# 대체 레지스트리를 통한 일회성 설치
npm install react --registry https://registry.npmmirror.com

# 현재 사용자에 대해 전역적으로 설치
npm config set registry https://registry.npmmirror.com

# 현재 레지스트리 확인
npm config get registry

# 공식 레지스트리로 되돌리기
npm config set registry https://registry.npmjs.org

중요한 점: 프로젝트에서 명령으로 미러로 전환하는 경우, 이를 .npmrc 파일에 고정하는 것이 좋습니다. 그러면 팀의 모든 구성원이 프로젝트를 클론할 때 자동으로 올바른 구성을 받게 됩니다.

# 프로젝트 루트의 .npmrc
registry=https://registry.npmmirror.com

.npmrc를 통한 프록시 설정: 전체 구문

미러가 도움이 되지 않을 경우 (예: 모든 외부 HTTPS 트래픽이 차단된 경우), npm에 프록시 서버의 주소를 명시적으로 지정해야 합니다. .npmrc 파일은 npm의 주요 구성 파일이며, 프록시 설정이 저장됩니다.

.npmrc 파일의 위치

npm은 여러 위치에서 구성을 검색합니다 — 우선 순위 순서 (높은 것에서 낮은 것):

• 프로젝트 — /path/to/project/.npmrc — 이 프로젝트에만 적용됨
• 사용자 — ~/.npmrc — 현재 시스템 사용자에게 적용됨
• 전역 — $PREFIX/etc/npmrc — npm 설치 전체에 적용됨
• 내장 — /path/to/npm/npmrc — npm의 기본 설정

.npmrc에서 프록시 설정 구문

# HTTP 트래픽을 위한 프록시
proxy=http://proxy.example.com:8080

# HTTPS 트래픽을 위한 프록시 (레지스트리에 대한 대부분의 요청에 사용됨)
https-proxy=http://proxy.example.com:8080

# 인증이 있는 프록시 (URL에 로그인:비밀번호 포함)
proxy=http://username:[email protected]:8080
https-proxy=http://username:[email protected]:8080

# 예외 — 프록시를 우회하는 주소
noproxy=localhost,127.0.0.1,internal.company.com

npm config 명령을 통한 프록시 설정

파일을 수동으로 편집하는 대안으로 npm config set 명령을 사용할 수 있습니다. 이 명령은 사용자 ~/.npmrc에 설정을 자동으로 기록합니다:

# 프록시 설정
npm config set proxy http://proxy.example.com:8080
npm config set https-proxy http://proxy.example.com:8080

# 현재 프록시 설정 확인
npm config get proxy
npm config get https-proxy

# 프록시 설정 삭제 (직접 연결로 되돌리기)
npm config delete proxy
npm config delete https-proxy

# 전체 npm 구성 보기
npm config list

npm을 위한 환경 변수 프록시

npm은 프록시를 위해 표준 시스템 환경 변수를 자동으로 읽습니다. 이는 CI/CD 파이프라인, Docker 컨테이너 및 환경 수준에서 구성이 설정되는 시스템에서 유용합니다.

표준 환경 변수

# Linux / macOS — 현재 세션에 설정
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1

# 소문자 버전 (npm은 두 가지를 모두 이해함)
export http_proxy=http://proxy.example.com:8080
export https_proxy=http://proxy.example.com:8080

# Windows (명령 프롬프트)
set HTTP_PROXY=http://proxy.example.com:8080
set HTTPS_PROXY=http://proxy.example.com:8080

# Windows (PowerShell)
$env:HTTP_PROXY = "http://proxy.example.com:8080"
$env:HTTPS_PROXY = "http://proxy.example.com:8080"

npm 구성 우선 순위

npm은 프록시를 결정할 때 다음과 같은 우선 순위를 사용합니다 (높은 것에서 낮은 것):

1. 명령줄 플래그: --proxy http://...
2. 프리픽스가 있는 환경 변수 npm_config_: 예를 들어, npm_config_proxy
3. 프로젝트 .npmrc
4. 사용자 ~/.npmrc
5. 전역 $PREFIX/etc/npmrc
6. 표준 환경 변수 HTTP_PROXY / HTTPS_PROXY

.npmrc에 프록시가 설정되어 있지만 환경 변수가 다른 주소를 가리키는 경우 — .npmrc가 우선합니다. 이는 CI/CD 시스템에서 혼란을 초래하는 일반적인 원인입니다.

CI/CD에서 설정 (GitHub Actions, GitLab CI)

# GitHub Actions — job 또는 step의 env 섹션에 추가
jobs:
  build:
    runs-on: ubuntu-latest
    env:
      HTTP_PROXY: http://proxy.example.com:8080
      HTTPS_PROXY: http://proxy.example.com:8080
      NO_PROXY: localhost,127.0.0.1
    steps:
      - uses: actions/checkout@v3
      - run: npm install

# GitLab CI — 프로젝트 변수 또는 .gitlab-ci.yml에
variables:
  HTTP_PROXY: "http://proxy.example.com:8080"
  HTTPS_PROXY: "http://proxy.example.com:8080"

인증 및 SSL 검사와 함께하는 기업 프록시

기업 프록시 서버는 가장 복잡한 경우입니다. 이들은 단순히 트래픽을 리디렉션하는 것이 아니라 인증을 요구하며, 종종 SSL 검사를 수행합니다 (HTTPS 트래픽의 가로채기 및 해독). 이는 npm이 기본적으로 처리할 수 없는 특정 인증서 오류를 발생시킵니다.

NTLM/기본 인증이 있는 프록시

기업 프록시가 로그인과 비밀번호를 요구하는 경우 (기본 인증), 이를 URL에 직접 전달할 수 있습니다. 그러나 NTLM 인증 (Windows 도메인)의 경우는 더 복잡합니다 — npm은 NTLM을 기본적으로 지원하지 않습니다. 이 경우 중간 도구를 사용합니다.

# 기본 인증 — URL에 로그인과 비밀번호 포함
npm config set proxy http://user:[email protected]:8080
npm config set https-proxy http://user:[email protected]:8080

# 비밀번호에 특수 문자가 포함된 경우 — URL 인코딩 필요
# @ → %40, # → %23, : → %3A
# 예: 비밀번호 "p@ss#word" → "p%40ss%23word"
npm config set proxy http://user:p%40ss%[email protected]:8080

NTLM 인증을 위해 cntlm 유틸리티를 사용합니다 — 이 유틸리티는 로컬에서 실행되며 일반 HTTP 요청을 수신하고 기업 프록시와 NTLM 핸드셰이크를 수행합니다. npm에서는 이를 인증 없는 일반 프록시처럼 인식합니다:

# cntlm 설정 후 localhost:3128에서 수신
npm config set proxy http://localhost:3128
npm config set https-proxy http://localhost:3128

SSL 검사 문제 해결

SSL 검사를 수행하는 기업 프록시는 사이트의 인증서를 기업 인증서로 변경합니다. npm은 신뢰 체인을 확인하고 이러한 인증서를 거부합니다. 다음 세 가지 접근 방식이 있습니다:

방법 1 (권장): 기업 CA 인증서를 신뢰할 수 있는 인증서에 추가

# IT 부서에서 기업 인증서 받기 (.crt 또는 .pem 파일)
# 이를 npm 구성에 지정
npm config set cafile /path/to/corporate-ca.crt

# 또는 cafile을 통해 여러 인증서 추가
# 여러 CA를 하나의 PEM 파일로 결합할 수 있습니다

방법 2 (임시, 안전하지 않음): SSL 검증 비활성화

# 진단을 위한 임시 해결책으로만 사용하세요!
npm config set strict-ssl false

# 또는 한 명령에 대해
npm install --legacy-peer-deps --no-strict-ssl

npm을 위한 SOCKS5 프록시: 헬퍼 유틸리티를 통한 설정

npm은 HTTP/HTTPS 프록시만 기본적으로 지원합니다. SOCKS5 프록시 (예: 주거용 프록시 제공업체의 경우) 는 npm 구성에서 직접 지정할 수 없습니다. 중간 계층이 필요합니다 — npm의 HTTP 요청을 수신하고 SOCKS5를 통해 리디렉션하는 유틸리티입니다.

방법 1: proxychains (Linux/macOS)

# proxychains 설치
# Ubuntu/Debian:
sudo apt-get install proxychains4

# macOS:
brew install proxychains-ng

# /etc/proxychains4.conf 구성
[ProxyList]
socks5 proxy.example.com 1080 username password

# proxychains를 통해 npm 실행
proxychains4 npm install

방법 2: 로컬 HTTP to SOCKS5 변환기

privoxy 또는 polipo 유틸리티는 SOCKS5를 통해 트래픽을 터널링하는 로컬 HTTP 프록시를 생성합니다. 실행 후 npm은 localhost에서 일반 HTTP 프록시를 인식합니다:

# privoxy 설치
sudo apt-get install privoxy  # Ubuntu/Debian
brew install privoxy          # macOS

# /etc/privoxy/config에 추가:
forward-socks5 / proxy.example.com:1080 .

# Privoxy는 기본적으로 localhost:8118에서 수신
# npm이 이 주소를 사용하도록 지정:
npm config set proxy http://localhost:8118
npm config set https-proxy http://localhost:8118

방법 3: SOCKS5 프록시로서 SSH 터널

외부 인터넷에 접근할 수 있는 원격 서버에 접근할 수 있는 경우, SSH SOCKS5 터널을 생성하고 이를 통해 npm 트래픽을 리디렉션할 수 있습니다. 이는 제한된 접근이 있는 기업 네트워크에서 작업할 때 특히 유용합니다:

# 로컬 포트 1080에서 SSH SOCKS5 터널 생성
ssh -D 1080 -f -C -q -N [email protected]

# 이후 privoxy 또는 proxychains를 사용하여 HTTP로 변환
# 또는 직접 환경 변수를 통해 (Node.js는 일부 라이브러리를 통해 SOCKS를 이해함)

# 대안 — curl을 테스트로 사용:
curl --socks5 localhost:1080 https://registry.npmjs.org/react/latest

프록시 대안으로서의 자체 프라이빗 레지스트리

기업 및 격리된 환경에서는 각 개발자를 위한 프록시 설정보다 내부 네트워크에 자체 npm 레지스트리를 배포하는 것이 더 나은 해결책입니다. 이러한 레지스트리는 공개 npmjs.org에서 패키지를 캐시하고 내부 네트워크에서 제공합니다. 개발자는 인터넷에 접근할 필요가 없으며, 모든 것이 로컬 레지스트리를 통해 작동합니다.

Verdaccio: 10분 만에 빠른 시작

Verdaccio는 프록시 및 캐싱을 지원하는 오픈 소스 npm 레지스트리입니다. npm 패키지로 설치되며 별도의 서비스로 작동합니다:

# Verdaccio를 전역적으로 설치
npm install -g verdaccio

# 실행 (기본적으로 http://localhost:4873에서 수신)
verdaccio

# npm을 로컬 레지스트리를 사용하도록 설정
npm config set registry http://localhost:4873

# 로컬 레지스트리에 패키지 게시
npm adduser --registry http://localhost:4873
npm publish --registry http://localhost:4873

Verdaccio 구성 (~/.config/verdaccio/config.yaml)은 npmjs.org에서 패키지를 다운로드하기 위해 외부 프록시를 통해 프록시를 설정할 수 있습니다:

# config.yaml — 프록시가 있는 uplink 설정
uplinks:
  npmjs:
    url: https://registry.npmjs.org/
    # Verdaccio가 프록시 뒤에 있는 경우:
    agent_options:
      http_proxy: http://proxy.company.com:8080
      https_proxy: http://proxy.company.com:8080
      no_proxy: localhost,127.0.0.1

packages:
  '@*/*':
    access: $all
    publish: $authenticated
    proxy: npmjs
  '**':
    access: $all
    publish: $authenticated
    proxy: npmjs

격리된 환경을 위한 솔루션 비교

일반적인 오류 진단 및 해결

프록시를 올바르게 설정한 후에도 문제가 발생할 수 있습니다. 다음은 진단을 위한 체계적인 접근 방식과 가장 일반적인 오류 목록 및 해결 방법입니다.

1단계: 현재 npm 구성 확인

# 모든 npm 설정 표시 (프록시 포함)
npm config list

# 프록시 설정만 표시
npm config get proxy
npm config get https-proxy
npm config get registry
npm config get strict-ssl

# 진단을 위한 자세한 출력 활성화
npm install react --verbose
npm install react --loglevel verbose

2단계: 레지스트리 접근 가능성 직접 확인

# curl을 통해 레지스트리 접근 가능성 확인
curl -v https://registry.npmjs.org/react/latest

# 프록시를 통해 확인
curl -v --proxy http://proxy.example.com:8080 https://registry.npmjs.org/react/latest

# ping 확인 (HTTPS에 대해 항상 유용하지는 않음)
ping registry.npmjs.org

# DNS 해상도 확인
nslookup registry.npmjs.org

일반적인 오류 및 해결 방법

모든 프록시 설정 초기화

# 사용자 구성에서 모든 프록시 설정 삭제
npm config delete proxy
npm config delete https-proxy
npm config delete noproxy

# 레지스트리를 공식 레지스트리로 되돌리기
npm config set registry https://registry.npmjs.org

# strict-ssl 되돌리기 (비활성화한 경우)
npm config set strict-ssl true

# 최종 구성 확인
npm config list

차단된 레지스트리에서 pnpm 및 Yarn 사용하기

대체 패키지 관리자를 사용하는 경우, 프록시 설정은 유사하지만 구문이 약간 다릅니다:

# pnpm — npm과 동일한 .npmrc 사용
# 추가로 pnpm config를 통해 설정 가능:
pnpm config set proxy http://proxy.example.com:8080
pnpm config set https-proxy http://proxy.example.com:8080
pnpm config set registry https://registry.npmmirror.com

# Yarn Classic (v1) — 자체 .yarnrc 파일
yarn config set proxy http://proxy.example.com:8080
yarn config set https-proxy http://proxy.example.com:8080
yarn config set registry https://registry.npmmirror.com

# Yarn Berry (v2+) — .yarnrc.yml 파일
# httpProxy: "http://proxy.example.com:8080"
# httpsProxy: "http://proxy.example.com:8080"
# npmRegistryServer: "https://registry.npmmirror.com"

특정 스코프 패키지에 대한 프록시 설정

때때로 서로 다른 패키지에 대해 서로 다른 레지스트리를 사용해야 합니다: 예를 들어, 공개 패키지는 공식 npmjs.org에서 가져오고, 기업 패키지 @company/*는 내부 Nexus에서 가져옵니다. 이는 .npmrc에서 스코프별 레지스트리를 통해 설정됩니다:

# .npmrc — 서로 다른 스코프에 대해 서로 다른 레지스트리
registry=https://registry.npmjs.org

# 기업 패키지 @company는 내부 Nexus를 통해
@company:registry=http://nexus.company.local/repository/npm-hosted/

# @myorg 패키지는 Verdaccio를 통해
@myorg:registry=http://localhost:4873/

# 특정 레지스트리에 대한 인증
//nexus.company.local/repository/npm-hosted/:_authToken=YOUR_TOKEN_HERE

결론 및 최종 권장 사항

npm 레지스트리 차단 문제를 해결하기 위해 다양한 방법을 살펴보았습니다. 각 방법의 장단점을 이해하고, 상황에 맞는 최적의 솔루션을 선택하는 것이 중요합니다. 기업 환경에서는 프록시 설정을 통해 접근성을 높이고, 필요에 따라 자체 레지스트리를 운영하는 것도 좋은 선택이 될 수 있습니다. 항상 보안과 안정성을 고려하여 설정을 진행하시기 바랍니다.