sandbox-npm-install について
virtiofsでマウントされたワークスペースを使うDockerサンドボックス向けのnpm依存関係インストールスキルです。ローカルのext4上でインストールし、node_modulesをワークスペースへリンクしてネイティブバイナリの障害を避けます。
主な機能
- 01ローカルext4上で依存関係をインストール
- 02node_modulesをワークスペースへリンク
- 03指定されたネイティブバイナリを検証
- 04Playwright Chromiumの任意インストール
活用シーン
- 01新しいサンドボックスの依存関係を準備
- 02packageロックファイル変更後の再インストール
- 03ネイティブバイナリのクラッシュに対処
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/sandbox-npm-installを入力して読み込まれたか確認します。
同梱ファイルscripts/install.sh
詳細
Sandbox npm インストール
このスキルを使用するタイミング
次の場合はいつでも、このスキルを使用してください。
- 新しいサンドボックスセッションで、初めて npm パッケージをインストールする必要がある
package.jsonまたはpackage-lock.jsonが変更され、再インストールが必要であるSIGILL、SIGSEGV、mmap、unaligned sysNoHugePageOSなどのエラーを伴うネイティブバイナリのクラッシュが発生したnode_modulesディレクトリがない、または破損している
前提条件
- virtiofs でワークスペースをマウントした Docker サンドボックス環境
- コンテナで Node.js と npm を利用できること
- 対象のワークスペースに
package.jsonファイルがあること
背景
Docker のサンドボックスワークスペースは、通常 virtiofs（ホストと Linux VM 間でファイルを同期）を介してマウントされます。ネイティブの Go および Rust バイナリ（esbuild、lightningcss、rollup など）は、aarch64 で virtiofs 上から実行すると、mmap のアラインメントエラーによりクラッシュします。これを修正するには、コンテナのローカル ext4 ファイルシステムにインストールし、ワークスペースにシンボリックリンクを作成します。
インストール手順
ワークスペースのルートから、同梱のインストールスクリプトを実行します。
bash scripts/install.sh
一般的なオプション
| オプション | 説明 |
|---|---|
--workspace <path> | package.json を含むディレクトリのパス（省略した場合は自動検出） |
--playwright | E2E テスト用の Playwright Chromium ブラウザーもインストールします |
スクリプトの処理内容
package.json、package-lock.json、および存在する場合は.npmrcを、ローカル ext4 ディレクトリにコピーします- ローカルファイルシステム上で
npm ci（ロックファイルがない場合はnpm install）を実行します node_modulesをワークスペースに戻すシンボリックリンクを作成します- 既知のネイティブバイナリ（esbuild、rollup、lightningcss、vite）が存在する場合は検証します
- 必要に応じて、Playwright ブラウザーとシステム依存関係をインストールします（利用可能な場合は
sudoを使用します）
検証に失敗した場合は、スクリプトをもう一度実行してください。初回セットアップ中のクラッシュは断続的に発生することがあります。
インストール後の検証
スクリプトの完了後、ツールチェーンが動作することを確認します。例：
npm test # Run project tests
npm run build # Build the project
npm run dev # Start dev server
重要な注意事項
- ローカルのインストールディレクトリ（例：
/home/agent/project-deps）はコンテナ内のみにあり、ホストには同期されません node_modulesのシンボリックリンクはホスト上ではリンク切れとして表示されますが、通常node_modulesは Git の対象外であるため問題ありません- ホスト上で
npm ciまたはnpm installを実行すると、シンボリックリンクは実ディレクトリに置き換わります package.jsonまたはpackage-lock.jsonを変更した後は、必ずインストールスクリプトを再実行してください- マウントされたワークスペースで
npm ciまたはnpm installを直接実行しないでください。ネイティブバイナリがクラッシュします
トラブルシューティング
| 問題 | 解決策 |
|---|---|
開発サーバーの実行時に SIGILL または SIGSEGV が発生する | インストールスクリプトを再実行してください。ワークスペースで npm install を直接実行していないことを確認してください |
インストール後に node_modules が見つからない | シンボリックリンクが存在するか確認します：ls -la node_modules |
| インストール中に権限エラーが発生する | ローカルの依存関係ディレクトリに、現在のユーザーが書き込みできることを確認してください |
| 検証が断続的に失敗する | スクリプトをもう一度実行してください。初回読み込み時のネイティブバイナリのクラッシュは、非決定的に発生することがあります |
Vite との互換性
プロジェクトで Vite を使用している場合、server.fs.allow でシンボリックリンク先のパスを許可する必要があることがあります。Vite がシンボリックリンクを介してファイルを配信できるように、シンボリックリンク先の親ディレクトリ（例：/home/agent/project-deps/）を Vite の設定に追加してください。