如果你跟我一样，把 Claude Code 当成日常项目的编程副驾，一定遇到过这种场景：任务跑到一半，终端像死机一样卡住，光标闪烁，日志也不更新。重启吧，舍不得进度；不重启吧，又不知道它卡在哪。我在 Linux 上用 Claude Code 做自动化重构的时候，被这种“黑盒卡顿”反复折磨，后来想到 Linux 上最硬的排查工具 pstack——直接把进程的调用栈拉出来，看看它到底停在哪一行、在等什么。于是就有了 pstack-claude 这个小项目：一套用 pstack 抓取 Claude Code 进程栈、快速定位卡死原因的诊断工作流。这篇博文会从 Claude Code 的进程模型开始，讲到 pstack 的原理和权限，再给出一套可以直接抄的采样脚本和排查流程，最后把我踩过的坑和解决方式整理出来。
1. Claude Code 先想清楚它到底是怎么跑的
1.1 终端里的自动化编程助手到底在忙什么
Claude Code 本质上是一个跑在终端里的编程助手，它跟网页版最大的区别是：它拥有项目工作区的读写能力，会主动读取你的目录结构、打开文件、搜索代码，甚至直接在终端里执行命令。你可以把它理解成一个“能操作电脑的模型”，而不只是“一个聊天的模型”。
这种能操作的特性意味着，它的大多数工作并不是在纯文本对话里完成的，而是拆成一个又一个动作：读文件、查代码、跑测试、改代码、再验证。每一个动作背后都涉及实际的系统调用，比如read、write、execve。所以当你看到终端里光标停了很久，它可能正在做下面几件事之一：
- 模型正在思考，等待推理结果返回；
- 子进程正在执行某个命令，比如
npm test、grep -R； - 程序在等待网络请求返回；
- 某个 MCP 工具服务卡住，拖住了主任务；
- 真的死锁了，线程互相等待资源。
不把进程内部的状态暴露出来，光靠肉眼看终端，永远区分不了“它在思考”和“它卡死了”。这也是我在 pstack-claude 里最先想解决的问题：能不能在任何一个可疑时刻，给 Claude Code 的进程拍一张快照，直接看到它停在哪里。
1.2 安装前把环境收拾利索
Claude Code 的安装入口非常简单，一个 npm 全局安装命令就能搞定：
npm install -g @anthropic-ai/claude-code安装完成之后直接敲claude就能进入交互式对话界面。但实际使用之前，有几个环境问题非常值得提前处理，否则后面全是坑。
首先是 Node.js 的版本。Claude Code 依赖较新的 Node 运行时，建议至少 18 以上。我遇到过老 node 版本导致 CLI 启动直接报错的情况，所以如果你已经装了 node，先用node -v看一下。
然后是 Windows 环境。Claude Code 在 Windows 下跑，经常会出现一个报错：Claude's workspace requires the Virtual Machine Platform on Windows。这个报错的意思是，你的系统没有打开“虚拟机平台”这个 Windows 功能，Claude Code 的隔离工作区依赖这个虚拟化能力。解决办法是在管理员权限的终端里执行：
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart执行完要重启电脑，然后在 Microsoft Store 安装 WSL 2，或者用wsl --install -d Ubuntu-22.04快速装一个 Linux 发行版。如果你在 WSL 里跑 Claude Code，整体体验比在 Windows 原生环境下稳定得多，MCP 和 pstack 这些调试工具也能直接用。
1.3 让日志成为排查的第一手资料
Claude Code 会把运行过程的每一步轨迹写到本地日志文件里，路径一般在用户目录下的.claude/logs里。你可以在启动 Claude Code 后开另一个终端窗口，用下面的命令实时盯日志：
tail -f ~/.claude/logs/claude*.jsonl这些日志是 JSONL 格式，每行一条事件记录，包含时间戳、事件类型、模型调用信息等。比如tool_use事件代表它准备调用某个工具，tool_result代表工具执行完成。日志的价值在于，你可以在用 pstack 抓完栈之后，把栈里的时间点和日志里的最后一条事件对上，立刻知道卡之前它在做什么。
我习惯每次跑长任务之前，先把日志文件路径记下来，卡住的第一反应不是杀进程，而是先看日志最后几条写了什么。这是后面整套排查链路的关键地基。
2. pstack 工具选型：一把快准稳的进程探针
2.1 为什么选中 pstack 而不是一上来就 gdb
Linux 下查看进程栈的方式有好几种，pstack、gdb、strace 各有各的适用场景。我在设计 pstack-claude 的时候首选 pstack，原因很直接：它快。
pstack 的用法一句话就能说明白：
pstack <pid>它会输出目标进程当前所有线程的调用栈，而且不需要你手动 attach、继续运行、再 detach。整个操作是一次性的，就像给进程拍一张 X 光片，拍完马上恢复运行。Claude Code 在生产环境跑自动化任务的时候，我不想用 gdb 那种重型工具去打断它，pstack 快进快出，侵入性非常低。
从原理上讲，pstack 是通过ptrace系统调用 attach 到目标进程，读取/proc/<pid>/task目录下的线程信息，然后借助调试接口把每个线程的调用栈符号化，最后再 detach。所以它能看到的是某一个瞬间的状态。这个特性和我排查卡顿的需求完美匹配：我想知道的就是“这一刻它停在哪”。
对比几个常见工具，我的选型逻辑是这样的：
| 工具 | 侵入性 | 输出完整度 | 上手难度 | 适合场景 |
|---|---|---|---|---|
| pstack | 低 | 中 | 低 | 快速查看所有线程栈 |
| gdb attach | 中 | 高 | 高 | 崩溃分析、条件断点 |
| strace | 低 | 只跟踪系统调用 | 中 | 分析文件、网络、进程阻塞 |
如果 Claude Code 是直接崩溃退出了，那我会用 gdb 去分析 core dump；如果只是卡住不动，pstack 的输出已经完全够用。
2.2 三个备选工具的真实差距
pstack 的输出比较简洁，默认只给线程号和每一层的函数名。gdb attach 能做的事情更多，比如动态打断点、查看内存变量，但对于“进程还活着，只是卡住”这个场景，gdb 的能力是过剩的。
strace 是另一个常见选择，它不输出栈，而是输出系统调用序列。你可以通过strace -p <pid>看到进程正在执行的系统调用，如果它卡在read上，你会看到一直阻塞在read调用里。这个信息其实很有价值，我在分析 Claude Code 卡在网络请求的时候也会用。但 strace 有个问题：它只告诉你“卡在 read”，却不一定告诉你“是哪个业务逻辑触发这次 read”。pstack 能直接告诉你调用链是从哪个函数走到这一步的，定位更直观。
所以我在 pstack-claude 里的做法是：默认先上 pstack，拿不到有效信息再上 strace 补系统调用维度，最后才考虑 gdb。没必要一上来就上大炮打蚊子。
2.3 权限和 ptrace_scope 是绕不开的坎
在你第一次运行pstack <pid>的时候，很有可能会看到Operation not permitted。这不是 pstack 坏了，而是 Linux YAMA 安全模块在拦你。
检查一下这个文件：
cat /proc/sys/kernel/yama/ptrace_scope如果输出是1，说明系统默认只允许进程追踪它的子进程。Claude Code 是在你终端里启动的，照理说你可以 trace 它，但如果你把 Claude Code 放到后台、或者用服务方式启动，它可能就不是你的子进程了，这时候 pstack 会被拒绝。
临时解决方案是在测试机上把限制调低：
echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope或者直接对 pstack 用 sudo：
sudo pstack <pid>我的建议是尽量用 sudo 去抓，不要轻易改 ptrace_scope 全局配置，尤其是在公司共享的开发机上。这个改动的安全影响范围太大，你不想因为排一个 bug 把整台机器的不设防状态留给别人。
3. pstack-claude 实战：从抓栈到定位卡顿的完整链路
3.1 先写一个不会污染现场的采样脚本
我最开始是纯手工操作，卡住了就打开另一个终端，pgrep找 PID，再pstack。但手工操作有个问题：卡顿往往是间歇性的，你人不在终端前的时候它开始卡，回来的时候已经恢复，根本抓不到现场。
所以我写了第一个采样脚本，思路很简单：定时对目标进程抓一次栈，连续抓十次，把结果存成带时间戳的文件。
#!/bin/bash # sample-claude-stack.sh target_pid=$(pgrep -f "claude" | head -n 1) if [ -z "$target_pid" ]; then echo "no claude process found" exit 1 fi out_dir="stack_$(date +%Y%m%d_%H%M%S)" mkdir -p "$out_dir" for i in $(seq 1 10); do timestamp=$(date +%H%M%S) pstack "$target_pid" > "$out_dir/${timestamp}.txt" 2>&1 sleep 10 done echo "saved to $out_dir"为什么连续采样十次而不是一次？因为单次栈只能代表一瞬间的状态。进程可能恰好停在一个正常的等待点，比如事件循环在等下一次循环，你误判成卡死。连续采样之后，如果每次的栈都停在同一位置，那基本可以断定它真的卡在这里；如果栈的内容各不相同，说明它还在推进，只是输出比较慢。
实际使用的时候，我会把采样间隔调成 5 秒，连续抓 20 次，这样能覆盖 100 秒左右的窗口，基本上能抓住卡顿的完整形态。
3.2 Node.js 进程栈到底怎么看
Claude Code 是 Node.js 应用，所以 pstack 抓出来的栈里会看到大量 libuv、V8 和 Node 底层的函数。很多人第一次看这种栈会懵，觉得不像是自己能理解的东西。其实不用怕，你只需要关注几个关键信息。
一个典型的正常等待中的栈可能是这样的：
Thread 1 (process 12345): #0 epoll_wait (k=3, events=0x7ffe..., timeout=...) #1 uv_run (...) #2 node::Start (...) ...epoll_wait是事件循环在等待新事件，这是 Node.js 最正常的空闲状态。如果 Claude Code 正在等待用户输入，或者等待网络数据，你大概率会看到这个栈。
另一种情况是栈里出现大量 V8 内部编译和执行相关函数，比如v8::internal::...，这说明它还活着，正在密集计算，可能就是模型推理过程中的本地处理。这种情况下不需要太担心，过一会儿它自然会继续输出。
真正值得警惕的是多个线程卡在互相等待的锁上。如果多个线程的栈里都有futex_wait、pthread_cond_wait这类调用，说明可能有锁竞争或者死锁趋势。Claude Code 会启动一些并行的后台任务，比如 MCP 工具服务器，它们跟主进程之间的协同一旦出问题，就容易出现这种局面。
你不需要理解每一层函数，先扫栈顶，再找重复出现的符号，然后对着日志看时间线，基本就能还原现场。
3.3 用 MCP 工具子进程把范围扩大
Claude Code 支持通过 MCP 协议接入外部工具服务器，常见的启动方式会用到npx。比如你在配置里写一个 mcpServers 项，Claude Code 就会拉一个本地子进程起来跑那个工具服务。
这些 MCP 子进程也是会卡住的。它们卡住的时候，Claude Code 的日志里会一直显示等待tool_result，但实际命令可能根本没执行完。
这时候 pstack 要用两次：一次抓 Claude Code 主进程，一次抓 MCP 子进程。先找所有相关进程：
pgrep -af "claude|mcp|npx"然后分别抓栈。如果有某个 MCP 工具的子进程一直停在一个业务函数里，那问题几乎可以定位到那个工具本身。用这种分层抓栈的方式，我在实际项目中排除过很多次“看起来是 Claude Code 卡死，其实是某个代码搜索工具慢”的情况。
3.4 把诊断流程收进一个函数
采样脚本解决了“抓”的问题，但每次都要敲那么一长串命令还是麻烦。所以我后来把它收成了 shell 函数，放进~/.bashrc里：
claude-stack() { pid=$(pgrep -f "@anthropic-ai/claude-code" | head -n 1) if [ -z "$pid" ]; then echo "Claude Code 没在运行" return 1 fi echo "=== pstack $pid ===" pstack "$pid" echo "=== 最近日志 ===" tail -n 5 ~/.claude/logs/claude*.jsonl 2>/dev/null | tail -n 5 }这样每次卡住了，新开一个终端敲claude-stack，就能同时拿到进程栈和最近日志。这个命令我从头用到现在，是 pstack-claude 整套流程里最顺手的一环。
4. 高频问题实录：安装、版本与权限的坑
4.1 Windows 下虚拟机平台报错怎么解
Windows 原生跑 Claude Code 的朋友肯定见过这条：Claude's workspace requires the Virtual Machine Platform on Windows。我第一次看到也愣了一下，后来才知道这是它要用到 Windows 的虚拟化能力来构造隔离工作区。
报错的根源基本是两个，一是虚拟机平台功能没有开启，二是 WSL 内核没更新或者没安装。
虚拟机平台功能的开启方式我在前面已经写过了，用 dism 命令。如果执行完还是报同样的错误，检查一下系统是否启用了 Hyper-V，部分旧版本 Windows 需要去“控制面板 - 程序和功能 - 启用或关闭 Windows 功能”里手动勾选“虚拟机平台”和“适用于 Linux 的 Windows 子系统”。开启后重启，再跑一次wsl --update，大概率就解决了。
我个人的建议是，如果只是日常写代码，直接装一个 WSL2 发行版，把项目放在 Linux 文件系统里跑，这个问题能避就避。Windows 和 Linux 文件系统的交互本身就是一把性能损耗刀，Claude Code 大量读写文件的时候，放在 WSL 里会明显顺滑一些。
4.2 自动更新失败：no write permission to npm prefix
Claude Code 默认会自动更新，更新失败时会报这类错误：
auto-update failed: no write permission to npm prefix这个错误的本质是：Claude Code 被安装到了系统级 npm 全局目录，通常是/usr/lib/node_modules，普通用户没有写权限。每次启动时它尝试检查自身版本、准备升级，一写就报权限错误。
最干净的解法是让 npm 的全局目录落在用户目录下，而不是系统目录。先看当前 npm prefix：
npm prefix -g如果返回的是/usr或者/usr/local，那就把它改到用户级目录：
npm config set prefix ~/.npm-global然后把~/.npm-global/bin加进环境变量：
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc source ~/.bashrc重新安装：
npm install -g @anthropic-ai/claude-code之后启动 Claude Code 就不会再遇到权限类自动更新问题了。这里有个教训：不要去chmod -R 777系统目录来绕过问题，往后版本越升越乱，用户级目录才是干净方向。
4.3 pstack 抓不到栈或者只有一行
pstack 偶尔会给你一个“空手而归”的结果。常见原因有三个：
- 目标进程不是你的子进程，且 ptrace_scope 限制了你，需要加 sudo；
- 进程已经退出了，或者 PID 被复用，导致 pstack 抓到一个跟 Claude Code 无关的进程；
- Claude Code 的某些子进程是内核线程或者已经进入不可中断睡眠，用户态栈为空。
如果 pstack 确实拿不到有效栈，我还有一个备用方案：
gdb -p <pid> -batch -ex "thread apply all bt"这条命令能拿到每个线程的完整 backtrace，信息量比 pstack 更大，只是速度慢一些。遇到特别诡异的问题时，我会用这个命令做交叉验证。
4.4 排查卡顿时的几条铁律
用 pstack-claude 排过几十次问题之后，我总结出三条特别重要的原则。
第一，先采样再重启。进程一杀掉，现场就没了，任何栈信息都不会留下。哪怕你觉得已经没救了，也先抓一次栈再决定下一步。
第二，多抓几次，别信一次快照。单次抓出来的可能只是正常状态，连续抓几次才能看出趋势。我的脚本默认抓十次，就是为了避免误判。
第三，时间戳对齐。pstack 输出的文件名带时间，日志里每条事件也有时间，把两者对齐才能重建完整的现场。很多问题，看到栈里卡在某个工具调用，再回到日志里看对应的工具执行时间，原因瞬间就清楚了。
5. 写在最后的一点私货
从构思到写完这套流程，我最大的感受是：开发工具再聪明，也终究是个进程，进程就一定会遇到卡死、阻塞、资源等待的问题。与其等到出了问题拍脑袋重启，不如提前准备一把趁手的“探针”，让它在你需要的时候给你答案。pstack-claude 并不是一个复杂的项目，它只是一个把 pstack、日志、定时采样这些基础能力组合起来的工作流。但正是这样的工作流，帮我把几十次“救不回来”的长时间任务救回来了。
我的习惯是把claude-stack函数放在所有长期任务的启动脚本旁边，每次 Claude Code 开始执行长时间重构任务前，我都会先开启日志跟踪，然后随时准备采样。现在如果再遇到它卡住，我不会急着按 Ctrl+C，而是先抓栈，再翻日志，基本都能说出个一二三来。
如果你也在被 Claude Code 的长任务卡顿困扰，可以从一个最简单的采样脚本开始，不用一开始就做得很重。关键是让数据替你说“它到底卡在哪”，而不是凭感觉盲猜。这套思路也不只适用于 Claude Code，所有 Node.js 后台服务卡顿，pstack 都是同样的用法。希望这篇文章能帮你在排查路上省下一点时间。
