1. 从一次真实的卡顿说起Spinner 到底在转什么用 Claude Code 写代码的人大概率都遇到过这种场景敲完回车终端里那个小小的 Spinner 开始转转了两秒停了你以为它要出结果结果它又转起来再停再转。有时候转着转着就彻底不动了光标还在闪但屏幕上什么新内容都不再出现。你盯着那个转圈符号心里只有一个念头——它到底是在干活还是已经死了这个问题我踩过太多次从最初以为是自己网络的问题到后来怀疑是模型服务的问题再到最后发现根因五花八门有配置层面的、有上下文层面的、有本地环境层面的甚至还有纯粹因为项目太大导致索引卡死的。所以这篇内容我打算把 Claude Code 的 Spinner 状态标识、卡顿的常见根源、以及一套可复用的排查方案完整讲清楚。先说清楚这篇内容适合谁看。如果你刚开始用 Claude Code还在摸索阶段那这篇能帮你建立一套“看到卡顿不慌”的判断框架如果你已经用了一段时间遇到过各种莫名其妙的卡死那这篇里的排查清单和参数调整思路应该能直接抄作业如果你是在团队里负责给其他人配置开发环境的那这篇可以当作一份排障手册来用。Spinner 这个转圈符号本质上是一个状态指示器它代表 Claude Code 正在等待某个异步操作的返回。这个异步操作可能是模型推理、可能是工具调用比如读写文件、执行命令、可能是网络请求、也可能是本地索引扫描。关键在于Spinner 转和不转、转多久、转完之后出什么这三个信息组合起来其实能反推出当前卡在了哪个环节。很多人只看到“它在转”但没有区分“它在转但没输出”和“它停了但没输出”这两种完全不同的状态这两种状态对应的根因和排查方向是截然不同的。我个人的经验是Claude Code 的卡顿大致可以分成四类等待类卡顿Spinner 持续转说明在等某个操作返回、阻塞类卡顿Spinner 停了但没输出说明主线程被占住了、循环类卡顿Spinner 反复启停说明在反复尝试某个失败的操作、假死类卡顿Spinner 完全不出现说明进程可能已经挂了或者界面渲染出了问题。这四类的排查路径完全不一样后面我会逐一拆解。2. 拆解 Spinner 的状态语义转、停、闪分别意味着什么2.1 Spinner 的三种基本状态与对应含义Claude Code 的 Spinner 不是简单的“转就是忙不转就是闲”。在实际使用中我观察到它至少有三种可区分的行为模式每种模式背后对应不同的执行阶段。第一种是匀速持续旋转。这是最正常的状态说明 Claude Code 正在等待一个预期内的异步操作返回比如模型正在生成 token、正在读取一个大文件、正在执行一条命令。这种情况下你只需要等通常几秒到几十秒内会有结果。如果超过两分钟还在匀速转那就要开始怀疑是不是卡在某个超时逻辑上了。第二种是旋转但伴随间歇性停顿。这种模式我遇到得最多表现为转一下、停半秒、再转一下。这通常说明 Claude Code 在等待多个串行的操作每完成一个操作就短暂停顿一下然后发起下一个。比如它先读文件 A读完停顿再读文件 B再停顿。这种模式本身是正常的但如果停顿越来越长或者停顿之后不再继续转那就说明某个中间环节卡住了。第三种是旋转突然停止且无输出。这是最让人焦虑的状态。Spinner 停了但屏幕上没有新内容光标还在闪。这种情况通常意味着主进程遇到了未捕获的异常、或者某个同步操作阻塞了事件循环、或者界面渲染线程和逻辑线程之间出现了死锁。这时候你等再久也没用必须主动干预。提示区分“转但没输出”和“停且没输出”是排查的第一步。前者大概率是等待问题后者大概率是阻塞或崩溃问题。很多人把这两种混为一谈导致排查方向完全跑偏。2.2 为什么 Spinner 的状态语义容易被误读这里有一个设计层面的原因。Claude Code 作为一个终端交互工具它的界面刷新和逻辑执行是在同一个进程里协调的。当逻辑线程被一个耗时操作占住时界面线程可能来不及刷新 Spinner 的状态导致你看到的“停”其实只是界面没刷新逻辑还在跑。反过来当界面线程正常刷新但逻辑线程在等待网络返回时你看到的“转”其实只是在等一个可能永远不会来的响应。我实测下来的经验是不要只依赖 Spinner 的视觉状态来判断要结合终端的行为一起看。比如你可以试着在卡住的时候按一下回车或者输入一个字符如果终端有反应比如光标移动、字符回显说明界面线程还活着问题在逻辑层如果终端完全没反应连字符都打不进去那说明整个进程可能已经挂死了。还有一个容易被忽略的点不同终端模拟器对 Spinner 的渲染行为不一样。我在某些终端里看到 Spinner 转得很流畅换一个终端就变成一顿一顿的。这本身不是 Claude Code 的问题而是终端渲染性能的差异。所以如果你怀疑是卡顿先确认一下是不是只有你的终端有这个问题换个终端试试能排除掉一大类误判。2.3 Spinner 背后的执行流水线要真正理解 Spinner 在等什么得知道 Claude Code 一次交互背后的完整流水线。大致是这样的你输入指令后Claude Code 先做本地预处理解析指令、组装上下文、读取相关文件然后把请求发出去等模型返回模型返回后如果有工具调用需求它会在本地执行工具读写文件、跑命令执行完再把结果发回去继续等模型如此循环直到任务完成。Spinner 在这条流水线的每个等待点都会出现。所以当你看到 Spinner 在转时它可能在等模型也可能在等本地文件读取也可能在等命令执行。不同的等待点超时行为和卡顿表现完全不同。模型等待通常有网络超时本地文件读取通常很快但如果文件巨大也会卡命令执行则完全取决于你跑的是什么命令。这就解释了一个常见现象同样是 Spinner 转很久有时候等一等就出来了有时候等再久也没用。因为前者是模型在生成一个长回复后者可能是某个命令卡住了永远不会返回。区分方法很简单如果是模型等待通常会有 token 逐步输出的迹象哪怕很慢如果是命令执行卡住屏幕上通常完全静默。3. 卡顿根源全解析从配置到环境到上下文的六层排查3.1 第一层网络与模型服务连通性这是最容易被怀疑但也最容易被误判的一层。很多人一看到卡顿就认为是网络问题但实际上 Claude Code 的网络等待通常有明确的超时机制不会无限期卡住。如果你遇到的是“转了很久最后报超时错误”那确实是网络问题但如果是“转了很久最后什么也没发生”那大概率不是网络。网络层面的卡顿通常表现为Spinner 持续转转到一个固定的时间点比如 30 秒或 60 秒后报错或者自动重试。如果你观察到的是这种规律性的行为那可以往网络方向排查。排查方法也很直接看终端有没有输出重试相关的提示看错误信息里有没有连接超时、DNS 解析失败之类的关键词。但这里有个坑有些网络问题不会报错而是表现为响应极慢。比如请求发出去了服务端也收到了但返回的数据包在链路上丢了导致客户端一直在等。这种情况 Spinner 会一直转直到触发超时。如果你怀疑是这种可以试着换一个网络环境对比一下或者用简单的连通性测试工具确认一下到服务端的延迟是否正常。注意不要一遇到卡顿就去改网络配置。我见过太多人把本地环境问题误判成网络问题结果折腾半天网络配置真正的问题在别处。先用“是否有超时错误”这个标准做一次快速分流。3.2 第二层本地项目规模与文件索引这一层是我在实际使用中遇到最多的卡顿根源也是最容易被忽略的。Claude Code 在工作时会读取项目文件来组装上下文如果你的项目目录里有大量文件比如 node_modules、.git、构建产物目录它可能会在扫描和索引阶段花费大量时间。我做过一个实测在一个包含约 8 万个文件的前端项目里Claude Code 启动后的首次交互明显比在小型项目里慢Spinner 在“读取项目结构”阶段会转很久。后来我把不需要的目录加到忽略列表里首次交互的等待时间从接近一分钟降到了几秒。这个差异非常明显。所以如果你在一个大型项目里频繁遇到卡顿第一件该做的事就是检查项目里有没有应该被忽略的目录。常见的需要忽略的包括依赖目录、构建输出目录、版本控制内部目录、缓存目录、日志目录。这些目录里的文件对代码理解没有帮助但会严重拖慢索引速度。具体怎么配置忽略不同版本的 Claude Code 可能略有差异但核心思路是一样的找到配置文件通常是项目根目录下的配置文件或者用户级配置文件在里面指定要排除的路径模式。我一般会按目录名做模式匹配比如把依赖目录名、构建输出目录名都加进去。配置完之后重启 Claude Code 让配置生效然后再观察 Spinner 的行为有没有改善。3.3 第三层上下文窗口与对话历史Claude Code 的上下文窗口是有限的当对话历史积累到一定程度或者单次请求携带的上下文过大时处理速度会明显下降。这不是 Claude Code 独有的问题所有基于大上下文窗口的工具都有这个特性。表现是什么呢通常是对话进行到中后段时Spinner 转的时间越来越长。刚开始几轮对话响应很快聊到十几轮之后每次响应都要等很久。如果你观察到的是这种“越聊越慢”的模式那基本可以确定是上下文膨胀导致的。应对方法有几个。一是定期开启新会话不要把无关的任务堆在同一个会话里。二是如果某个任务确实需要很长的上下文可以考虑把关键信息整理成文档让 Claude Code 去读文档而不是靠对话历史来携带。三是检查一下有没有不必要的文件被反复读取有时候一次误操作让 Claude Code 读了一个巨大的文件之后每次请求都会带上这个文件的内容导致上下文迅速膨胀。我个人的习惯是每完成一个独立的任务就开一个新会话。虽然这样会丢失一些对话连续性但换来的响应速度提升是值得的。而且新会话里 Claude Code 的注意力更集中输出质量往往也更好。3.4 第四层工具调用与命令执行Claude Code 在执行任务时会调用各种工具比如读写文件、执行 shell 命令、搜索代码。如果某个工具调用卡住了Spinner 就会一直转。这一层的卡顿特点是Spinner 转但屏幕上没有任何工具调用的输出。最常见的卡住场景是执行了一个交互式命令。比如某个命令需要用户输入确认但 Claude Code 在执行时没有正确处理这个交互导致命令一直在等输入而 Claude Code 在等命令返回形成死锁。另一个常见场景是执行了一个耗时极长的命令比如全量构建、大规模测试这些命令本身就要跑很久Spinner 转着是正常的但如果你不知道它在跑什么就会误以为是卡住了。排查这一层的关键是看 Claude Code 有没有输出它正在执行什么命令。正常情况下它在调用工具前会显示要执行的操作。如果你看到它显示了某个命令之后就卡住了那问题大概率就在这个命令上。这时候你可以手动在另一个终端里跑一下同样的命令看看是不是命令本身的问题。提示如果你发现 Claude Code 经常卡在某个特定命令上可以在项目配置里把这类命令加入排除列表或者改成非交互式的执行方式。比如给命令加上自动确认的参数避免它等待输入。3.5 第五层本地资源占用与进程状态有时候卡顿跟 Claude Code 本身无关而是本地机器资源不够了。CPU 跑满、内存吃紧、磁盘 I/O 饱和这些都会导致 Claude Code 的响应变慢。表现是 Spinner 转得很卡顿不流畅同时机器上其他操作也变慢。这一层的排查很直接卡住的时候打开系统监控工具看 CPU、内存、磁盘的占用情况。如果发现某个进程吃满了资源那先解决那个进程的问题。我遇到过几次是后台在跑大型构建任务同时用 Claude Code结果两边都慢。把构建任务停掉之后Claude Code 立刻恢复正常。还有一个容易被忽略的点是磁盘空间。如果磁盘快满了文件读写会变得极慢Claude Code 读写项目文件时就会卡。这个用系统自带的磁盘检查工具就能看出来清理一下空间通常能明显改善。3.6 第六层版本兼容与安装问题最后一层是安装和版本相关的问题。Claude Code 在不同操作系统、不同终端环境下的表现可能有差异。如果你是在 Windows 上通过某种兼容层运行或者在比较老的系统版本上安装可能会遇到一些兼容性导致的卡顿。这一层的典型表现是卡顿没有规律有时候正常有时候卡而且换一个项目、换一个会话也一样卡。如果你排除了前面五层的原因那就要考虑是不是安装本身有问题。可以试着重新安装最新版本或者换一个安装方式对比一下。另外如果你是通过某种插件形式在编辑器里使用 Claude Code那编辑器的性能也会影响体验。编辑器本身卡的话Claude Code 的界面响应也会跟着卡。这种情况下可以试着在独立的终端里运行 Claude Code对比一下是否还有卡顿以此判断问题出在编辑器还是 Claude Code 本身。4. 一套可复用的排查流程从观察到定位到解决4.1 排查前的准备工作在开始排查之前先做两件事。第一件是确认问题可复现。偶发的卡顿和必现的卡顿排查难度完全不同。如果一个问题只出现了一次那可能只是临时的网络波动或资源争抢不一定值得深挖。但如果一个问题反复出现那就值得花时间定位。第二件是记录现场信息。卡住的时候记下几个关键信息Spinner 是在转还是停了、卡了多久、卡之前最后一条输出是什么、当时机器资源占用如何、用的是哪个终端、项目大概多大。这些信息看起来琐碎但能极大加速定位过程。我一般会直接截个图或者复制一下终端内容方便后续对比。4.2 快速分流三个问题定位大类面对一个卡顿问题我通常先问三个问题来快速分流。第一个问题Spinner 还在转吗如果在转说明进程还活着问题在等待环节如果停了说明进程可能阻塞或崩溃了问题在逻辑或渲染环节。第二个问题卡之前最后一条输出是什么如果是“正在读取文件”之类的那问题在文件操作如果是“正在执行命令”那问题在命令执行如果是“正在生成回复”那问题在模型等待。最后一条输出基本就指明了卡住的环节。第三个问题换个项目或换个会话还卡吗如果换一个小的、干净的项目也卡那问题在环境或安装层面如果只有特定项目卡那问题在项目配置或上下文层面。这一步能快速区分是普遍性问题还是特定场景问题。这三个问题问完基本就能把问题归到前面六层里的某一层或某两层然后针对性地深入排查。4.3 逐层验证与解决对照表下面这张表是我自己整理的一个速查对照把常见现象、可能根因和解决方向对应起来方便快速查阅。现象可能根因排查方向解决思路Spinner 匀速转很久后报超时网络或服务端响应慢检查网络连通性和延迟切换网络环境或稍后重试Spinner 转很久但无任何输出大文件读取或命令执行卡住看最后一条输出指向哪个操作忽略大目录或改用非交互命令越聊越慢新会话正常上下文膨胀检查对话轮数和上下文大小开新会话或精简上下文Spinner 转但界面卡顿不流畅本地资源不足查看 CPU、内存、磁盘占用释放资源或关闭其他重任务Spinner 突然停止且无输出进程阻塞或崩溃尝试输入字符看终端是否有反应强制退出重启检查日志特定项目必卡其他项目正常项目配置或目录结构问题检查项目规模和忽略配置配置忽略目录精简项目换终端后卡顿消失终端渲染性能问题对比不同终端的表现换用性能更好的终端这张表不是万能的但能覆盖大部分常见情况。实际排查时往往是多个因素叠加比如项目大加上资源紧张两个因素一起导致卡顿。所以排查时要有耐心一层一层排除。4.4 几个我踩过的坑和对应的经验第一个坑是把界面卡顿当成逻辑卡顿。有一次我看到 Spinner 不转了以为进程挂了直接强制退出。后来才发现只是终端渲染没跟上逻辑其实还在跑再等几秒就出结果了。从那以后我养成了一个习惯Spinner 停了之后先等十秒同时试着输入一个字符看终端有没有反应确认真的死了再强制退出。第二个坑是忽略了项目里的巨型文件。有一次我在一个项目里频繁卡顿排查了半天网络和配置都没问题。后来发现项目里有一个几百兆的日志文件Claude Code 在扫描项目时读了这个文件导致每次请求都极慢。把日志文件加到忽略列表后问题立刻解决。这个教训是排查卡顿时一定要看一眼项目里有没有异常大的文件。第三个坑是在资源紧张时强行使用。有一次我一边跑着大型构建任务一边用 Claude Code 改代码结果两边都卡得不行。我以为是 Claude Code 的问题折腾了很久。后来构建跑完了Claude Code 立刻恢复正常。这个教训是卡顿时先看一眼机器资源别急着怀疑工具本身。第四个坑是配置文件改了没生效。Claude Code 的某些配置需要重启才生效我有几次改完配置直接测试发现没变化以为配置写错了。后来养成习惯改完配置先重启再测试避免这种低级误判。5. 进阶优化让 Claude Code 在大型项目里也保持流畅5.1 项目结构的预处理如果你经常在大型项目里用 Claude Code那花点时间做项目结构的预处理是值得的。核心思路是让 Claude Code 只看到它需要看到的文件。具体做法包括把依赖目录、构建产物、缓存、日志这些对代码理解无帮助的目录统一放到忽略配置里把大的二进制文件、数据文件、生成的代码文件也排除掉如果项目是 monorepo 结构可以考虑只让 Claude Code 关注当前正在开发的子包而不是整个仓库。我实测下来一个配置良好的忽略列表能让大型项目里的首次响应时间从几十秒降到几秒。这个投入产出比非常高值得每个重度用户花半小时配置一次。5.2 会话管理与上下文控制会话管理是另一个能显著改善体验的点。我的做法是按任务划分会话一个独立任务一个会话任务完成就关掉。不在一个会话里连续做多个不相关的任务因为那样会让上下文里堆积大量无关信息既拖慢速度又影响输出质量。如果某个任务确实需要参考之前的对话我会把关键结论整理成一段简短的说明在新会话里贴进去而不是直接延续旧会话。这样既保留了必要信息又避免了上下文膨胀。另外如果发现某个会话响应明显变慢不要犹豫直接开新会话把当前进展用几句话总结一下带过去通常比继续在旧会话里挣扎要快得多。5.3 工具调用策略的调整对于工具调用导致的卡顿可以通过调整策略来规避。比如把可能交互式等待的命令改成非交互式执行把耗时极长的命令拆分成小步骤把不必要的文件读取操作去掉。如果你发现 Claude Code 经常读一些不需要的文件可以在指令里明确告诉它只关注哪些文件或目录减少它的探索范围。还有一个技巧是对于需要反复执行的命令可以提前在项目里配置好快捷方式或脚本让 Claude Code 直接调用脚本而不是从头拼命令。这样既减少了出错概率也避免了因为命令拼写问题导致的意外等待。5.4 环境层面的长期优化环境层面的优化主要是保证机器有足够的资源余量。具体来说确保内存充足不要同时跑太多重任务确保磁盘有足够空间定期清理临时文件和缓存如果条件允许把项目放在读写速度更快的磁盘上。这些看起来是常识但实际中很多人是在资源已经吃紧的情况下还在用 Claude Code然后抱怨卡顿。另外保持 Claude Code 和终端软件都是较新的版本也很重要。新版本通常会修复一些性能问题和兼容性问题我遇到过几次卡顿在升级版本后就消失了。所以如果你遇到莫名其妙的卡顿不妨先检查一下有没有新版本可用。6. 几个高频问题的直接回答6.1 Spinner 转很久到底该不该等这个问题没有统一答案取决于它在等什么。我的判断标准是如果最后一条输出显示它在生成回复那可以等因为模型生成长回复确实需要时间如果最后一条输出显示它在执行命令或读取文件那等超过三十秒就要警惕了大概率是卡住了如果屏幕上完全没有任何输出Spinner 凭空在转那等超过一分钟就不要再等了直接干预。6.2 强制退出会不会丢失工作Claude Code 的对话历史通常是持久化的强制退出再重新进入之前的对话一般还在。但正在执行中的操作会中断如果它正在写文件可能会留下不完整的文件。所以强制退出前如果可能的话先看一下它正在操作哪些文件退出后检查一下这些文件有没有被写坏。我个人的习惯是强制退出后先看一眼 git 状态确认没有意外的文件改动。6.3 为什么同样的操作有时候快有时候慢这通常是因为上下文状态不同。第一次操作时上下文干净响应快后续操作时上下文里已经积累了很多内容响应就慢。另外服务端的负载波动也会影响响应速度同一操作在不同时间执行速度可能不一样。如果这种快慢差异非常明显且持续那就要考虑是不是上下文膨胀或者项目配置的问题了。6.4 怎么判断是 Claude Code 的问题还是我的问题一个简单的判断方法换一个全新的、最小的项目执行一个最简单的操作看是否流畅。如果流畅那问题在你的项目配置或上下文如果还是卡那问题在环境或安装。这个方法能快速把责任范围缩小避免在错误的方向上浪费时间。7. 我个人的一些使用习惯用 Claude Code 这段时间我逐渐形成了一些习惯能明显减少遇到卡顿的概率。第一个习惯是开工前先清理项目把不需要的目录加到忽略列表把大的临时文件删掉让项目保持干净。第二个习惯是按任务开会话一个任务做完就关不拖泥带水。第三个习惯是卡顿时先看资源打开系统监控看一眼 CPU 和内存排除掉资源问题再往深了查。第四个习惯是保持版本更新有新版本就升很多小问题升级后就没了。还有一个习惯是记录卡顿案例。每次遇到卡顿并解决之后我会简单记一下现象、根因和解决方法。积累多了之后再遇到类似现象就能快速定位不用从头排查。这个习惯看起来麻烦但长期来看节省的时间非常多。最后分享一个小技巧如果你怀疑是某个特定操作导致的卡顿可以试着把这个操作拆成更小的步骤一步一步执行看具体卡在哪一步。比如一个大的重构任务卡住了可以拆成“先读文件”“再改这个函数”“再改那个函数”逐步执行这样既能定位卡顿点也能避免一次性改动太大导致难以回滚。