1. 先看明白 Spinner 到底在转什么1.1 Spinner 不是加载动画那么简单很多刚接触 Claude Code 的人看到终端里的 spinner 转起来第一反应是坏了是不是卡死了。我第一次用的时候也这样让它分析一个项目的整体启动流程光标旁边的 spinner 转了两分多钟输出迟迟不出来我差点手一抖就把进程杀了。后来我把交互日志翻出来逐行看才彻底想明白一个问题Claude Code 的 spinner 只是终端 UI 层在显示有一个异步请求正在挂起它不等于 AI 正在思考也不等于程序死锁它只代表一个还没有返回结果的请求。Claude Code 本质上是一个交互式终端程序它的运行逻辑是输入指令 - 调用底层模型接口 - 等待响应 - 输出结果。spinner 转只说明程序走到等待响应发出去之后回传这个环节了。至于响应是正在模型侧生成、被网络堵在半路、还是已经丢了没人知道spinner 本身看不出任何区别。它就像一个门铃按下去之后响了但门到底开不开你听门铃是听不出来的。理解这一点非常关键。因为很多人排查卡顿一上来就在终端里疯狂按快捷键甚至直接重启完全没有意识到spinner 的转动状态只是一个提示真正能说明问题的是程序内部的事件循环、日志记录和网络请求状态。1.2 正常等待和异常卡死的判断线在哪要给正常慢和异常卡死画一条线我总结出三个可操作的判断标准实测下来比较靠谱。第一个判断标准是键盘响应。Claude Code 的主进程如果还活着即使请求挂起终端里 Esc、ShiftTab 这类快捷键应该仍然有效你能看到输入框的切换。如果连按键都没反应那说明终端会话本身出了问题大概率不是 Claude Code 一个进程能解决的要考虑更高层级的环境问题。第二个判断标准是日志时间戳。正常处理中的请求日志文件里会持续出现新的时间戳记录哪怕输出没有展现在终端里底层 API 调用记录也是在往前走的。我遇到过最典型的假卡死就是日志里每隔十几秒就有一条API request in progress的记录spinner 一直转但最后能正常出结果。而真正的异常是日志时间戳完全停在一个点上后面再也没有新记录。第三个判断标准是工具调用的状态。Claude Code 在执行终端命令、读取文件时会调用本地工具如果某个工具进程卡住了spinner 也会一直转但此时你可以在另一个窗口里看到那个进程的具体状态。比如它执行了npm install你去查进程表能看到 npm 进程还挂着这就说明卡点在工具执行层而不是模型层。这三个标准核心目的只有一个区分问题到底在应用层还是终端层还是网络链路层。分清楚层级后面排查才有方向。2. 卡顿根源别一上来就怪网络2.1 模型长思考是最常见的假卡顿我这两年接手过的卡顿排查接近三分之一最后都确认是模型侧的正常思考根本不是 bug。Claude 这类大模型在应对复杂任务时会有一段较长的内部推理过程。你让它做跨文件的代码架构分析、设计一套缓存方案、梳理一个大型函数的调用链它前端展示的表现就是 spinner 长时间转动然后突然一次性吐出一大段结果。这个现象在拆解任务时特别容易出现因为大模型要把整段逻辑在内部推演完才组织语言输出和平时一问一答的即时响应完全是两种节奏。怎么判断它是思考还是断了我实测中最有效的办法就是看 API 请求的持续时间。你可以在日志里看到模型的响应耗时如果耗时很长但最终返回了内容那它就是思考如果请求发出几秒钟后就报了超时或者连接中断那才是真正的问题。这里也要给团队里的朋友提个醒不是所有 spinner 转得久都值得紧张尤其是面对复杂的架构设计任务时给模型多一点时间常常比反复中断重试更有效率。我自己就犯过错误一个复杂的重构方案第一次转了三分钟我直接放弃了嫌它慢重来后又转了两分半才出结果回头一看第一次生成的内容其实已经质量不错了白白浪费了一次机会。2.2 工具调用卡住是隐藏最深的大坑第二个高频卡顿根源是 Claude Code 在调用本地工具执行命令时被阻塞。Claude Code 会把一些终端命令作为工具来调用比如读取文件、执行 git 操作、运行测试脚本。它做这件事有个流程先申请权限再执行命令然后把命令结果拿回来交给模型继续处理。这个链路中任何一环卡住spinner 都会一直转下去。我自己踩过一次非常典型的坑在一个依赖特别多的项目里让它帮忙做依赖补全结果它在终端里执行了npm install这个命令因为网络原因卡了十几分钟不返回。那十几分钟里 Claude Code 的 spinner 就一直转终端上没有任何输出界面看起来像是死掉了。我当时甚至准备去卸载重装还好第二天冷静下来查了一下进程列表发现 npm 进程还挂着把它杀掉之后Claude Code 立刻从卡滞状态恢复过来。这个案例教会我一个经验看到 spinner 卡住第一反应不要是重装软件而是去查有没有本地进程被挂起。用ps查一下相关进程或者打开任务管理器看一下 CPU、网络占用如果看到一个命令进程长期不结束那多半就是它把工具调用链堵死了。2.3 上下文膨胀越用越卡的隐形推手还有一个特别容易被忽略的根源是会话上下文不断膨胀。Claude Code 的每次请求都会把当前会话的历史消息、最近几次工具调用的结果一起打包发给模型。你用的会话越久读取过的文件越多历史消息累积得越长每次请求携带的数据量就越大。本来三秒能返回的响应到了后期可能变成三十秒甚至更久表现同样是 spinner 一直转。我做过一次很直观的测试在一个会话里让它分析了一份三千行的日志文件从那次之后同会话内所有请求的响应延迟都明显上升从不到三秒变成接近半分钟。后来我换成用tail -100截取日志末尾 100 行再让它分析延迟又降回了三秒左右。这里面的原理很简单模型接口的处理时间和输入长度不是线性关系当上下文到了几万 token 级别光是传输和处理这些内容就要消耗大量时间。所以我现在的习惯是需要处理大文件时尽量用 grep、head、tail 这类工具先做预筛选只把真正需要的部分喂给模型不要让它在完整文件里自己翻找。独立的小任务也尽量开新会话做不要跟一个大项目的长期会话挤在一起。2.4 网络问题反而应该放在后面排查关于网络我想说的可能非常反直觉大部分 spinner 卡住排查到最后都不是网络的锅。真正的网络问题往往特征明显要么直接报超时错误要么日志里出现连接被重置、连接失败这类明确的关键词。如果你只是看到 spinner 在转没有任何报错信息那先去查模型思考、工具调用、上下文这些因素优先度远高于检查网络。为什么这么说因为网络问题一旦出现通常不会是静默的。API 请求超时、连接断开这些异常在日志里都有记录可查。反而是前面提到的模型长思考、工具调用阻塞、上下文膨胀这些因素在界面上看起来一模一样——就是一个 spinner 在转没有任何报错最容易让人误判成网络故障。我见过很多团队的排障记录花了大半天在检查网络链路最后发现把日志打开一看请求明明发出去了是模型侧一直没回。所以我的建议是网络放最后查并且一定要有日志里的明确证据再往这个方向投入精力。3. 一套能落地的排查操作流程3.1 第一步打开日志不要靠猜排查卡顿第一件事永远是打开日志而不是反复重启。Claude Code 的交互记录会写到本地项目目录下的日志文件里按项目路径归档。具体路径可能因为版本不同略有差异但大致范围是用户目录下的.claude目录。打开日志之后按时间排序找最后一次输出的位置重点看几类关键词有没有 error、timeout、retry、connection 这些记录。日志的作用是把我觉得它卡住了变成一个明确的判断依据。如果日志里显示 API 请求发出去了但一直没有回包那问题就在请求链路如果日志里根本没有发出请求的记录那说明问题在更早期的环节——可能是提示词处理、工具调度或者本地配置问题。这一步看着简单但它决定了整个排查的方向。方向错了后面做得再多都是瞎忙。我见过太多人卡在反复卸载重装的循环里实际上只要花三分钟打开日志看一眼就能少走很多弯路。3.2 第二步用 debug 模式和最小化复现锁定环节如果常规日志看不出明确线索下一步就要上 debug 模式。Claude Code 在调试模式下会输出更详细的步骤记录能直接看到程序当前是停在等待模型回复还是正在执行工具调用。打开调试模式后我强烈建议做一次最小化复现。所谓最小化复现就是把当前复杂的会话清空只给它一个特别简单的任务比如告诉我当前的时间或者列一下这个目录的文件。这样做的目的是快速做一次二分定位如果简单任务也卡问题一定出在基础层比如 API 配置、终端环境、输入输出链路如果简单任务正常那问题就是复杂任务触发的重点排查上下文太长、工具调用太多、某条命令执行时间过长。这套二分思路和排查后端接口问题是完全一样的先缩小范围再精细化定位。我自己用这套方法十分钟内基本都能把卡顿定位到具体环节。3.3 第三步精简上下文效果立竿见影在定位到复杂任务触发这个方向之后最有效的手段就是精简上下文。具体操作有几个第一不要一上来就让它读整个项目。先看目录结构和关键文件按需逐文件打开而不是一次性把所有内容灌给它。第二大文件必须预筛选。用head、tail、grep这些工具做过滤只保留前后文相关的部分。读一个完整的三千行日志和读它的最后一百行请求速度完全是两个量级。第三定期开新会话。一个会话超过几十条消息之后历史记录已经非常庞大了这时候继续叠加新任务性能下降和卡顿风险都会增加。我自己的习惯是凡是完成一个独立功能模块就开一个新会话承接下一个任务用新会话的干净状态保证响应速度。我用这个习惯之后明显感觉自己的使用流畅度提升了一个档次。这个建议成本为零收益却非常直接。3.4 第四步检查终端环境这个坑很多人不知道极容易踩的一个坑是终端环境对 Claude Code 的影响。这个工具对终端依赖程度很高在部分终端模拟器里对输入事件、ANSI 控制序列的处理有兼容问题表现就是 spinner 卡在某个状态不动或者按键无响应。但你切到另一个终端模拟器它又完全正常了。我自己遇到过一次在本机用自带终端跑 Claude Code 一切正常但在 IDE 内置终端里跑频繁出现 spinner 停转、输入框弹不出来的现象。折腾很久之后才发现是 IDE 终端在转发控制序列时做了特殊处理把相关选项调整之后问题就消失了。所以如果排查了半天发现不是模型问题、不是工具调用问题那最后一个方向就是终端。直接换到系统自带的默认终端测试一下这个操作成本极低却经常能快速定位问题。不要在你的 IDE 终端里面反复折腾各项设置先把环境切换到最干净的场景验证往往一步就能定位。4. 常见问题速查与实测经验4.1 常见问题速查表整理一张速查表方便以后遇到同类型问题时快速对照。这些场景我都在自己的项目里实际遇到过表格只覆盖比较高频的情况具体排查时仍然以日志为准。现象大概率根源优先处理动作spinner 长时间转动后一次性输出模型深度思考中观察日志时间戳是否持续更新耐心等待spinner 转但完全无输出且日志停住API 请求挂起取消当前请求重试检查超时配置spinner 在工具执行阶段一直转本地命令进程卡住查看并终止卡住的进程或改用带超时的命令简单任务正常复杂任务慢到异常上下文膨胀精简输入内容开启新会话交互无响应输入框都弹不出终端环境异常切换终端模拟器测试启动时 spinner 转一下就退出API Key 或组织策略配置异常检查配置项确认当前账号的访问权限4.2 我验证过很多次的实操处理顺序真实排查中我不建议一上来就做大规模测试。我自己的处理顺序是这样的先不动界面直接打开日志看最后二十行日志里有 error 或 timeout直接先处理对应问题日志显示停在执行命令阶段就去查进程列表找那个卡住的命令进程杀掉或等它结束日志显示停在调用 API 阶段取消请求几秒钟后重试以上都没眉目打开 debug 模式做最小化复现最小化复现也卡就去检查基础配置和终端环境。按这个顺序我遇到的大部分卡顿都能在十分钟内定位到一个具体环节。如果你每次卡住都直接重启会话当然也能解决但重启只是绕过了问题没有找到根源后面大概率还会再遇到。这里分享一个成本最低的小技巧遇到 spinner 长时间不结束不要急着关终端先按一次 Esc。很多情况下这只是某个工具调用在等待确认Esc 可以把流程拉回来这个动作实测经常有效。4.3 把个人排查经验沉淀成团队资产最后聊一点团队层面的经验。Claude Code 在团队里越来越普及之后我发现一个问题每个成员遇到卡顿的原因可能都不一样有的是文件读取太大有的是某个命令执行太慢有的是会话历史太长。如果没有一份统一的速查文档每个人都要从零踩一遍坑。我比较推荐的做法是团队里至少整理一份自己的排查手册把项目里实际遇到过的卡顿场景、现象、根因和处理方式记录下来。这个手册的沉淀价值会越来越高因为后来者遇到问题不用在排障的迷宫里兜圈子直接对照手册按步骤排查。从我个人的体会来说spinner 卡顿这件事远没有看起来那么神秘。它就是一个普通的程序问题无非是请求、处理、响应、回传这几个环节中的一个出了问题每个环节都对应着可以排查的证据——日志、时间戳、进程状态、debug 输出。只要把这些证据串起来从感觉卡住了变成大概率卡在哪个具体环节再针对这个环节去解决绝大多数问题都能顺利化解。 
长河君 · 2026/10/29 7:41:13 · 阅读 1.2k Claude Code spinner卡顿排查：从模型思考到工具调用与上下文优化
1. 先看明白 Spinner 到底在转什么1.1 Spinner 不是加载动画那么简单很多刚接触 Claude Code 的人看到终端里的 spinner 转起来第一反应是坏了是不是卡死了。我第一次用的时候也这样让它分析一个项目的整体启动流程光标旁边的 spinner 转了两分多钟输出迟迟不出来我差点手一抖就把进程杀了。后来我把交互日志翻出来逐行看才彻底想明白一个问题Claude Code 的 spinner 只是终端 UI 层在显示有一个异步请求正在挂起它不等于 AI 正在思考也不等于程序死锁它只代表一个还没有返回结果的请求。Claude Code 本质上是一个交互式终端程序它的运行逻辑是输入指令 - 调用底层模型接口 - 等待响应 - 输出结果。spinner 转只说明程序走到等待响应发出去之后回传这个环节了。至于响应是正在模型侧生成、被网络堵在半路、还是已经丢了没人知道spinner 本身看不出任何区别。它就像一个门铃按下去之后响了但门到底开不开你听门铃是听不出来的。理解这一点非常关键。因为很多人排查卡顿一上来就在终端里疯狂按快捷键甚至直接重启完全没有意识到spinner 的转动状态只是一个提示真正能说明问题的是程序内部的事件循环、日志记录和网络请求状态。1.2 正常等待和异常卡死的判断线在哪要给正常慢和异常卡死画一条线我总结出三个可操作的判断标准实测下来比较靠谱。第一个判断标准是键盘响应。Claude Code 的主进程如果还活着即使请求挂起终端里 Esc、ShiftTab 这类快捷键应该仍然有效你能看到输入框的切换。如果连按键都没反应那说明终端会话本身出了问题大概率不是 Claude Code 一个进程能解决的要考虑更高层级的环境问题。第二个判断标准是日志时间戳。正常处理中的请求日志文件里会持续出现新的时间戳记录哪怕输出没有展现在终端里底层 API 调用记录也是在往前走的。我遇到过最典型的假卡死就是日志里每隔十几秒就有一条API request in progress的记录spinner 一直转但最后能正常出结果。而真正的异常是日志时间戳完全停在一个点上后面再也没有新记录。第三个判断标准是工具调用的状态。Claude Code 在执行终端命令、读取文件时会调用本地工具如果某个工具进程卡住了spinner 也会一直转但此时你可以在另一个窗口里看到那个进程的具体状态。比如它执行了npm install你去查进程表能看到 npm 进程还挂着这就说明卡点在工具执行层而不是模型层。这三个标准核心目的只有一个区分问题到底在应用层还是终端层还是网络链路层。分清楚层级后面排查才有方向。2. 卡顿根源别一上来就怪网络2.1 模型长思考是最常见的假卡顿我这两年接手过的卡顿排查接近三分之一最后都确认是模型侧的正常思考根本不是 bug。Claude 这类大模型在应对复杂任务时会有一段较长的内部推理过程。你让它做跨文件的代码架构分析、设计一套缓存方案、梳理一个大型函数的调用链它前端展示的表现就是 spinner 长时间转动然后突然一次性吐出一大段结果。这个现象在拆解任务时特别容易出现因为大模型要把整段逻辑在内部推演完才组织语言输出和平时一问一答的即时响应完全是两种节奏。怎么判断它是思考还是断了我实测中最有效的办法就是看 API 请求的持续时间。你可以在日志里看到模型的响应耗时如果耗时很长但最终返回了内容那它就是思考如果请求发出几秒钟后就报了超时或者连接中断那才是真正的问题。这里也要给团队里的朋友提个醒不是所有 spinner 转得久都值得紧张尤其是面对复杂的架构设计任务时给模型多一点时间常常比反复中断重试更有效率。我自己就犯过错误一个复杂的重构方案第一次转了三分钟我直接放弃了嫌它慢重来后又转了两分半才出结果回头一看第一次生成的内容其实已经质量不错了白白浪费了一次机会。2.2 工具调用卡住是隐藏最深的大坑第二个高频卡顿根源是 Claude Code 在调用本地工具执行命令时被阻塞。Claude Code 会把一些终端命令作为工具来调用比如读取文件、执行 git 操作、运行测试脚本。它做这件事有个流程先申请权限再执行命令然后把命令结果拿回来交给模型继续处理。这个链路中任何一环卡住spinner 都会一直转下去。我自己踩过一次非常典型的坑在一个依赖特别多的项目里让它帮忙做依赖补全结果它在终端里执行了npm install这个命令因为网络原因卡了十几分钟不返回。那十几分钟里 Claude Code 的 spinner 就一直转终端上没有任何输出界面看起来像是死掉了。我当时甚至准备去卸载重装还好第二天冷静下来查了一下进程列表发现 npm 进程还挂着把它杀掉之后Claude Code 立刻从卡滞状态恢复过来。这个案例教会我一个经验看到 spinner 卡住第一反应不要是重装软件而是去查有没有本地进程被挂起。用ps查一下相关进程或者打开任务管理器看一下 CPU、网络占用如果看到一个命令进程长期不结束那多半就是它把工具调用链堵死了。2.3 上下文膨胀越用越卡的隐形推手还有一个特别容易被忽略的根源是会话上下文不断膨胀。Claude Code 的每次请求都会把当前会话的历史消息、最近几次工具调用的结果一起打包发给模型。你用的会话越久读取过的文件越多历史消息累积得越长每次请求携带的数据量就越大。本来三秒能返回的响应到了后期可能变成三十秒甚至更久表现同样是 spinner 一直转。我做过一次很直观的测试在一个会话里让它分析了一份三千行的日志文件从那次之后同会话内所有请求的响应延迟都明显上升从不到三秒变成接近半分钟。后来我换成用tail -100截取日志末尾 100 行再让它分析延迟又降回了三秒左右。这里面的原理很简单模型接口的处理时间和输入长度不是线性关系当上下文到了几万 token 级别光是传输和处理这些内容就要消耗大量时间。所以我现在的习惯是需要处理大文件时尽量用 grep、head、tail 这类工具先做预筛选只把真正需要的部分喂给模型不要让它在完整文件里自己翻找。独立的小任务也尽量开新会话做不要跟一个大项目的长期会话挤在一起。2.4 网络问题反而应该放在后面排查关于网络我想说的可能非常反直觉大部分 spinner 卡住排查到最后都不是网络的锅。真正的网络问题往往特征明显要么直接报超时错误要么日志里出现连接被重置、连接失败这类明确的关键词。如果你只是看到 spinner 在转没有任何报错信息那先去查模型思考、工具调用、上下文这些因素优先度远高于检查网络。为什么这么说因为网络问题一旦出现通常不会是静默的。API 请求超时、连接断开这些异常在日志里都有记录可查。反而是前面提到的模型长思考、工具调用阻塞、上下文膨胀这些因素在界面上看起来一模一样——就是一个 spinner 在转没有任何报错最容易让人误判成网络故障。我见过很多团队的排障记录花了大半天在检查网络链路最后发现把日志打开一看请求明明发出去了是模型侧一直没回。所以我的建议是网络放最后查并且一定要有日志里的明确证据再往这个方向投入精力。3. 一套能落地的排查操作流程3.1 第一步打开日志不要靠猜排查卡顿第一件事永远是打开日志而不是反复重启。Claude Code 的交互记录会写到本地项目目录下的日志文件里按项目路径归档。具体路径可能因为版本不同略有差异但大致范围是用户目录下的.claude目录。打开日志之后按时间排序找最后一次输出的位置重点看几类关键词有没有 error、timeout、retry、connection 这些记录。日志的作用是把我觉得它卡住了变成一个明确的判断依据。如果日志里显示 API 请求发出去了但一直没有回包那问题就在请求链路如果日志里根本没有发出请求的记录那说明问题在更早期的环节——可能是提示词处理、工具调度或者本地配置问题。这一步看着简单但它决定了整个排查的方向。方向错了后面做得再多都是瞎忙。我见过太多人卡在反复卸载重装的循环里实际上只要花三分钟打开日志看一眼就能少走很多弯路。3.2 第二步用 debug 模式和最小化复现锁定环节如果常规日志看不出明确线索下一步就要上 debug 模式。Claude Code 在调试模式下会输出更详细的步骤记录能直接看到程序当前是停在等待模型回复还是正在执行工具调用。打开调试模式后我强烈建议做一次最小化复现。所谓最小化复现就是把当前复杂的会话清空只给它一个特别简单的任务比如告诉我当前的时间或者列一下这个目录的文件。这样做的目的是快速做一次二分定位如果简单任务也卡问题一定出在基础层比如 API 配置、终端环境、输入输出链路如果简单任务正常那问题就是复杂任务触发的重点排查上下文太长、工具调用太多、某条命令执行时间过长。这套二分思路和排查后端接口问题是完全一样的先缩小范围再精细化定位。我自己用这套方法十分钟内基本都能把卡顿定位到具体环节。3.3 第三步精简上下文效果立竿见影在定位到复杂任务触发这个方向之后最有效的手段就是精简上下文。具体操作有几个第一不要一上来就让它读整个项目。先看目录结构和关键文件按需逐文件打开而不是一次性把所有内容灌给它。第二大文件必须预筛选。用head、tail、grep这些工具做过滤只保留前后文相关的部分。读一个完整的三千行日志和读它的最后一百行请求速度完全是两个量级。第三定期开新会话。一个会话超过几十条消息之后历史记录已经非常庞大了这时候继续叠加新任务性能下降和卡顿风险都会增加。我自己的习惯是凡是完成一个独立功能模块就开一个新会话承接下一个任务用新会话的干净状态保证响应速度。我用这个习惯之后明显感觉自己的使用流畅度提升了一个档次。这个建议成本为零收益却非常直接。3.4 第四步检查终端环境这个坑很多人不知道极容易踩的一个坑是终端环境对 Claude Code 的影响。这个工具对终端依赖程度很高在部分终端模拟器里对输入事件、ANSI 控制序列的处理有兼容问题表现就是 spinner 卡在某个状态不动或者按键无响应。但你切到另一个终端模拟器它又完全正常了。我自己遇到过一次在本机用自带终端跑 Claude Code 一切正常但在 IDE 内置终端里跑频繁出现 spinner 停转、输入框弹不出来的现象。折腾很久之后才发现是 IDE 终端在转发控制序列时做了特殊处理把相关选项调整之后问题就消失了。所以如果排查了半天发现不是模型问题、不是工具调用问题那最后一个方向就是终端。直接换到系统自带的默认终端测试一下这个操作成本极低却经常能快速定位问题。不要在你的 IDE 终端里面反复折腾各项设置先把环境切换到最干净的场景验证往往一步就能定位。4. 常见问题速查与实测经验4.1 常见问题速查表整理一张速查表方便以后遇到同类型问题时快速对照。这些场景我都在自己的项目里实际遇到过表格只覆盖比较高频的情况具体排查时仍然以日志为准。现象大概率根源优先处理动作spinner 长时间转动后一次性输出模型深度思考中观察日志时间戳是否持续更新耐心等待spinner 转但完全无输出且日志停住API 请求挂起取消当前请求重试检查超时配置spinner 在工具执行阶段一直转本地命令进程卡住查看并终止卡住的进程或改用带超时的命令简单任务正常复杂任务慢到异常上下文膨胀精简输入内容开启新会话交互无响应输入框都弹不出终端环境异常切换终端模拟器测试启动时 spinner 转一下就退出API Key 或组织策略配置异常检查配置项确认当前账号的访问权限4.2 我验证过很多次的实操处理顺序真实排查中我不建议一上来就做大规模测试。我自己的处理顺序是这样的先不动界面直接打开日志看最后二十行日志里有 error 或 timeout直接先处理对应问题日志显示停在执行命令阶段就去查进程列表找那个卡住的命令进程杀掉或等它结束日志显示停在调用 API 阶段取消请求几秒钟后重试以上都没眉目打开 debug 模式做最小化复现最小化复现也卡就去检查基础配置和终端环境。按这个顺序我遇到的大部分卡顿都能在十分钟内定位到一个具体环节。如果你每次卡住都直接重启会话当然也能解决但重启只是绕过了问题没有找到根源后面大概率还会再遇到。这里分享一个成本最低的小技巧遇到 spinner 长时间不结束不要急着关终端先按一次 Esc。很多情况下这只是某个工具调用在等待确认Esc 可以把流程拉回来这个动作实测经常有效。4.3 把个人排查经验沉淀成团队资产最后聊一点团队层面的经验。Claude Code 在团队里越来越普及之后我发现一个问题每个成员遇到卡顿的原因可能都不一样有的是文件读取太大有的是某个命令执行太慢有的是会话历史太长。如果没有一份统一的速查文档每个人都要从零踩一遍坑。我比较推荐的做法是团队里至少整理一份自己的排查手册把项目里实际遇到过的卡顿场景、现象、根因和处理方式记录下来。这个手册的沉淀价值会越来越高因为后来者遇到问题不用在排障的迷宫里兜圈子直接对照手册按步骤排查。从我个人的体会来说spinner 卡顿这件事远没有看起来那么神秘。它就是一个普通的程序问题无非是请求、处理、响应、回传这几个环节中的一个出了问题每个环节都对应着可以排查的证据——日志、时间戳、进程状态、debug 输出。只要把这些证据串起来从感觉卡住了变成大概率卡在哪个具体环节再针对这个环节去解决绝大多数问题都能顺利化解。