解决 'pnpm: command not found' 错误

当在命令行执行 npm run dev 或其他脚本时遇到 sh: pnpm: command not found 错误，表明系统没有正确识别 pnpm 命令。这在刚克隆的 Next.js 项目或首次设置环境时经常发生。

问题原因

出现该错误的根本原因是系统环境变量（PATH）找不到可执行的 pnpm 程序，常见于：

• 未全局安装 pnpm
• 使用了 corepack 但未启用 pnpm
• 项目使用 pnpm 但本地环境未配置
• 系统权限问题（Windows/Linux）

推荐解决方案

✅ 方法一：使用 Node.js 内置的 corepack（首选）

Node.js 从 v16.9.0 开始内置了 corepack，可直接管理包管理器：

# 启用 corepack
corepack enable

# 启用 pnpm 支持
corepack enable pnpm

# 验证安装
pnpm -v

执行后系统会引导完成必要依赖安装，按提示操作即可（通常会要求输入 Y 确认）。

Windows 系统注意

在 PowerShell 或 CMD 中以管理员身份运行：

# 启动管理员 PowerShell
Start-Process PowerShell -Verb RunAs

# 启用 corepack
corepack enable pnpm

✅ 方法二：通过 npm 全局安装 pnpm

如果方法一无效或使用旧版 Node.js：

# 全局安装最新版本 pnpm
npm install -g pnpm

# 验证安装
pnpm -v

安装完成后建议重启终端会话使环境变量生效。

解决方案对照表

方案	适用场景	优点
corepack enable pnpm	Node.js ≥v16.9.0	官方推荐，不需额外安装
npm install -g pnpm	兼容任意 Node.js 版本	操作简单直接

项目同步操作

配置好 pnpm 后，在项目根目录执行：

# 安装项目依赖
pnpm install

# 启动开发服务器
pnpm run dev

验证技巧

• 执行 which pnpm（Linux/macOS）或 where pnpm（Windows）查看安装路径
• 若仍报错，检查终端会话是否继承 PATH 变量，可尝试 source ~/.zshrc 等重置

故障排除

如以上方案均无效：

1. 确认 Node.js 版本：node -v（推荐 ≥v18.0.0）
2. 检查环境变量：echo $PATH 是否包含 Node 全局路径
3. 尝试安装明确版本：npm install -g pnpm@9
4. Windows 用户可运行 pnpm.cmd -v 测试是否路径问题

⚠️ 注意：项目若包含 pnpm-lock.yaml 文件，说明必须使用 pnpm，不可用 npm/yarn 替代

通过上述步骤可解决环境配置问题，正常情况下再次执行 pnpm run dev 即可启动开发服务器。