npm link 在 VSCode 终端不生效的根本原因是集成终端未加载全局 node_modules 的 bin 路径，需在 VSCode 设置中手动注入对应 PATH 并完全重启 VSCode 才生效。
npm link 为什么在 VSCode 终端里不生效
根本原因不是 npm link 命令本身出错，而是 VSCode 的集成终端（尤其是 PowerShell）没加载到全局 node_modules 的 bin 目录路径。你执行 npm link 后，它确实在 %APPDATA%Roaming
pm（Windows）或 ~/.npm-global/bin（macOS/Linux）生成了可执行文件，但 VSCode 启动时读取的 $env:PATH 里没包含这个位置。
常见现象包括：
-
npm link my-package执行成功，但紧接着my-package命令报“无法识别” -
where my-package（Windows）或which my-package（macOS/Linux）返回空 - 系统 CMD 或独立终端能运行，VSCode 终端却不行 —— 这基本锁定是 PATH 继承问题
确认 npm 全局 bin 路径是否被 VSCode 加载
先查清楚 npm 把软链接装在哪了：
npm config get prefix
然后拼出 bin 路径：
- Windows：结果通常是
C:Users{user}AppDataRoaming pm，对应 bin 是C:Users{user}AppDataRoaming pm（.cmd 文件就放这） - macOS/Linux：结果可能是
/Users/{user}/.npm-global，对应 bin 是/Users/{user}/.npm-global/bin
再检查 VSCode 终端当前的 PATH 是否含这个路径：
echo $env:PATH
（PowerShell）或
echo $PATH
（bash/zsh）。如果没看到上面那个 bin 路径，就是它没被加载。
VSCode 设置中补全 npm 全局 bin 路径
不要改系统环境变量，直接在 VSCode 用户设置里注入。按 Ctrl + Shift + P → 输入 Preferences: Open Settings (JSON) → 添加：
{
"terminal.integrated.env.windows": {
"PATH": "${env:PATH};C:\Users\{your-username}\AppData\Roaming\npm"
},
"terminal.integrated.env.linux": {
"PATH": "${env:PATH}:/home/{your-username}/.npm-global/bin"
},
"terminal.integrated.env.osx": {
"PATH": "${env:PATH}:/Users/{your-username}/.npm-global/bin"
}
}
注意：
- Windows 路径必须用双反斜杠
\转义 - 用户名不能写
%USERPROFILE%或变量，得硬编码（VSCode 不解析 Windows 环境变量嵌套） - 改完保存，**必须完全关闭并重启 VSCode**，只重启终端不够
npm link 后仍找不到命令？检查软链接目标是否存在
npm link 本质是创建符号链接，但它依赖源包的 package.json 中 "bin" 字段定义。如果这个字段缺失、路径写错、或指向的文件没可执行权限，link 就会静默失败。
验证方式：
- 进你 link 的包目录，运行
npm pack --dry-run，看输出里有没有列出bin对应的文件 - 检查
package.json是否有类似："bin": "./dist/cli.js"，且./dist/cli.js存在、首行是#!/usr/bin/env node - Windows 下若用 Git Bash 或 WSL，
.cmd文件可能被忽略，优先用 PowerShell 或 CMD 测试
最容易被忽略的是：link 成功后，VSCode 终端里必须新开一个 tab 才能继承新 PATH；已打开的终端不会自动刷新环境变量。
