WSL 启动 VS Code 的配置记录：PATH、登录 Shell 与右键菜单

这次要解决的问题

我的开发环境放在 WSL 中，VS Code 安装在 Windows 上。为了减少 Windows 路径对 Linux 命令查找的干扰，我关闭了 Windows PATH 自动注入，但仍希望保留两个入口：

在 WSL 项目目录里执行 code .。
在 Windows 资源管理器的当前目录空白处右键，直接打开对应的 WSL 工作区。

这篇文章记录当时采用的配置、遇到的命令查找问题，以及最后保留下来的右键命令，方便以后重装或排查时回看。

文中的 Windows 用户名统一写作 winuser，Linux 用户名写作 dev，项目目录写作 demo；这些都是脱敏示例，使用时需要替换。发行版以 Ubuntu 为例。当时没有记下 Windows、WSL 和 VS Code 的具体版本，下面的成功与失败现象仅代表我的使用环境。

保留下来的配置

Windows 放编辑器，WSL 放开发环境

这套配置的前提是 Windows 已安装 VS Code 和 WSL 扩展，WSL 中已有可用的 Ubuntu 与 Bash。窗口显示在 Windows 上，终端和开发工具在 WSL 工作区中运行；首次连接时，扩展会在 WSL 内安装所需的 VS Code Server。相关工作方式见 VS Code 的 WSL 文档。

Windows：VS Code 窗口 + WSL 扩展
                  │
                  ▼
WSL：VS Code Server + 项目 + Linux 工具链

关闭 Windows PATH 注入，保留互操作

WSL 内的 /etc/wsl.conf 保留以下配置；已有其他配置时合并到对应小节：

1
[interop]
2
enabled=true
3
appendWindowsPath=false

enabled 控制能否启动 Windows 进程，appendWindowsPath 控制是否把 Windows 路径追加到 WSL 的 $PATH。这两个设置是独立的，因此可以继续调用 Windows 程序，同时不自动导入它们的命令搜索路径。配置含义见 WSL 高级配置文档。

修改配置后，我在 Windows PowerShell 中执行以下命令，再重新进入 WSL：

wsl --shutdown

这会终止所有正在运行的 WSL 发行版，应先保存工作、结束相关任务。命令行为见 WSL 基本命令文档。

单独保留 `code` 入口

当时 WSL 中的 code 是放在用户目录下的软链接，指向 Windows 安装目录中的启动脚本：

/home/dev/.local/bin/code
  → /mnt/c/Users/winuser/AppData/Local/Programs/Microsoft VS Code/bin/code

这里记录的是已有链接的结构，目标是 bin/code 脚本。Windows 安装方式、安装目录或盘符变化后，这个目标也需要相应调整。

在 WSL 终端中检查命令解析结果和链接：

type -a code
command -v code
ls -l ~/.local/bin/code
readlink -f ~/.local/bin/code

软链接和 PATH 分别解决两个问题：链接决定文件指向哪里，PATH 决定 Shell 到哪些目录查找命令。链接存在，并不能单独保证输入 code 就能找到它。

排查记录：终端能用，Windows 直接调用却失败

在平时使用的 WSL 终端中，进入项目后可以启动：

cd ~/code/demo
code .

但从 Windows PowerShell 直接调用时：

wsl -d Ubuntu -- code .

当时出现了以下错误：

/bin/bash: line 1: code: command not found

于是我检查了这种启动方式下的命令搜索环境。在 Windows PowerShell 中执行：

wsl -d Ubuntu -- sh -c 'echo $PATH; command -v code'

这次检查输出的 PATH 没有包含 /home/dev/.local/bin。这提示我：从 Windows 发起一次命令调用，得到的 Shell 环境可能与日常终端不同。这里的 sh -c 用于对照排查，不能视为所有 WSL 调用方式的完整复现。

改用登录 Bash 后能解析到命令

接着在 Windows PowerShell 中测试：

wsl -d Ubuntu -- bash -lc 'command -v code'
wsl -d Ubuntu -- bash -lc "code ."

当时第一条命令能够解析到 /home/dev/.local/bin/code，第二条能够启动 VS Code，因此最后保留了 bash -lc 这个入口。

-l 表示登录 Shell，-c 表示执行后面的命令字符串。登录 Bash 会读取 /etc/profile，再依次查找 ~/.bash_profile、~/.bash_login、~/.profile，读取其中第一个存在且可读的文件；它并不保证自动读取所有这些文件，也不保证自动读取 ~/.bashrc。详见 Bash 启动文件说明。

调用方式	Shell 类型	与这次排查的关系
`bash -c`	非登录、非交互	不主动走登录配置流程
`bash -lc`	登录、非交互	当时能解析并启动 `code`，最终采用
`bash -ic`	交互、非登录	通常读取 `~/.bashrc`，本次未采用

这里仍有一个没有追完的细节：当时使用 bash -lc 检查时，PATH 文本输出也没有直接显示用户的 .local/bin，但 command -v code 却返回了其中的路径。仅凭这些输出，还不能断言具体是哪段初始化配置起了作用，也不能认定 -l 会自动补齐 PATH。

如果以后需要追查，应在同一次 Bash 调用中查看 PATH、命令类型和哈希记录。在 Windows PowerShell 中执行：

wsl -d Ubuntu -- bash -lc 'echo $PATH; type -a code; command -V code; hash -t code 2>/dev/null'

再到 WSL 内检查相关启动文件；如果这些文件引用了其他脚本，还需要继续沿引用查找：

grep -nE 'local/bin|hash.*code|code=' \
  ~/.profile ~/.bash_profile ~/.bash_login ~/.bashrc /etc/profile \
  2>/dev/null

把可用入口接到资源管理器右键菜单

WSL 项目可以通过资源管理器中的 UNC 路径访问，例如：

\\wsl.localhost\Ubuntu\home\dev\code\demo

我也使用过 \\wsl$\Ubuntu\home\dev\code\demo 这种写法。仅看到编辑器打开了这个目录，还不足以判断是否连接到了 WSL；我会检查 VS Code 左下角是否显示 WSL: Ubuntu，确认工作区的连接状态。

目录背景菜单的命令

最后保留的“目录背景”右键菜单命令值是：

"C:\Windows\System32\wsl.exe" -d Ubuntu --cd "%V" -- bash -lc "code ."

这是菜单的命令值，%V 由资源管理器替换，不是直接粘贴进 PowerShell 的测试命令。使用时，将这一行填入目录背景菜单的命令配置；下文说明各参数的作用。

部分	用途
`"C:\Windows\System32\wsl.exe"`	调用 Windows 的 WSL 启动程序
`-d Ubuntu`	指定发行版
`--cd "%V"`	将资源管理器当前目录作为启动目录
`-- bash -lc "code ."`	启动登录 Bash，在该目录执行 `code .`

原配置中，目录背景菜单用 %V 表示当前目录；文件夹对象菜单通常使用 %1。两种菜单位置应分别检查，不直接混用命令值。

发行版名称可以在 Windows PowerShell 中用 wsl -l -v 查看。如果实际名称是 Ubuntu-24.04，命令的 -d 参数与 UNC 路径中的发行版名称都需要对应替换。这条命令固定选择一个发行版，不会根据路径自动切换。

整个入口可以概括为：

资源管理器当前目录
  → wsl.exe 选择发行版并进入目录
  → 登录 Bash 解析 code
  → VS Code 打开 WSL 工作区

为什么保留 `bash -lc`

写成 /home/dev/.local/bin/code . 也可以绕过对命令名 code 的搜索，但会把 Linux 用户路径写进 Windows 菜单配置。

这次保留 bash -lc "code ."，是为了让菜单复用 WSL 内已有的命令入口。它的前提仍然是：登录 Bash 能解析到正确的 code，且启动配置没有把当前目录切换到别处。

以后失效时的检查顺序

右键启动失败时，窗口可能一闪而过。我会先在 Windows PowerShell 中逐层检查，而不是直接反复调整菜单。

1. 确认发行版与命令入口

wsl -l -v
wsl -d Ubuntu -- bash -lc 'command -V code'
wsl -d Ubuntu -- bash -lc 'code --version'

先确认发行版名称，再确认解析到的入口与 CLI 是否可执行。code --version 成功只能说明 CLI 可运行，远程连接状态还需要在窗口中确认。

2. 确认启动目录与远程工作区

先用 Linux 路径检查目录，再测试当时使用的 UNC 路径。以下示例目录需要事先存在：

wsl -d Ubuntu --cd /home/dev/code/demo -- bash -lc 'pwd'
wsl -d Ubuntu --cd "\\wsl.localhost\Ubuntu\home\dev\code\demo" -- bash -lc 'pwd'
wsl -d Ubuntu --cd "\\wsl.localhost\Ubuntu\home\dev\code\demo" -- bash -lc "code ."

先看 pwd 是否对应目标目录，再看窗口左下角是否显示 WSL: Ubuntu。如果当前 WSL 不接受这条 UNC 路径，先使用 Linux 路径继续定位，并通过 wsl --help 核对本机支持的参数；这条路径在我的环境中可用，其他版本仍需实际检查。

3. 必要时让菜单窗口停留

可临时把目录背景菜单命令值换成下面这一行，观察目录、命令解析、PATH 和退出状态。这里的 $PATH、$? 由 Bash 展开；不要把整行当作 PowerShell 命令使用：

"C:\Windows\System32\wsl.exe" -d Ubuntu --cd "%V" -- bash -lc "pwd; command -V code; echo PATH=$PATH; code .; result=$?; echo exit=$result; read -r -p 'Press Enter...'"

排查结束后恢复普通命令。如果 WSL 在进入 Bash 之前就失败，末尾的等待输入也不会执行，此时仍需回到 PowerShell 查看启动错误。

留给下次配置的速记

这次最终保留下来的组合是：enabled=true、appendWindowsPath=false、用户目录里的 code 软链接，以及右键菜单中的 bash -lc "code ."。

回头看，最有用的排查顺序是先确认文件入口，再确认当前 Shell 能否找到命令，最后确认打开的是目标 WSL 工作区。软链接、命令搜索环境和远程连接分别检查，比只盯着一句 code . 更容易找到问题所在。