企业官网建设流程全解析

最近好多朋友私信问我同一个问题：Claude Code 用着用着终端就卡住了，那个转圈的 spinner 一直在原地打转，等十几秒甚至一分钟都不出结果。这个现象太典型了，我在自己的机器上也踩过不少次坑。Claude Code 本质上是个交互式 AI 编程代理，它把“读代码、改文件、跑命令、看结果”拆成一串带状态的异步任务，spinner 其实就是它在汇报“我正在干活”。但具体卡在哪一环、为什么卡，大多数人根本没认真看过一眼。这篇文章不聊虚的，就从 spinner 状态标识入手，把卡顿根源、排查路径和可落地的配置方案一次性讲清楚。不管你是刚装好 Claude Code 不知道怎么下手的，还是已经卡到想砸终端的，都能按图索骥找到问题。

1. 先把 Spinner 看明白：它不是死机，是任务状态的风向标

1.1 Spinner 停在哪，问题大概率就出在哪

很多人一看到终端里长时间转圈，第一反应是“又死了”，抬手就是 Ctrl+C 杀掉进程。其实多数情况下 Claude Code 没死，只是被某个环节拖住了。spinner 的本质是“当前任务状态的可视化”，它对应一条完整的任务循环：模型思考、调用工具、读取结果、继续生成、渲染输出。

我建议你先别急着打断，而是盯住 spinner 停住的位置。如果光标的 spinner 停在“等待模型返回”的阶段，那多半是 API 响应慢或者上下文太长；如果停在某个工具执行之后，比如刚跑完一条 git 命令或者刚读完一个大文件，那问题大概率出在工具调用本身；如果是输出代码块的时候逐字符地卡，那就是终端渲染在拖后腿。判断这一步，比任何排查工具都管用，因为后续的所有手段都建立在“你大概知道卡在哪一段”的基础上。

1.2 不同环节卡住的特征与判断方法

我做了个简单的对照，方便你一眼定位：

有了这个初步印象，再往下排查就不会像无头苍蝇。我自己习惯的做法是：先不打断，等 30 秒到 1 分钟，同时打开另一个终端窗口去看日志和进程状态；如果连日志都在更新但输出迟迟不来，说明是模型侧或上下文的问题；如果日志完全没有新内容，那就要检查是不是某个外部进程把 Claude Code 卡死了。

1.3 判断“真死”还是“假死”的两个实用技巧

第一个技巧是看网络流量。在 macOS 上用nettop过滤 claude 进程，Windows 上打开资源监视器看网络活动，如果请求还在持续发送，说明只是响应慢，进程是活的。第二个技巧是直接开一个最小请求去测 API——比如用 curl 单独发一次消息，看模型多久能返回结果。如果 API 本身要 10 秒才回，那终端里转圈 10 秒是正常现象，不需要杀进程；反过来，API 已经返回了但终端还在转，那就是下游渲染或工具调用的问题。

2. 卡顿根源拆解：模型、上下文、终端一个都跑不了

2.1 模型侧的隐形瓶颈：限流、排队与首字延迟

Claude Code 背后调用的模型服务是共享资源，官方 API 在高峰期出现排队和限流非常正常。你感觉到的“卡”，很多时候其实是 API 返回首字的时间（TTFT）变高了。TTFT 受两个因素影响最大：一是当前服务的负载，二是你这次请求携带的上下文长度。

打个比方，你点外卖的时候商家页面一直显示“制作中”，可能是店里单太多，也可能是你这份订单配菜特别复杂。Claude Code 也一样，如果你在同一个会话里积累了大量历史消息，每次新请求都会把全部上下文重新发给模型做 prefill，这部分的计算量是随 token 数线性增长的。上下文有 2 万 token 和 20 万 token，首字响应时间差出 10 倍以上都不稀奇。

所以我一直强调：spinner 持续转，很多时候不是你运气差，而是你让模型每次都在“复习”一整本长篇小说。

2.2 上下文膨胀是最大的隐性杀手

很多人有个习惯，一个会话从早用到晚，什么东西都在里面聊。代码文件整段贴进去、报错信息复制进来、工具输出不断追加，不知不觉上下文就顶到了几十万 token。这时候每一次交互，模型都要把几十万 token 重新处理一遍，卡顿就成了必然结果。

我自己踩过一次很深的坑：让 Claude Code 在一个会话里反复修改同一个大型配置文件，期间我又贴了三四次完整文件内容，最后每个问题都要等 40 秒才回。后来用/context一看，上下文占用已经超过了模型窗口的一半，等于是让模型每次回答前都先读完一本厚书。从那以后我养成了习惯，超过 50% 占用就果断/compact或者/clear，卡顿立刻缓解。

2.3 本地环境：终端渲染、插件叠加与资源消耗

Claude Code 的终端交互体验依赖所在终端的渲染能力。Windows 自带的经典控制台窗口对 ANSI 转义序列的支持一般，遇到大段彩色 diff 输出容易出现逐字符渲染、光标闪动、输入延迟。我强烈建议 Windows 用户换 Windows Terminal，实测下来渲染压力至少减半。

除此之外，如果你用的是 VS Code 集成终端，又装了语言服务插件、代码补全插件、Git 增强插件，它们会跟你输入时的键盘事件和输出渲染抢资源。特别是某些插件会在你回车之后立即触发代码检查和格式化，跟 Claude Code 的输出混在一起，观感上就像“整个界面都卡了”。这种问题其实不是你网络慢，而是本地多个进程在打架。

2.4 外部命令挂起：偷偷卡住 spinner 的“卧底”

Claude Code 在执行任务时会调用终端命令来完成工具操作，比如读目录、跑测试、查 git 状态。这些命令一旦挂起，spinner 就会一直转。最常见的挂起点有几种：在超大 Git 仓库里跑 status 或 diff、某个命令等待用户输入却没接受到输入流、脚本里的网络请求长期无响应、或者命令本身有交互式提示符。

遇到这种情况，你会发现 spinner 卡在一个工具调用的结果输出之后，后面再也没有新动作。这时候需要去查 Claude Code 的日志，它会记录到底执行了哪条命令、命令的退出状态和耗时。搞清楚是哪条命令在拖时间，再针对性地优化，而不是一味地重试或干脆不用这个功能。

3. 排查方案：从现象到根因的四步实操路径

3.1 让日志开口说话：打开调试模式并定位日志文件

Claude Code 的日志目录一般在~/.claude/logs下，macOS 的另一种常见位置是~/.local/share/claude/logs，Windows 则在%USERPROFILE%\.claude\logs。不确定的话，可以启动时带变量让日志输出到终端。我常用的一个办法是开一个额外终端窗口，用 tail 实时跟踪日志：

# macOS / Linux tail -f ~/.claude/logs/*.log # Windows Terminal / PowerShell Get-Content "$env:USERPROFILE\.claude\logs\*" -Wait

同时用调试模式启动 Claude Code：

claude --debug

开启之后，终端会打印更详细的请求发送记录、工具调用记录、耗时数据。不信你可以下一次卡住时切到另一个终端看日志，通常都能看到某一条工具调用的时间戳明显异常，或者某个 API 请求的耗时超长。

3.2 用最小请求隔离 API 层的问题

当你怀疑是模型 API 的问题时，最快的验证办法是绕过 Claude Code 直接测一次 API。先确认你的密钥和端点配置，然后用 curl 发一个尽量小的请求，记录从发出到收到第一个字符的时间：

curl -N -X POST "https://api.anthropic.com/v1/messages" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "claude-3-7-sonnet-latest", "max_tokens": 64, "messages": [{"role": "user", "content": "ping"}] }'

如果这个最小请求都等了 10 秒以上，说明服务侧或者你当前网络环境到 API 端点的链路本身就不稳，Claude Code 卡住顺手就能解释了。反过来，如果最小请求秒回，但在 Claude Code 里依然卡，问题就堆在你当前会话的上下文规模和本地环境上。

3.3 检查上下文占用与会话体积

在卡住或刚启动的时候，直接在会话里输入/context，它会展示当前上下文的使用比例和 token 分布。输入/status可以查看当前账户状态、模型信息和 API 连通状态。这两个命令是排查卡顿最该先用的组合。

我建议把/status的输出当作“体温计”，当它显示 API 连接正常但 context 占比已经 70% 以上的时候，不用犹豫，立刻/compact。压缩历史记录能显著减小后续每次请求的 payload，spinner 转圈时间会肉眼可见地缩短。如果你正在做一个跨多个文件的大改动，索性就在完成一个阶段后/clear开新会话，让模型轻装上阵。

3.4 最小复现实验：用二分法定位触发条件

如果日志、API、上下文都查过，问题依然无法解释，那就做最小复现。把当前任务拆到一个全新的空会话里，只给它一个极小的指令、只涉及一个文件，看还会不会卡。如果小任务不卡，那就是原会话的累积信息量太大；如果小任务也卡，再看是不是特定目录、特定命令或者特定输入触发的。

我遇到过一次非常奇怪的情况：只要让 Claude Code 读取某个固定目录，spinner 就会卡 20 秒，但其他目录完全正常。最后查出来是那个目录里挂载了一个网络磁盘，每次读取目录都要等网络超时。这种问题靠“全局重装”是解决不了的，必须用最小复现把它逼出来。

4. 针对性解决方案与实践配置

4.1 管好上下文，从源头降低每次请求的耗时

上下文管理是解决 Claude Code 卡顿最直接的手段。我自己当前的标准操作是：任务开始前用CLAUDE.md固化项目约定，避免每轮对话重复描述项目背景；需要贴代码时，不整段粘贴，而是先用 grep 把关键行筛出来再贴；任务每完成一个小里程碑就/clear一次，让会话始终维持在“轻量”状态。

# 查看当前上下文占用（在会话中输入斜杠命令即可） /context # 压缩历史，保留核心上下文 /compact # 彻底清空当前会话 /clear

压缩之后模型的“记忆”会丢掉一些细节，如果发现它忘了前面的约定，把关键约定补进CLAUDE.md即可。这不是妥协，而是提高效率的正确姿势——让模型每次只聚焦当前最重要的信息，响应速度才能稳定。

4.2 调整环境变量与重试策略

Claude Code 支持通过环境变量控制一些运行参数。比如设置最大输出 token、超时时间、重试次数等。在 bash 或 PowerShell 里导出环境变量后再启动，可以避免某些请求无限制地等下去。

# 限制单次最大输出 token，避免生成过长内容导致终端长时间转圈 export CLAUDE_CODE_MAX_OUTPUT_TOKENS=4096 # 通过环境变量设置 API 端点（第三方兼容端点时常用） export ANTHROPIC_BASE_URL="https://your-endpoint.example.com" export ANTHROPIC_API_KEY="your-api-key"

对于第三方模型或本地模型，重点要关注并发和超时参数。有些兼容服务本身吞吐很低，如果你还开了多个会话同时跑，互相排队会让每个任务都显得“卡死”。我一般只在单个会话里跑重活，其他窗口只读代码。

4.3 给终端减负：换终端、降插件、开缓冲

终端渲染是最容易被忽略的卡顿源。Windows 上优先换 Windows Terminal，关掉旧终端的快速编辑模式；macOS 上用 iTerm2 或保持终端应用为最新版本；Linux 桌面环境下，实测 Ghostty 和 kitty 的渲染性能都比较好。同时把终端缓冲区加大，这样大量日志输出时不会触发频繁滚动重绘。

如果你在 VS Code 里用 Claude Code，建议做个对比实验：把那些非必要的扩展临时禁用，特别是自动保存、自动格式化、GitLens 这类高频监听插件。很多时候，你感觉是 Claude Code 卡，其实是编辑器本身在背后疯狂做增量索引和代码检查，把 CPU 占满了。

4.4 接入第三方模型与本地模型时的特殊卡点

热词里很多人提到用 cc-switch 接 DeepSeek、Qwen、GLM，或者用 LM Studio 跑本地模型。这类方案能跑通，但卡点会更隐蔽。第三方兼容端点通常吞吐和限流策略跟官方不一致，请求量稍大就会被限速。本地模型则完全受显卡算力约束：模型量化精度太低、上下文窗口设得太大、显存不够触发 CPU offload，都会让 token 生成速度掉到每秒几条。

接入后的第一件事不是干大活，而是先测速。给第三方端点发一个 100 token 的小请求，记录总耗时；给本地模型也发同样的小请求，对比官方 API。如果你算下来每秒生成速度连 20 token 都不到，那后续任何复杂任务都会很卡。正确的策略是把任务拆小块，减少单次 token 生成量，同时把上下文窗口调小，别让本地模型不断把旧内容搬进显存。

5. 高频卡顿场景速查表与隐蔽坑

5.1 先检索这个表，再决定要不要重装

下面这张对照表是我从实际运维自己环境的过程中总结出来的。遇到卡顿，先花 30 秒对照一下，比直接重装工具高效得多。

5.2 几个容易被忽略的隐蔽坑

我额外整理几个常规文档里不会写的坑，这些我都是真金白银踩出来的。

第一个是日志文件膨胀。Claude Code 跑久了日志文件可能涨到几个 GB，日志写入和终端监听都会拖累整体性能。定期清空~/.claude/logs下的旧日志，很多“越用越卡”的问题直接消失。

第二个是输入法冲突。Windows 上使用中文输入法时，终端里的键盘事件偶尔会被 IME 拦截，导致你感觉“输入没反应”。如果你发现自己敲命令时明显延迟，但 spinner 早就不转了，留意一下系统托盘里的输入法状态。

第三个是时钟不同步。API 通信依赖 TLS 证书和认证签名，如果本机时间偏差过大，握手阶段会反复失败重试，表象就是每次请求前先卡十几秒。跑一下系统时间同步，卡顿莫名消失的情况我见得太多了。

第四个是残留 hook 或自动化脚本。Claude Code 支持自定义 hook，会在特定事件触发时执行脚本。如果 hook 脚本写得有性能问题或者网络请求超时，它会阻断主流程。检查一下配置里有没有无效或过时的 hook，暂时禁用对比一下速度。

5.3 最后分享一个我自己常用的“十分钟排障法”

不吹不黑，我用这套方法解决过至少十几次卡顿：先开调试模式看日志，确认卡点在哪一层；再用 curl 测 API 最小请求，排除服务端问题；然后看/context和/status，确认上下文和账户状态；最后再用最小复现实验确认是不是某个特定文件或目录的问题。整套流程十分钟内做完，一般都能定位到根因。

说得直接一点，Claude Code 卡顿这件事，九成以上不是工具坏了，而是上下文、环境和服务端三者之间的匹配出了问题。别急着卸载重装，先花十分钟按这套流程走一遍，多半能找到能立竿见影的解法。如果你也有过离奇的卡顿经历，对照上面的速查表逐项试过来，应该比网上那些“重启一下就好”的回复靠谱得多。