安装与更新 Claude Code CLI：Mac、Linux、Windows

安装 Claude Code 每个平台都只需一条命令：在 macOS、Linux 和 WSL 上执行 curl -fsSL https://claude.ai/install.sh | bash，在 Windows PowerShell 中执行 irm https://claude.ai/install.ps1 | iex；更新则要么自动完成（默认行为），要么一条 claude update 搞定。大多数页面略过的，恰恰是第一条命令之后的部分：有四种方式时该选哪一种安装方法、自动更新器如何工作又如何关闭、如何锁定到某个特定版本，以及如何干净地卸载每一种安装方式。本页就是这份参考，一项任务配一张表，内容截至 v2.1.224（2026 年 8 月）。¹

TL;DR

• 请使用原生安装器。 它不依赖 Node.js，为每个平台提供经过测试的二进制文件，自 v2.1.113 起就是默认方式。npm 包属于遗留方案，自 v2.1.15 起已弃用，如今还要求 Node.js 22 及以上版本。¹
• 更新默认是自动的： Claude Code 会在启动时以及会话进行中定期检查，在后台下载，并在下次启动时应用。claude update 则立即强制更新一次。²
• 关闭更新有两个不同的开关： DISABLE_AUTOUPDATER=1 停止后台更新；DISABLE_UPDATES=1（v2.1.118 及以上）会封锁所有更新路径，包括手动执行的 claude update。²
• 锁定版本只需把版本号传给安装器：curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58。用 claude --version 查看当前运行的版本，用 /release-notes 浏览各版本改动。¹²
• 一旦出现异常，先运行 claude doctor——它会报告安装类型、版本和检测到的问题；自 v2.1.205 起，会话内的 /doctor 不仅能诊断，还能直接修复配置问题。²

如何安装 Claude Code CLI？

按平台，各一条命令：

# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

更习惯用包管理器？两种都是一等公民：

brew install --cask claude-code          # macOS / Linux (stable channel)
winget install Anthropic.ClaudeCode      # Windows

随后在项目目录中运行 claude，使用 Claude Pro/Max/Team 订阅或 Anthropic API 账户完成认证即可。¹ 原生安装器不需要 Node.js，不需要 sudo，也不需要任何预装组件。如果必须走遗留的 npm 路径（npm install -g @anthropic-ai/claude-code），它要求 Node.js 22 或更高版本，并且绝不要用 sudo 运行——归 root 所有的全局模块会带来一直遗留到安装之后的权限问题。¹ 已经用了 npm？claude install 会就地把你迁移到原生二进制文件。

关于首次会话的准备工作——认证方式的选择、第一条提示词、权限模式——快速上手教程覆盖了从零到首个结果的完整路径。

Claude Code 支持哪些平台？

关于 Windows 反复出现的那个问题，答案是：原生 Windows 可以直接使用，且无需管理员权限；Anthropic 自己的建议是按项目所在位置和所需功能来选择，需要 Linux 工具链或沙箱化命令执行时选用 WSL 2，同一个 Linux 安装器也可以在其中运行。³ Claude Code 自动模式不是安全边界一文认为，真正的边界是操作系统隔离，而不是自动模式。

如何更新 Claude Code？

通常你不需要动手。Claude Code 默认自动更新——它会在启动时以及会话过程中定期检查新版本，在后台下载，并在下次启动时应用更新。² 若想立刻强制更新，或者你已经关闭了自动更新器：

claude update

通过包管理器安装的版本，走各自的渠道更新——brew upgrade --cask claude-code、winget upgrade Anthropic.ClaudeCode；自 v2.1.129 起，设置 CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1 可让这类安装在后台执行包管理器升级，并提示重启。²

控制更新靠的是两个彼此独立的开关，在受限环境中这个区别相当关键：

两者都可以设为环境变量，或写在 settings.json 的 "env" 之下。²

如何安装指定版本？

把版本号传给安装器即可——复现某个 bug、让团队停留在已知可用的版本，或者回滚时，这一招都很有用：

# Specific version
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

# Latest, explicitly
curl -fsSL https://claude.ai/install.sh | bash -s latest

# Windows PowerShell, specific version
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58

用 claude --version 确认，再通过会话内的 /release-notes 选择器阅读每个版本的改动。² 如果锁定了版本，记得同时设置 DISABLE_AUTOUPDATER=1——否则自动更新器会在下次启动时彬彬有礼地帮你解除锁定。（若连手动的 claude update 也要禁掉，改用 DISABLE_UPDATES=1。）

如何卸载 Claude Code？

卸载方式要与安装方式对应：

配置单独存放在 ~/.claude/ 中，因此删除二进制文件不会清除设置、技能或历史记录——只有当你真想彻底重来时，才一并删掉那个目录。¹

一张表看完整个生命周期

而当出现异常时——报告的版本不对、更新后找不到命令、安装只完成了一半——在 shell 中运行 claude doctor 会报告安装类型、版本和检测到的问题；会话内的 /doctor（v2.1.205 及以上）则会做一次完整体检，并且能修复它发现的问题。² 安装之后的一切——配置、权限、hooks、MCP 和子代理——都在 Claude Code 完整指南中。

Windows 故障排除：claude 无法识别、Shell 用错、脚本被阻止

Windows 上的大多数故障都属于以下九种之一，每一种都有可辨认的错误信息。下面的每项修复都来自 Anthropic 的安装故障排除页面和设置页面，内容截至 2026 年 9 月 7 日。³⁴

1. 'claude' is not recognized as an internal or external command（CMD）或 The term 'claude' is not recognized as the name of a cmdlet（PowerShell）。 安装器把 claude.exe 放在了 %USERPROFILE%\.local\bin\claude.exe；要么该目录不在您的 PATH 中，要么您仍在执行安装的那个终端里，而它保留着旧的 PATH。先检查，再添加，然后打开一个新终端：⁴

$env:PATH -split ';' | Select-String '\.local\\bin'      # no output = not on PATH
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

在 CMD 中，检查命令是 echo %PATH% | findstr /i "local\bin"，修复方法是在“环境变量”中把 %USERPROFILE%\.local\bin 添加到用户 PATH。⁴

2. 'irm' is not recognized、The token '&&' is not a valid statement separator 或 A parameter cannot be found that matches parameter name 'fsSL'。 您运行的是另一种 shell 的安装命令。缺少 irm 说明您在 CMD 中（提示符为 C:\）：请使用上文的 CMD 安装命令，或打开 PowerShell（PS C:\）。&& 被拒绝说明您在 PowerShell 中运行了 CMD 的命令：请改用 irm https://claude.ai/install.ps1 | iex。报错提到 fsSL，说明您把 macOS/Linux 的 curl -fsSL ... | bash 命令粘贴进了 PowerShell，而在 PowerShell 里 curl 是 Invoke-WebRequest 的别名。如果命令打印出脚本文本却什么都没安装，说明您只运行了下载那一半，缺少执行脚本的那一部分。⁴

3. running scripts is disabled on this system / PSSecurityException。 PowerShell 的执行策略阻止了 npm 创建的 .ps1 启动垫片（npm.ps1、claude.ps1）。它不影响原生安装器，因为原生安装器通过 iex 执行下载下来的文本，而不是一个保存在磁盘上的文件；至于把 ClaudeInstall.ps1 保存下来再用 -ExecutionPolicy Bypass -File 运行，并不属于 Anthropic 文档中的安装路径（设置页面只列出 irm 命令、CMD 安装命令、WinGet 和 npm）。修复方法依次为：Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser；或者调用 claude.cmd（该策略不覆盖 .cmd）；或者用原生安装器替换 npm 安装。⁴

4. iex 解析错误中引用了 HTML 标签或 CSS，或者出现 curl: (22) The requested URL returned error: 403。 安装地址返回的是网页而不是脚本。如果页面显示“App unavailable in region”，说明 Claude Code 未在您所在的国家或地区提供；否则就是代理或过滤器从中阻拦。可用 curl.exe -sI https://downloads.claude.ai/claude-code-releases/latest 测试连通性（务必显式调用 curl.exe，因为 PowerShell 的 curl 别名不接受 -sI）：第一行为 200 即表示主机可达，此前的失败只是暂时性的。文档给出的替代方案是 winget install Anthropic.ClaudeCode。⁴

5. Could not establish trust relationship for the SSL/TLS secure channel，或 CRYPT_E_NO_REVOCATION_CHECK (0x80092012)。 对于前者，请在运行安装器之前强制使用 TLS 1.2：[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12。吊销相关的错误说明您的网络阻止了证书吊销查询：在 CMD 的 curl 命令中加上 --ssl-revoke-best-effort，或者改用 PowerShell 安装器，它通过 .NET 下载，能够容忍无法访问的吊销服务器。⁴

6. The process cannot access the file ... because it is being used by another process。 之前的安装器仍在运行，或者杀毒软件正在扫描 %USERPROFILE%\.claude\downloads 中下载了一半的文件。关闭其他 PowerShell 窗口，等待扫描结束，然后执行：⁴

Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\downloads"
irm https://claude.ai/install.ps1 | iex

7. 运行的版本不对，或两个安装互相冲突。 where.exe claude 会列出 PATH 上的每一个 claude；Test-Path "$env:USERPROFILE\.local\bin\claude.exe" 可以确认原生安装器是否放置了它的二进制文件。保留原生版本，移除其余的（winget uninstall Anthropic.ClaudeCode、npm uninstall -g @anthropic-ai/claude-code，遗留的本地 npm 安装则用 Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\local"）。claude doctor 会打印它实际运行的安装类型和版本。⁴

8. Claude Code on Windows requires either Git for Windows (for bash) or PowerShell。 两种 shell 都没有找到。Git for Windows 是可选的：没有它，Claude Code 通过其 PowerShell 工具运行命令；装了它，Bash 工具会使用 Git Bash。如果已安装 Git Bash 却找不到，请在 settings.json 中指定它的路径：³

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

9. Claude Code does not support 32-bit Windows。 您在 64 位机器上打开了 x86 版的 PowerShell 入口。请打开“Windows PowerShell”，而不是带“(x86)”的那一项。⁴

如果以上都对不上，claude doctor（只读，不会启动会话）会报告安装健康状况、设置文件错误以及上一次更新尝试的结果；Anthropic 的故障排除页面则保留着完整的错误与修复对照表。³⁴

常见问题

如何把 Claude Code CLI 更新到最新版本？

运行 claude update，或者干脆重启——Claude Code 默认会在启动时和会话过程中检查更新，在后台下载并于下次启动时应用。通过 Homebrew 和 winget 安装的版本，则分别用 brew upgrade --cask claude-code 和 winget upgrade Anthropic.ClaudeCode 更新。

Claude Code 会自动更新吗？

会，这是默认行为：它在启动时以及运行过程中定期检查，然后在下次启动时应用已下载的更新。DISABLE_AUTOUPDATER=1 关闭后台更新但保留手动的 claude update；DISABLE_UPDATES=1 则封锁所有更新路径。

如何在 Windows 上安装 Claude Code？

在 PowerShell 中运行 irm https://claude.ai/install.ps1 | iex（或 winget install Anthropic.ClaudeCode）。原生 Windows 10（1809+）在 x64 和 ARM64 上均受支持，且无需管理员权限；需要 Linux 工具链或沙箱化命令执行时，请选择 WSL 2，并在其中运行 Linux 的安装命令，以获得与 Linux 完全一致的体验。

安装 Claude Code 需要 Node.js 吗？

不需要——推荐的原生安装器不依赖 Node.js。只有遗留的 npm 包（npm install -g @anthropic-ai/claude-code，自 v2.1.15 起弃用）才需要 Node，且要求 Node.js 22 或更高版本。如果你用的是 npm 安装，claude install 会把你迁移到原生二进制文件。

如何查看自己用的是哪个版本的 Claude Code？

在 shell 中执行 claude --version，或在会话内使用 /release-notes 打开交互式更新日志选择器。claude doctor 还会额外报告安装类型和检测到的配置问题。