はじめに
Viteでnpm run devを実行したらエラーが出たのでその解決方法をまとめます。
エラーが出た環境のバージョンは以下になります。
- Vite 8.3.0
- Node.js 24.22.0
- npm 11.19.1
- Volta 2.0.2
エラーが出た状況
Vite+Reactで開発したアプリをGitHub Actionsで自動デプロイさせようとしていました。
GitHub ActionsのワークフローにNode.jsのバージョンを書く必要があり、開発環境とワークフローのNode.jsのバージョンを同一にして一元管理したかったため以下のようにしました。
node-version-file: "package.json"
プロジェクトのpackage.jsonのNode.jsのバージョンを参照することで、今後バージョンアップをする際にpackage.jsonの編集だけで済みます。
package.jsonにNode.jsのバージョンを固定する記述をしていなかったので以下を追記しました。
"volta": {
"node": "24.22.0"
}
Node.jsのバージョン管理にVoltaを使用しているのでVoltaでバージョンを固定しました。
ワークフローの実行はこれで問題無かったのですが、npmの方で問題があったようでnpm run devやnpm run buildを実行してもエラーが出てしまいました。
エラーの原因と解決方法
Error: Cannot find native binding. npm has a bug related to optional dependencies. Please try `npm i` again after removing both package-lock.json and node_modules directory.
このエラーはパッケージが必要とするネイティブバインディング（プラットフォーム固有のバイナリなど）を見つけられなかったことを示しています。
原因としては、npmのoptionalDependencies（オプション依存関係）の処理に関する不具合や、プラットフォーム固有のバイナリが正しくインストールされていないことなどが考えられます。
エラー文にも書かれている通り、node_modulesとpackage-lock.json を削除してからnpm installを実行することで解決しました。
rm -rf node_modules package-lock.json
npm install
エラーが出る原因になったと思われる行動
個人的にはNode.jsでバージョンを固定する前にnode_modulesをインストールしていたのが原因ではないかと考えています。
というのも、Viteでプロジェクトを作成する際にいくつかの質問が表示されますが、その中に「npmのインストールをするか？」という質問があります。
? Install with npm and start now?
❯ Yes
No
「Yes」を選択すると、node_modulesのインストールと開発サーバーが起動された状態でプロジェクトが作成されます。この時にインストールされるnode_modulesはpackage.jsonにNode.jsのバージョンが記載されていれば、そのバージョンに依存したパッケージでインストールされます。
私の環境の場合はVoltaを使っているため、VoltaのデフォルトのNode.jsのバージョン25.2.1に依存したnode_modulesがインストールされていました。
その後にpackage.jsonでNode.jsのバージョンを固定しましたが、元々インストールしていたnode_modulesと固定したNode.jsのバージョンの依存関係で互換性の問題が起きてエラーが出てしまったのではないかと推測しています。
試しにpackage.jsonに書いたNode.jsのバージョン固定の記述を削除したらnpmコマンドが使えたのでNode.jsのバージョン違いによる可能性が高いと思っています。直接の原因であるかは断定出来ないけど。。。
Viteのプロジェクト作成時にnpmパッケージのインストールの有無を聞かれなかった記憶ですが、いつのバージョンからか追加されているようですね。
手動でnpm installするのが面倒なので「Yes」にしていましたが、今後は「No」を選んでpackage.jsonにNode.jsのバージョンを固定したからnpm installした方が良さそうです。
おわりに
今回は学習用の個人開発のアプリですが、Node.jsのバージョン管理はやはり気をつけた方が良いですね。