先讲一下我这边的真实处境Claude Code跑一个“把整个代码库重构一次”的长期任务跑到一半终端光标还在但彻底没反应了。CPU飙到百分之百风扇狂转命令输进去完全不执行连CtrlC都压不死。日志停留在“Reading workspace...”就再也不走了一切看起来就像个黑洞。那会儿我还没写 pstack-claude 这个工具第一反应是上经典的 pstack打算直接看这个进程堵在哪。结果发现问题比想象中麻烦Claude Code 是 Node.js 写的传统 pstack 打印出来的 C/C 栈几乎全是 libuv 和 V8 的调度代码完全看不出来业务代码卡在哪一行。也就是那次我决定专门给 Claude Code 写一个抓取进程栈快照的小工具名字就叫 pstack-claude。这篇文章会把它的设计思路、核心实现和几个真实排查案例完整拆给你。同时你大概率会在安装和使用 Claude Code 时遇到那一堆经典报错——Windows 虚拟化平台没开、npm prefix 没写权限、自动更新失败、app unavailable、MCP server 起不来等等我也会一并把排查思路和解决方案写清楚。适合谁看被 Claude Code 卡死、报错、版本混乱折磨的人以及任何想深入理解 Node CLI 进程诊断的人。1. 先说清楚为什么排查 Claude Code 要用“进程栈”1.1 一个卡死现场的观察先回到那个我印象极深的下午。CPU 100%但进程没有崩溃没有退出日志也不再刷新。很多人到这里会直接杀掉进程重启但重启之后大概率还会在同一个位置卡住因为你根本不知道它为什么卡住。我当时做了一步关键观察进程还活着说明不是 OOM 崩溃也不是 segfault。它可能是陷入了同步死循环也可能是事件循环被某个不可让出的任务长时间占用还有一种可能是它并没有在计算而是在等一个永远不会回来的异步回调——比如子进程挂起、网络请求超时但没有设置上限。这里有个特别容易踩的误区日志不输出 ≠ 程序死了。Node 的 stdout 写入往往是异步的如果事件循环被一个长任务彻底阻塞那么所有待写入的日志都堆在缓冲区里表现出来就是“最后一条日志之后再无动静”。这时候最需要的不是日志而是拍一张进程在“当前瞬间”的调用栈快照。1.2 为什么传统 pstack 在 Node 进程上失灵pstack 是 Linux 下非常经典的工具原理是读取/proc/pid/stack通过 ptrace 附加到目标进程把用户态每个线程的函数调用栈打印出来。排查 C/C 程序、JVM 本地代码、系统守护进程时非常好用几秒钟就能定位到线程堵在哪个 syscall 或者锁上。但 Node.js 不一样。JS 代码运行在 V8 引擎里你的业务代码早就被编译成了 JIT 机器码。直接用 pstack 看看到的是 V8 内部的v8::internal::Runtime_...、v8::platform::...、uv__io_poll这类底层符号。你只能知道“V8 正在干活”或者“libuv 正在等 I/O”根本不知道是哪个函数、哪一行 JS 在跑。说个生活化类比普通进程的栈像一本能直接翻开读的书每页都写着具体在哪一行。到了 Node 进程这里pstack 只能告诉你“这本书印刷机正在运转”但印刷的是哪一章、哪一句它看不到。所以要诊断 Claude Code核心是抓 JS 调用栈而不是 C/C 调用栈。好在 V8 本身提供了完善的 inspector 协议关键是怎么把一个已经在运行的进程附加进去。1.3 给运行中的 Node 进程拍“栈快照”的三种办法我调研下来给运行中的 Node 进程抓栈主流有三条路第一启动时就加参数。用node --inspect或NODE_OPTIONS--inspect127.0.0.1:9229启动 Claude Code进程会提前开放调试端口。这种方案最干净但要求你预判到将来要诊断所以只能作为“预防”手段对已经在裸奔运行的进程没用。第二运行时发信号激活。Node 官方支持一个冷知识向运行中的 Node 进程发送SIGUSR1信号它会动态开启 inspector默认监听127.0.0.1:9229。也就是说不需要提前做任何配置只要进程还活着你就能从外部让它暴露调试端口。Linux 和 macOS 实测都有效。Windows 原生不支持 SIGUSR1所以 Windows 建议提前注入NODE_OPTIONS或者干脆在 WSL2 里跑 Claude Code。kill -USR1 12345 curl http://127.0.0.1:9229/json/list第三采样式 CPU Profiler。端口开启后通过 Chrome DevTools Protocol 连接发送Profiler.start等个几秒再Profiler.stop所有采样点会被聚合成“热点栈”。这是 pstack-claude 最核心的抓取手段因为它看到的是 JS 层真实调用路径而不是一堆底层符号。2. 安装与前置Claude Code 常见的“起不来”问题2.1 用 npm 正确安装 Claude Code 并检查权限在聊 pstack-claude 的用法之前得先把 Claude Code 本身装好。很多人在第一步就倒了后面全白搭。安装命令很简单就一行npm install -g anthropic-ai/claude-code但有几个前置检查必须做对。第一确认 Node 版本满足要求我建议至少 18 以上版本太老容易出现各种诡异的运行时问题。第二检查 npm 的全局安装目录到底在哪npm config get prefix这个目录决定了 Claude Code 的可执行文件装到哪。如果你之前用sudo装过任何全局包那么这个目录很可能属于 root当前用户对它没有写权限。这种状态下第一次安装可能还能过一旦 Claude Code 自动更新就会报出让人头疼的“no write permission to npm prefix”。如果你在内地网络环境npm 官方源经常很慢建议先切换到一个国内网络环境普遍稳定可用的镜像源这属于常规基础设施配置不涉及任何额外的东西npm config set registry https://registry.npmmirror.com装完验证一下claude --version如果提示 command not found多半是 PATH 里没有包含 npm 的全局 bin 目录。用npm prefix -g看一下把对应的bin目录加到.bashrc或.zshrc。2.2 Windows Virtual Machine Platform 报错的完整解法在 Windows 上安装 Claude Code很多人会撞上这么一条错误claudes workspace requires the virtual machine platform on windows. enable这个错误真的不是玄学。Claude Code 在 Windows 上的 workspace 隔离机制依赖 Windows 的“虚拟机平台”功能官方推荐配合 WSL2 使用。你大概率是在一个没开虚拟化功能的 Windows 环境里装了它。解法分两步走。首先管理员权限打开 PowerShell依次执行dism /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart dism /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart第二步更新 WSL2 内核并重启wsl --update重启之后确认一下状态wsl --status如果看到默认版本是 2说明基础环境通了。我个人的建议是Windows 上跑 Claude Code直接装到 WSL2 的 Ubuntu 里而不是 Windows 原生。原因很实在Claude Code 里面要启动各种子进程、操作文件系统、跑 shell 命令Windows 原生的路径转换和权限模型经常让这些行为变得极慢甚至卡住而在 WSL2 里这些操作的行为更接近 Linux也更容易用 pstack-claude 这类依赖/proc和信号的诊断工具。2.3 自动更新失败npm prefix 没写权限的根治方法“auto-update failed: no write permission to npm prefix”是出现频率极高的报错。Claude Code 每次启动会检查新版本尝试向 npm 全局目录写入更新文件。如果你的 npm prefix 指向的是一个需要 root 权限的目录更新必然失败。我推荐彻底根治用的方法是把 npm 全局目录改到用户目录下npm config set prefix ~/.npm-global export PATH$HOME/.npm-global/bin:$PATH把export PATH这一行写进.bashrc或者.zshrc然后重新登录或者source一下。之后重新安装 Claude Codenpm install -g anthropic-ai/claude-code这样全局包都在~/.npm-global下权限完全属于当前用户自动更新不会再报权限错误。另一种更省心的方案是用 nvm 管理 Nodenvm 会把 Node 和所有全局包都放在用户目录下天然没有权限问题。如果你暂时不想让它自动更新也可以设置环境变量禁用自动更新变量名视具体版本而定多数版本支持DISABLE_AUTOUPDATER1需要更新时手动执行npm install -g anthropic-ai/claude-codelatest就行。3. pstack-claude 的设计与核心实现3.1 工具定位与命令设计写 pstack-claude 的初衷很简单Claude Code 卡死时我想快速得到一份“这个进程现在到底在干什么”的报告而不是靠猜。它是一条命令行工具使用方式大概是# 附加到正在运行的 claude 进程采样 15 秒 pstack-claude attach --pid 12345 --duration 15 # 保存/转发诊断报告 pstack-claude attach --pid 12345 --duration 15 --output snapshot.json pstack-claude report --input snapshot.json --format markdown整个工具定位很窄只做“诊断采样”不做任何修改进程状态的操作。附加诊断时也只用只读的 inspector 协议不会去注入代码、不会杀掉进程、不会改动 Claude Code 的任何数据。所以你可以放心在卡死状态下使用。3.2 核心链路从 SIGUSR1 到 CDP 采样pstack-claude 的工作链路可以分为六个步骤每一步都有各自的坑。第一步确认目标进程确实是 Claude Code。读取/proc/pid/cmdline检查里面有没有claude或者cli.js这样的关键字。这一步很关键避免用户不小心对别的 Node 进程下手。第二步发送kill -USR1 pid让目标进程动态激活 inspector。这里有个小细节信号发送后Node 不会立刻监听端口需要轮询等待http://127.0.0.1:9229/json/list返回有效数据我实测通常几百毫秒到一两秒。第三步通过 HTTP 接口拿到webSocketDebuggerUrlconst http require(http); function getDebuggerUrl(port 9229) { return new Promise((resolve, reject) { http.get(http://127.0.0.1:${port}/json/list, (res) { let body ; res.on(data, (c) (body c)); res.on(end, () { const targets JSON.parse(body).filter((t) t.type node); resolve(targets[0]?.webSocketDebuggerUrl); }); }).on(error, reject); }); }第四步用 WebSocket 连接上这个地址依次发送Runtime.enable、Profiler.enable、Profiler.start。同时用Runtime.evaluate执行几条只读的探测表达式把事件循环里挂起的东西拉出来const expressions [ process._getActiveHandles().map(h h.constructor.name), process._getActiveRequests().map(r r.constructor.name), process.memoryUsage(), ];这里有个实测经验process._getActiveHandles()返回的是对象数组直接 JSON 序列化会丢信息pstack-claude 在 evaluate 时会用process.mainModule.require(util).inspect(...)包一层把内部对象转成便于阅读的字符串再返回。第五步等待--duration指定的秒数然后发送Profiler.stop。V8 会返回一个巨大的 profile 对象里面包含nodes、samples、timeDeltas三块数据。nodes是调用栈节点的扁平数组samples是每次采样点对应的 node id。第六步聚合采样数据。我的做法是把samples遍历一遍统计每个 functionName 出现的次数然后针对排名靠前的几个 node向上递归 parent还原出完整的调用链。输出时把函数名、采样占比、文件路径如果 sourcemap 可用都打印出来。3.3 为什么不用 strace 和 ltrace不少朋友会问诊断进程卡死为什么不用 strace 看系统调用说实话strace 在简单场景下确实能快速看出“这个进程在等哪个 syscall”但对 Node 这种多线程、高 I/O 并发、内部全是异步回调的进程来说strace 的输出是灾难级的。每秒几千上万行绝大多数是epoll_wait、read、write噪音巨大而且 attach 上去会对性能产生明显影响。pstack-claude 选择的是“采样式 CPU Profiler”它不会阻塞目标进程也不会产生 GB 级日志只会在固定间隔抓一次栈最后给你一张热点统计表。这种方式对生产诊断足够而且开销低到基本无感。3.4 抓不到栈时的兜底方案如果目标进程在 Windows 原生环境运行SIGUSR1 信号不可用整个 CDP 链路就走不通。这种情况 pstack-claude 会退化成“外部观察”模式读取/proc/pid/status看线程状态读/proc/pid/task/*/wchan看内核等待点再结合任务管理器里的句柄数给出一份粗粒度的判断。不过我更推荐 Windows 用户在 WSL2 里跑 Claude Code一劳永逸。不然你不仅用不了信号诊断连基础的ps、kill、top都不顺手很多 Linux 生态的诊断工具都白搭。4. 实战用 pstack-claude 排查三个疑难杂症4.1 场景一卡在“Loading workspace”CPU 100%我遇到的第一例就是文章开头提到的重构任务。pstack-claude 采样 10 秒后热点栈清晰显示如下45.2% FSReqCallback.oncomplete 22.8% readdirSync 11.6% path.join 9.3% JSON.parse 6.1% statSync事件循环挂起句柄列表里全是FSWatcher、FSReqCallback基本可以断定Claude Code 在递归扫描整个仓库一边建索引一边做缓存而且完全没有增量缓存的意思。整个热点分布说明它卡在文件系统操作上不是死循环也不是网络问题就是扫描量太大了。解决办法非常直接在.claudeignore里排除掉node_modules、dist、.git、build这些巨型目录如果项目本身很大可以考虑把 Claude Code 的工作目录缩小到某个子模块。经过这两步同样的任务再跑进入工作区的耗时从原来的一分多钟降到了几秒。4.2 场景二Tool Call 已发出但没有任何后续动作另一个典型案例是日志里明明已经显示了Tool Use: Bash(npm install)但之后就永远停住了。pstack-claude 的输出很有意思——JS 层没有任何热点采样事件循环挂起句柄里躺着一个ChildProcess的PipeWrap。这说明 node 进程本身没有在算东西而是在等一个子进程退出。JS 采样没有热点反而是个明确信号它堵在 I/O 等待上不在 CPU 密集计算里。顺着 ChildProcess 去查发现这个卡死的进程是 npm 安装依赖的子进程因为 registry 源超时npm 在无限重试。杀掉残留的 npm 子进程把安装源切换成干净可靠的镜像再设置 npm 的请求超时问题就消失了。这个案例给了一个很重要的排查心法CPU 100% 时看热点栈CPU 几乎为 0 时看事件循环挂起句柄两条路分别对应“死循环”和“死等待”。4.3 场景三自动更新与新版本不匹配导致的诡异行为还有一个很隐蔽的问题表现形式是每次启动 Claude Code 都要干等半分钟之后才进入交互界面偶尔还会报出类似“找不到 start in cowork”这种莫名其妙的命令错误。用 pstack-claude 对启动阶段采样发现热点集中在node-gyp、npm install相关的调用路径上也就是说自动更新在后台偷偷运行。而报错之所以诡异是因为 CLI 已经被更新成新版本但 VSCode 扩展还停留在旧版本两边协议对不上于是功能入口错乱。处理思路先统一版本手动执行claude update或者重新安装最新版 CLIVSCode 扩展也升级到相同版本然后禁用自动更新。经过这一轮整治启动速度和稳定性都正常了。这种问题不用栈诊断确实也能试出来但看不到“后台在跑安装流程”这个根因很容易白折腾半天。5. 高频报错速查表报错信息根因处理建议claudes workspace requires the virtual machine platform on windowsWindows 虚拟化功能未启用WSL2 不可用启用 VirtualMachinePlatform 和 WSL 功能wsl --update重启后确认版本为 2auto-update failed: no write permission to npm prefixnpm 全局目录对当前用户不可写设置npm config set prefix ~/.npm-global或改用 nvm 管理 Nodecommand not found: claudePATH 没包含 npm 全局 bin 目录npm prefix -g找到 bin 路径加入 shell 配置App unavailable / unfortunately, claude is only available in certain regions官方按区域提供服务所在环境不在支持范围确保账号与使用环境符合官方支持范围以官方文档为准MCP server failed to start via npxnpx 缓存损坏、网络源不稳定或 Node 版本过旧检查.mcp.json配置清 npx 缓存切换稳定 npm 源升级 Node找不到 start in cowork 类命令CLI 与 VSCode 扩展版本不匹配升级 CLI 与扩展到相同最新版重载窗口启动后 CPU 100% 卡在 Loading递归扫描超大目录且无缓存配置.claudeignore排除 node_modules、dist 等目录上面这些报错几乎都能在安装和运行 Cluade Code 的路上遇到。如果你配备了 pstack-claude 这类栈诊断工具遇到表格里前两类“环境问题”可能还用不上但一旦遇到“卡死类”问题它能省下的时间以小时计。6. 一点个人体会写 pstack-claude 的过程让我重新确认了一件被很多人忽略的事AI CLI 再智能底层仍然跳不出进程、事件循环、文件描述符、子进程这些经典概念。日志记录的是“它打算做什么”而进程栈记录的是“它此刻真的停在哪”。两者互补缺一不可。我在实际使用中还有一个很实用的小习惯启动诊断前先记录一下当时的时间点和 CPU 使用率诊断结束后再记录一次。两次对比能快速区分“瞬间抖动”和“稳定卡死”——前者采样几秒可能就恢复正常后者采多久热点都纹丝不动。这个细节帮你避免误判。如果你也常被 Claude Code 的卡死和报错困扰或者对 Node 进程诊断感兴趣可以动手复刻一个最小版本SIGUSR1 CDP Profiler 采样核心代码并不长。后续可以考虑给 pstack-claude 加上更友好的图形化火焰图输出或者把采样结果自动关联到当时日志的时间线诊断效率还能再上一个台阶。