Claude Code 安装卡住、很慢、失败怎么办：先测下载服务器，再按报错对照（下载中断、Killed、PATH、PowerShell）

本文根据 Claude Code 官方文档《Troubleshoot installation and login》《Troubleshooting》整理，资料核对于 2026-11-05。配图为本站整理的示意图，不是界面截图。本站（bigolab.com）不是 Anthropic 官方网站。

适用于谁

• 搜「claude code 安装卡住」「claude code 安装失败」，安装命令跑到一半不动或报错的人；
• 安装一直很慢，不知道是网络问题还是别的问题的人；
• 装完提示 command not found，或者 Windows 上命令一执行就报错的人。

官方没有单独写一节「安装很慢」。下面按官方对「下载中断」「超时」「内存不足」等情况的通用排查来归类，原文用的是英文报错，本文保留原文。

结论先说

1. 第一步永远是测下载服务器：安装器从 downloads.claude.ai 下载。macOS 和 Linux 运行 curl -sI https://downloads.claude.ai/claude-code-releases/latest；Windows PowerShell 要写成 curl.exe -sI ...（PowerShell 里的 curl 是 Invoke-WebRequest 的别名，不认 -sI）。第一行是 200 就说明连上了。
2. 下载中断官方会自动重试：最多 3 次，仍失败会提示 The connection dropped while downloading the update，一般再运行一遍 claude update 就好；下载超过 10 分钟没完成，报 Download timed out: exceeded the total deadline，这一类官方不会自动重试。
3. Linux 小内存服务器上出现 Killed，多半是内存不足：官方说安装需要约 512 MB 空闲内存，运行 Claude Code 需要更多，至少 4 GB 内存。
4. Windows 上先看你用的是 PowerShell 还是 CMD，用错命令是最常见的原因。
5. 装完 command not found 是 PATH 问题，不是没装上，把安装目录加进 PATH 并开一个新终端。

图：本站根据 Claude Code 官方文档：Troubleshoot installation and login 整理的示意图

一、先测网络

返回结果的含义，官方写得很清楚：

• 第一行是 200：连上了；
• 403：通常是代理或网络过滤拦截了这个域名，或者 Claude Code 在你所在的国家不可用（官方有支持国家和地区名单，见 /guides/claude-supported-countries-regions）；
• 5xx：多半是服务暂时有问题，等几分钟再试，状态页怎么看见 /guides/claude-down-check-status-page；
• 没有输出、Could not resolve host、连接超时：说明网络把这个连接拦了。常见原因是公司防火墙或代理拦截了 downloads.claude.ai，或者 TLS/SSL 的问题（更新系统 CA 证书，或检查有没有配 HTTPS_PROXY）。

如果你在公司网络里，需要代理，官方的做法是在安装前设置 HTTP_PROXY 和 HTTPS_PROXY，再运行安装命令：

bash
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell 对应的是 $env:HTTPS_PROXY = '...'，再运行 irm https://claude.ai/install.ps1 | iex。代理地址问你们的 IT 要。

二、下载卡住或中途断开

• curl: (56) 或 curl: (23) Failure writing output to destination：Bash 没收到完整脚本。56 表示下载本身被中断，23 表示 curl 写不进管道（通常是 Bash 提前退出了）。官方建议先测连通性，若能连上，多半是偶发，重试即可；也可以换一种安装方式（macOS 用 brew install --cask claude-code，Windows 用 winget install Anthropic.ClaudeCode）。这两种方式装出来的版本默认不会自动更新，更新见 /guides/claude-code-update-uninstall。
• The connection dropped while downloading the update：连接在下载时被关闭，重试三次都没成功。官方说长时间传输可能被代理或网关截断，建议再运行 claude update，必要时设 HTTPS_PROXY，企业网络要让网络团队放行 downloads.claude.ai 的完整下载。
• Release verification failed for Claude Code：Claude Code 没法确认要安装的版本是可信的，所以什么都没装，旧版本继续可用。官方让你按括号里的原因处理：以 sidecar_fetch_ 开头的，原命令再运行一次；其他原因稍后再试。反复出现可以反馈给官方。
• 红色的 Auto-update failed · Run claude doctor：后台自动更新没装上，可以继续工作。官方说 claude doctor 只给日期不给原因，想真正完成更新要在 shell 里运行 claude update，看它报的具体错误。
• claude update 或 claude doctor 卡在 Checking for updates 没输出：官方说这两条命令会扫描 ~/.zshrc、~/.bashrc 等 shell 配置文件找过时的 claude 别名，如果其中某个路径是目录，旧版本会卡住。更新到 v2.1.214 或更新版本即可；旧版本上卡住时，用 ls -ld 找到那个目录挪开，或重跑安装脚本。

三、Linux 和 Docker 上的卡住

Killed 或 Installation was killed before it could finish (exit code 137)：官方说退出码 137 在 Linux 上是 SIGKILL，小内存机器上通常是内核的 OOM（内存不足）杀掉了安装。官方给的办法：

1. 加 swap。官方示例是创建 2 GB 的 swap 文件：sudo fallocate -l 2G /swapfile，sudo chmod 600 /swapfile，sudo mkswap /swapfile，sudo swapon /swapfile，然后重新安装；
2. 关掉其他进程腾内存；
3. 能的话换大一点的机器。

Docker 里装到一半不动：官方说在 Docker 里以 root 在 / 下安装可能卡住，因为从 / 运行时安装器会扫描整个文件系统，占用大量内存。解决办法是先设置工作目录：

dockerfile
WORKDIR /tmp
RUN curl -fsSL https://claude.ai/install.sh | bash

用 Docker Desktop 的话，构建容器共用虚拟机的内存，可以在 Settings > Resources 里调高内存上限后重新构建。

四、Windows 上的几类问题

图：本站根据 Claude Code 官方文档：Troubleshoot installation and login 整理的示意图

• 'irm' is not recognized、The token '&&' is not a valid statement separator、A parameter cannot be found that matches parameter name 'fsSL'、'bash' is not recognized：官方说这是你复制了另一个系统或另一个 shell 的安装命令。在 PowerShell 里用 irm https://claude.ai/install.ps1 | iex；在 CMD 里用 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd。命令只复制了一半（只下载没执行）也会出现「打印一堆脚本但什么都没装」。
• The process cannot access the file ... because it is being used by another process：安装器没法写 %USERPROFILE%\.claude\downloads，通常是上一次安装还在跑，或杀毒软件在扫描没下完的文件。关掉其他安装窗口、等杀毒扫描结束，删掉 downloads 文件夹再装一遍。
• Claude Code does not support 32-bit Windows：官方说开始菜单里有 Windows PowerShell 和 Windows PowerShell (x86) 两个入口，后者是 32 位进程，在 64 位机器上也会报这个错，要开前者。
• Claude Code on Windows requires either Git for Windows (for bash) or PowerShell：官方说 Git for Windows 是可选的，Git Bash 不在时 Claude Code 用 PowerShell 工具，这个报错说明两者都没找到。可以装 Git for Windows（安装时选 Add to PATH），或把 PowerShell 的目录加进 PATH。Git 的完整说明见 /guides/claude-code-install-methods-git-npm-official。
• running scripts is disabled on this system：这是用 npm 安装时，PowerShell 的执行策略拦了 .ps1 启动脚本。官方的办法：Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser，或改用 .cmd 启动器，或直接用 PowerShell 安装器。

五、装完提示 command not found

官方说这表示安装目录不在 PATH 里：安装器把 claude 放在 macOS/Linux 的 ~/.local/bin/claude 或 Windows 的 %USERPROFILE%\.local\bin\claude.exe。检查和加 PATH 的命令在官方「Verify your PATH」一节，按你的系统选。加完要开一个新终端。其他常见报错对照见 /guides/claude-code-common-errors。

装好之后

装好并用 claude 登录后，是用订阅登录还是 API 计费，可以先看 /guides/claude-code-pro-max-or-api；需要订阅的可以了解 /chongzhi/claude-code。第一次怎么用见 /guides/claude-code-getting-started。

常见问题

Q：安装很慢，怎么加速？

官方没有提供「加速」选项。它的做法是下载失败时自动重试，总下载时限 10 分钟。官方没有解释「慢」的原因；先用第一节的命令测一下到 downloads.claude.ai 的连通情况，再按报错归类处理。

Q：能不能先装个图形界面的？

官方的排查页提到，不想用终端的话，可以用 Claude Code 桌面版，通过图形界面安装和使用，介绍见 /guides/claude-code-desktop。

Q：官方的 claude doctor 是干什么的？

官方说 claude doctor 是在 shell 里运行的安装诊断；能进入 Claude Code 之后，用 /doctor 做安装、设置、扩展和上下文使用的检查，并给出可在你确认后应用的修复。

相关教程

• /guides/claude-code-install-methods-git-npm-official：四种安装方式怎么选
• /guides/claude-code-update-uninstall：更新和卸载

参考资料

• Claude Code 官方文档：Troubleshoot installation and login — https://code.claude.com/docs/en/troubleshoot-install
• Claude Code 官方文档：Troubleshooting — https://code.claude.com/docs/en/troubleshooting