はじめに (対象読者・この記事でわかること)

本記事は、Windows Subsystem for Linux（WSL）上で Bash や Zsh などのシェルをデフォルトターミナルとして VS Code を使用している開発者を対象としています。特に、VS Code の「タスク」(tasks.json) を利用したビルドやテストの自動化が、期待したとおりに実行されない、環境変数が正しく渡らない、パスの解釈がずれるといった不具合に直面した経験がある方に向けた内容です。この記事を読むことで、WSL シェルでタスクが動作しない原因を体系的に理解し、設定変更やスクリプト調整によって確実にタスクを走らせる方法が身につきます。実践的な手順とよくあるトラブルの対処法を具体例とともに示すので、すぐに自分のプロジェクトに適用できるはずです。

前提知識

この記事を読み進める上で、以下の知識があるとスムーズです。

  • Windows 10/11 と WSL2 の基本的なインストール手順
  • VS Code の基本操作と拡張機能（Remote - WSL）の導入
  • tasks.json によるタスク定義の概念
  • 基本的なシェルコマンド（export, pwd, cd など）

概要と背景

VS Code のタスク機能は、tasks.json に記述したコマンドを VS Code 側から呼び出す仕組みです。通常、Windows のコマンドプロンプトや PowerShell がデフォルトのシェルとして用いられますが、WSL をシェルとして設定すると、内部で実行されるコマンドが Linux 環境へと橋渡しされます。この変換過程で、以下のような問題が潜在的に発生します。

  1. パス変換の不整合
    Windows パス (C:\project\src) と WSL の Linux パス (/mnt/c/project/src) が混在すると、タスク内でファイルやディレクトリが見つからないケースがあります。

  2. 環境変数のスコープ
    VS Code がタスク実行時に渡す環境変数は Windows 側のものです。そのまま WSL のシェルに流すと、PATH が期待する Linux ディレクトリを含まないため、実行ファイルが見つからないエラーになることがあります。

  3. シェルの実行権限
    VS Code はデフォルトで cmd.exe か PowerShell を呼び出しますが、WSL シェルを明示的に指定しないと、内部的に wsl.exe がラップされ、結果的にエラーコードが Windows 側に帰属してしまいます。

これらの背景を踏まえ、タスクが「WSL シェルで正しく動く」ために必要な設定や、よくある落とし穴を整理します。

具体的な設定とトラブルシューティング

本セクションでは、実際に VS Code のタスクを WSL シェルで動作させるための手順を順を追って解説します。コードサンプルやコマンド例を交えて、設定ファイルの書き方からデバッグ方法まで網羅します。

ステップ1：WSL シェルをタスクのデフォルトに指定する

VS Code の settings.json に次の設定を追加します。

Json

{
    "terminal.integrated.defaultProfile.windows": "WSL",
    "terminal.integrated.profiles.windows": {
        "WSL": {
            "path": "C:\\WINDOWS\\system32\\wsl.exe",
            "args": [],
            "icon": "terminal-linux"
        }
    }
}

この設定により、VS Code の統合ターミナルが起動するたびに WSL が呼び出され、タスク実行時も同じシェルが利用されます。ポイントは path にフルパスで wsl.exe を指定し、args を空にしておくことです。これで VS Code は Windows 側の cmd.exe ではなく、WSL の Bash/Zsh に直接コマンドを渡します。

ステップ2：tasks.json の記述を Linux 形式に統一

WSL シェルでは Linux 形式のパスとシェル構文が必要です。以下は典型的なビルドタスクの例です。

Json

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "npm: build",
            "type": "shell",
            "command": "npm",
            "args": ["run", "build"],
            "options": {
                "cwd": "${workspaceFolder}"
            },
            "presentation": {
                "reveal": "always",
                "panel": "shared",
                "clear": true
            },
            "problemMatcher": []
        }
    ]
}

重要な点
- type を shell にし、command を Linux でも有効な npm とする。
- cwd（カレントディレクトリ）は ${workspaceFolder} のままで OK。VS Code が自動的に WSL のマウントパス（/mnt/c/...）に変換します。
- Windows の環境変数展開 (%VAR%) は使用せず、代わりに ${env:VAR} の形で統一します。

ステップ3：環境変数と PATH の継承を明示的に設定

WSL シェルで Node.js や Python などの実行ファイルが見つからない場合、PATH が不完全なことが原因です。tasks.json の options.env フィールドで必要なパスを追加します。

Json

"options": {
    "env": {
        "PATH": "/usr/local/bin:/usr/bin:/bin:${env:PATH}"
    }
}

ここで ${env:PATH} は Windows側の PATH を取得しますが、WSL が自動的に変換するので、Linux パスを先頭に付けることで優先順位を上げられます。

ステップ4：デバッグ用に echo と env をタスクに組み込む

タスクが正しくシェルに渡っているか確認するため、簡易デバッグタスクを作成します。

Json

{
    "label": "debug: env",
    "type": "shell",
    "command": "env && echo \"PWD=$PWD\" && echo \"Shell: $SHELL\"",
    "presentation": {
        "reveal": "always"
    }
}

実行結果に Linux の環境変数一覧や PWD、SHELL が出力されれば、WSL シェルが正しく呼び出されていることが確認できます。この手順は、パスが期待通りかどうかや、シェルが /bin/bash か /usr/bin/zsh かを見極める際に有用です。

ハマった点やエラー解決

1. 「npm が見つからない」エラー

  • 原因：WSL 内に Node.js がインストールされていないか、PATH が Windows のままになっていた。
  • 対策：WSL に nvm を導入し、node と npm をインストール。~/.bashrc に export PATH=$HOME/.nvm/versions/node/vXX.X.X/bin:$PATH を追加した上で、tasks.json の options.env.PATH に同様のパスを設定。

2. 「/mnt/c/... パスが二重に付く」現象

  • 原因：VS Code の cwd を手動で Windows 形式に書き換えていたため、WSL が再度 Windows パスへ変換して二重化した。
  • 対策：cwd は ${workspaceFolder} のみ使用し、絶対パスや ${workspaceFolder}\\subdir といった Windows 形式は避ける。相対パスであれば、WSL が自動的に正しいマウントポイントへ変換する。

3. タスクが即座に終了してしまう

  • 原因：type が process に設定されていた（process は標準出力のリダイレクトに適さず、WSL のシェルが完了するとすぐに終了）。
  • 対策：必ず type: "shell" に変更し、シェルラッパーを通すことで && や ; といった複数コマンド実行が可能になる。

解決策まとめ

問題 原因 解決策
npm が見つからない WSL に Node が未インストール、PATH 未設定 WSL に Node/nvm を導入し、options.env.PATH に追加
パスが二重になる cwd に Windows パスを書いた ${workspaceFolder} のみ使用し、相対パスに統一
タスク即終了 type: process 使用 type: shell に変更しシェルラッパー経由で実行
環境変数が Windows のまま options.env 未設定 options.env.PATH で Linux パスを先頭に付加

まとめ

本記事では、WSL をシェルとして利用している環境で VS Code のタスク機能が正しく動作しない原因と、具体的な設定手順・トラブルシューティング方法を体系的に解説しました。

  • WSL シェルをデフォルトターミナルに設定し、wsl.exe を直接呼び出す
  • tasks.json を Linux 形式に統一し、パスや環境変数を明示的に指定
  • デバッグタスクで実行環境を可視化し、問題箇所を迅速に特定

これにより、WSL 上でのビルド・テスト・デプロイタスクを安定的に自動化でき、開発フローの高速化が実現します。今後は、複数ディストリビューション間での共通タスクテンプレートや、VS Code の Remote Development 拡張機能との連携強化についても取り上げる予定です。

参考資料