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

> yoga.wasm 报错只出现在 2.0.25 及更早的 npm 版 Claude Code 上：用 which -a claude 找出在跑的旧副本，删掉它，只留一个渠道重装。

- URL: https://blog.laozhang.ai/zh/posts/claude-code-cannot-find-module-yoga-wasm
- Published: 2026-10-16
- Updated: 2026-10-16
- Author: LaoZhang AI Team (https://blog.laozhang.ai/zh/about)
- Topic: Claude Code
- Tags: Claude Code, yoga.wasm, 报错, npm, 故障排查

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

```text
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 更新日志](https://code.claude.com/docs/en/changelog)，2.0.25 到 2.0.26 之间的打包变化在更新日志里没有写，是逐个列出 2.0.24、2.0.25、2.0.26 安装包内容得出的：

| npm 版本 | `yoga.wasm` 的形态 | 会不会报这条错 |
| --- | --- | --- |
| 2.0.25 及更早（2.0.25 发布于 2025 年 10 月 21 日） | 单独文件，`cli.js` 启动时按 `./yoga.wasm` 加载 | 会：文件缺失就报 |
| 2.0.26（2025 年 10 月 23 日）至 2.1.84 | 没有单独文件，WASM 打包在 `cli.js` 内部 | 不会 |
| 2.1.85（2026 年 3 月 26 日）至 2.1.112 | 布局改用纯 TypeScript 实现，不再用 WASM | 不会 |
| 2.1.113（2026 年 4 月 17 日）起 | npm 包只是原生二进制的包装，没有 `cli.js` | 不会 |

复现里也确认了这一点：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 报错）](https://github.com/anthropics/claude-code/issues/7193) 里解释过：2025 年的自动更新如果中途被打断（网络错误、合盖、系统中断），会留下缺少 `yoga.wasm` 等关键文件的半更新状态；在 [GitHub issue #1103](https://github.com/anthropics/claude-code/issues/1103) 里也提到，旧的自动更新基于 `npm update`，原子性很差，单独拷贝 `cli.js` 到别处也不行，它需要同目录下的 `yoga.wasm` 等配套文件。GitHub 上不少报告都提到，报错是在"昨天还能用""会话开着放了一夜"之后出现的。

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

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

![yoga.wasm 报错的四步修法：which -a claude 找出在跑的副本、删掉旧副本、只选一个渠道重装、用 claude --version 验证](https://blog.laozhang.ai/posts/zh/claude-code-cannot-find-module-yoga-wasm/img/fix-steps.webp)

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

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

```bash
which -a claude
```

输出的第一行就是你输入 `claude` 时实际执行的那个。按官方[检查重复安装的说明](https://code.claude.com/docs/en/troubleshoot-install#check-for-conflicting-installations)，再看三个常见位置：

```bash
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` 所在的目录：

```bash
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 路径：

| Require stack 里的路径 | 是哪一份 | 删除方式 |
| --- | --- | --- |
| `~/.nvm/versions/node/v版本号/lib/node_modules/...` | nvm 下某个 Node 版本的 npm 全局安装 | 当前 Node 就是这个版本时用 `npm uninstall -g`；不是的话直接删该版本下的包目录和 `bin/claude` |
| `~/.local/share/mise/installs/node/版本号/lib/node_modules/...` | mise 管理的 Node 的 npm 全局安装（未实测） | 同上 |
| `/opt/homebrew/lib/node_modules/...` | Homebrew 装的 Node 的 npm 全局安装（未实测） | 同上 |
| `~/.npm-global/lib/node_modules/...` | 自定义 npm 全局目录 | 同上 |
| `~/.claude/local/` 下 | 旧版"本地安装" | `rm -rf ~/.claude/local`，再删掉 shell 配置里指向它的 alias |

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

动手前先退出所有正在运行的 Claude Code，包括其他终端窗口和编辑器里的会话。Claude Code 维护者在 [GitHub issue #3172](https://github.com/anthropics/claude-code/issues/3172) 里说明过，安装器和更新器不支持多个进程同时运行。

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

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

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

```bash
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/` 下**：

```bash
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 都是官方[安装文档](https://code.claude.com/docs/en/setup)里列出的途径，装出来的是同一个原生二进制。选一个就够了，不要两个都装。

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

```bash
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 下是：

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

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

```bash
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 验证

```bash
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 更靠前的目录：

```text
$ 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)`。

![删除前旧的 2.0.25 副本排在 PATH 第一位导致 yoga.wasm 报错，删掉后只剩 ~/.local/bin/claude 并显示 2.1.301](https://blog.laozhang.ai/posts/zh/claude-code-cannot-find-module-yoga-wasm/img/path-order.webp)

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

日文社区的 [Zenn 文章（naruhiro，2025 年 6 月）](https://zenn.dev/naruhiro/articles/8a883102262445)记录的是同一类情况：先用 npm 在 nvm 的 Node 下装过，后来用 pnpm 重装，nvm 那份仍排在前面，删掉它之后才恢复。

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

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

```text
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 的说明](https://code.claude.com/docs/en/troubleshoot-install#npm-enotempty-during-update-or-reinstall)，删掉包目录和这些临时目录，再重装：

```bash
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 问题了，按[官方说明](https://code.claude.com/docs/en/troubleshoot-install#native-binary-not-found-after-npm-install)去掉这些参数重装，或者手动运行提示里给出的 `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`，以及原生版在不在：

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

删除重复安装：

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

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

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

用原生安装器重装：

```powershell
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](https://github.com/anthropics/claude-code/issues) 提交，附上操作系统、你用过的安装命令、`which -a claude` 的输出和完整报错。

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

- 进程以 code 1 退出：看 [Claude Code process exited with code 1 怎么修](https://blog.laozhang.ai/zh/posts/error-claude-code-process-exited-with-code-1)。
- 只在 VS Code 扩展或面板里出问题，终端里正常：看 [Claude Code 在 VS Code 里用不了？先定位失败表面](https://blog.laozhang.ai/zh/posts/claude-not-working-in-vscode)。
- 其他安装和登录报错：查官方的 [Claude Code 安装与登录排障页](https://code.claude.com/docs/en/troubleshoot-install)。

## 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`，那是安装脚本被跳过，按上文那一节处理。

## 参考来源

本文引用的外部页面，按正文出现顺序排列。最后更新于 2026-10-16。

- [Claude Code 更新日志](https://code.claude.com/docs/en/changelog) (code.claude.com)
- [GitHub issue #7193（yoga.wasm 报错）](https://github.com/anthropics/claude-code/issues/7193) (github.com)
- [GitHub issue #1103](https://github.com/anthropics/claude-code/issues/1103) (github.com)
- [检查重复安装的说明](https://code.claude.com/docs/en/troubleshoot-install) (code.claude.com)
- [GitHub issue #3172](https://github.com/anthropics/claude-code/issues/3172) (github.com)
- [安装文档](https://code.claude.com/docs/en/setup) (code.claude.com)
- [Zenn 文章（naruhiro，2025 年 6 月）](https://zenn.dev/naruhiro/articles/8a883102262445) (zenn.dev)
- [Claude Code 的 GitHub issues](https://github.com/anthropics/claude-code/issues) (github.com)