npm 환경 구성의 핵심: .npmrc 완전 정리
Node.js 개발을 하다 보면 패키지 설치 속도, 사내 프록시, 사설 npm 서버,
SSL 인증서 문제, CI/CD 자동화, 개인 토큰 관리 등 다양한 이유로.npmrc 설정이 필수적이다.
npm은 다음 경로의 .npmrc 파일들을 순서대로 병합하여 최종 설정을 결정한다:
- 프로젝트 로컬:
<프로젝트>/ .npmrc - 사용자 로컬:
~/.npmrc - 전역(Global):
$PREFIX/etc/npmrc - 내장(Default):
npm config -l
설정 우선순위는 프로젝트 > 사용자 > 전역 > 기본값이다.
📌 1. 기본 구조
.npmrc 파일은 키=값 형태의 단순한 설정 파일이다.
예:
registry=https://registry.npmjs.org/
strict-ssl=false
🔐 2. 프록시 설정(proxy)
사내 네트워크나 보안망 환경에서는 npm이 외부에 직접 접속할 수 없으며
프록시를 거쳐야 하는 경우가 흔하다.
HTTP 프록시
proxy=http://12.34.56.78:8080
HTTPS 프록시
https-proxy=http://12.34.56.78:8080
프록시가 인증을 요구할 경우
proxy=http://username:[email protected]:8080
https-proxy=http://username:[email protected]:8080
TIP
- 패스워드에 특수 문자가 있으면 반드시 URL 인코딩해야 한다.
- 프록시 사용 시 SSL 인증서를 건들여야 하는 경우가 많다. (아래 SSL/CA 항목 참고)
🔏 3. SSL 및 인증서 설정 (strict-ssl / CA / 인증서 파일)
사내 VPN, 프록시, 사설 인증서 등을 사용하는 경우
npm 설치 시 자주 보이는 에러:
UNABLE_TO_VERIFY_LEAF_SIGNATURE
SELF_SIGNED_CERT_IN_CHAIN
CERT_HAS_EXPIRED
이럴 때 .npmrc SSL 설정이 필요하다.
✔ strict-ssl 끄기 (권장 ❌)
가장 쉬운 방법이지만 보안적으로 위험하다.
strict-ssl=false
이렇게 하면 npm이 인증서를 검증하지 않는다.
임시 해결로는 가능하나 장기적으로는 권장하지 않는다.
✔ 사내 인증서(CA) 등록 (권장 ⭕
방법 1) CA 파일 직접 지정
cafile=/path/to/company-ca.pem
예:
cafile=C:\certs\corp-ca.pem
방법 2) 여러 CA를 수동 입력 (권장)
ca="-----BEGIN CERTIFICATE-----
...(생략)...
-----END CERTIFICATE-----"
여러 개 등록도 가능하다.
✔ npm이 기본 제공 CA 외의 CA도 신뢰하도록 설정
strict-ssl=true
ca[]=/path/ca1.pem
ca[]=/path/ca2.pem
🏛 4. 레지스트리(registry) 설정
기본값은 npm 공식 레지스트리:
registry=https://registry.npmjs.org/
사내에서 Nexus, Artifactory, Verdaccio 등 사설 npm 저장소를 운영한다면:
registry=http://my-nexus.company.com/repository/npm/
🔑 5. 인증 토큰(authToken) · 로그인 · npm publish
공개 저장소와 사설 저장소 모두 인증이 필요할 수 있다.
✔ 토큰 저장 (Bearer Token)
//registry.npmjs.org/:_authToken=YOUR_TOKEN_HERE
✔ 기본 인증 계정 정보
_username=myuser
_password=base64encodedpassword
[email protected]
⚠ _password는 base64로 인코딩해야 한다. (암호화가 아님)🔄 6. 캐시(Cache) 관련 설정
npm 캐시 경로 변경:
cache=/path/to/custom/cache
깨진 캐시가 원인일 때는:
npm cache clean --force
📦 7. 패키지 설치 옵션
✔ package-lock.json 저장 안 함
CI/CD 환경에 따라 비활성화할 때 사용
package-lock=false
✔ peerDependencies 자동 설치 허용
legacy-peer-deps=true
✔ optionalDependencies 무시
optional=false
🗂 8. Scoped Registry 설정(@scope)
조직별/프로젝트별 private registry를 사용할 때:
@mycompany:registry=http://my-nexus.company.com/repository/npm-group/
특정 scope만 사설 서버에서 받고,
나머지는 기본 npm registry로 받도록 할 수 있다.
🚚 9. Proxy + Private Registry + CA를 함께 사용한 실전 예시
아래는 실제 기업 환경에서 가장 흔히 사용하는 조합이다:
registry=http://nexus.mycorp.com/repository/npm-group/
proxy=http://12.34.56.78:8080
https-proxy=http://12.34.56.78:8080
cafile=C:\certs\mycorp-ca.pem
strict-ssl=true
@mycorp:registry=http://nexus.mycorp.com/repository/npm-private/
🧪 10. 설정 확인 및 테스트
현재 적용된 모든 npm 설정 확인:
npm config list
특정 항목 확인:
npm config get registry
npm config get proxy
설치 테스트:
npm install axios
🎉 마무리
.npmrc는 단순한 파일처럼 보이지만,
프록시, 인증서, 사설 레지스트리, 인증 토큰 등
네트워크/보안 환경이 복잡할수록 반드시 필요해지는 핵심 설정이다.
정리하자면:
- 회사·기관 네트워크 = proxy + CA + registry 필수
- strict-ssl=false는 임시 조치 → 권장 X
- 여러
.npmrc가 병합되므로 최종 config를 확인하는 습관이 중요 - CI/CD 환경에서는 토큰·scoped registry 설정이 핵심