기술 · 실용 가이드
npm ETARGET? registry·요청 범위·게시 버전을 먼저 증명하세요
“No matching version found”는 게시되지 않은 버전, tag/range 불일치, scope별 private registry, 오래된 mirror metadata에서 생길 수 있습니다. cache나 lockfile을 지우기 전에 누락된 일치를 찾으세요.
npm이 ETARGET 또는 “No matching version found”를 보고하면 전체 package spec을 보존하고 npm이 실제 사용한 registry에서 검증하세요. 결정적 증거는 requester, registry endpoint, 게시된 version 집합, dist-tag 매핑이지 cache나 lockfile 삭제 후 우연히 달라진 결과가 아닙니다.
정확한 spec과 requester를 기록하세요
파일을 바꾸기 전에 ETARGET 전체 줄을 복사합니다. package 이름, exact version, range 또는 tag, npm version, 요청 출처가 package.json, package-lock.json, workspace, 생성 template, transitive dependency 중 무엇인지 기록합니다. 두 manifest를 검색하고 transitive면 install log와 dependency tree로 부모를 찾습니다.
npm이 실제 쓰는 같은 registry를 조회하세요
npm config get registry를 실행하고 token을 출력하지 않은 채 project, user, CI npmrc의 scope registry를 확인합니다. 같은 endpoint에 npm view <package> versions --json과 npm view <package> dist-tags --json을 실행합니다. npmjs.com에 보이는 version이 private registry나 mirror에도 있다는 증거는 아닙니다.
exact version, range, tag를 구분하세요
4.2.1 exact request는 실제 게시되어야 합니다. ^4.2.1 range는 registry가 반환한 version 중 하나 이상과 일치해야 합니다. latest, beta, next는 독립적으로 이동하는 dist-tag입니다. Git tag, Node.js version, GitHub release를 npm package version으로 착각하지 마세요.
prerelease와 게시 경계를 확인하세요
SemVer에서 3.0.0-beta.9는 일반 3.0.0보다 precedence가 낮고 같은 식별자가 아닙니다. registry에 prerelease만 있으면 exact 3.0.0은 여전히 일치하지 않습니다. range 변경 전에 publish time과 dist-tag를 보고 실패 spec을 보존해 미게시, unpublish, 일시 누락을 구분합니다.
manifest, lockfile, mirror를 분리해 감사하세요
같은 registry에서 npm view가 version을 보여 주면 실패한 CI/IDE의 registry URL, scope mapping, proxy, credentials를 비교합니다. package.json과 package-lock.json에서 직접 또는 transitive 요청인지 찾습니다. private proxy는 관리자가 지원하는 metadata refresh를 사용하고 원인을 알기 전 lockfile 삭제나 강제 cache clean을 하지 않습니다.
증명된 불일치만 고치세요
version이 없었다면 호환성을 확인해 template/dependency를 수정합니다. dist-tag가 예상과 다르면 검증된 exact version을 쓰거나 publisher를 기다립니다. mirror가 오래됐으면 mirror를 refresh하고 CI만 다르면 credential 노출 없이 scope registry를 맞춥니다. 마지막으로 npm view, install, lockfile diff를 확인합니다.
