1. 从一次深夜调试说起Spinner 卡住到底卡在哪凌晨一点半终端里那个小小的 Spinner 已经转了快四分钟。光标不动日志不刷新CPU 风扇倒是转得挺欢。我盯着屏幕心里清楚这不是网络问题——因为同一台机器上另一个窗口的请求刚返回。这种场景用过 Claude Code 的人大概率都遇到过它没崩也没报错就是“卡住了”Spinner 一直在转但你不知道它在等什么。这篇内容就是围绕这个现象展开的。我会把 Claude Code 的 Spinner 状态标识拆开讲清楚说明它每一种形态背后代表什么然后顺着这些状态去定位卡顿的真正根源最后给出一套我自己反复验证过的排查方案。适合两类人看一是刚装上 Claude Code、被卡顿搞得一头雾水的新手二是已经用了一段时间、想搞清楚“为什么有时候快有时候慢”的老用户。不管你是 Windows、macOS 还是 Linux排查思路是通用的。先说一个基本认知Claude Code 的 Spinner 不是装饰动画它是一个状态机的外在表现。它转与不转、转得快与慢、旁边有没有文字都在告诉你当前请求走到了哪一步。很多人把它当成“加载中”三个字这就浪费了它携带的信息量。搞懂 Spinner等于拿到了排查卡顿的第一把钥匙。2. Spinner 状态标识全解析每一种形态都在说话2.1 Spinner 的三种基础形态与对应含义Claude Code 在终端里的 Spinner 大致分三种形态我按自己观察到的频率从高到低排第一种是纯旋转动画无附加文字。这通常出现在请求刚发出的最初阶段客户端正在建立连接、发送请求体。这个阶段一般很短几百毫秒到一两秒。如果它长时间停在这个形态说明请求根本没发出去或者发出去了但没收到任何响应头。第二种是旋转动画加状态短语比如 “Thinking…”、“Working…”、“Reading files…”。这是最常见的形态说明请求已经到达服务端模型正在处理或者正在执行工具调用。这个阶段的长短取决于任务复杂度几秒到几十秒都算正常。第三种是旋转动画加进度提示比如显示已读取的文件数、已执行的命令数。这出现在多步任务里说明 Claude Code 正在按计划推进每一步都有反馈。提示如果你看到 Spinner 旁边出现了具体的文件名或命令说明它没卡只是在干活。真正需要警惕的是“纯旋转、无文字、超过 30 秒”。2.2 为什么 Spinner 的状态设计成这个样子这里要解释一个“为什么”。Claude Code 是终端工具没有图形界面那种进度条和百分比。它的设计哲学是用最少的视觉元素传递最多的状态信息。Spinner 旋转代表“活着”文字代表“在干什么”两者组合就能覆盖大部分场景。但这也带来一个副作用当它真的卡住时视觉上和“正在思考”几乎一样。这就是为什么很多人分不清“慢”和“卡”。我的经验是看文字有没有变化。如果文字在变哪怕很慢它也是在推进如果文字超过 30 秒一动不动那才是真卡。2.3 Spinner 不转了的几种情况有时候 Spinner 直接停了光标回到输入框但你没看到结果。这通常是以下几种情况请求超时客户端静默重试或放弃没有明显报错。工具调用返回了空结果Claude Code 认为任务结束。终端渲染问题Spinner 动画被其他输出覆盖了。这几种情况里第一种最容易被误判为“卡住”。实际上它已经结束了只是结束得不够明显。你可以按一下回车看是否有新输出或者直接看终端标题栏有没有变化。3. 卡顿根源逐层拆解从网络到本地从模型到终端3.1 第一层网络链路与 API 响应Claude Code 的核心工作方式是调用远端模型 API。所以第一层排查永远是网络。但这里的“网络问题”不是简单的一句“网不好”要拆成几个具体指标DNS 解析时间如果 DNS 慢请求还没发出去就卡住了。TCP 连接建立时间握手慢说明链路质量差。TLS 握手时间证书验证、加密协商也会耗时。首字节时间TTFB服务端处理请求的时间。传输时间响应体大小除以带宽。我实测下来大部分“卡住”发生在 TTFB 阶段。也就是请求发出去了服务端在排队或处理客户端只能等。这个阶段 Spinner 会一直转文字可能停在 “Thinking…”。3.2 第二层本地资源与终端渲染这一层经常被忽略。Claude Code 跑在终端里终端的渲染性能直接影响体验。如果你用的是 VS Code 内置终端同时开了很多插件或者终端里已经输出了几万行日志Spinner 的动画就会掉帧看起来像卡住。另外CPU 占用也是关键。Claude Code 本身不重但如果你的机器同时在跑编译、Docker、浏览器几十个标签页那它抢不到 CPU 时间片Spinner 自然转不动。我在一台老笔记本上试过关掉 Chrome 之后同样的请求从“卡住”变成“秒回”。3.3 第三层模型侧的任务复杂度这一层是很多人不愿意承认的有些请求就是需要很久。比如你让它读一个几千行的文件、分析整个项目结构、执行多步重构模型需要多轮推理和工具调用。这时候 Spinner 转几分钟是正常的。判断方法很简单看 Spinner 旁边的文字有没有在变。如果从 “Reading files…” 变成 “Analyzing…”再变成 “Writing…”那它一直在推进只是任务本身重。这时候你能做的只有等或者把任务拆小。3.4 第四层配置与权限问题这一层比较隐蔽。比如你的组织禁用了某个订阅访问权限客户端可能在反复重试认证Spinner 一直转但永远拿不到结果。这类问题通常会在日志里留下痕迹但默认不显示。你需要开启详细日志才能看到。还有一种情况是本地模型配置。如果你把 Claude Code 指向本地运行的模型服务而那个服务没启动或端口不对Spinner 也会一直转因为客户端在等一个永远不会来的响应。4. 排查方案实操一套可复现的定位流程4.1 第一步确认 Spinner 当前状态不要急着杀进程。先看三件事Spinner 旁边有没有文字文字是什么文字在过去 30 秒内有没有变化终端标题栏有没有变化比如从 “Claude Code” 变成文件名把这三个信息记下来它们决定了你下一步往哪个方向查。4.2 第二步分层验证网络与本地我习惯用一套固定的命令来快速分层。以下命令在 macOS 和 Linux 上通用Windows 可以用 PowerShell 对应命令替代。# 测试 DNS 解析时间 time nslookup api.anthropic.com # 测试 TCP 连接和 TLS 握手时间 curl -o /dev/null -s -w DNS: %{time_namelookup}s\nTCP: %{time_connect}s\nTLS: %{time_appconnect}s\nTTFB: %{time_starttransfer}s\nTotal: %{time_total}s\n https://api.anthropic.com/v1/messages如果 TTFB 超过 5 秒基本可以确定是服务端或链路问题。如果 DNS 或 TCP 时间异常那是本地网络问题。同时开一个终端窗口跑top或htop看 Claude Code 进程的 CPU 和内存占用。如果 CPU 长期 100%说明本地在忙如果 CPU 接近 0 但 Spinner 在转说明在等网络。4.3 第三步开启详细日志Claude Code 支持通过环境变量开启调试日志。具体变量名可能随版本变化但思路是一样的把日志级别调到 debug然后看输出。# 示例开启调试日志后重新运行 DEBUG* claude日志里重点看几个关键词retry、timeout、auth、connection。如果看到反复 retry说明请求在失败重试如果看到 auth 相关说明权限有问题。4.4 第四步缩小任务范围如果日志显示请求正常发出、正常返回但就是慢那问题在任务本身。这时候把大任务拆成小任务不要一次让它读整个项目先指定具体文件。不要一次让它做多步重构先做一步验证一步。不要让它分析超大日志文件先截取关键片段。我自己的经验是单次请求涉及的文件超过 5 个或者需要执行超过 3 条命令卡顿概率会明显上升。这不是 Claude Code 的问题是任务复杂度的问题。4.5 第五步检查终端环境如果以上都正常但 Spinner 还是卡换一个终端试试。比如从 VS Code 内置终端换到系统自带终端或者从 iTerm2 换到 Terminal.app。有时候是终端模拟器的渲染问题。另外检查终端里已经输出的行数。如果超过一万行清屏clear或CmdK再试。这个操作听起来很傻但我确实遇到过清屏之后就不卡了的情况。5. 常见问题速查表与避坑经验5.1 高频问题对照表现象最可能原因优先排查动作Spinner 纯转无文字超过 30 秒请求未发出或网络阻塞跑 curl 测 TTFB检查 DNSSpinner 有文字但长时间不变服务端处理慢或任务过重看日志是否有 retry拆小任务Spinner 转但 CPU 占用高本地终端渲染或进程竞争关掉其他重负载程序清屏Spinner 转但 CPU 接近 0在等网络响应检查网络链路和 API 状态Spinner 突然消失无结果超时静默结束或空返回按回车看输出查日志换终端后正常终端渲染问题固定使用一个轻量终端5.2 我踩过的几个坑第一个坑以为卡住就狂按 CtrlC。结果把正在执行的多步任务中断了之前的工作全白费。后来我学会先等 30 秒看文字有没有变化再决定是否中断。第二个坑在 VS Code 里开了太多插件。特别是那些实时 lint、实时预览的插件它们和 Claude Code 抢终端资源。关掉之后Spinner 明显流畅了。第三个坑把本地模型服务地址配错。Spinner 一直转我还以为是模型在加载其实是端口写错了客户端在等一个不存在的服务。后来养成习惯配完先 curl 一下本地端口。第四个坑忽略组织权限提示。有些环境会限制订阅访问客户端不报错但也不返回结果。这种情况必须看详细日志才能发现。5.3 几个提升流畅度的小技巧把常用的大文件路径做成别名减少每次输入和解析时间。在项目根目录放一个.claudeignore文件排除node_modules、dist、.git等目录减少文件扫描量。如果经常处理长任务用tmux或screen保持会话避免终端断开导致任务丢失。定期清理终端历史输出保持渲染轻量。6. 不同平台下的配置差异与注意事项6.1 Windows 环境Windows 下 Claude Code 通常跑在 WSL 或 PowerShell 里。WSL 的文件系统跨层访问Windows 盘符挂载到/mnt/c会明显拖慢文件读取。如果卡顿发生在读文件阶段把项目放到 WSL 原生文件系统里比如~/projects速度会快很多。PowerShell 下要注意编码问题。某些特殊字符可能导致输出阻塞Spinner 看起来像卡住。建议用 Windows Terminal 而不是老版控制台。6.2 macOS 环境macOS 下主要问题是终端选择。iTerm2 功能强但重Terminal.app 轻但功能少。如果追求流畅Terminal.app 反而更稳。另外macOS 的 Spotlight 索引在后台跑的时候会抢 IO如果卡顿发生在文件读取阶段可以临时关闭索引。6.3 Linux 环境Linux 下变数最多因为发行版和终端组合太多。我建议用最朴素的组合GNOME Terminal 或 Alacritty配 bash 或 zsh。避免在终端里跑太多后台任务。如果用的是服务器环境注意 SSH 连接质量网络抖动会直接表现为 Spinner 卡顿。6.4 VS Code 集成环境VS Code 里用 Claude Code最大的坑是终端复用。VS Code 的终端面板如果同时开了多个会话切换时可能触发重绘Spinner 会短暂卡住。建议给 Claude Code 单独开一个终端标签不要和其他任务混用。另外VS Code 的设置里有一项terminal.integrated.gpuAcceleration开启 GPU 加速通常更流畅但在某些显卡驱动下反而会卡。如果遇到渲染问题可以试着关掉它。7. 当卡顿成为常态从工具使用习惯上找原因排查到最后我发现很多“卡顿”其实不是工具的问题是使用习惯的问题。比如习惯一次性丢一个巨大的需求让模型自己拆解。模型拆解需要多轮推理自然慢。习惯让模型读整个目录而不是指定文件。文件扫描和内容读取是两回事后者慢得多。习惯在同一个会话里连续做很多不相关的事。上下文越积越长每轮请求要处理的历史就越多响应越来越慢。我的做法是一个会话只做一件事做完就开新会话。需要跨会话保持的信息手动记到文件里。这样每次请求的上下文都是干净的Spinner 转的时间明显缩短。还有一个反直觉的经验不要频繁打断。模型正在推理的时候打断重新发起请求等于前面的计算全浪费了而且新请求还要重新处理上下文。除非确认卡死否则多等一会儿往往比反复重试更快。8. 一个真实案例的完整排查记录最后分享一个我上周遇到的案例把上面的流程串一遍。现象Claude Code 在读取一个中型项目时Spinner 停在 “Reading files…” 超过两分钟不动。第一步看状态有文字但两分钟没变。判断不是纯网络阻塞可能是文件读取卡住。第二步测网络curl 测 TTFB 正常1.2 秒。排除网络问题。第三步看本地htop显示 Claude Code 进程 CPU 占用 3%IO 等待很高。说明在等磁盘。第四步查目录项目里有node_modules几万个文件。Claude Code 在扫描目录时被拖住了。第五步解决在项目根目录加.claudeignore排除node_modules、dist、.next。重新发起请求Spinner 从 “Reading files…” 到出结果只用了 8 秒。这个案例的核心教训是卡顿不一定在网络上本地 IO 同样是瓶颈。尤其是前端项目依赖目录动辄几万文件不排除的话每次扫描都是灾难。后来我把这个习惯固定下来新建项目第一件事就是写.claudeignore。内容参考如下node_modules/ dist/ build/ .next/ .cache/ .git/ *.log *.lock这个文件不大但能省下大量等待时间。如果你还没加建议现在就加上。