企业官网建设流程全解析

1. pstack-claude 是什么？先说项目背景

pstack-claude 这个项目，最早是从一次 Claude Code 卡死开始的。当时我正在改一段还算复杂的脚本，Claude Code 跑着跑着就不输出内容了，终端光标在闪，电脑风扇却越转越快。我等了半分钟没反应，第一反应是崩溃了，最后直接在终端里敲了pgrep -af claude，然后把对应的进程树翻出来。那时候就产生了一个特别直接的想法：要是能像 Linux 下的 pstack 一样，随时看一眼 Claude 进程到底“卡在哪一行”，调试就会轻松很多。

pstack 这个命令，老运维应该很熟。它可以把一个正在运行的进程的调用栈打印出来，等同于快速抓取当前线程的执行位置。Claude Code 则是 Anthropic 推出的命令行编程助手，核心跑在 Node.js 上。表面看这两者没什么关系，但组合起来很有价值：Claude Code 的进程在复杂任务里会长时间驻留，一旦遇到死锁、等待子进程、更新脚本卡住，日志只会告诉你“刚才发生了什么”，不会告诉你“现在到底卡在哪个函数里”。pstack 正好补上这个缺口。

所以 pstack-claude 不是要替代 Claude Code，也不是要 hack Anthropic 的协议，而是一套围绕 Claude Code 的“现场快照型诊断工具”。它把四件事放在一起：环境自检、进程栈抓取、日志对照、模型服务切换。适合正在折腾 Claude Code、遇到了安装失败或运行卡死的人，尤其是 Windows 下用 WSL 跑 Claude Code 的这批用户。

1.1 为什么偏偏选了 pstack 而不是日志

先说结论：日志适合复盘，栈快照适合定位“现在”。

Claude Code 自身也提供调试模式，比如ANTHROPIC_LOG=debug、claude --verbose，日志文件会落在~/.claude/logs下。但日志量一多，找有效信息的时间成本很高。更麻烦的是，有些卡死发生在模型已经返回、终端输出却被子进程吞掉的场景里，日志末尾看起来一切正常，但用户端就是没有反应。这时候日志帮不上忙，只有去看进程栈，才知道线程停在读取管道、等待锁、还是在忙轮询。

pstack 的思路和体检一样，不看你过去得过什么病，而是测你此刻的心跳、血压和脑电波。带着这个想法，我给 Claude Code 的进程做了一套采样脚本，并把项目命名为 pstack-claude。名字里的 pstack 就是一种方法论的代号：先看现场，再翻历史。

1.2 pstack-claude 的组成模块

这个项目按使用场景分成三个模块：

• 环境模块：检测 WSL、Windows 虚拟机平台、Node/npm 安装状态，处理virtual machine platform not available、npm prefix权限这类安装或升级问题。
• 诊断模块：用 pstack 或 gdb 抓 Claude Code 进程的调用栈，支持连续多次采样，对比栈帧变化，判断是真死锁还是单纯等待。
• 接入模块：通过环境变量切换 Anthropic 兼容的模型服务，比如把 Claude Code 接到 DeepSeek 的 Anthropic 兼容端点，让工具链不被某一家的限制绑死。

模块之间互相独立。即使你不用模型切换，也能靠环境模块和诊断模块解决大部分运行问题。

2. Claude Code 环境准备与安装踩坑

2.1 Windows 下开启虚拟机平台和 WSL

在 Windows 上跑 Claude Code，最常用的方式是开 WSL，在 Ubuntu 里安装。但不少人第一次安装就撞上一行报错：Claude's workspace requires the virtual machine platform on Windows. Enable the Windows Hypervisor Platform。这个报错不是 Claude Code 的问题，而是 Windows 的虚拟化功能没有开。

你需要在“控制面板 - 程序 - 启用或关闭 Windows 功能”里勾选这几项：

• 虚拟机平台
• Windows 虚拟机监控程序平台
• 适用于 Linux 的 Windows 子系统

选完之后重启电脑。这里要重点提醒一句：如果你平时还用 VMware 或 VirtualBox 跑别的虚拟机，开启 Hypervisor Platform 之后可能会有性能或兼容性影响，需要在装 Claude Code 之前想好是否要长期开启。

重启后打开管理员 PowerShell，安装并确认 WSL：

wsl --install -d Ubuntu-22.04 wsl -l -v

wsl -l -v输出里能看到 Ubuntu 的版本号，如果显示 VERSION 2，说明 WSL2 正常。如果你之前装的 WSL1，需要手动转换：

wsl --set-version Ubuntu-22.04 2

Claude Code 的源码和运行模型都依赖 WSL2 提供的完整内核能力，WSL1 会导致不少诡异问题，比如文件监听失效、网络访问异常，这些症状很难通过日志判断。

2.2 使用 npm 安装 Claude Code

WSL 启动后，在 Ubuntu 里装 Node.js 和 npm。我建议先用 nvm 装 LTS 版本，避免系统包管理器给的 Node 版本太老：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install --lts node -v npm -v

然后安装 Claude Code：

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

安装完成后直接运行claude，走官方登录流程即可。如果你更习惯传密钥，也可以用ANTHROPIC_API_KEY环境变量直连，这样不需要浏览器登录流程。

2.3 自动更新报错 no write permission to npm prefix

这是真正高频出现的坑。Claude Code 内置自动更新，默认逻辑是把 npm 全局包替换成新版本。如果你的 npm 全局目录是/usr/local/lib/node_modules，而当前用户对/usr/local没有写权限，就会看到：

auto-update failed: no write permission to npm prefix

这个问题有两种修法。第一种，把 npm 全局目录改到用户目录下，然后重装 Claude Code：

npm config set prefix ~/.npm-global echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc source ~/.bashrc npm install -g @anthropic-ai/claude-code

第二种，保留系统级全局目录，直接把 node_modules 和命令目录的属主改成当前用户。但这对多用户环境不友好，所以我更推荐第一种。改完之后记得检查：

which claude npm prefix -g

如果which claude指向~/.npm-global/bin/claude，说明路径已经生效。之后再跑自动更新，基本不会再碰到权限报错。

2.4 VSCode 和 Trae 里使用 Claude Code

如果你习惯在 VSCode 里操作，可以直接安装 Claude Code 扩展，然后在扩展设置里绑定 WSL 环境中的 CLI 路径。重点是把扩展的 shell 环境配置成和你终端一致的 npm 全局路径，不然扩展里会出现“找不到 claude 命令”。

Trae 这类 IDE 的原理也一样。IDE 本身只是提供一个终端和上下文窗口，核心还是调用命令行里的 claude 程序。所以你在 IDE 里配 Claude 模型的时候，真正要做的是让 IDE 能读到同一个 Node、同一个 npm 全局安装路径、同一份~/.claude/settings.json。很多人在 Trae 里配不上，不是因为 IDE 不支持，而是环境变量没配对。

如果你要用 MCP，记得确认npx也在 PATH 里。Claude Code 的不少 MCP server 是以 npx 命令形式启动的，npx找不到会导致 MCP 连接失败，报错内容和权限无关，容易被误判。

3. 核心实现：pstack-claude 如何抓取进程栈

3.1 为什么需要循环采样

单次 pstack 只能看到一瞬的栈帧，很多卡死状态是“间歇性”的。比如进程每秒醒一次，然后又睡过去，你单次采样很可能刚好采到睡眠状态，看起来一切都正常，但实际任务就是推不下去。

所以 pstack-claude 的脚本做了一件很简单但很实用的变换：连续采样三次，每次隔三秒，然后把三次结果合并到一个日志文件里。如果三次的栈顶都停在同一处，说明进程大概率在一个长期阻塞或死循环里；如果三次栈各不相同，说明进程还在活动，只是暂时没有输出或等待网络，这种情况可能需要继续观察或查网络连接状态。

3.2 一份可直接落地的采样脚本

下面是我在 pstack-claude 里使用的简化版本，放在 Ubuntu/WSL 里可以直接跑：

#!/usr/bin/env bash set -uo pipefail LOG_DIR="${1:-/tmp/pstack-claude}" mkdir -p "$LOG_DIR" PIDS=$(pgrep -af "claude-code|@anthropic-ai" | awk '{print $1}') if [ -z "$PIDS" ]; then PIDS=$(pgrep -af "claude" | awk '{print $1}' | head -n 20) fi if [ -z "$PIDS" ]; then echo "no claude process found" exit 1 fi for i in 1 2 3; do LOG_FILE="$LOG_DIR/sample-$i-$(date +%H%M%S).log" echo "==== sample $i at $(date) ====" | tee -a "$LOG_FILE" for PID in $PIDS; do echo "---- PID $PID ----" | tee -a "$LOG_FILE" pstack "$PID" >> "$LOG_FILE" 2>&1 || \ gdb -p "$PID" -batch -ex "thread apply all bt" >> "$LOG_FILE" 2>&1 done sleep 3 done

这里的逻辑是：先用pgrep找 Claude Code 对应的 Node 进程，再逐一对进程执行pstack。如果系统没有 pstack，则自动退回到gdb -p PID -batch -ex "thread apply all bt"，效果类似，只是 gdb 输出的符号信息更粗糙一些。生成的日志在/tmp/pstack-claude/sample-*.log下，文件名带时间戳，方便对照某个时间点前后的行为。

3.3 栈输出到底怎么读

抓完栈之后，很多人会盯着十六进制地址发呆。实际不需要看懂全部，只需要抓住栈顶和栈底。

栈顶就是当前 CPU 正在执行的函数。栈底等于入口函数，通常保持不变。举例来说，如果栈顶停在epoll_wait、uv__io_poll、do_sys_poll这类位置，说明 Node 事件循环在等待 I/O 事件，这最多算“空闲”，不代表真卡死。真正的卡死通常有两个特征：栈顶长时间没有任何变化，并且 CPU 占用保持在高位；或者多个线程都停在某个锁函数上，比如futex_wait、pthread_cond_wait，那大概率是线程死锁。

我碰过一种情况，pstack 采样三次，栈顶始终停在process_buffer一类的自定义函数上，CPU 拉满但终端不输出。查了 Claude Code 日志，才发现是自动更新脚本和主进程在抢同一个临时目录锁。最后把自动更新权限问题解决掉，再重启 Claude Code，问题就消失了，这个案例也正是 pstack-claude 最有价值的场景。

需要注意的是，pstack对目标进程有短时间停顿影响。调试一个自己正在使用的工作进程没问题，但如果在生产服务器上抓别人的进程，最好先评估影响，不要随手狂采。

4. 让 Claude Code 对接 DeepSeek 等 Anthropic 兼容服务

4.1 换模型服务不意味着换工具

最近不少人在把 Claude Code 接到 DeepSeek 上。这里先澄清一个概念：Claude Code 本身只是一个客户端，它通过 Anthropic Messages API 协议和模型服务通信。只要服务端能够兼容这套协议，Claude Code 并不关心对面跑的是 Claude 大模型还是 DeepSeek。

DeepSeek 提供 Anthropic 兼容端点，所以你可以直接用环境变量切换。这比很多IDE里硬改插件配置要干净得多，而且对 pstack-claude 这类诊断工具来说，环境变量是透明的，进程栈、日志、采样逻辑都不需要改动。

4.2 切换 DeepSeek 的具体步骤

在 WSL 里执行：

export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic" export ANTHROPIC_AUTH_TOKEN="你的DeepSeek API Key" export ANTHROPIC_MODEL="deepseek-chat"

然后运行：

claude

如果你想在.claude/settings.json里固化这个配置，可以写到env字段：

{ "env": { "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic", "ANTHROPIC_AUTH_TOKEN": "你的DeepSeek API Key", "ANTHROPIC_MODEL": "deepseek-chat" } }

这里有两个容易出错的地方。第一个，变量名不是ANTHROPIC_API_KEY，而是ANTHROPIC_AUTH_TOKEN。兼容服务解析认证信息时读的是ANTHROPIC_AUTH_TOKEN，用错变量会一直报 401。第二个，模型名要把默认的 Claude 模型改成实际可用的deepseek-chat或你账号下对应的模型 ID，保留默认模型会导致 “model not found” 的报错。

4.3 用 pstack-claude 确认配置是否生效

切换完模型之后，怎么确认进程真的读到了新配置？可以在 Claude Code 运行的情况下，用 pstack-claude 的记录脚本顺带把进程环境变量翻出来：

PID=$(pgrep -f "claude-code" | head -n 1) tr '\0' '\n' < /proc/$PID/environ | grep -E "ANTHROPIC|DEEPSEEK"

如果输出里有ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic，说明配置已经生效。如果输出为空，说明环境变量没传到进程，可能在启动 Claude Code 之前就没写入，或 IDE 在启动时覆盖了环境。

这种方式特别适合排错，因为它能看到进程真正的运行环境，而不是你在终端里临时 setup 的“理想环境”。VSCode 扩展、Trae IDE、WSL 开机自启服务都会各自维护一套环境，你很难保证它们配置一致，用/proc检查是唯一可信的确认途径。

5. 常见问题排查速查表

5.1 高频报错与处理对照

这张表基本覆盖了 Claude Code 从安装到使用过程里最容易踩的位置。很多问题只靠看日志无法判断，真实原因是环境变量或文件权限。

5.2 几个排查心法

先说第一个，遇到卡死不要急着 kill。先采样，再复现，最后再处理。pstack-claude 的脚本三秒采样一次，日志文件会保留，后续复盘非常有价值。很多时候所谓卡死只是网络波动，进程内部在等待超时，多等 30 秒自己就恢复了。

第二个，Claude Code 的自动更新是很多问题的根因。如果你刚跑完claude就出现各种奇怪现象，先看进程中是不是多了一个“安装更新”的临时进程。检查方式很简单：

ps -ef | grep -i claude | grep -i install

有的话等它做完再继续操作。频繁切换模型服务和模型版本时，旧进程和新版本同时存在也会导致行为异常。

第三个，环境变量一定要通过/proc验证，而不是只信终端输出。尤其是用了 VSCode 和 Trae 之后，环境差异是看不见的。pstack-claude 里加一个env子命令，把所有相关进程的环境变量打出来，这是我在实际调试中习惯了很久、但收益最高的一个习惯。

我第一次跑通 pstack-claude 的完整流程，是在 Windows 11 上开 WSL2，装完 Claude Code，然后抓了一次某次卡死的进程栈。那次抓栈的输出让我意识到，所谓“Claude Code 傻了”，很多时候只是它在等待自动更新锁。现在我的做法很固定：先看版本，再看栈，最后看日志，三步下来基本不会再浪费时间乱猜。