pnpm 全局安装包报错 pnpm setup 解决

场景

执行 pnpm add -g ts-node 报如图所示错误

根据错误提示，他让我们去设置 pnpm 全局包存储在电脑的中的目录，以及环境变量等可以执行 pnpm setup 去自动设置

这里我们执行 pnpm setup 去自动设置执行完成后关闭当前终端，重新开一个终端，执行 pnpm add -g ts-node 即可

报错的完整信息与原因

这个错误的原文大意是 ERR_PNPM_NO_GLOBAL_BIN_DIR Unable to find the global bin directory，后面跟一句提示让你运行 pnpm setup 或者手动设置 PNPM_HOME。

原因在于 pnpm 处理全局包的方式和 npm 完全不同。npm 有一个内置的全局前缀目录（npm config get prefix），全局包直接铺进那个目录的 lib/node_modules 里。pnpm 不这么干，它的全局包也是走内容寻址 store 的，需要一个独立的 PNPM_HOME 目录来放全局包的软链接和可执行文件，而这个目录还必须在 PATH 里，否则装完了命令也调不出来。pnpm 装的时候会先校验这两件事，任一不满足就直接拒绝执行，而不是装完让你自己发现调不动。

pnpm setup 到底改了什么

它做三件事：

选定一个全局目录作为 PNPM_HOME。macOS/Linux 默认是 ~/Library/pnpm（macOS）或 ~/.local/share/pnpm（Linux），Windows 是 %LOCALAPPDATA%\pnpm。
把 export PNPM_HOME=... 和 export PATH="$PNPM_HOME:$PATH" 追加写进你的 shell 配置文件（~/.zshrc、~/.bashrc 等，按当前 $SHELL 判断）。Windows 上则是写用户级环境变量。
顺便把 pnpm 自己也装到那个目录下，所以之后 pnpm add -g pnpm 可以自更新。

也就是说它只动了 shell 配置文件和环境变量，没有修改 npm 的任何配置。这也解释了为什么必须重开终端——已经启动的 shell 不会重读配置文件。不想重开的话手动 source 一下也行：

source ~/.zshrc
# 确认变量生效
echo $PNPM_HOME
which pnpm

不想用 setup 就手动配

有些场景下不方便让脚本改我的 shell 配置（比如 CI 镜像、或者我的 dotfiles 是版本管理的），那就手动指定：

# ~/.zshrc
export PNPM_HOME="$HOME/Library/pnpm"
export PATH="$PNPM_HOME:$PATH"

也可以走 pnpm 自己的配置项，效果一样：

pnpm config set global-bin-dir ~/Library/pnpm

Docker 镜像里更省事的写法是直接在 Dockerfile 里给环境变量，避免依赖交互式 shell 的配置文件：

ENV PNPM_HOME="/usr/local/share/pnpm"
ENV PATH="$PNPM_HOME:$PATH"
RUN corepack enable && pnpm add -g ts-node

几个后续会碰到的问题

setup 之后还是报找不到全局 bin。 大概率是 PATH 里的 PNPM_HOME 被后面某行覆盖了。多个版本管理器（nvm、volta、asdf）都会往 PATH 前面插东西，检查一下 echo $PATH | tr ':' '\n' 里 pnpm 那一项的实际位置。

全局装完的命令仍然调不出来。 用 pnpm list -g --depth 0 确认包确实装上了，再看 ls $PNPM_HOME 里有没有对应的可执行文件软链接。有包没链接通常是包本身没声明 bin 字段。

换机器后全局包不见了。 全局包是记在 $PNPM_HOME 对应的一个虚拟 package.json 里的，不跟仓库走。想批量迁移可以先在旧机器上 pnpm list -g --depth 0 导出清单，再到新机器上一次性装回来。

其实更推荐少用全局安装。 ts-node 这类工具我现在基本都改用 pnpm dlx 临时跑，或者装成项目的 devDependency 再用 pnpm exec 调用。全局版本和项目版本不一致引发的诡异问题排查成本很高，而 dlx 每次拉的都是干净的指定版本。