Tauri iOS 开发中 "pnpm: command not found" 错误解决方案

问题描述

在使用 Tauri 2 进行 iOS 开发时，运行 pnpm tauri ios dev 命令时遇到以下错误：

bash 复制代码

/Users/xu/Library/Developer/Xcode/DerivedData/note-gen-coowqggwgabxygdvvpindbhbxduh/Build/Intermediates.noindex/ArchiveIntermediates/note-gen_iOS/IntermediateBuildFilesPath/note-gen.build/release-iphoneos/note-gen_iOS.build/Script-BCAE7E672E9B737A5106BE1A.sh: line 2: pnpm: command not found
Command PhaseScriptExecution failed with a nonzero exit code

问题原因分析

1. Xcode 构建环境的特殊性

Xcode 的构建脚本运行在一个受限的环境中，其 PATH 环境变量与用户终端环境不同。即使你在终端中可以正常使用 pnpm，Xcode 的构建脚本也无法找到它。

2. NVM 安装路径问题

大多数开发者使用 NVM (Node Version Manager) 来管理 Node.js 版本，NVM 将 Node.js 和相关工具（如 pnpm）安装在用户目录下：

bash 复制代码

/Users/用户名/.nvm/versions/node/v24.11.0/bin/pnpm

而 Xcode 的默认 PATH 通常只包含系统级目录：

/usr/bin
/bin
/usr/sbin
/sbin
/usr/local/bin

3. 构建脚本执行机制

Tauri 在生成 Xcode 项目时，会在构建阶段（Build Phases）添加一个 "Run Script" 步骤，该脚本会执行类似以下命令：

bash 复制代码

pnpm tauri ios xcode-script -v --platform iOS --sdk-root ${SDKROOT:?} ...

由于 Xcode 的 PATH 中不包含 NVM 的路径，脚本执行时就会报 "command not found" 错误。

解决方案

官方推荐方案：创建符号链接

根据 Tauri GitHub 社区的讨论（Discussion #6382），最可靠的解决方案是将 pnpm 和 node 创建符号链接到 /usr/local/bin/ 目录：

bash 复制代码

# 创建 pnpm 符号链接
sudo ln -s $(which pnpm) /usr/local/bin/pnpm

# 创建 node 符号链接  
sudo ln -s $(which node) /usr/local/bin/node

为什么这个方案有效？

系统级可访问性 ：/usr/local/bin/ 在 Xcode 的默认 PATH 中
保持版本一致性：符号链接指向你当前使用的 NVM 版本
无需修改配置 ：不需要修改 tauri.conf.json 或 Xcode 项目设置
永久解决方案：一次配置，所有项目都能使用

验证安装

执行以下命令验证符号链接是否创建成功：

bash 复制代码

ls -la /usr/local/bin/ | grep -E "pnpm|node"

预期输出：

bash 复制代码

lrwxr-xr-x  1 root  wheel  46 日期  node -> /Users/用户名/.nvm/versions/node/v24.11.0/bin/node
lrwxr-xr-x  1 root  wheel  46 日期  pnpm -> /Users/用户名/.nvm/versions/node/v24.11.0/bin/pnpm

其他尝试过的方案（不推荐）

1. 修改 tauri.conf.json

尝试在 beforeDevCommand 中使用完整路径：

json 复制代码

{
  "build": {
    "beforeDevCommand": "/Users/用户名/.nvm/versions/node/v24.11.0/bin/pnpm dev"
  }
}

问题：Xcode 构建脚本仍然会执行 pnpm tauri ios xcode-script，这个命令无法通过配置文件修改。

2. 设置环境变量

尝试在构建脚本中设置 PATH：

bash 复制代码

export PATH="$HOME/.nvm/versions/node/v24.11.0/bin:$PATH" && pnpm dev

问题：Xcode 的构建脚本执行环境限制，环境变量设置可能不生效。

3. 使用 npx

尝试使用 npx pnpm：

json 复制代码

{
  "build": {
    "beforeDevCommand": "npx pnpm dev"
  }
}

问题：Xcode 环境中连 npx 也找不到。

最佳实践

1. 一次性配置

建议在设置新的开发环境时，就执行符号链接创建命令，避免后续开发中遇到问题。

2. 版本管理

如果你切换 Node.js 版本，需要重新创建符号链接：

bash 复制代码

# 切换 Node.js 版本后
sudo rm /usr/local/bin/node /usr/local/bin/pnpm
sudo ln -s $(which node) /usr/local/bin/node
sudo ln -s $(which pnpm) /usr/local/bin/pnpm

3. 团队协作

在团队开发中，确保所有成员都执行了相同的符号链接配置，避免环境差异导致的问题。

总结

"pnpm: command not found" 错误是 Tauri iOS 开发中的常见问题，根本原因是 Xcode 构建环境与用户终端环境的 PATH 差异。通过创建系统级符号链接，可以让 Xcode 正确找到 NVM 安装的 Node.js 工具，这是目前最可靠和推荐的解决方案。

这个方案不仅解决了当前问题，也为后续的 Tauri iOS 开发提供了稳定的环境基础。