npm グローバル管理から mise に移行したら npm キャッシュにハマった話

TL;DR — mise の npm バックエンドで @latest が存在しないバージョンに解決される場合、mise cache clear で mise の versions host キャッシュを消すと直る。

npm でグローバル管理していたツールを mise に移行しようとしたら、キャッシュ問題でちょっとハマったので記録しておく。

移行対象

$ npm list -g --depth=0
├── @playwright/[email protected]   ← 新しいやつ（旧: playwright-cli）
├── @tobilu/[email protected]
├── @playwright/[email protected]
└── [email protected]

今回 mise に移行したのは @playwright/cli と @tobilu/qmd の2つ。

@playwright/cli の移行でハマった

まず Deprecated なパッケージを入れてしまう

まず playwright-cli（旧・Deprecated）と @playwright/cli（新）を間違えて Deprecated の方を mise に入れてしまった。mise unuse で無効化してから改めてやり直し。

そしたら謎のエラーが出た。

$ mise use --global npm:@playwright/cli@latest
npm error code ETARGET
npm error notarget No matching version found for @playwright/[email protected].

@latest を指定しているのに 0.262.0 という存在しないバージョンを引いてくる。なにそれ。

ひとまず バージョン指定でインストールしてみる

どうにもならないので、ひとまず Claude さんが固定バージョンでインストールしろと言ってたのでやってみたらインストールできた。

# バージョン固定で入れる
$ mise use --global npm:@playwright/[email protected]
Reshimming mise lts...
npm:@playwright/[email protected] added 3 packages in 2s
✔
mise ~/.config/mise/config.toml tools: npm:@playwright/[email protected]

でも気持ち悪いので、latest にできないのか更に調査を進める。

状況の整理

npm info @playwright/cli dist-tags を確認すると：

{ latest: '0.1.8' }

レジストリ側は正常。mise の設定ファイルにも残っていない。MISE_VERBOSE=1 のログを眺めていたらヒントがあった。

DEBUG [vfox] Getting metadata for yarn

Claude さん曰く

見えた！[vfox] Getting metadata for yarn が怪しい。vfox というプラグインが yarn のメタデータを取得するときに @playwright/[email protected] を引いてきてる可能性がある。〜中略〜 find ~/.local/share/mise -name "*vfox*" 2>/dev/null の結果見せて

とのことで、Claude さんが暴走しようとしてたので再度指示した。

「これ調べる前に mise の公式ドキュメントとか調査してもらえる？」

解決

mise の公式ドキュメント に普通に書いてあった。

$ mise cache clear

mise cache clear の実態は rm -rf ~/.cache/mise/* で、versions host キャッシュが消えて正しく npm レジストリを参照するようになる。

$ mise use --global npm:@playwright/cli@latest
npm:@playwright/[email protected]
mise ~/.config/mise/config.toml tools: npm:@playwright/[email protected]
$ mise list
Tool                 Version  Requested
npm:@playwright/cli  0.1.8    latest   ✅

最初から公式ドキュメントを読め

ほんこれ。

手探りでキャッシュファイルを探し回る前に、まず公式ドキュメントのトラブルシューティングページを確認すべきだった（俺も Claude さんも）。

mise cache clear はドキュメントにズバリ書いてある。

@tobilu/qmd の移行

データは消えるのか

以前 QMD を導入したとき、インデックスは ~/.cache/qmd/index.sqlite に置かれている。npm 本体とは完全に独立した場所なので、アンインストールしてもデータは消えない。公式 README にも明記されている。

念のため qmd status で確認してみる。

$ qmd status
QMD Status

Index: /home/xxx/.cache/qmd/index.sqlite
Size:  21.7 MB

Documents
  Total:    131 files indexed
  Vectors:  2917 embedded

よし、ちゃんと残ってる。

移行

$ npm uninstall -g @tobilu/qmd
$ mise use --global npm:@tobilu/qmd@latest
$ qmd status  # データ確認

131 files indexed 2917 embedded がそのまま残っていることを確認して完了。

最終状態

$ mise list
Tool                 Version  Requested
go                   1.26.1   latest
node                 24.14.1  lts
npm:@playwright/cli  0.1.8    latest
npm:@tobilu/qmd      2.1.0    latest
rust                 1.95.0   latest

which qmd や which playwright-cli が mise の shim を指すようになり、バージョンアップの確認も mise outdated だけで完結するようになった。

まとめ

mise の npm バックエンドでバージョン解決がおかしいと思ったら、まず mise cache clear を試してみると良い。