volta 在 vscode 中不自动切换 node 版本，需手动执行 volta pin 生成 .node-version 文件；vscode 终端因非 login shell 不加载 volta 路径，须配置 shell 初始化文件及默认 profile；ts 服务与调试器需单独设置 runtimeexecutable 并重启。
Volta 在 VSCode 里不自动切 Node 版本，不是配置没生效，而是它根本不会主动写 .node-version —— 你必须手动 volta pin 才能触发项目级版本绑定。
VSCode 终端不识别 Volta 的根本原因
VSCode 集成终端默认不是 login shell，所以不会加载 $HOME/.volta/bin 到 PATH，导致 node 命令仍走系统全局路径。这不是 VSCode 设置问题，而是 shell 初始化缺失。
- macOS/Linux：确认
~/.zshrc或~/.zprofile中有export PATH="$HOME/.volta/bin:$PATH"，并在 VSCode 设置中把terminal.integrated.defaultProfile.osx设为zsh（或你实际用的 shell） - Windows：PowerShell 必须在
$PROFILE里加$env:PATH = "$HOME.voltain;" + $env:PATH；新版 VSCode 不再支持terminal.integrated.shellArgs.windows，改用terminal.integrated.defaultProfile.windows指向 PowerShell - 验证方式：新开 VSCode 终端，运行
which node（macOS/Linux）或where node（Windows），输出路径必须含.volta/bin；再跑volta list node和node -v，两者应一致
volta pin 是唯一触发项目级切换的动作
Volta 不监听目录变更、不读 package.json 的 engines.node、也不自动生成 .node-version。它只读不写，pin 是显式声明项目意图的唯一入口。
- 进入项目根目录后执行
volta pin node@16.20.2（必须写具体版本号，node@^16或node@lts会静默失败） - 成功后会生成
.node-version文件，内容为纯文本16.20.2；也可复用已有.nvmrc，Volta 能读但不覆盖它 - 如果项目已提交
.node-version，新协作者只需装 Volta，cd 进目录后node -v就自动生效，无需额外命令 - 注意：若当前目录无
.node-version，Volta 默认回退到全局安装的最新版（由volta install node设定），不是系统自带 Node
VSCode JS/TS 语言服务不随终端同步？和 Volta 无关
VSCode 的 TypeScript Server 启动时固化了 node 可执行路径，它不读 shell 环境变量，也不感知 Volta 的垫片逻辑。即使终端里 node -v 正确，IntelliSense 仍可能报错“Node version mismatch”。
- 重启 TS Server：Cmd+Shift+P → 输入
Typescript: Restart TS server - 更彻底的方式是关闭 VSCode 再重开，确保语言服务启动时加载的是 Volta 注入后的环境
- 调试器（
launch.json）也需单独处理：runtimeExecutable不能留空，得显式填"runtimeExecutable": "${env:HOME}/.volta/bin/node"（macOS/Linux）或"runtimeExecutable": "${env:USERPROFILE}\.volta\bin\node.exe"（Windows）
迁移 nvm 到 Volta 时最易忽略的三件事
卸载 nvm 后直接装 Volta 很容易踩坑，尤其 Windows 用户。
-
nvmoff必须先执行，否则残留的NODE_OPTIONS或PATH干扰 Volta 垫片工作，表现为node命令偶尔跳回旧版本 - Volta 默认装在
C:Program FilesVolta，但所有工具缓存（node/npm二进制）存在%LOCALAPPDATA%Volta oolsinventory，C 盘空间紧张时务必提前设VOLTA_HOME环境变量并指向非系统盘 - CI/CD 流水线里不能依赖 Volta 自动识别
.node-version，必须显式插入volta install node@x.x.x和volta pin node@x.x.x步骤，否则会 fallback 到镜像预装的 Node 版本
