pnpm doctor

添加于: v11.14.0

对 pnpm 的安装及其运行环境执行诊断。

pnpm doctor [--offline] [--benchmark] [--json]

每项检查都会报告如何修复其发现的问题，且当任何检查失败时，该命令会以非零状态码退出。警告不会导致命令失败。

✓ Versions: pnpm 11.14.0, Node.js 22.20.0
✓ Install method: pnpm
✓ Global bin directory: /Users/example/Library/pnpm/bin
✓ Cache directory: /Users/example/Library/Caches/pnpm
✓ Store directory: /Users/example/Library/pnpm/store/v10
✓ Filesystem: available: reflink, hardlink, symlink
✓ Registry connectivity: https://registry.npmjs.org/ (128ms)
✓ Install smoke test: offline "file:" install linked its dependency

All checks passed

检查#

版本#

报告运行的 pnpm 和 Node.js 版本。

安装方法#

报告 pnpm 的安装方式（是作为 pnpm 软件包安装，还是作为 @pnpm/exe 独立构建版本安装），并在 pnpm 由 Corepack 运行时发出警告——因为 Corepack 会自行管理 pnpm 版本，导致 pnpm self-update 命令无法使用。

全局 bin 目录#

检查 pnpm 链接全局可执行文件的目录是否在 PATH 环境变量中且具有写入权限。如果它不在 PATH 中，解决方法是运行 pnpm setup。

缓存目录#

检查 缓存目录 是否可写。

存储目录#

检查 存储目录 是否可写。没有配置存储目录时跳过。

文件系统#

基于存储卷运作的链接策略包括：引用链接（写时复制）、硬链接和符号链接。这决定了包在 node_modules 中的落盘方式以及安装速度——引用链接或硬链接的开销几乎为零，而普通复制则不然。

如果引用链接和硬链接均无法使用，检查程序会发出警告，提示安装过程将回退到复制模式，并建议将存储区放置在与项目相同的文件系统上。

注册源连接性#

向已配置的注册源发送 15 秒超时的 Ping 请求，并报告往返时间。如果无法连接到注册源或注册源返回错误状态，则操作失败；这通常指向网络、代理或身份验证配置方面的问题。

使用 --offline 跳过。

安装烟雾测试#

将一个一次性包作为 file: 依赖项安装到临时目录中，全程完全离线。这会端到端地测试解析、存储和链接路径，并确认正在运行的二进制文件确实能够执行安装操作。

该检查在设计上始终处于离线状态，因此 --offline 选项不会跳过它。

配置项#

--offline#

跳过需要网络访问的检查。

--benchmark#

还有时间文件系统和安装检查，与每个结果一起报告持续时间。

--json#

将结果报告为 JSON。输出是一个对象，其中包含一个 checks 数组，每个条目都有 title、status（pass、warn 或 fail），以及可选的 detail、fix 和 durationMs。

{
  "checks": [
    {
      "title": "Filesystem",
      "status": "pass",
      "detail": "available: reflink, hardlink, symlink",
      "durationMs": 3
    }
  ]
}