1. 那个转圈的小图标到底在说什么用 Claude Code 写代码的人大概都经历过这种时刻终端里那个小小的 Spinner 转啊转一开始你还挺淡定觉得它在思考三十秒过去一分钟过去它还在转你开始怀疑是不是网络断了是不是模型挂了是不是自己命令敲错了。然后你按了 CtrlC重新来一遍结果还是一样。这种体验非常消耗耐心尤其是当你正处在思路顺畅、想快速验证一个想法的时候。Spinner 这个状态标识本质上就是 Claude Code 在告诉你我正在处理还没出结果。它出现的位置通常在终端界面的底部或者当前对话流的末尾表现形式可能是⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏这样的盲文点阵动画也可能是Thinking...配合一个旋转符号。很多人把它当成一个简单的加载中图标但实际上它背后对应的是 Claude Code 与模型服务之间的完整请求生命周期。理解这个生命周期是排查卡顿的第一步。这篇文章想解决的问题很具体当 Claude Code 的 Spinner 长时间不停转、界面看起来像卡死的时候你该怎么判断它到底是在正常工作还是真的出问题了以及不同原因导致的卡顿分别该怎么处理。适合已经装好 Claude Code、正在日常使用中遇到卡顿的开发者也适合刚接触 Claude Code、想提前了解常见故障模式的新手。我不会只给你一堆检查网络的废话而是把每个排查动作背后的原理讲清楚让你下次遇到类似情况能自己定位。2. Spinner 背后的请求生命周期2.1 从你按下回车到 Spinner 开始转当你在 Claude Code 里输入一段提示词并回车事情并不是直接发给模型然后等回复这么简单。中间至少经过这几个阶段本地 CLI 解析你的输入、组装上下文包括当前工作目录的文件信息、对话历史、系统提示词、通过 HTTPS 把请求发到模型服务端、服务端排队和推理、流式返回结果、本地渲染输出。Spinner 通常是在请求发出之后、第一个 token 返回之前开始转的也就是说它覆盖的是等待首个响应这段时间。这里有个关键点Claude Code 默认使用流式输出。理论上只要服务端开始返回内容Spinner 就应该停止或者变成内容逐字出现。所以如果你看到 Spinner 一直转、屏幕上迟迟没有任何文字冒出来说明问题出在首个 token 到达之前这个阶段。这个阶段的耗时受很多因素影响包括你的网络到服务端的链路质量、服务端当前的负载、你这次请求的上下文大小、以及你选择的模型。2.2 为什么上下文大小会直接影响等待时间很多人忽略了一点Claude Code 不是只把你这一句话发过去。它会把你当前项目的相关文件、之前的对话轮次、系统指令等一起打包。如果你在一个大型项目里工作或者对话已经进行了很多轮这个上下文可能非常庞大。上下文越大服务端需要处理的信息越多首个 token 的返回时间就越长。这不是 bug而是大语言模型推理的固有特性。我实测过一个对比在一个只有几个文件的小项目里简单提问的首 token 等待通常在 2 到 5 秒而在一个包含数百个文件、对话已经进行了二十多轮的项目里同样的提问可能要等 15 到 30 秒。这个差距是正常的Spinner 在这段时间里一直转也是正常的。问题在于很多人分不清正常的长等待和异常的卡死于是一看到转圈就慌。2.3 Spinner 卡住和界面卡死的区别这两个概念经常被混为一谈但处理方式完全不同。Spinner 卡住指的是动画还在转但迟迟没有输出这通常是网络或服务端的问题。界面卡死指的是整个终端失去响应你敲键盘没反应CtrlC 也按不动这通常是本地进程的问题比如内存占用过高、终端渲染阻塞、或者 Claude Code 进程本身陷入了某种死循环。判断方法很简单看 Spinner 动画是否还在动。如果动画在动说明主进程还活着只是在等外部响应如果动画也停了整个界面像冻住一样那就是本地问题。这个区分非常重要因为它决定了你是该去检查网络还是该去检查本地资源占用。3. 网络链路最容易被误判的卡顿源头3.1 为什么能上网不等于能顺畅访问模型服务这是我最想强调的一点。很多人的排查逻辑是我浏览器能打开网页所以网络没问题。但 Claude Code 访问模型服务和浏览器访问普通网页对网络的要求完全不是一个级别。普通网页请求小、超时宽容度高、有 CDN 缓存而模型服务请求需要建立长连接、传输大量上下文数据、对延迟和丢包非常敏感。我遇到过好几次这样的情况浏览器一切正常视频也能看但 Claude Code 就是转圈不出结果。后来用curl测试到服务端的连通性发现延迟高得离谱而且有明显的丢包。这种情况下Spinner 会一直转因为请求发出去了但响应回不来或者 TCP 连接反复重试。你可以用这个命令做一个基础测试curl -o /dev/null -s -w DNS解析: %{time_namelookup}s\n建立连接: %{time_connect}s\n首字节: %{time_starttransfer}s\n总耗时: %{time_total}s\n https://api.anthropic.com如果time_connect超过 1 秒或者time_starttransfer超过 3 秒说明链路质量有问题。注意这里只是测试到域名的连通性不代表模型服务的实际响应速度但能帮你排除掉明显的网络问题。3.2 代理配置的坑环境变量与 Claude Code 的读取顺序如果你处于需要使用代理的网络环境这里有个非常容易踩的坑。Claude Code 读取代理配置的顺序和很多工具不一样。它优先读取HTTPS_PROXY和HTTP_PROXY环境变量但如果你的终端会话里这些变量没有正确导出或者被其他工具的配置覆盖了Claude Code 就会走直连然后一直转圈。我建议在启动 Claude Code 之前先确认当前 shell 的代理变量echo $HTTPS_PROXY echo $HTTP_PROXY echo $NO_PROXY如果输出为空而你的网络环境确实需要代理那就需要先设置好。另外要注意NO_PROXY里不要包含模型服务的域名否则会强制走直连。这个细节很多人会忽略因为NO_PROXY通常是给内网地址用的但如果不小心把外部域名加进去了就会导致 Claude Code 无法正常访问。3.3 DNS 解析慢导致的假卡顿还有一种情况很隐蔽DNS 解析慢。每次 Claude Code 发起请求都需要先解析域名。如果你的 DNS 服务器响应慢或者配置了一个不稳定的 DNS那么每次请求都会在解析阶段卡住几秒。这种卡顿的特点是第一次请求特别慢后续请求可能快一些因为有缓存但缓存过期后又会变慢。排查方法是直接用 IP 测试绕过 DNS# 先解析出 IP nslookup api.anthropic.com # 然后用解析出的 IP 测试连通性 curl -o /dev/null -s -w 连接耗时: %{time_connect}s\n --resolve api.anthropic.com:443:解析出的IP https://api.anthropic.com如果直接用 IP 明显比用域名快那问题就在 DNS 上。解决办法是换一个响应更快的 DNS 服务器或者在本地 hosts 文件里做静态解析。4. 本地环境被忽视的卡顿放大器4.1 终端模拟器对渲染性能的影响这个点很少有人提但我实测下来影响很大。Claude Code 的输出是流式的意味着终端需要频繁地重绘界面。如果你用的终端模拟器渲染性能不好或者开启了某些特效比如透明背景、模糊、动画过渡那么在大量文本快速输出时终端本身就会成为瓶颈表现为界面卡顿、输入延迟。我在 Windows Terminal、iTerm2、以及某些基于 Electron 的终端里都做过对比。同样的 Claude Code 会话在轻量级终端里流畅得多在功能花哨的终端里明显更卡。如果你遇到的是输出内容时卡等待时不卡的情况大概率是终端渲染的问题。解决办法是关掉终端的透明和模糊效果降低字体渲染的复杂度或者换一个更轻量的终端。4.2 Node.js 版本与 Claude Code 的兼容性Claude Code 是基于 Node.js 运行的。Node.js 的版本会直接影响它的性能和稳定性。我遇到过用某个较老的 LTS 版本时Claude Code 频繁出现无响应的情况升级到较新的 LTS 版本后就正常了。这不是玄学而是因为不同 Node.js 版本在异步 I/O、内存管理、以及某些内置模块的实现上有差异。检查当前版本node --version npm --version如果你用的是比较老的版本比如 16.x 或更早建议升级到当前的 LTS 版本。升级后记得重新全局安装 Claude Code确保依赖关系正确。另外如果你同时装了多个 Node.js 版本比如通过 nvm 管理要确认 Claude Code 用的是你期望的那个版本。4.3 内存与 CPU 占用的实时观察当 Spinner 卡住时第一件事应该是打开另一个终端窗口观察系统资源占用。在 macOS 或 Linux 上top -o cpu # 或者 htop在 Windows 上可以用任务管理器或者tasklist | findstr node重点看 Claude Code 对应的 Node 进程占用了多少 CPU 和内存。如果 CPU 持续接近 100%说明它在做大量计算可能是上下文处理或者某个插件在跑如果内存占用持续增长可能存在内存泄漏。这两种情况都会导致界面响应变慢Spinner 看起来像卡住了。我的经验是正常情况下 Claude Code 的 Node 进程 CPU 占用应该在个位数到百分之二三十之间波动内存占用通常在几百 MB。如果远超这个范围就需要进一步排查。5. 配置层面的隐形陷阱5.1 模型选择与响应速度的关系Claude Code 支持切换不同的模型。不同模型的推理速度差异很大。如果你选择了能力更强但速度更慢的模型Spinner 转的时间自然会更长。这不是故障而是权衡。很多人抱怨卡顿其实只是用了一个本身就更慢的模型。你需要根据自己的实际需求选择如果是快速迭代、频繁提问的场景选响应更快的模型如果是复杂推理、需要高质量输出的场景接受更长的等待时间。关键是要知道自己在等什么而不是盲目地以为所有等待都是异常。5.2 上下文窗口设置过大的代价Claude Code 允许配置上下文窗口的大小。有些人为了让模型看到更多信息把上下文窗口设得很大。但上下文窗口越大每次请求需要处理的数据越多首 token 等待时间越长而且更容易触发服务端的限流。这是一个典型的贪多嚼不烂的配置陷阱。我的建议是根据项目实际规模设置。对于中小型项目没必要开满。如果你发现每次提问都要等很久可以先检查一下上下文配置适当调小观察是否有改善。5.3 插件与扩展的干扰Claude Code 支持通过 MCPModel Context Protocol等方式接入各种扩展。这些扩展在提供便利的同时也可能成为卡顿的来源。比如某个扩展在每次请求前都要去读取大量文件、调用外部服务、或者执行耗时的初始化逻辑那么每次交互都会变慢。排查方法是临时禁用所有扩展看卡顿是否消失。如果消失了再逐个启用定位到具体的扩展。这个二分排查法虽然笨但非常有效。我遇到过好几次卡顿最终都定位到某个扩展的初始化逻辑上禁用后立刻恢复正常。6. 一套可复现的排查流程6.1 第一步确认 Spinner 是否还在动这是所有排查的起点。如果 Spinner 动画还在转进入网络和服务端排查如果完全不动进入本地进程排查。不要跳过这一步因为它能帮你省掉大量无用功。6.2 第二步用最小请求测试连通性打开一个新的终端窗口用最简单的请求测试。如果 Claude Code 支持命令行直接提问就用最短的提示词试一次。如果最小请求也卡说明是链路或服务端问题如果最小请求正常说明是上下文或配置问题。6.3 第三步分层排查网络按照 DNS、TCP 连接、TLS 握手、首字节响应这几个层次逐一测试。前面给的curl命令可以覆盖大部分场景。重点看哪一层的耗时异常然后针对性处理。6.4 第四步检查本地资源与配置确认 Node.js 版本、内存占用、CPU 占用、终端渲染设置、上下文窗口配置、扩展启用情况。这一步的目的是排除本地因素把问题范围缩小到网络或服务端。6.5 第五步查看日志定位具体错误Claude Code 通常会在本地留下日志文件。日志的位置因平台而异一般在用户目录下的配置文件夹里。查看日志中是否有超时、连接重置、认证失败等错误信息。这些信息比 Spinner 本身有用得多能直接告诉你问题出在哪。# macOS/Linux 常见日志位置 ls ~/.claude/logs/ # 查看最新日志 tail -f ~/.claude/logs/latest.log7. 那些我踩过的坑和对应的解法7.1 坑一以为卡住了就狂按 CtrlC这是最常见的错误操作。Spinner 转的时候请求可能已经发出去了服务端可能正在处理。你按 CtrlC 中断然后重新发一次结果就是服务端要处理两个请求反而更慢。更糟的是频繁中断可能导致会话状态混乱后续请求更容易出问题。正确做法是给足等待时间。我的经验是如果上下文不大等待超过 60 秒没有任何输出才考虑中断。如果上下文很大等待 2 到 3 分钟也是正常的。耐心在这个场景下是一种技术能力。7.2 坑二忽略终端本身的性能问题前面提过但值得再强调。我曾经花了半天时间排查网络最后发现是终端模拟器的渲染设置问题。关掉透明效果后卡顿立刻消失。这个教训是排查要从最近改动过的地方开始。如果你刚换了终端、刚改了主题、刚装了新字体先怀疑这些。7.3 坑三在大型项目根目录直接启动Claude Code 启动时会扫描当前工作目录。如果你在包含成千上万个文件的目录比如整个用户目录、或者包含 node_modules 的项目根目录启动扫描过程本身就会很慢而且后续每次请求的上下文组装也会变慢。建议在具体的项目子目录里启动并且确保.claudeignore或类似配置排除了不需要的目录。7.4 坑四网络切换后没有重启 Claude Code如果你从 Wi-Fi 切换到有线或者从公司网络切换到家庭网络Claude Code 可能还保持着旧的连接状态。这时候 Spinner 会一直转因为它在等一个已经失效的连接。解决办法是退出 Claude Code 重新启动让它建立新的连接。这个坑很隐蔽因为网络本身是好的只是 Claude Code 不知道。8. 让 Spinner 少转几圈的日常习惯与其等卡顿了再排查不如在日常使用中养成一些习惯从源头减少卡顿的发生。这些习惯都是我长期使用后总结出来的成本很低但效果明显。第一保持 Claude Code 和 Node.js 都是较新的稳定版本。新版本通常修复了已知的性能问题和连接问题。第二控制单次对话的轮次。对话太长时主动开新会话避免上下文无限膨胀。第三定期清理不需要的扩展和配置减少每次请求的额外开销。第四在项目目录里维护好忽略规则把node_modules、构建产物、日志目录等排除在外。第五遇到卡顿时先观察再操作不要条件反射地中断和重试。还有一个很实用的小技巧如果你经常需要处理大上下文可以在提问前先用简洁的语言概括需求而不是把一大堆文件路径和代码片段直接丢进去。模型需要处理的信息越精炼响应越快。这既是使用技巧也是减少卡顿的有效手段。最后说一个我自己的体会。Claude Code 的 Spinner 卡顿绝大多数情况下不是工具本身坏了而是网络、配置、或者使用方式的问题。把它当成一个需要理解的系统而不是一个黑盒排查起来就会有条理得多。我现在的习惯是每次遇到卡顿先花十秒钟判断 Spinner 是否在动然后决定往哪个方向查。这个简单的判断帮我省下了大量瞎折腾的时间。