SWC バイナリの読み込み失敗エラーの解決方法
Next.js 12以降で導入されたRustベースの高速コンパイラSWCを使用する際に発生する「failed to load SWC binary」エラーの解決方法を解説します。
問題の概要
Next.jsの開発サーバー（npm run dev）を実行すると、以下のエラーが発生します：
failed to load SWC binaryこのエラーは、SWC（Speedy Web Compiler）がシステムアーキテクチャに合ったバイナリを正常にダウンロードまたは読み込みできない場合に発生します。
SWCとは？
SWCはRustで書かれた高速なJavaScript/TypeScriptコンパイラで、Babelの代わりに使用されます。ビルドパフォーマンスが大幅に向上しますが、システム固有のバイナリが必要なため環境によって問題が発生することがあります。
主な原因
このエラーの主な原因は以下の通りです：
- Node.jsのアーキテクチャ不一致（32bit vs 64bit）
- 依存関係の不整合（node_modulesやロックファイルの問題）
- システムライブラリの不足（特にWindowsのVC++ Redistributable）
- Docker環境におけるライブラリの問題（musl vs glibc）
- 不完全なパッケージインストール
解決方法
🎯 基本的なトラブルシューティング
まずは最も一般的な解決方法から試してください：
# node_modulesとロックファイルを削除して再インストール
rm -rf node_modules package-lock.json
npm installTIP
macOSユーザーは、システムのストレージ最適化機能がSWCバイナリを削除している可能性があります。ストレージ設定でnode_modulesフォルダを除外すると予防できます。
🔍 Node.jsのアーキテクチャ確認
システムアーキテクチャとNode.jsのアーキテクチャが一致しているか確認します：
# Node.jsのアーキテクチャを確認
node -p "process.arch"
# システム情報を確認（Windows）
systeminfo | findstr "系統の種類"
# システム情報を確認（Linux/macOS）
uname -m重要
64ビットシステムでは64ビット版のNode.jsを、32ビットシステムでは32ビット版のNode.jsを使用する必要があります。不一致の場合は、正しいバージョンのNode.jsを再インストールしてください。
🪟 WindowsでのVC++ Redistributableのインストール
Windows環境では、Microsoft Visual C++ Redistributableのインストールが必要な場合があります：
- Microsoft公式サイトから最新のVC++ Redistributableをダウンロード
- システムアーキテクチャに合ったバージョンを選択：
🐋 Docker環境での対応
Dockerを使用している場合、ベースイメージの選択が重要です：
# alpineベース（musl）ではなく、bullseyeベース（glibc）のイメージを使用
FROM node:18-bullseye-slim
# または明示的にSWCをインストール
RUN npm install -D @swc/cli @swc/core📦 オプション依存関係の明示的インストール
特定の環境向けのSWCパッケージを明示的にインストールします：
# Linux (x64 GNU)
npm install -D @next/swc-linux-x64-gnu --save-optional
# Linux (x64 musl)
npm install -D @next/swc-linux-x64-musl --save-optional
# macOS (ARM64)
npm install -D @next/swc-darwin-arm64 --save-optional
# macOS (x64)
npm install -D @next/swc-darwin-x64 --save-optionalnpmインストール時の注意
npm install --no-optionalフラグを使用している場合、SWCバイナリがインストールされないため、このフラグを外してください。
⚠️ 緊急措置：Babelへのフォールバック
どうしても解決しない場合、一時的な措置としてBabelを使用する方法もあります：
- プロジェクトルートに
.babelrcファイルを作成：
{
"presets": ["next/babel"]
}next.config.jsでSWCミニファイを無効化：
module.exports = {
swcMinify: false
}パフォーマンス注意
この方法はSWCのパフォーマンスメリットを失います。あくまで一時的な対応としてください。
その他の特殊なケース
Jestテスト環境での問題
テスト環境では、SWCバイナリのダウンロードが完了する前にテストが実行されることがあります。 package.jsonに以下の設定を追加してください：
{
"scripts": {
"test": "npm install && npm run test:actual",
"test:actual": "jest"
}
}pnpmユーザー向け対策
pnpmを使用している場合、ロックファイルとキャッシュの問題が発生しやすいです：
# キャッシュとモジュールの完全クリーンアップ
rm -rf node_modules pnpm-lock.yaml
pnpm install予防策
- Node.jsのバージョン管理に
nvmを使用する - 常にシステムアーキテクチャに合ったNode.jsをインストールする
- Docker環境では適切なベースイメージを選択する
- 定期的に
npm cache clean --forceでキャッシュをクリーンアップする
まとめ
SWCバイナリの読み込み失敗は、主に環境設定の問題から発生します。基本的なトラブルシューティングから始め、システム環境に応じた適切な解決方法を選択してください。最新の情報はNext.js公式ドキュメントも参照してください。