Node Version Manager Switch

中文 | English

在 VSCode 中快速切换当前工作区使用的 Node.js 版本，让每个项目独立管理自己的 Node 运行环境。无需离开编辑器，也无需手动修改环境变量，只需几次点击即可完成版本切换。

Quickly switch the Node.js version for the current workspace in VSCode, allowing each project to manage its own Node runtime independently. No need to leave the editor or manually modify environment variables — just a few clicks and you're done.

简介 | Introduction

在日常开发中，不同项目往往依赖不同版本的 Node.js。有的项目需要 v18 的长期支持，有的项目则需要 v20 的新特性，而使用 nvm、fnm 等版本管理器时，每次切换项目都要手动在终端中执行命令，既繁琐又容易出错。Node Version Manager Switch 扩展将这一过程集成到 VSCode 内部，自动检测本机已安装的所有 Node 版本，并为每个工作区独立配置所需的运行环境。

In daily development, different projects often rely on different Node.js versions. Some projects need the LTS of v18, while others need the new features of v20. When using version managers like nvm or fnm, switching between projects requires manually executing commands in the terminal every time, which is tedious and error-prone. The Node Version Manager Switch extension integrates this process into VSCode, automatically detects all installed Node versions on your machine, and independently configures the required runtime environment for each workspace.

核心优势 | Key Benefits：

• 零配置开箱即用 — 安装扩展后自动扫描本机 Node 安装，无需手动填写路径

• 工作区级隔离 — 版本配置绑定到 .vscode/settings.json，团队成员打开项目自动生效

• 不污染全局环境 — 通过修改 PATH 实现切换，不会影响系统默认的 Node 版本或其他项目

• 与 VSCode 深度集成 — 支持活动栏面板、状态栏显示、命令面板三种交互方式

• Zero-config out of the box — Automatically scans local Node installations after installation, no manual path entry needed

• Workspace-level isolation — Version config is bound to .vscode/settings.json, team members automatically get the correct version when opening the project

• No global pollution — Switching is done by modifying PATH, without affecting the system default Node version or other projects

• Deep VSCode integration — Supports Activity Bar panel, status bar display, and Command Palette for interaction

功能特性 | Features

• 项目级版本隔离 — 每个工作区独立配置 Node 版本，互不干扰

• 自动检测已安装版本 — 自动扫描 nvm-windows、nvm、fnm 以及系统路径下的 Node 安装

• 手动添加自定义路径 — 支持手动输入或通过文件管理器浏览选择 Node 安装目录

• 一键切换 / 重置 — 点击"应用"即可切换，点击"重置"恢复系统默认

• 状态栏实时显示 — 底部状态栏始终显示当前生效的 Node 版本

• npm 脚本联动 — 切换版本后，新打开的终端和 npm 脚本均使用指定版本

• Project-level version isolation — Each workspace configures its own Node version independently without interfering with others

• Auto-detect installed versions — Automatically scans nvm-windows, nvm, fnm, and system paths for Node installations

• Add custom paths manually — Supports manual input or browsing via file manager to select Node installation directories

• One-click switch / reset — Click "Apply" to switch, click "Reset" to restore system default

• Real-time status bar display — The bottom status bar always shows the currently active Node version

• npm script integration — After switching, newly opened terminals and npm scripts use the specified version

快速开始 | Quick Start

1. 打开面板 | Open the Panel

安装扩展后，有三种方式打开 Node Version Manager Switch 面板：

After installing the extension, there are three ways to open the Node Version Manager Switch panel:

2. 选择版本 | Select Version

1. 在面板中点击 "选择版本..." 下拉框

2. 从列表中选择目标 Node 版本

3. 点击 "应用" 按钮

4. Click the "Select Version..." dropdown in the panel

5. Choose the target Node version from the list

6. Click the "Apply" button

3. 验证生效 | Verify

打开一个新的集成终端，运行：

Open a new integrated terminal and run:

node --version

确认输出与面板中显示的版本一致即可。

Confirm the output matches the version shown in the panel.

注意 / Note：版本切换仅对新打开的终端生效，已打开的终端需要关闭后重新打开。
Version switching only takes effect in newly opened terminals. Close and reopen existing terminals.

版本来源 | Version Sources

Node Version Manager Switch 会自动从以下位置检测已安装的 Node.js 版本：

Node Version Manager Switch automatically detects installed Node.js versions from the following locations:

如果自动检测未覆盖你的安装位置，可以通过面板底部的 "添加自定义路径" 手动添加。

If auto-detection doesn't cover your installation location, use "Add Custom Path" at the bottom of the panel.

添加自定义路径 | Add Custom Path

1. 点击下拉框底部的 "添加自定义路径"

2. 选择以下任一方式指定路径：

   • 点击输入框右侧的 文件夹图标 📁，在文件管理器中选择 Node 安装目录
   • 手动输入目录路径（如 C:\node\v18），按 Enter 或点击"添加"

3. 验证通过后，该版本会自动出现在版本列表中

4. Click "Add Custom Path" at the bottom of the dropdown

5. Specify the path using either method:

   • Click the folder icon 📁 next to the input box and select the Node installation directory in the file manager
   • Manually enter the directory path (e.g. C:\node\v18), press Enter or click "Add"

6. After verification, the version will automatically appear in the version list

添加的路径需包含 node.exe（Windows）或 node（macOS/Linux）可执行文件。
The added path must contain the node.exe (Windows) or node (macOS/Linux) executable.

工作原理 | How It Works

Node Version Manager Switch 通过修改工作区的 .vscode/settings.json 实现版本切换：

Node Version Manager Switch switches versions by modifying the workspace .vscode/settings.json:

{
  "terminal.integrated.env.windows": {
    "PATH": "C:\\nvm\\v20.11.0;${env:PATH}"
  }
}

• 将选定 Node 版本的目录前置到 PATH 环境变量

• 配置存储在工作区级别，每个项目独立，不会影响全局环境

• 点击"重置"会清除该配置项，恢复系统默认 Node 版本

• Prepends the selected Node version directory to the PATH environment variable

• Configuration is stored at the workspace level, independent per project, without affecting the global environment

• Clicking "Reset" clears this configuration and restores the system default Node version

命令 | Commands

常见问题 | FAQ

切换版本后终端仍然是旧版本？

Terminal still shows the old version after switching?

版本切换只对新打开的终端生效。请关闭旧终端，重新打开一个新的终端窗口。

Version switching only takes effect in newly opened terminals. Please close old terminals and open a new one.

npm 脚本侧边栏运行时用的是哪个版本？

Which version is used when running npm scripts from the sidebar?

VSCode 的 npm 脚本面板在集成终端中运行任务，因此会自动使用当前工作区配置的 Node 版本（需在切换后重新运行脚本）。

VSCode's npm script panel runs tasks in the integrated terminal, so it automatically uses the Node version configured for the current workspace (you need to rerun scripts after switching).

版本列表为空 / 找不到我的 Node？

Version list is empty / Can't find my Node?

1. 确认 Node.js 已正确安装 / Confirm Node.js is properly installed
2. 如果使用 nvm-windows，检查 NVM_HOME 环境变量是否已设置 / If using nvm-windows, check if NVM_HOME environment variable is set
3. 尝试使用"添加自定义路径"手动指定 Node 安装目录 / Try using "Add Custom Path" to manually specify the Node installation directory
4. 点击面板标题栏的刷新按钮重新扫描 / Click the refresh button in the panel title bar to rescan

如何查看调试日志？

How to view debug logs?

Ctrl+Shift+P → Output: Show Output Channels → 选择 Node Version Manager Switch，可查看扩展的激活和运行日志。

Ctrl+Shift+P → Output: Show Output Channels → Select Node Version Manager Switch to view extension activation and runtime logs.

配置了 terminal.integrated.env 但在 PowerShell 终端不生效？

Config set in terminal.integrated.env but not working in PowerShell terminal?

原因 | Cause：

PowerShell 的配置文件（$PROFILE）会在每次启动时执行，如果你的配置文件中包含直接覆盖 $env:Path 的语句，会清除 VS Code 注入的环境变量。

典型问题代码：

# ❌ 错误写法：直接覆盖，会清除 VS Code 注入的 PATH
$env:Path = [Environment]::GetEnvironmentVariable("Path", "Machine") + ";" + [Environment]::GetEnvironmentVariable("Path", "User")

解决方法 | Solution：

将 PowerShell 配置文件改为合并模式，保留 VS Code 注入的 PATH：

# ✅ 正确写法：合并原有 PATH（含 VS Code 注入的部分）+ 系统环境变量
$systemPath = [Environment]::GetEnvironmentVariable("Path", "Machine")
$userPath  = [Environment]::GetEnvironmentVariable("Path", "User")
$originalPath = $env:Path

$allPaths = ($originalPath -split ";") + ($systemPath -split ";") + ($userPath -split ";")
$uniquePaths = $allPaths | Where-Object { $_.Trim() -ne "" } | Select-Object -Unique
$env:Path = $uniquePaths -join ";"

修改步骤：

1. 在 PowerShell 中运行 notepad $PROFILE 打开配置文件
2. 将原有内容替换为上述正确写法
3. 保存文件，重新打开 VS Code 终端验证

验证是否生效，在终端运行：

$env:Path -split ";" | Select-String "node"

Config set in terminal.integrated.env but not working in PowerShell terminal?

配置了 terminal.integrated.env 但在 PowerShell 终端不生效？

Cause:

PowerShell profile ($PROFILE) runs on every terminal start. If your profile contains a statement that directly overwrites $env:Path, it will clear the environment variables injected by VS Code.

Problematic code:

# ❌ Wrong: directly overwrites, clears VS Code injected PATH
$env:Path = [Environment]::GetEnvironmentVariable("Path", "Machine") + ";" + [Environment]::GetEnvironmentVariable("Path", "User")

Solution:

Change your PowerShell profile to merge mode, preserving the PATH injected by VS Code:

# ✅ Correct: merge original PATH (including VS Code injected part) + system env vars
$systemPath = [Environment]::GetEnvironmentVariable("Path", "Machine")
$userPath  = [Environment]::GetEnvironmentVariable("Path", "User")
$originalPath = $env:Path

$allPaths = ($originalPath -split ";") + ($systemPath -split ";") + ($userPath -split ";")
$uniquePaths = $allPaths | Where-Object { $_.Trim() -ne "" } | Select-Object -Unique
$env:Path = $uniquePaths -join ";"

Steps:

1. Run notepad $PROFILE in PowerShell to open the profile
2. Replace the content with the correct code above
3. Save and reopen VS Code terminal to verify

Verify with:

$env:Path -split ";" | Select-String "node"

系统要求 | Requirements

• VSCode 1.74.0 及以上 / VSCode 1.74.0 or higher
• 已安装 Node.js（至少一个版本）/ Node.js installed (at least one version)
• 支持 Windows、macOS、Linux / Supports Windows, macOS, Linux