npm install が idealTree build でフリーズする問題の解決法

Node.jsプロジェクトで npm install を実行した際に、"sill idealTree buildDeps" ステップでフリーズする問題について、包括的な解決策を紹介します。

問題の概要

npm install コマンドが idealTree ステップで停止し、依存関係ツリーの構築が完了しない現象が発生します。以下のような症状が見られます：

• プログレスバーが停止し、何時間も応答がない
• ネットワーク接続があるにもかかわらず処理が進まない
• ログに "sill idealTree buildDeps" や "sill idealTree build" メッセージが残る

主な原因と解決策

1. ネットワーク関連の問題

最も一般的な原因はネットワーク接続の問題です。

IPv6設定の問題

多くの環境でIPv6設定が原因となっています：

macOS

# ネットワーク設定 → 詳細 → TCP/IP → IPv6設定を「リンクローカルのみ」に変更

Ubuntu/Linux

# 一時的にIPv6を無効化
sudo sysctl -w net.ipv6.conf.all.disable_ipv6=1
sudo sysctl -w net.ipv6.conf.default.disable_ipv6=1

# 恒久的に無効化（再起動が必要）
# /etc/default/grub を編集：
GRUB_CMDLINE_LINUX_DEFAULT="quiet splash ipv6.disable=1"
sudo update-grub

Windows

# ネットワーク接続 → プロパティ → 「インターネットプロトコルバージョン6 (TCP/IPv6)」のチェックを外す

VPN・プロキシ設定

VPNやプロキシがnpmの通信を阻害している可能性があります：

# VPNを一時的に無効化して試す
# またはNO_PROXY環境変数を設定
export NO_PROXY="registry.npmjs.org,your-private-registry.com"

2. SSL証明書の問題

企業ネットワークなどではSSL証明書の検証が失敗することがあります：

# SSL検証を一時的に無効化（セキュリティリスクに注意）
npm config set strict-ssl false

# または特定のレジストリを設定
npm config set registry http://registry.npmjs.org/

WARNING

strict-ssl false は一時的な解決策としてのみ使用し、本来は正しい証明書を設定することを推奨します。

3. キャッシュと設定ファイルの問題

npmのキャッシュや設定ファイルに問題がある場合：

# キャッシュのクリア
npm cache clean --force

# node_modulesとlockファイルの削除
rm -rf node_modules package-lock.json

# .npmrcファイルの確認と設定
echo "registry=https://registry.npmjs.org/" > ~/.npmrc

4. システム時間のずれ

システムクロックに問題がある場合：

# システム時間を確認
date

# ネットワーク経由で時間を同期（Linux）
sudo ntpdate pool.ntp.org

# または（systemd使用時）
sudo timedatectl set-ntp true

詳細なトラブルシューティング手順

ステップ1: 詳細ログの確認

npm install --verbose

このコマンドでどのステップで停止しているか、ネットワークリクエストの応答時間などを確認できます。

ステップ2: 別ネットワークでのテスト

モバイルホットスポットなど、別のネットワーク環境で試すことで、現在のネットワーク設定が原因かどうかを判別できます。

ステップ3: 基本的な修復手順

1. Lockファイルの確認: yarn.lock と package-lock.json の競合を避けるため、不要な方を削除
2. Node.jsバージョンの統一: プロジェクトメンバー間でNode.jsとnpmのバージョンを合わせる
3. 管理者権限での実行: 必要に応じて sudo を使用（ただし推奨されない方法）

ステップ4: 代替ツールの使用

# pnpmで試す
pnpm install

# またはYarn
yarn install

予防策

1. .npmrcの適切な設定: プロジェクトルートに正しい設定ファイルを配置
2. ネットワーク環境の最適化: 安定した接続環境の確保
3. 定期的なキャッシュクリーン: 古いキャッシュによる問題を予防
4. バージョン管理: Node.jsとnpmのバージョンを適切に管理

まとめ

npm install の idealTree ステップでのフリーズは、主にネットワーク関連の問題によって発生します。IPv6設定の調整、SSL設定の見直し、キャッシュのクリアなど、段階的なアプローチで解決できます。本記事で紹介した解決策を順に試し、お使いの環境に適した方法を見つけてください。

INFO

問題が解決しない場合は、npmのGitHub Issues で類似の事例を検索したり、新しいIssueを作成したりすることを検討してください。