[Astro #19] Windows の EPERM エラー対策と WSL2 への開発環境移行

1. トラブルの背景：Windows ネイティブ環境の限界

Windows 上での Node.js 開発、特に Vite をベースとした Astro のプロジェクトにおいて、開発者を最も悩ませるのが EPERM: operation not permitted エラーである。

このエラーは単なる権限不足ではなく、Windows のファイルシステム（NTFS）と Linux 由来のツールチェーンとの設計思想の違いから生じる。

1.1 NTFS のファイルロック仕様

Windows は、あるプロセスがファイルを開いている間、そのファイルに対する変更や削除を制限する 「排他的ロック」 の傾向が非常に強い。

• Vite の依存関係最適化: Vite は開発サーバー起動時に node_modules/.vite 内にキャッシュを生成し、必要に応じて書き換えを行う。この際、アンチウイルスソフトや Windows Indexer、あるいは VS Code 自身のインデックス作成プロセスがファイルを掴んでいると、Vite はアクセスを拒否され EPERM を吐いて停止する。
• ゴーストプロセスの残存: 開発サーバーを Ctrl+C で停止させたつもりでも、Node.js のプロセスが完全には終了せずバックグラウンドでファイルを保持し続けることがある。この状態で再度サーバーを立ち上げようとすると、古いプロセスがファイルをロックしているため起動に失敗する。

1.2 node_modules の膨大さとパスの深さ

Astro プロジェクトでは、依存パッケージが 1,000 を超えることも珍しくない。

• 削除の遅延: rm -rf node_modules を実行した際、Windows では「削除のマーク」を付けてから順次処理を行うため、大量の微細なファイルを消去するのに数分単位の時間を要する。
• パスの最大長制限: かつての Windows にあった 260 文字制限（MAX_PATH）は緩和されつつあるが、依然として深い階層にあるシンボリックリンクやパッケージ構造が原因で、予期せぬ権限エラーや読み込み失敗を誘発するケースが後を絶たない。

1.3 開発体験への影響

一度 EPERM が発生すると、エディタを再起動し、タスクマネージャーから迷子になった Node プロセスを強制終了させ、手動で node_modules を削除するという、非生産的な「儀式」を強いられることになる。

この「ファイル操作に対する過保護な仕様」こそが、Windows ネイティブ環境における開発の限界点と言える。

2. 解決策としての WSL2 移行

Windows ネイティブ環境で発生するファイルロック問題への根本的な回答は、OS の抽象化レイヤーで戦うのではなく、開発環境そのものを Linux カーネル上へ移管することである。WSL2 (Windows Subsystem for Linux 2) は、この移行を最小限のオーバーヘッドで実現する。

2.1 Linux カーネルによる直接制御

WSL1 がシステムコールを Windows API に変換する「翻訳レイヤー」であったのに対し、WSL2 は Microsoft が最適化した実物の Linux カーネルを軽量 VM 上で動作させる。

• ファイル操作の独立: ファイルシステムの管理は Windows 側の NTFS ではなく、Linux 側の ext4 上で行われる。Linux カーネルは「ファイルが他のプロセスによって開かれている最中でも削除（アンリンク）や移動が可能」という仕様を持っており、Vite のような動的なキャッシュ更新を行うツールと極めて相性が良い。
• Inotify のネイティブサポート: Vite や Astro のホットリロード（HMR）は、ファイルの変更を検知するために inotify を利用する。WSL2 ではこれがネイティブに動作するため、Windows 側で発生しがちな「変更が検知されない」「検知の遅延」といった問題が解消される。

2.2 ファイルシステムのパフォーマンス最適化

WSL2 の性能を最大限に引き出すための絶対条件は、プロジェクトファイルを Linux 側のルートファイルシステム（~/ 配下など）に配置することである。

• 9p プロトコルの回避: /mnt/c/（Windows 側のドライブ）にあるファイルを Linux から操作する場合、9p プロトコルを介した通信が発生し、パフォーマンスが著しく低下する。一方、Linux 内部（VFS）にファイルを置くことで、ネイティブな ext4 の速度で npm install やビルドを実行できる。
• メモリ管理の効率化: Linux カーネルは空きメモリを積極的にファイルキャッシュに割り当てる。これにより、大規模な node_modules のスキャンが Windows ネイティブ環境よりも高速化される。

2.3 エコシステムの親和性

Node.js や Git、各種ビルドツールは、本来 Linux 環境での動作を第一に想定して設計されている。WSL2 への移行は、単なるエラー回避に留まらず、ツールチェーンが持つ本来のポテンシャルをフルに発揮させるための「標準的な構成」への回帰と言える。

3. WSL2 へのプロジェクト移行手順

3.1 プロジェクトの移動

プロジェクトファイルは、Windows 側の /mnt/c/ 配下ではなく、Ubuntu 側のファイルシステム（~/）内に配置する必要がある。

# Ubuntu 側のディレクトリ作成と移動
mkdir -p ~/github
cp -r /mnt/c/Users/[User]/[Project] ~/github/

3.2 Git および GitHub 接続の再構築

WSL2 は独立した Linux 環境であるため、Git 設定と SSH 鍵の再作成が必要となる。

# Git 基本設定
git config --global user.name "Your Name"
git config --global user.email "email@example.com"

# SSH鍵の作成と登録
ssh-keygen -t ed25519 -C "email@example.com"
cat ~/.ssh/id_ed25519.pub
# 表示された鍵を GitHub の SSH keys に登録

4. Linux ネイティブな Node.js 環境の構築

Windows 側のバイナリとの混在を避けるため、fnm (Fast Node Manager) を使用して Ubuntu 内部に Node.js をインストールする。

# fnm のインストール
curl -fsSL https://fnm.vercel.app/install | bash
source ~/.bashrc

# Node.js (LTS) のインストール
fnm install --lts

5. VS Code の WSL モード連携

VS Code を「Windows 上のエディタ」から「WSL リモートエディタ」へ昇華させる。

1. WSL 拡張機能 のインストール（Microsoft 製）。
2. Ubuntu ターミナルから code . を実行。
3. VS Code Server が Ubuntu 側に自動インストールされ、UI は Windows、処理は Linux という分離構成が完了する。

6. 移行後の検証

WSL2 移行後、以下のコマンドで環境を再構築した。

# 既存の node_modules 等を削除（Linux 上では爆速で完了）
rm -rf node_modules .astro .vite

# インストールと起動
npm install --legacy-peer-deps
npm run dev -- --remote

結果

• EPERM エラーの完全な消失。
• ファイル変更の検知（HMR）およびパッケージインストールの劇的な高速化。
• Netlify リモート DB（Astro DB）との安定した接続。

まとめ

Windows 開発におけるファイル権限トラブルは、WSL2 への移行によってその殆どが解決する。VS Code Server を介した開発環境は、ネイティブ Linux と遜色ないパフォーマンスを提供し、開発者はインフラの不具合ではなくコードの実装に集中することが可能になる。