1. 从 Spinner 说起那个转圈的小图标到底在告诉你什么用 Claude Code 的人大概率都经历过这种场景敲完一段提示词终端里那个小小的 Spinner 开始转你盯着它转了三秒、五秒、十秒然后它突然不动了。光标还在闪但 Spinner 像被冻住一样整个会话陷入一种薛定谔的响应状态——你不知道它是在思考还是已经挂了。这个 Spinner 不是装饰品。它是 Claude Code 与用户之间唯一的实时状态通道。理解它基本等于理解了 Claude Code 的运行节奏。1.1 Spinner 的本质一个状态机的可视化投影Claude Code 的 Spinner 本质上是一个状态指示器它对应的是 CLI 内部一个有限状态机。当你提交一条指令后程序会经历几个阶段请求组装、网络传输、模型推理、工具调用如果需要、结果流式返回、渲染输出。Spinner 的转动、暂停、闪烁、变色其实都在映射这些阶段中的某一个。我实测下来Spinner 至少有四种可辨识的状态Spinner 表现对应阶段正常持续时间异常信号匀速旋转等待模型响应1-15 秒超过 30 秒需警惕短暂停顿后继续流式 token 返回中断续出现停顿超过 5 秒异常停止但光标闪烁工具调用执行中视工具而定超过 60 秒大概率卡死完全静止无光标进程挂起或崩溃不应出现立即排查很多人误以为 Spinner 停了就是卡了其实不然。工具调用阶段 Spinner 本来就会停因为此时 Claude Code 正在执行你让它跑的终端命令、文件读写或者搜索操作。这时候它不转是正常的真正该看的是光标是否还在闪、终端是否还能响应 CtrlC。1.2 为什么这个小圈圈值得单独拿出来讲因为它是你排查问题的第一手信号源。Claude Code 不像图形界面软件那样有丰富的可视化反馈终端里能给你的信息就那么点。Spinner 的行为模式加上终端输出的日志行基本构成了全部的诊断依据。我踩过的一个坑早期用 Claude Code 的时候看到 Spinner 停了就习惯性 CtrlC 重来结果发现很多次其实是工具调用正在跑一个耗时的构建命令被我硬生生打断了。后来学乖了先看终端有没有输出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 第一步确认卡顿的具体表现不要笼统地说卡了要精确描述。我通常问自己几个问题Spinner 是完全不动还是转得很慢终端有没有任何新输出CtrlC 能不能正常中断是所有操作都卡还是特定操作卡之前正常吗什么时候开始卡的这几个问题的答案基本能把问题范围缩小一半。比如CtrlC 能中断说明进程还活着大概率是等待响应而非死锁只有特定操作卡说明可能跟该操作涉及的工具或文件有关。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 5Claude Code 自身排查# 查看版本确认不是旧版本的已知问题 claude --version # 用调试模式启动查看详细日志 claude --debug调试模式会输出大量内部日志包括请求组装时间、网络等待时间、工具调用耗时等。这些数据是定位瓶颈的关键。3.3 第三步针对性解决根据排查结果对症下药。我把常见问题和对应方案整理成了一张速查表卡顿表现可能原因解决方案Spinner 长时间匀速转网络延迟高或服务端慢检查网络换时段重试Spinner 停住但光标闪工具调用执行中等待或查看终端日志确认在跑什么输出到一半中断流式连接断开检查网络稳定性重试首次响应特别慢项目上下文过大配置 .claudeignore 排除无关目录所有操作都慢系统资源不足关闭其他占用资源的程序Windows 下额外卡顿终端环境兼容性切换到 WSL2特定文件操作卡文件过大或编码问题检查文件大小和格式3.4 第四步验证与回归解决问题后别急着继续干活先做一轮验证。我会跑几个标准操作读一个文件、执行一个简单命令、做一次小范围代码修改确认响应时间回到正常水平。如果问题复现说明根因没找对回到第二步重新排查。注意每次只改一个变量。同时改网络、改配置、改终端出了问题你根本不知道是哪个改动起的作用。4. 高频问题实录那些我踩过的坑和验证过的解法这一节是我个人使用 Claude Code 过程中积累的问题记录都是实际遇到并解决过的不是从文档里抄的。4.1 Spinner 卡住但实际在正常工作这是最常见的误判。Claude Code 在执行某些工具调用时Spinner 会停止转动但程序其实在正常运行。比如它正在执行一个npm install或者跑测试套件这些操作本身就要花时间Spinner 不转是设计如此。判断方法看终端有没有输出。如果终端在持续输出命令执行日志那就是正常的耐心等。如果终端完全没动静超过 30 秒才需要考虑干预。我个人的习惯是遇到 Spinner 停住先等 15 秒同时观察终端。15 秒内没有任何新输出再按 CtrlC 中断检查。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 变慢时先别急着排查先开一个新会话试试。有时候只是当前会话的上下文积累太多导致的新会话能立刻恢复流畅。这个判断只需要几秒钟但能帮你省下大量不必要的排查时间。如果新会话也慢那才是环境或网络的问题再按前面的流程排查也不迟。