npm 11.5.0以降でoptional dependenciesが正しくインストールされない問題の対処法

Posted at 2025-10-20

この問題は現在npm開発チームによって2025/10/19の段階で対処中です。修正版がリリースされた場合、本記事の内容は対処済みの可能性があります。最新の状況については、以下のGitHub Issueを必ず確認してください: https://github.com/npm/cli/issues/8464

はじめに

npm 11.5.0以降のバージョンで、optional dependenciesが正常にインストールされない問題が発生しています。この問題により、npm ciやnpm installコマンドが成功したように見えても、プラットフォーム固有のバイナリが実際にはインストールされておらず、実行時にエラーが発生する事例が報告されています。

本記事では、この問題の詳細と3つの対処方法について解説します。

問題の追跡情報

この問題は以下のGitHub Issueで追跡されています:
https://github.com/npm/cli/issues/8464

対象とする環境

# 影響を受けるバージョン
npm: ^11.5.0

この問題はnpm 11.5.0以降のバージョンで発生します。npm CLIの問題であり、Node.jsのバージョンには依存しません。

対象とする読者

npmおよびpackage.jsonの基本的な構造を理解している方
optional dependenciesの概念を知っている方
プラットフォーム固有のバイナリパッケージ（esbuild、swcなど）を使用するプロジェクトに関わる方

発生する問題

npm ciを実行すると、コマンド自体は正常に完了しますが、プラットフォーム固有のoptional dependenciesが実際にはインストールされていません。

問題: プラットフォーム固有バイナリの欠損

影響を受けるパッケージの例

この問題は、プラットフォームごとに異なるバイナリファイルを提供するパッケージに影響します。代表的な例:

esbuild - JavaScriptバンドラー
@swc/core - TypeScript/JavaScriptコンパイラ
@rollup/rollup-linux-x64-gnu - Rollupのネイティブバインディング
sharp - 画像処理ライブラリ
その他、プラットフォーム固有のネイティブアドオンを含むパッケージ

再現手順

1 : npm 11.5.0以降をインストールする

npm install -g npm@latest

2 : プラットフォーム固有バイナリを使用するパッケージをインストールし、package-lock.jsonを生成する

npm install -D vitest

この時点で、package-lock.jsonには現在のプラットフォーム用のバイナリエントリーが記録されます。

2-1 : 同じプラットフォームで再度npm installを実行する

npm install

この操作により、package-lock.jsonから他のプラットフォーム用のバイナリエントリーが削除されることがあります。

3 : 生成されたpackage-lock.jsonを 別のプラットフォーム（例: macOSからLinux CI環境）に持ち込み、クリーンインストールを実行する

npm ci

4 : インストールログでは成功と表示される

added 500 packages in 30s

5 : 実際にツールを実行しようとするとエラーが発生する

npm run test

> vitest run

Error: Cannot find module @rollup/rollup-linux-x64-gnu. npm has a bug related to optional dependencies (https://github.com/npm/cli/issues/4828).

エラーメッセージ中のIssue番号について

Rollupのエラーメッセージには古いIssue番号（#4828）が表示されますが、npm 11.5.0以降で発生している問題は別のIssue #8464で追跡されています。

原因

npm CLI 11.5.0以降で導入されたoptional dependenciesの処理ロジックに不具合があります。具体的には:

optional dependenciesとして定義されたプラットフォーム固有パッケージの依存関係解決が正しく行われない
インストール処理自体はエラーなく完了するため、問題の発見が遅れる
node_modulesを確認すると、プラットフォーム固有のパッケージディレクトリが存在しないか、空になっている

想定される状況

この問題は以下のような状況で発生します:

CI/CD環境でnpm ciを使用してクリーンインストールを実行する場合
新しいマシンやDockerコンテナーでプロジェクトをセットアップする場合
npm 11.5.0以降にアップグレードした後の初回インストール時
node_modulesを削除して再インストールする場合

解決方法

状況に応じて以下の4つの対処方法から選択できます。

解決方法1: package-lock.jsonの再生成

プラットフォームを跨いでしまったpackage-lock.jsonを削除し、対象環境で再生成する方法です。

手順

# package-lock.jsonとnode_modulesを削除
rm package-lock.json
rm -rf node_modules

# 対象環境でインストールを実行
npm install

重要: 両方を削除すること

node_modulesディレクトリを削除せずにnpm installを実行すると、package-lock.jsonにSHAフィンガープリントが保存されません。必ずpackage-lock.jsonとnode_modulesの両方を削除してからnpm installを実行してください。

これにより、現在のプラットフォームに適したoptional dependenciesを含むpackage-lock.jsonが新規生成されます。

メリット

手順がシンプルで即座に実行できる
対象プラットフォームに適したpackage-lock.jsonが確実に生成される
npm最新版を使用し続けられる

デメリット

Git管理されているpackage-lock.jsonを破棄する必要がある
依存パッケージのバージョンが変更される
厳密にlockファイルで依存関係を管理しているプロジェクトでは使用できない
チーム全体での合意とlockファイルの再コミットが必要

推奨される状況

個人開発や小規模プロジェクト
lockファイルの厳密な管理が要求されていない環境
緊急で問題を解決する必要があり、依存関係の変更が許容される場合

解決方法2: npmバージョンのダウングレード

もっとも簡単で即効性のある対処法は、npm 11.4.0以前のバージョンにダウングレードすることです。

手順

# npm 11.4.0にダウングレード
npm install -g npm@11.4.0

# バージョン確認
npm --version
# 11.4.0

# 依存関係を再インストール
npm ci

メリット

即座に問題を解決できる
既存のプロジェクト構成を変更する必要がない
チーム全体への影響が最小限

デメリット

npm 11.5.0以降の新機能や改善が使えない（例: Trusted Publishers）
一時的な対症療法であり、根本的な解決ではない
将来的には再度アップデートが必要

推奨される状況

緊急で本番環境やCI/CDパイプラインを修復する必要がある場合
npm CLI側の修正を待つ間の暫定対処として
チーム全体で統一されたnpmバージョンを管理している場合

解決方法3: package.jsonへのoptionalDependencies追加

プラットフォーム固有のパッケージを明示的にoptionalDependenciesフィールドに追加することで、npm最新版を使用しながら問題を回避できます。

手順

たとえば、esbuildを使用している場合:

{
  "name": "your-project",
  "dependencies": {
    "esbuild": "^0.25.0"
  },
  "optionalDependencies": {
    "@esbuild/linux-x64": "^0.25.0",
    "@esbuild/darwin-arm64": "^0.25.0",
    "@esbuild/win32-x64": "^0.25.0"
  }
}

swcの場合:

{
  "dependencies": {
    "@swc/core": "^1.13.0"
  },
  "optionalDependencies": {
    "@swc/core-linux-x64-gnu": "^1.13.0",
    "@swc/core-darwin-arm64": "^1.13.0",
    "@swc/core-win32-x64-msvc": "^1.13.0"
  }
}

変更後、依存関係を再インストール:

npm install

メリット

npm最新版を使用し続けられる
依存関係が明示的になり、プロジェクト構成が明確になる
npm CLIの修正を待たずに問題を解決できる

デメリット

package.jsonの変更が必要
プラットフォームごとのパッケージ名とバージョンを手動で管理する必要がある
新しいプラットフォーム対応時に追加作業が必要
本来は自動で解決されるべき依存関係を手動管理することになる

推奨される状況

npm最新版の機能を使用したい場合
プロジェクトで使用するプラットフォームが限定されている場合
依存関係を厳密に管理したい場合

解決方法4: 別のパッケージマネージャーへの移行

pnpmやyarnなど、この問題の影響を受けない別のパッケージマネージャーに移行する方法です。

pnpmへの移行

# pnpmのインストール
npm install -g pnpm

# 依存関係のインストール
pnpm install

# package.jsonのscriptsはそのまま使用可能
pnpm run build

yarnへの移行

# yarnのインストール
npm install -g yarn

# 依存関係のインストール
yarn install

# scriptsの実行
yarn build

メリット

この問題の影響を完全に回避できる
長期的な解決策となる

デメリット

ツールの変更に伴う学習コストが発生する
CI/CD環境の設定変更が必要
チーム全体での合意と移行作業が必要
プロジェクトに新しいロックファイル（pnpm-lock.yaml / yarn.lock）が追加される

推奨される状況

新規プロジェクトを開始する場合
長期的な解決策を求める場合
チーム全体でツール変更に合意できる場合
pnpmやyarnの他の機能にも魅力を感じる場合

まとめ

npm 11.5.0以降で発生するoptional dependencies問題には、4つの対処方法があります:

状況別の推奨対策

状況	推奨対策	理由
個人開発・小規模プロジェクト	package-lock.json再生成	もっとも簡単、即座に解決
緊急の本番対応	ダウングレード	即座に解決、リスク最小
npm最新版の使用が必須	optionalDependencies追加	現行ツールでの回避策
新規プロジェクト	pnpm/yarn移行	長期的な解決、追加メリット
既存大規模プロジェクト	ダウングレード→CLI修正待ち	変更範囲を最小化

根本的な解決に向けて

この問題はnpm CLIのバグであり、開発チームによる修正が進行中です。GitHub Issueを定期的に確認し、修正版がリリースされたらアップデートすることをオススメします。

それまでの間は、プロジェクトの状況に応じて上記の対処方法を選択してください。

以上、ありがとうございました。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up