Claude Code 卡顿排查指南：Spinner 状态与性能优化

1. 从 Spinner 说起：那个转圈的小图标到底在告诉你什么

用 Claude Code 的人，大概率都经历过这种场景：敲完一段提示词，终端里那个小小的 Spinner 开始转，你盯着它转了三秒、五秒、十秒，然后它突然不动了。光标还在闪，但 Spinner 像被冻住一样，整个会话陷入一种"薛定谔的响应"状态——你不知道它是在思考，还是已经挂了。

这个 Spinner 不是装饰品。它是 Claude Code 与用户之间唯一的实时状态通道。理解它，基本等于理解了 Claude Code 的运行节奏。

1.1 Spinner 的本质：一个状态机的可视化投影

Claude Code 的 Spinner 本质上是一个状态指示器，它对应的是 CLI 内部一个有限状态机。当你提交一条指令后，程序会经历几个阶段：请求组装、网络传输、模型推理、工具调用（如果需要）、结果流式返回、渲染输出。Spinner 的转动、暂停、闪烁、变色，其实都在映射这些阶段中的某一个。

我实测下来，Spinner 至少有四种可辨识的状态：

很多人误以为 Spinner 停了就是卡了，其实不然。工具调用阶段 Spinner 本来就会停，因为此时 Claude Code 正在执行你让它跑的终端命令、文件读写或者搜索操作。这时候它不转是正常的，真正该看的是光标是否还在闪、终端是否还能响应 Ctrl+C。

1.2 为什么这个"小圈圈"值得单独拿出来讲

因为它是你排查问题的第一手信号源。Claude Code 不像图形界面软件那样有丰富的可视化反馈，终端里能给你的信息就那么点。Spinner 的行为模式，加上终端输出的日志行，基本构成了全部的诊断依据。

我踩过的一个坑：早期用 Claude Code 的时候，看到 Spinner 停了就习惯性 Ctrl+C 重来，结果发现很多次其实是工具调用正在跑一个耗时的构建命令，被我硬生生打断了。后来学乖了，先看终端有没有输出Running command...之类的提示，再决定要不要干预。

提示：Spinner 停止不等于卡死。先观察 10 秒，看终端是否有新日志输出，再判断是否需要干预。

2. 卡顿根源拆解：从网络到本地环境的全链路分析

Claude Code 卡顿的原因五花八门，但归纳下来无非几个层面：网络链路、模型服务端、本地终端环境、项目上下文规模、以及配置问题。我按排查优先级从高到低排列，这也是我实际遇到问题时的检查顺序。

2.1 网络链路：最常见的"隐形杀手"

Claude Code 的核心工作模式是流式请求——它需要与模型服务端保持长连接，持续接收 token。这意味着它对网络稳定性的要求比普通 HTTP 请求高得多。一次普通的网页请求断了可以重试，但流式连接断了，整个会话就废了。

常见的网络层卡顿表现：

• Spinner 转了很久突然报连接超时
• 输出到一半突然中断，光标卡住
• 频繁出现重连提示

排查方法很直接，在另一个终端窗口跑一个持续性的连通性测试：

# 持续 ping 测试，观察丢包和延迟波动 ping -c 100 api.anthropic.com # 或者用 curl 测试实际响应时间 curl -o /dev/null -s -w "DNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTTFB: %{time_starttransfer}s\nTotal: %{time_total}s\n" https://api.anthropic.com

重点看TTFB（首字节时间）和延迟波动。如果 TTFB 超过 2 秒，或者 ping 的延迟忽高忽低（比如从 50ms 跳到 500ms），那卡顿基本就是网络问题。

我个人的经验是，晚高峰时段（20:00-23:00）的卡顿概率明显高于其他时段，这跟国际带宽的拥塞规律吻合。如果你发现特定时段特别卡，可以考虑调整使用时间，或者检查本地网络是否有其他大流量应用在抢占带宽。

2.2 模型服务端：你控制不了但需要理解的部分

有时候卡顿跟你的网络和本地环境都没关系，纯粹是服务端在高峰期响应慢。这种情况的特征是：

• 所有请求都变慢，不只是某一个
• 换个时间段就恢复正常
• 错误信息里出现 429（限流）或 529（过载）

遇到这种情况，除了等待没有太好的办法。但你可以做一件事：降低单次请求的复杂度。比如把一个大的重构任务拆成几个小任务分步执行，减少单次推理的 token 量，这样即使服务端慢，你的等待时间也可控。

2.3 本地终端环境：被忽视的重灾区

这一块是我见过最多人踩坑的地方。Claude Code 运行在终端里，终端的性能、配置、以及操作系统环境都会直接影响体验。

Windows 平台的特殊性值得单独说。Claude Code 在 Windows 上的原生支持一直是个话题，很多用户反馈在 Windows 下运行时有额外的卡顿。核心原因在于 Claude Code 的很多底层操作依赖 Unix 风格的终端行为，Windows 的终端模拟层（无论是 CMD、PowerShell 还是 Windows Terminal）在处理流式输出和 ANSI 转义序列时，性能表现和 Unix 终端有差异。

如果你在 Windows 上用 Claude Code，我强烈建议：

• 优先使用WSL2环境，而不是原生 Windows 终端
• 如果必须用原生环境，选择Windows Terminal而非 CMD
• 关闭终端里的透明效果、背景图片等视觉特效，这些会显著增加渲染负担

在 WSL2 里跑 Claude Code，体验和原生 Linux 基本一致，卡顿问题会少很多。这个切换成本很低，但收益很明显。

macOS 和 Linux 用户相对省心，但也有需要注意的点。比如 macOS 上如果用了 iTerm2，某些版本的 GPU 渲染设置可能导致滚动卡顿；Linux 上如果终端模拟器配置了复杂的提示符（比如带 git 状态、时间、电池信息的 powerline），每次输出刷新都要重绘这些内容，也会拖慢响应。

2.4 项目上下文规模：大项目的大麻烦

Claude Code 会读取你的项目文件来理解上下文。项目越大，需要处理的文件越多，初始加载和每次请求的上下文组装就越慢。

我做过一个对比测试：在一个只有十几个文件的小项目里，Claude Code 的响应几乎是即时的；但在一个包含上千个文件、node_modules 体积超过 500MB 的项目里，首次响应时间明显拉长，有时候 Spinner 要转十几秒才出第一个 token。

解决办法是精确控制上下文范围。Claude Code 支持通过配置文件或命令行参数指定关注的文件范围，把不相关的目录排除掉。比如：

# 在项目根目录创建 .claudeignore 文件 node_modules/ dist/ build/ *.log .git/

这个.claudeignore的作用类似于.gitignore，告诉 Claude Code 哪些目录不需要扫描。加上之后，大项目的响应速度会有肉眼可见的提升。

2.5 配置问题：那些"看起来没问题"的坑

配置层面的卡顿往往最隐蔽，因为程序不报错，就是慢。常见的配置问题包括：

• API 端点配置不当：如果你通过第三方中转服务使用 Claude Code，中转服务器的响应速度直接决定你的体验。有些中转服务本身负载高，或者做了额外的请求处理，会引入额外延迟。
• 模型选择：不同模型的推理速度差异很大。如果你选了参数规模大的模型处理简单任务，等待时间自然长。
• 并发设置：某些配置下 Claude Code 会尝试并发处理多个操作，如果本地资源不足，反而会互相拖累。

3. 实操排查流程：一套可复用的诊断方法论

上面讲了原理，这一节讲怎么动手。我把自己排查 Claude Code 卡顿的流程整理成了一套固定动作，基本上按顺序走一遍，90% 的问题都能定位。

3.1 第一步：确认卡顿的具体表现

不要笼统地说"卡了"，要精确描述。我通常问自己几个问题：

1. Spinner 是完全不动，还是转得很慢？
2. 终端有没有任何新输出？
3. Ctrl+C 能不能正常中断？
4. 是所有操作都卡，还是特定操作卡？
5. 之前正常吗？什么时候开始卡的？

这几个问题的答案基本能把问题范围缩小一半。比如"Ctrl+C 能中断"说明进程还活着，大概率是等待响应而非死锁；"只有特定操作卡"说明可能跟该操作涉及的工具或文件有关。

3.2 第二步：分层排查

按照从外到内的顺序排查：

网络层排查：

# 测试基础连通性 curl -I https://api.anthropic.com # 测试 DNS 解析速度 time nslookup api.anthropic.com # 检查是否有代理配置干扰 env | grep -i proxy

系统资源排查：

# 查看 CPU 和内存占用 top -o cpu # 查看网络连接状态 netstat -an | grep ESTABLISHED | wc -l # 检查磁盘 I/O（大项目文件读取可能成为瓶颈） iostat -x 1 5

Claude Code 自身排查：

# 查看版本，确认不是旧版本的已知问题 claude --version # 用调试模式启动，查看详细日志 claude --debug

调试模式会输出大量内部日志，包括请求组装时间、网络等待时间、工具调用耗时等。这些数据是定位瓶颈的关键。

3.3 第三步：针对性解决

根据排查结果对症下药。我把常见问题和对应方案整理成了一张速查表：

3.4 第四步：验证与回归

解决问题后，别急着继续干活，先做一轮验证。我会跑几个标准操作：读一个文件、执行一个简单命令、做一次小范围代码修改，确认响应时间回到正常水平。如果问题复现，说明根因没找对，回到第二步重新排查。

注意：每次只改一个变量。同时改网络、改配置、改终端，出了问题你根本不知道是哪个改动起的作用。

4. 高频问题实录：那些我踩过的坑和验证过的解法

这一节是我个人使用 Claude Code 过程中积累的问题记录，都是实际遇到并解决过的，不是从文档里抄的。

4.1 Spinner 卡住但实际在正常工作

这是最常见的误判。Claude Code 在执行某些工具调用时，Spinner 会停止转动，但程序其实在正常运行。比如它正在执行一个npm install或者跑测试套件，这些操作本身就要花时间，Spinner 不转是设计如此。

判断方法：看终端有没有输出。如果终端在持续输出命令执行日志，那就是正常的，耐心等。如果终端完全没动静超过 30 秒，才需要考虑干预。

我个人的习惯是，遇到 Spinner 停住，先等 15 秒，同时观察终端。15 秒内没有任何新输出，再按 Ctrl+C 中断检查。

4.2 大项目里首次响应极慢

前面提过.claudeignore的用法，这里补充一个细节：排除目录的顺序也有讲究。把体积最大的目录放在最前面，Claude Code 会优先跳过它们，扫描效率更高。

另外，如果你的项目里有大量二进制文件（图片、视频、编译产物），也一定要排除。Claude Code 尝试读取这些文件时会浪费大量时间，而且它们对代码理解没有任何帮助。

4.3 Windows 环境下的兼容性卡顿

Windows 用户遇到卡顿的概率确实更高，这跟 Claude Code 的设计取向有关。它最初是为 Unix 终端环境设计的，很多操作假设了 POSIX 行为。在 Windows 原生环境下，这些操作需要通过兼容层转换，性能损耗是客观存在的。

我的建议很明确：Windows 用户优先用 WSL2。安装 WSL2 的成本不高，但体验提升是质的。在 WSL2 里，Claude Code 跑起来和 Linux 原生基本没区别。

如果你因为某些原因必须用原生 Windows，那至少做到这几点：

• 用 Windows Terminal，别用 CMD
• 关闭所有终端视觉特效
• 把项目文件放在 SSD 上，别放机械硬盘
• 确保 Windows 系统本身没有其他性能问题

4.4 第三方 API 接入时的额外延迟

很多人会用第三方中转服务来接入 Claude Code，这时候卡顿的来源就多了一层。中转服务器本身的响应速度、它到模型服务端的链路质量、以及它是否做了额外的请求处理，都会影响你的体验。

排查这类问题时，可以先用 curl 直接测试中转端点的响应时间：

curl -o /dev/null -s -w "TTFB: %{time_starttransfer}s\nTotal: %{time_total}s\n" https://your-proxy-endpoint/v1/messages

如果 TTFB 明显高于直连，那问题就在中转服务上。这时候要么换服务，要么接受这个延迟。

4.5 终端渲染导致的"假卡顿"

有一种卡顿是视觉上的，程序本身响应正常，但终端渲染跟不上。典型表现是：输出内容很多时，终端滚动卡顿，看起来像程序卡了，实际上数据已经接收完了，只是终端在慢慢画。

这种情况在输出大量代码或长文本时特别明显。解决办法是减少终端的渲染负担：

• 关闭终端的平滑滚动
• 减少提示符的复杂度
• 如果终端支持，开启 GPU 加速渲染
• 限制滚动缓冲区大小

我用 iTerm2 的时候遇到过一次，输出长文件时卡得不行，后来发现是开了"无限滚动缓冲"，改成限制 10000 行之后流畅多了。

4.6 排查工具速查表

最后整理一份我常用的排查命令清单，遇到问题直接照着跑：

# 网络诊断 ping -c 20 api.anthropic.com curl -o /dev/null -s -w "TTFB: %{time_starttransfer}s\n" https://api.anthropic.com # 系统资源 top -o cpu -n 10 free -h df -h # Claude Code 调试 claude --version claude --debug # 项目上下文检查 du -sh */ | sort -rh | head -20 find . -type f -size +10M | head -20

这套流程走下来，基本没有定位不到的问题。关键是要有耐心，一层一层排除，别一上来就重装或者换工具。

5. 预防优于治疗：让 Claude Code 保持流畅的日常习惯

排查是事后补救，更好的做法是让它一开始就别卡。这一节分享几个我长期使用后养成的习惯，都是低成本但效果明显的。

5.1 项目结构的优化

Claude Code 的响应速度和项目结构的清晰度直接相关。一个组织良好的项目，Claude Code 能快速定位到相关文件；一个混乱的项目，它要花大量时间扫描和理解。

我建议在项目根目录维护一个清晰的.claudeignore，并且定期检查。每当你新增了构建产物目录、依赖目录、日志目录，就顺手加进去。这个习惯花不了几秒钟，但能省下大量等待时间。

另外，保持文件命名和目录结构的语义化。Claude Code 理解项目的方式和人类似，清晰的命名能帮助它更快找到需要的内容，减少无效扫描。

5.2 任务拆分与上下文管理

不要一次性给 Claude Code 一个巨大的任务。比如"重构整个项目的错误处理"这种指令，它会尝试读取大量文件、理解大量上下文，响应时间自然长。

更好的做法是拆分成小步骤：先让它分析现有错误处理模式，再针对具体模块逐个修改。每一步的上下文范围可控，响应速度也快。而且分步执行还有个额外好处：你可以在每一步检查结果，及时纠正方向，避免它一路跑偏。

5.3 环境维护

定期更新 Claude Code 到最新版本。新版本通常会修复已知的性能问题，优化响应速度。更新命令很简单：

# 如果通过 npm 安装 npm update -g @anthropic-ai/claude-code # 检查更新 claude --version

同时保持终端环境干净。关闭不用的终端标签页，退出不用的后台进程，这些都会释放资源给 Claude Code 使用。

5.4 建立自己的"正常基线"

这一点很多人忽略，但很重要。你需要知道在你的环境下，Claude Code 的"正常响应速度"是什么样的。比如读一个小文件通常 2 秒内返回，执行一个简单命令通常 5 秒内完成。

有了这个基线，一旦响应时间明显偏离，你就能立刻察觉并开始排查，而不是等到卡得完全没法用了才反应过来。我自己的基线是：简单问答 3 秒内，文件操作 5 秒内，复杂任务 30 秒内。超过这个范围，我就会开始留意是不是哪里出了问题。

这个基线因环境而异，你需要自己在实际使用中慢慢建立。但一旦建立起来，它就是你判断"是否卡顿"最可靠的依据。

5.5 关于模型选择的经验

如果你通过第三方服务接入多种模型，模型选择对响应速度的影响很大。参数规模大的模型推理慢但质量高，参数规模小的模型快但可能不够聪明。

我的策略是按任务复杂度选模型：简单的代码格式化、重命名、小修改，用快速模型；复杂的架构设计、疑难 bug 排查，用高质量模型。这样在保证效果的前提下，整体等待时间最短。

Claude Code 本身支持在会话中切换模型，你可以根据当前任务随时调整。这个灵活性用好了，体验会好很多。

6. 一些零散但有用的补充

写到这里，主体内容差不多了，再补充几个零散但实际有用的点。

关于日志：Claude Code 的日志文件通常存放在用户目录下的配置文件夹里。遇到难以复现的问题时，翻日志往往能找到线索。日志里会记录每次请求的时间戳、耗时、错误信息等，是排查的宝贵资料。

关于版本兼容：如果你在多个机器上使用 Claude Code，尽量保持版本一致。不同版本的行为可能有差异，混用容易产生困惑。

关于反馈：遇到疑似 bug 的卡顿，除了自己排查，也值得通过官方渠道反馈。你提供的信息（版本、环境、复现步骤、日志）越详细，问题被修复的可能性越大。

关于心态：Claude Code 是个还在快速迭代的工具，偶尔的卡顿和不稳定是正常的。与其每次遇到问题就烦躁，不如把它当成了解工具内部机制的机会。我很多关于 Claude Code 运行原理的理解，都是在排查卡顿的过程中积累的。

最后分享一个我个人的小技巧：当你感觉 Claude Code 变慢时，先别急着排查，先开一个新会话试试。有时候只是当前会话的上下文积累太多导致的，新会话能立刻恢复流畅。这个判断只需要几秒钟，但能帮你省下大量不必要的排查时间。如果新会话也慢，那才是环境或网络的问题，再按前面的流程排查也不迟。