テクノロジー · 実用ガイド
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は返されたversionの少なくとも一つに一致する必要があります。latest、beta、nextはversionを指す可動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強制消去をしません。
証明した不一致だけ直す
versionが存在しないなら互換性を確認してtemplate/dependencyを修正します。dist-tagが予想外なら検証済みexact versionを使うかpublisherを待ちます。mirrorが古いならmirrorを更新し、CIだけ違うならcredentialを漏らさずscope registryを合わせます。最後にnpm view、install、lockfile diffを再確認します。
