踩坑记录：Mac M系列芯片下 pnpm dlx 触发的 esbuild 架构不匹配错误

背景

在日常开发中，克隆一个前端项目后，我们习惯性地执行 pnpm install 和 pnpm dev。但最近在搭载 Apple Silicon (M系列芯片) 的 Mac 上，项目启动时却抛出了一个极其刺眼的致命错误，甚至重新 git clone 项目也无法解决。

错误现象

执行命令后，终端抛出如下错误堆栈，直接导致进程退出 (exit code 1)：

bash 复制代码

node:internal/modules/run_main:123
    triggerUncaughtException(
    ^
Error:
You installed esbuild for another platform than the one you're currently using.
This won't work because esbuild is written with native code and needs to
install a platform-specific binary executable.
Specifically the "@esbuild/darwin-x64" package is present but this platform
needs the "@esbuild/darwin-arm64" package instead. People often get into this
situation by installing esbuild with npm running inside of Rosetta 2 and then
trying to use it with node running outside of Rosetta 2, or vice versa (Rosetta
2 is Apple's on-the-fly x86_64-to-arm64 translation service).
...
    at generateBinPath (/Users/xxx/Library/Caches/pnpm/dlx/fa19b49eb7fa...)
    at esbuildCommandAndArgs (/Users/xxx/Library/Caches/pnpm/dlx/fa19b...)
...

问题分析

错误信息其实已经说得很清楚了：架构不匹配 (Architecture Mismatch)。

esbuild 是一个使用 Go 语言编写的高性能构建工具，它在安装时会根据当前的操作系统和 CPU 架构下载对应的底层二进制文件。

在我们的场景中：

期望环境 ：Mac M系列芯片，原生架构是 arm64 (darwin-arm64)。
实际加载的包 ：系统却发现本地存在的是为 Intel 芯片编译的包 darwin-x64。

为什么重新 clone 项目也没用？

这就是这个 Bug 最搞人心态的地方。如果你仔细观察报错堆栈，会发现错误并不是从项目本地的 node_modules 抛出的，而是来自： /Users/xxx/Library/Caches/pnpm/dlx/...

这说明问题出在执行 pnpm dlx 命令时。pnpm dlx 类似于 npx，用于临时下载并执行一个包。pnpm 把之前（可能是在旧的 Intel Mac 上，或者是误用 Rosetta 终端时）下载的 darwin-x64 版本的包缓存在了全局的 dlx 目录中。

当你再次运行项目时，哪怕项目是全新 clone 的，pnpm dlx 依然会去读取这个全局的、架构错误的缓存，从而导致崩溃。

解决方案

明确了是全局缓存作祟，解决起来就非常简单粗暴了：进行深度清理。

第一步：核实 Node.js 架构

首先，必须确保你当前运行的 Node.js 本身是原生的 arm64 版本，而不是通过 Rosetta 2 翻译运行的 Intel 版本。

在终端输入：

bash 复制代码

node -p "process.arch"

如果输出是 arm64，说明环境正确，请进行下一步。
如果输出是 x64 ，说明你的 Node.js 版本不对。你需要卸载当前的 Node.js，并重新安装原生版本（例如使用 nvm install <version>）。同时检查你的终端软件（Terminal/iTerm2）是否在"显示简介"中勾选了"使用 Rosetta 打开"，如果有，请取消勾选。

第二步：彻底清空 pnpm 的全局 DLX 缓存

既然缓存污染了，我们就手动将其根除。在终端执行以下命令：

bash 复制代码

# 强制删除 pnpm 的全局 dlx 缓存目录（将 /Users/xxx 替换为你报错信息中的实际路径，通常是 ~/.local/share/pnpm 或 ~/Library/Caches/pnpm）
rm -rf ~/Library/Caches/pnpm/dlx

# 清理 pnpm 的全局 store 缓存
pnpm store prune

第三步：重新安装依赖

回到你的项目根目录，为了保险起见，清空本地的 node_modules，然后重新安装：

bash 复制代码

# 删除本地 node_modules
rm -rf node_modules

# 重新安装依赖，此时 pnpm dlx 会重新拉取正确的 arm64 版本
pnpm install

# 启动项目
pnpm dev

总结

当我们在 Mac M 系列芯片上遇到类似 @esbuild/darwin-x64 与 @esbuild/darwin-arm64 的冲突，且重装项目无效时，一定要优先排查全局缓存（如 pnpm dlx 缓存目录）以及 Node.js 自身的运行架构。暴力清理特定的全局缓存目录，往往是解决此类"幽灵报错"的最快途径。