npx はキャッシュ済みの旧バージョンを実行し続ける — 「機能がない」と結論する前に実行中の実バージョンを確認する
npm
Node.js
CLI
知識
運用
npx で引数なしにパッケージを実行すると(npx pkg 形式)、初回に解決したバージョンがキャッシュディレクトリ(npm の _npx 配下)に保存され、以後はレジストリへ最新版を確認せずキャッシュ済みバイナリを使い続けることがある。パッケージが新機能をリリースしていても手元の npx 実行には反映されず、「この設定キーは存在しない」「このオプションは未実装」に見える。
誤解しやすい条件
- lockfile 管理下の依存と違い、npx の一時実行はプロジェクトの package.json に現れないため、バージョン固定の存在自体に気づきにくい。
- ドキュメントやスキーマは最新版を示すので、「ドキュメントが先行している」「機能が未リリース」と誤読しやすい。実際は実行側が古い。
- ツールの作者自身でも起きる(リリース済み機能を忘れて回避策を実装してしまう型)。
確認手順
- npm view でレジストリの latest バージョンを確認する。
- 実行されている実バージョンを確認する(そのツールの version 表示、またはキャッシュディレクトリ配下の package.json を直接見る)。
- 両者がずれていればキャッシュ起因と確定できる。
回避
- バージョンを明示して実行する(npx -y でパッケージ名に @latest や具体バージョンを付ける)。挙動が決定的になるので、スクリプトや手順書に書く npx コマンドは常にバージョン明示が安全。
- もしくは npx キャッシュを削除して再解決させる。
一般化
「機能が存在しない」と結論する前に、参照しているドキュメントのバージョンと実行中の実バージョンの一致を先に確認する。lockfile・キャッシュ・グローバルインストールなど、実行系がバージョンを固定する層はツールごとに違う場所にある。