VS Code 调试配置怎样复用 workspaceFolder 变量

配置VS Code调试任务时，你只需要在launch.json、tasks.json这类调试配置文件里直接引用内置的${workspaceFolder}变量，它会自动映射到当前VS Code窗口打开的项目根文件夹，就不用写死本地绝对路径，轻松实现调试配置跨环境复用。

在 VS Code 的 launch.json 中，把项目根路径替换成 ${workspaceFolder}，就能让同一份配置适应项目目录移动。Node.js 调试里，program 指向入口文件，cwd 决定进程工作目录；两者可以复用同一个变量，但作用不同。

官方地址：https://code.visualstudio.com/

下面以安装了 Node.js 的本地单文件夹项目为例。最终目标是：移动整个项目目录后，仍可启动相同入口，并在断点处确认工作目录。界面图全部是原创操作说明图，采用简化布局，并非软件截图或本机执行记录；实际菜单文字可能随显示语言变化。

1. 打开项目文件夹，找到 launch.json 入口

选择 File → Open Folder…（文件 → 打开文件夹），打开一个用于演示的项目根目录。随后进入左侧 Run and Debug（运行和调试）→ create a launch.json file（创建 launch.json 文件），在环境选择中选择 Node.js。已有配置时，点击该视图的齿轮按钮打开配置，不要覆盖已有 configurations 条目。

确认资源管理器顶部是目标项目，文件树里能看到 .vscode/launch.json。只打开一个孤立的 JS 文件时，先补做打开文件夹，否则无法按这里的单根项目理解 workspaceFolder。

2. 在 program 和 cwd 中复用根目录

通过资源管理器的 New Folder / New File（新建文件夹 / 新建文件） 建立 src 和 src/check-path.cjs。文件内容如下，使用 cjs 扩展名明确采用 CommonJS；示例只读取进程路径信息。

// 停在下一行时可以查看工作目录，不读取业务数据
const observedCwd = process.cwd();
console.log("cwd:", observedCwd);
console.log("entry:", __filename);

打开 .vscode → launch.json → configurations，新增下面这一项；若是空白演示项目，可以直接保存完整文件。launch.json 支持 JSONC 注释，示例中的中文注释可保留。

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "检查项目路径",
      "type": "node",
      "request": "launch",
      // 入口文件随当前工作区根目录变化
      "program": "${workspaceFolder}/src/check-path.cjs",
      // 相对文件操作以项目根目录为基准
      "cwd": "${workspaceFolder}",
      "console": "internalConsole"
    }
  ]
}

保存文件后，确认运行和调试视图的配置下拉框出现“检查项目路径”，program 的后缀与实际文件一致。配置里保留变量表达式即可，不必手动替换为当前电脑的绝对路径。

3. 在断点处核对工作目录和入口

点击 src/check-path.cjs → console.log 所在行左侧边栏 设置断点，在 Run and Debug → 配置下拉框 选中“检查项目路径”，点击绿色启动按钮或按 F5。只运行自己信任的项目；如果提示找不到 Node.js，先完成运行时安装及可执行文件路径配置。

程序停住后，打开 Run and Debug → WATCH（监视）→ +，添加 process.cwd() 和 __filename。前者应是当前打开的项目根目录，后者应以 src/check-path.cjs 结尾。然后点击 Continue（继续），在 View → Debug Console（视图 → 调试控制台） 查看两行路径。具体绝对路径取决于读者环境，本文不预填一份虚构运行输出。

要确认迁移效果，先停止调试、关闭原项目，复制整个演示目录到另一个位置，再用 File → Open Folder 打开副本并启动相同配置。若入口仍然正确，且 process.cwd() 指向副本根目录，说明调试路径没有继续依赖旧目录。这里只移动演示项目，不操作生产目录。

多根工作区和常见异常怎样判断

多根工作区中，无限定名变量通常以所属配置的文件夹为范围，不等于当前活动编辑器文件所在目录。需要引用另一个根文件夹时，可使用带文件夹名的形式，例如 ${workspaceFolder:Backend}；Backend 必须与工作区中的实际文件夹名称一致。它是选择指定根目录，并不是自动搜索入口。

workspaceFolder 会改写源代码中的路径吗？不会。它在受支持的配置字段中参与替换，源码中写一个同名字符串并不会自动展开。

cwd 和 workspaceFolder 是同一个概念吗？不是。前者在这里是 Node 调试配置的工作目录属性，后者是可用于配置值的工作区变量。为 cwd 填入 workspaceFolder，是明确让进程从根目录启动。

路径里有空格要再加引号吗？program 和 cwd 已经是 JSON 字符串，不要把 shell 的额外引号直接套进路径。若把变量用于外部 shell 命令，则另有 shell 引号规则。

把 launch.json 与演示入口一起纳入项目记录时，保留必要配置及中文用途说明，避免提交私人绝对路径或凭据。下次接手项目的人只需打开正确根目录，就能从同一调试入口开始。

参考：VS Code 变量参考、Node.js 调试、调试配置入口。