本文へ移動
Signalcraft
English

← Signalcraft一覧へ戻る

WSL開発環境の問題を境界から切り分ける

WSL開発環境の問題を境界から切り分ける

WSLはWindows上でLinuxの開発環境を使えます。

一方で、問題の原因がWindowsとLinuxの境界にあると、アプリケーションの不具合に見えます。

commandが見つからない、explorer.exeを起動できない、文字コードが不安定、/mnt/cでI/O errorが出る、といった症状が代表例です。

Ubuntu 24.04と26.04をWSLで試したときの確認事項を、再利用できる切り分け手順へ整理します。

versionやWindows buildで挙動は変わるため、環境固有の観察と公式仕様を分けて読みます。

最初に環境を固定する

トラブルが起きたら、どのdistributionがどのWSL modeで起動し、どこから実行されているかを確認します。

Windows側では次を実行します。

wsl --status
wsl --version
wsl --list --verbose

Linux側では次を実行します。

cat /etc/os-release
uname -a
printf '%s\n' "$PATH"
locale
pwd

WSL 1とWSL 2のどちらかを確認します。

既定distributionと実際に起動したdistributionも比較します。

projectがLinux側のfile systemか、/mnt/cかを確認します。

Windows PATHがLinux側へ取り込まれているかも確認します。

「WSLが動かない」という症状は、distribution起動、shell設定、file systemのどれでも起こります。

compinitや補完が壊れた場合

zshを入れ替えた後や設定を整理した後は、compinit、fpath、.zcompdump、plugin cacheを疑います。

複数を同時に変更すると、原因を特定しにくいです。

まずpluginとuser設定を読まないzshを起動します。

zsh -f

# 最小環境で補完を確認する
autoload -Uz compinit
compinit
compaudit

zsh -fと最小環境のcompinitが動くなら、WSL binaryより.zshrc、fpath、plugin初期化を先に疑います。

通常設定は次の順番で戻します。

  1. shell本体の設定
  2. fpathと補完初期化
  3. plugin manager
  4. Atuin、prompt、その他の追加機能

compauditが表示したdirectoryのownerとpermissionだけを確認します。

広い範囲へ再帰的なchmodを実行して、無関係なfileまで変更しません。

localeを先に決める

localeが未設定だと、warning、sort順、文字化け、PythonやRubyのI/O問題が発生します。

日本語を表示することと、system全体のlocaleを日本語にすることは別です。

開発環境では、まずUTF-8を安定させます。

locale
locale charmap

環境によってはC.UTF-8を既定にし、applicationごとに表示言語を設定する方が扱いやすいです。

機械処理するscriptでは、error messageまで日本語になると判定しにくいです。

変更後は新しいshellで次を確認します。

printf '%s\n' "$LANG" "$LC_ALL" "$LC_CTYPE"
locale charmap

反映されない場合は、/etc/default/locale、shell設定、Windows Terminal profile、SSHの設定元を順に調べます。

.zshrcでlocale変数を無条件に上書きすると、non-interactive shellへも影響します。

explorer.exeが見つからない場合

WSLの相互運用機能により、Linux shellからWindows executableを起動できます。

MicrosoftのWSL interop資料にも、次の例があります。

explorer.exe .

command not foundなら、まず.exeのsuffixを付けているか確認します。

次にWindows PATHの取り込みを確認します。

printf '%s\n' "$PATH" | tr ':' '\n' | grep -i '/mnt/c/Windows'
command -v explorer.exe

Windows PATHがない場合は、/etc/profileや.zshrcで$PATHを残さず再代入していないか確認します。

必要なWindows commandだけを予測可能な形で取り込みます。

すべてのWindows PATHを無条件に追加することが修正とは限りません。

/mnt/cのI/Oとprojectの場所

WSL 2では、Linux file systemとWindows file systemをまたぐ処理に性能上の差が出ます。

Microsoftは、Linux toolで開発するprojectをWSL側のfile systemへ置くことを案内しています。

次の処理では差が見えやすいです。

  • node_modulesを含むNode.js project
  • 小さなfileが多いGit操作
  • RustやGoのbuild
  • 大量のfileを監視するdevelopment server

Linux CLIを主に使うprojectは、次のように置きます。

~/projects/my-app        # Git、Node、cargoをWSL内で実行する

Windows editorから開く場合は、\\wsl$または\\wsl.localhost経由でアクセスします。

Windows toolを主に使うprojectはWindows側へ置き、WSLから補助的に参照する方針も選べます。

/mnt/cでI/O errorが出ても、すぐにfileを削除したりmount設定を変えたりしません。

次の順番で確認します。

  1. Windows側から同じpathを開けるか確認する
  2. /tmpや$HOMEでWSLの読み書きを確認する
  3. wsl --list --verboseで対象distributionを確認する
  4. 実行中の処理を止めてからwsl --shutdownし、再起動する
  5. WSLを更新する
  6. 特定driveだけならWindows側のlock、permission、disk状態を確認する

クロスfile systemアクセスには変換層があります。

I/O errorと性能問題は同一ではありません。

両方とも境界をまたぐ処理から起こり得ます。

Ubuntuのversionを戻すとき

新しいUbuntuへ移行した後に問題が増えても、distribution自体の不具合とは限りません。

shell plugin、PATH、locale、package、設定fileを同時に変えていれば、先に変更範囲を小さくします。

開発が止まり、toolや依存packageの対応が原因だと確認できたら、安定していたversionへ戻す判断もあります。

削除や再登録の前に、次を保存します。

  • ~/.configと~/.localの必要なfile
  • SSH keyとpermission
  • Git設定と認証方式
  • install済みpackageの一覧
  • WSL側だけにあるprojectとdata
  • /etc/wsl.confなどのdistribution設定

Windows側からdistribution全体をexportする方法もあります。

wsl --export <distribution-name> <backup-path.tar>

export先、個別file、restore手順を確認してからunregisterや再登録をします。

distributionの削除は、内部のfileも失う可能性があります。

backupとexportを確認できない状態で削除しません。

versionを戻すことは失敗ではなく、開発作業を優先するための環境固定です。

症状別のチェックリスト

症状 最初に見るもの 次の確認
補完が壊れた zsh -f、compinit、compaudit、fpath pluginを1つずつ戻す
文字化けやlocale warning locale、locale charmap /etc/default/localeとshell設定
explorer.exeがない suffix、$PATH、command -v /etc/profileのPATH上書き
/mnt/cが遅い projectの場所 WSL側の$HOMEへ移して比較
/mnt/cでI/O error Windows側のアクセスと別path wsl --shutdown、WSL更新
distributionが起動しない wsl --status、wsl -l -v 仮想化、distribution、log

WSL全体の再installを最初の手段にしません。

作り直すと症状は消えても、再現条件と設定差分も消えるからです。

まとめ

WSLの切り分けでは、Linuxだけ、またはWindowsだけを見ません。

distributionとWSL本体を分けます。

Linux PATHとWindows PATHを分けます。

Linux file systemと/mnt/cを分けます。

shell本体とpluginを分けます。

Linux toolを主に使うprojectはWSL側へ置きます。

Windows連携が必要ならPATHと.exe呼び出しを確認します。

環境を戻すなら、削除前にdataと設定を退避します。

この3つをルールにすると、同じ問題を再び調べる時間を減らせます。

参考資料