Claude Code 报错 Cannot find module './yoga.wasm'：是旧版本在跑

在终端输入 claude 或 claude doctor，看到下面这段报错，说明你的 shell 实际执行的那份 Claude Code 是缺文件的旧 JavaScript 版本：

Error: Cannot find module './yoga.wasm'
Require stack:
- /Users/you/.nvm/versions/node/v20.13.0/lib/node_modules/@anthropic-ai/claude-code/cli.js
  code: 'MODULE_NOT_FOUND',

只有 npm 包 2.0.25 及更早的版本才把 yoga.wasm 作为单独文件放在 cli.js 旁边；2.0.26 起包里没有这个文件，当前版本更是连 cli.js 都没有。所以修法不是"补装一个模块"，而是找出那份旧副本、删掉它和其他重复安装，只保留一个安装渠道重装，最后确认 which -a claude 只剩一条、claude --version 显示当前版本。

实测范围：2026 年 10 月 16 日，在 macOS 26（Apple 芯片，arm64）、Node v24.11.0、npm 11.6.1 上，用隔离的 npm 安装目录（--prefix）和临时 HOME 实际运行过四组操作，没有动到真实环境里的安装：

• 安装 2.0.25 后删掉 yoga.wasm（模拟更新中断留下的半安装），claude --version、claude doctor 和直接启动都以这条报错退出；把文件放回去，又能显示 2.0.25 (Claude Code)。
• 在这份坏掉的安装上执行 npm install -g @anthropic-ai/claude-code@latest，升级到 2.1.301 后正常启动。
• 运行官方原生安装器，装出 2.1.301，并提示 ~/.local/bin 不在 PATH 里。
• 原生版已经装好、旧的坏 npm 副本排在 PATH 前面时，claude --version 仍然报这条错；删掉旧副本后恢复。

没有运行过：Windows、Linux、pnpm、mise、Homebrew 安装的 Node、真实发生的自动更新中断，以及 ENOTEMPTY 报错本身。文中涉及这些情况的命令来自 Claude Code 官方文档或社区报告，会在对应位置注明。

yoga.wasm 报错说明什么：跑的是 2.0.25 及更早的旧副本

yoga.wasm 是 Yoga 的 WebAssembly 构建。Yoga 是一个 flexbox 布局引擎，早期 Claude Code 的终端界面（基于 Ink）靠它排版。它一直是 Claude Code 包里自带的文件，不需要单独安装；npm 上叫 yoga-wasm 之类的包和这条报错无关，装了也不会修好。

npm 包的版本边界如下。这张表来自 npm 上已发布的安装包实物和官方 Claude Code 更新日志，2.0.25 到 2.0.26 之间的打包变化在更新日志里没有写，是逐个列出 2.0.24、2.0.25、2.0.26 安装包内容得出的：

复现里也确认了这一点：2.0.26 的包里只有 cli.js、package.json、vendor 等文件，没有 yoga.wasm，照样能显示 2.0.26 (Claude Code)。截至 2026 年 10 月 16 日，npm 上的最新版是 2.1.301。

文件为什么会缺？Claude Code 维护者在 GitHub issue #7193（yoga.wasm 报错） 里解释过：2025 年的自动更新如果中途被打断（网络错误、合盖、系统中断），会留下缺少 yoga.wasm 等关键文件的半更新状态；在 GitHub issue #1103 里也提到，旧的自动更新基于 npm update，原子性很差，单独拷贝 cli.js 到别处也不行，它需要同目录下的 yoga.wasm 等配套文件。GitHub 上不少报告都提到，报错是在"昨天还能用""会话开着放了一夜"之后出现的。

到了 2026 年下半年还能碰到它，通常是下面几种情况之一（根据版本边界推断，不是官方说法）：

• 2025 年留下的半安装一直没清理，换个终端或切了 Node 版本后它又被执行到。
• nvm、mise 给每个 Node 版本各存一套全局包。切回旧的 Node 版本时，那个版本目录下 2025 年装的 Claude Code 重新回到 PATH 上。
• 机器、CI 或 Docker 镜像锁定了旧版本，或者设置了 DISABLE_UPDATES 阻止所有更新。
• 新版已经装好，但旧副本在 PATH 里排得更靠前（下文单独讲）。

第一步：用 which -a claude 找出正在跑的是哪一份

Require stack 里 cli.js 的路径就是坏掉的那一份所在的位置。再看 PATH 上一共有几个 claude：

which -a claude

输出的第一行就是你输入 claude 时实际执行的那个。按官方检查重复安装的说明，再看三个常见位置：

ls -la ~/.local/bin/claude
ls -la ~/.claude/local/
npm -g ls @anthropic-ai/claude-code 2>/dev/null

~/.local/bin/claude 是原生安装器装的，指向 ~/.local/share/claude/versions/ 下的某个版本；~/.claude/local/ 是旧版 Claude Code 创建的"本地 npm 安装"；最后一条列出当前 Node 的 npm 全局安装。某条命令提示 No such file or directory 不是错误，只说明那个位置没有安装。

想确认 Require stack 指向的那一份是什么版本、文件是不是真的缺了，把下面的路径换成你报错里 cli.js 所在的目录：

grep '"version"' ~/.nvm/versions/node/v20.13.0/lib/node_modules/@anthropic-ai/claude-code/package.json
ls ~/.nvm/versions/node/v20.13.0/lib/node_modules/@anthropic-ai/claude-code/yoga.wasm

版本号在 2.0.25 及以下、ls 提示文件不存在，就对上了。注意：此时 claude doctor 也用不了，它和 claude 走的是同一份坏掉的 cli.js，复现里同样以这条报错退出。

Require stack 的路径大致能告诉你是哪种安装、该怎么删。下表的路径来自公开报告。其中"直接删包目录和同一前缀下的 bin/claude"这种做法在复现里跑过，用的是隔离目录，不是真实的 nvm 路径：

第二步：删掉报错的那份和其他重复安装

动手前先退出所有正在运行的 Claude Code，包括其他终端窗口和编辑器里的会话。Claude Code 维护者在 GitHub issue #3172 里说明过，安装器和更新器不支持多个进程同时运行。

坏的那份属于当前 Node 的 npm 全局安装（npm root -g 打印的目录就是 Require stack 里 node_modules 那一级）：

npm uninstall -g @anthropic-ai/claude-code

坏的那份在另一个 Node 版本下：npm uninstall -g 只管当前 Node 的全局目录，对别的版本"没反应"。可以先 nvm use 20.13.0 切过去再卸载，也可以直接删除报错路径对应的包目录和同一前缀下的 bin/claude。示例路径换成你自己的：

rm -rf ~/.nvm/versions/node/v20.13.0/lib/node_modules/@anthropic-ai/claude-code
rm -f ~/.nvm/versions/node/v20.13.0/bin/claude

~/.nvm、~/.local/share/mise 都在你的用户目录下，删除不需要 sudo。

坏的那份在 ~/.claude/local/ 下：

rm -rf ~/.claude/local

然后运行 alias claude，如果看到指向 ~/.claude/local/claude 的 alias，到 ~/.zshrc 或 ~/.bashrc 里删掉那一行，再开一个新终端。

只删 ~/.claude/local 这一个子目录。~/.claude/ 本身存着设置、会话记录和登录信息，和程序文件是分开的，修这条报错不需要也不应该删它。

which -a 里如果还有别的副本，按官方说明"只保留一个"：Homebrew 安装用 brew uninstall --cask claude-code，pnpm 全局安装用 pnpm remove -g @anthropic-ai/claude-code（pnpm 这条未实测）。打算保留原生版时，~/.local/bin/claude 留着不动。

卸载时如果报 npm error code ENOTEMPTY，先看下文的处理办法，再回到这一步。

第三步：原生安装器或 npm @latest，只选一个重装

原生安装器和 npm 都是官方安装文档里列出的途径，装出来的是同一个原生二进制。选一个就够了，不要两个都装。

原生安装器（官方在排查重复安装时推荐保留它）：

curl -fsSL https://claude.ai/install.sh | bash

复现里它装出了 2.1.301，位置是 ~/.local/bin/claude。如果最后提示 Native installation exists but ~/.local/bin is not in your PATH，照它打印的命令把目录加进 PATH；zsh 下是：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

npm：需要 Node.js 22 或更新版本。Node 版本更低时 npm 只打印 EBADENGINE 警告，安装照样完成，因为装下来的原生二进制运行时不依赖你的 Node。不要加 sudo：

npm install -g @anthropic-ai/claude-code@latest

如果坏的那份恰好就在当前 Node 的全局目录下，而且没有别的副本，第二步可以跳过，直接执行这条覆盖安装。复现里在缺了 yoga.wasm 的 2.0.25 上直接执行，npm 输出 added 8 packages, removed 2 packages, and changed 1 package，claude 变成指向 bin/claude.exe 的 arm64 原生程序，显示 2.1.301 (Claude Code)。

第四步：用 which -a claude 和 claude --version 验证

hash -r
which -a claude
claude --version

hash -r 让当前 shell 忘掉之前记住的命令位置，也可以直接开一个新终端。which -a claude 应该只剩一行（原生版是 ~/.local/bin/claude，npm 版是 npm prefix -g 所指目录下的 bin/claude），claude --version 显示 2.1.xxx (Claude Code) 这样的当前版本号。之后可以再运行 claude doctor 看一眼安装状态，它只读取诊断信息，不会启动会话。

装了新版还报 yoga.wasm：旧 npm 副本挡在 PATH 前面

只装新版不删旧的，问题不会消失。复现里，原生版 2.1.301 已经在 ~/.local/bin/claude，同时把一份缺了 yoga.wasm 的 2.0.25 放到 PATH 更靠前的目录：

$ which -a claude
.../old/bin/claude
.../.local/bin/claude
$ claude --version
Error: Cannot find module './yoga.wasm'

删掉旧的包目录和它的 bin/claude 后，which -a claude 只剩 ~/.local/bin/claude，claude --version 显示 2.1.301 (Claude Code)。

GitHub #7193 里有人说"自己用的是原生安装也遇到了"，但他也不确定自己装的是哪一种。原生二进制里没有 cli.js，Require stack 里出现 cli.js 就说明执行的是 JavaScript 版本。所以原生安装后还看到这条报错，先按第一步查 which -a claude，大概率是旧副本排在前面。

日文社区的 Zenn 文章（naruhiro，2025 年 6 月）记录的是同一类情况：先用 npm 在 nvm 的 Node 下装过，后来用 pnpm 重装，nvm 那份仍排在前面，删掉它之后才恢复。

重装时的另外三条报错：ENOTEMPTY、native binary、PATH

npm error code ENOTEMPTY：卸载或重装时目录无法重命名

npm error code ENOTEMPTY
npm error syscall rename
npm error path .../lib/node_modules/@anthropic-ai/claude-code
npm error dest .../lib/node_modules/@anthropic-ai/.claude-code-XXXXXXXX

这是之前中断的安装留下了 .claude-code- 开头的临时目录。按官方处理 ENOTEMPTY 的说明，删掉包目录和这些临时目录，再重装：

rm -rf "$(npm root -g)/@anthropic-ai/claude-code"
rm -rf "$(npm root -g)/@anthropic-ai/.claude-code-"*
npm install -g @anthropic-ai/claude-code

第二条在 zsh 下提示 no matches found，只说明没有临时目录可删。npm error path 那一行的目录如果不在 npm root -g 下面（比如用 nvm 切过 Node 版本），就删除报错里写出的那几个目录。这一节的报错没有在复现里出现过，命令来自官方文档。社区里两个案例：GitHub #7193 里的用户在 nvm 的 Node v20.10.0 下加 --force 也卸载不掉，手动删除包目录和 bin/claude 后重装成功；Zenn 上一位 mise 用户删掉 .claude-code- 临时目录后，卸载和重装都通过了。

Error: claude native binary not installed：npm 跳过了安装脚本

当前的 npm 包在安装后要运行一个安装脚本，从按平台区分的可选依赖里把原生程序复制到位。用了 --ignore-scripts、--omit=optional，或者 pnpm 的某些配置跳过了这一步，运行 claude 会提示 Error: claude native binary not installed.。这已经不是 yoga.wasm 问题了，按官方说明去掉这些参数重装，或者手动运行提示里给出的 install.cjs。

~/.local/bin is not in your PATH：原生版装好了但找不到

原生安装器装好后 claude 提示 command not found，或者 which -a claude 里没有 ~/.local/bin/claude，就是这个目录不在 PATH 里。执行安装器最后打印的那条命令（第三步里的 zsh 示例），再开新终端验证。

Windows 上的对应命令（来自官方文档，未实测）

下面的 PowerShell 命令都摘自官方的安装与排障文档，没有在 Windows 上运行过。

查看 PATH 上有几个 claude，以及原生版在不在：

where.exe claude
Test-Path "$env:USERPROFILE\.local\bin\claude.exe"

删除重复安装：

npm uninstall -g @anthropic-ai/claude-code
Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\local"
winget uninstall Anthropic.ClaudeCode

只执行和你的 where.exe 输出对应的那几条。ENOTEMPTY 的 PowerShell 写法：

Remove-Item -Recurse -Force "$(npm root -g)/@anthropic-ai/claude-code", "$(npm root -g)/@anthropic-ai/.claude-code-*"

用原生安装器重装：

irm https://claude.ai/install.ps1 | iex

过一天又报 yoga.wasm：只留一个安装渠道

GitHub #7193 里有人重装后"只好了一阵子"。在 2025 年的旧版本上，自动更新会就地改写 npm 安装，坏掉一次就可能反复坏。当前版本不会再报 yoga.wasm，但下面几条能避免旧副本卷土重来，也能避免别的安装问题：

• 只用一个安装渠道。原生、npm、Homebrew、WinGet 选一个，其余的都删掉。
• npm 安装升级用 npm install -g @anthropic-ai/claude-code@latest，不要用 npm update -g：官方文档说明后者遵循最初安装时的版本范围，不一定能升到最新版。
• 不要用 sudo npm install -g。
• 换了 Node 版本管理器、或者用 nvm/mise 切了 Node 版本之后，先跑一次 which -a claude，看看有没有旧版本目录下的副本冒出来。
• 更新或重装前退出所有正在运行的 Claude Code。

清理干净仍报 yoga.wasm：什么时候提 GitHub issue

which -a claude 只剩一条、版本号是当前版本，却仍然看到 Cannot find module './yoga.wasm'，这和版本边界对不上。先用 alias claude 和 type -a claude 查有没有 alias 或 shell 函数把 claude 指到别处；编辑器里的终端从编辑器继承 PATH，退出编辑器再重开。还是这样，就到 Claude Code 的 GitHub issues 提交，附上操作系统、你用过的安装命令、which -a claude 的输出和完整报错。

报错变成别的内容时，换一条路：

• 进程以 code 1 退出：看 Claude Code process exited with code 1 怎么修。
• 只在 VS Code 扩展或面板里出问题，终端里正常：看 Claude Code 在 VS Code 里用不了？先定位失败表面。
• 其他安装和登录报错：查官方的 Claude Code 安装与登录排障页。

yoga-wasm 包、~/.claude 目录和 pnpm 的补充问答

执行 npm i yoga-wasm，或手动放一个 yoga.wasm 能修好吗？

npm i yoga-wasm 不行，它装的是另一个无关的包，Claude Code 不会去那里找文件。把同版本的 yoga.wasm 放回原位，复现里 2.0.25 确实能重新启动，但那仍是 2025 年的旧版本，半更新状态下缺的也未必只有这一个文件。删掉旧副本、重装当前版本更省事。

修 yoga.wasm 报错要删除 ~/.claude 目录吗？

不用。~/.claude/ 里是设置、会话记录和登录信息，程序文件在别处。要删的只有报错路径对应的包目录、它的 bin/claude，以及旧版本地安装用的 ~/.claude/local 子目录。

原生安装的 Claude Code 也会报 Cannot find module './yoga.wasm' 吗？

原生二进制里没有 cli.js，也不加载单独的 yoga.wasm。看到这条报错，说明 shell 执行的是另一份 JavaScript 版本的旧副本，用 which -a claude 能找到它。

用 pnpm 装的 Claude Code 报 yoga.wasm 怎么办？

pnpm 的情况没有实测。公开的案例是 npm 和 pnpm 各装了一份、nvm 下的 npm 旧副本排在前面，删掉那份即可。如果换成 pnpm 重装当前版本后看到的是 claude native binary not installed，那是安装脚本被跳过，按上文那一节处理。