Claude Code 怎么安装、登录与更新（macOS / Linux / Windows / WSL）（2026）

推荐链接（推广）：数字严选大约 16 分钟ClaudeClaude Code 安装Claude Code 登录command not foundclaude doctor

阅读说明

官方信息查阅日期：2026-10-23。Claude Code 文档会更新，以官方原文为准。本文不写价格。

一句话结论

在终端里按系统运行官方安装命令，新开一个终端执行 claude --version，看到版本号后再运行 claude，按浏览器提示登录。原生安装会在后台自动更新。免费的 claude.aiopen in new window 计划不包含 Claude Code。

系统要求

Advanced setupopen in new window 写明的平台和配置：

项目	文档要求
操作系统	macOS 13.0+；Windows 10 1809+ 或 Windows Server 2019+；Ubuntu 20.04+；Debian 10+；Alpine Linux 3.19+
硬件	4 GB 以上内存，x64 或 ARM64
网络	需要联网
Shell	Bash、Zsh、PowerShell 或 CMD
地区	Anthropic supported countriesopen in new window，见 Claude 支持哪些国家和地区

额外依赖：ripgrep 通常已经随 Claude Code 带上。搜索失败时，文档指向搜索排错，不在本文展开。

快速开始还要求：终端已打开，手头有一个代码项目，以及 Claude 订阅（Pro、Max、Team 或 Enterprise）、Claude Consoleopen in new window 账号，或文档列出的云厂商访问。

安装命令

文档把原生安装标为推荐。安装命令下载时不显示进度。装完后新开一个终端，再运行 claude --version。

macOS、Linux、WSL：

curl -fsSL https://claude.ai/install.sh | bash

Windows 上，提示符是 PS C:\ 时为 PowerShell，没有 PS 的 C:\ 为 CMD。

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

Homebrew（不会自动更新；claude-code 跟踪 stable，通常比最新版晚大约一周，并跳过有重大回归的版本；claude-code@latest 跟踪最新通道）：

brew install --cask claude-code

WinGet（不会自动更新）：

winget install Anthropic.ClaudeCode

也可以用 npm。需要 Node.js 22 或更高。文档写明不要使用 sudo npm install -g。

npm install -g @anthropic-ai/claude-code

Debian、Fedora、RHEL、Alpine 还可以用 apt、dnf 或 apk。仓库地址、签名指纹和完整命令在 Advanced setupopen in new window 的 Linux 包管理器一节。本文不重复那一段。

装好后，在项目目录启动：

cd /path/to/your/project
claude

把路径换成你的项目。原生安装会在后台自动更新到最新版。

想装 stable 通道而不是最新版时，macOS、Linux、WSL：

curl -fsSL https://claude.ai/install.sh | bash -s stable

Windows PowerShell：

& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) stable

Windows CMD：

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd stable && del install.cmd

指定版本号时，把上面的 stable 换成版本号。文档的例子是 2.1.89。claude --version 会打印你传入的那个版本。

不想用终端时，文档提供桌面应用：macOSopen in new window、Windowsopen in new window。Linux 桌面应用按文档用 apt 安装。

Windows 本机还是 WSL

方式	文档写的条件	Sandboxing	何时用
本机 Windows	无额外要求；Git for Windowsopen in new window 可选	不支持	Windows 本机项目和工具
WSL 2	已启用 WSL 2	支持	Linux 工具链，或需要沙箱执行命令
WSL 1	已启用 WSL 1	不支持	没有 WSL 2 时

本机 Windows 不必用管理员身份安装。没有 Git for Windows 时，shell 命令走 PowerShell 工具；装了之后，Bash 工具使用 Git Bash。WSL 不需要 Git for Windows。在 WSL 发行版里运行 Linux 安装命令，并在 WSL 终端里启动 claude，不要从 PowerShell 或 CMD 启动。

Claude Code 找不到 Git Bash 时，在 settings.json 里写上路径：

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

Alpine 与 musl

Alpine 和其他 musl/uClibc 发行版上，安装命令需要 bash 和 curl，运行时需要 libgcc、libstdc++ 和 ripgrep。文档写明，默认没有 bash 或 curl 时，安装命令会报 not found。Alpine 示例：

apk add bash curl libgcc libstdc++ ripgrep

ripgrep 在 community 仓库。apk 说找不到包时，把你的 Alpine 版本写进 /etc/apk/repositories。文档示例是：

echo "https://dl-cdn.alpinelinux.org/alpine/v3.22/community" >> /etc/apk/repositories

然后 apk update，再执行上面的 apk add。并在 settings.json 里设置：

{
  "env": {
    "USE_BUILTIN_RIPGREP": "0"
  }
}

确认装好了

claude --version

正常时会打印版本号，文档举例为 2.1.211 (Claude Code)。快速开始写的是版本号后面带 (Claude Code)。

更完整的只读检查（不启动会话），包括安装健康、设置文件校验和带建议的警告：

claude doctor

会话已经能打开、但想在里面做检查时，文档写的是输入 /doctor。claude 完全起不来时，用上面的 shell 命令。

类型	文档说明
Claude Pro、Max、Team 或 Enterprise	标为推荐
Claude Console	API 访问。首次登录会在 Console 里自动创建一个名为 “Claude Code” 的 workspace
Amazon Bedrock、Google Cloud’s Agent Platform 或 Microsoft Foundry	企业云
自建 Claude apps gateway	管理员预先配置网关地址。`/login` 会直接打开 Cloud gateway 画面，用企业 SSO 登录

登录成功后凭证会保存，不必每次再登。以后切换账号或重新认证，在会话里输入 /login。浏览器没有自动打开时，按 c 把 OAuth URL 复制到剪贴板，再粘贴到浏览器。

更新

原生安装会在启动时以及运行期间检查更新，在后台下载安装，下次启动 Claude Code 时生效。要立刻更新：

claude update

装上更新时，命令报告 Successfully updated from <old version> to version <new version>。已经是最新版时，报告 Claude Code is up to date (<version>)。Homebrew、WinGet 或 apk 管理的安装则会报告 Claude is up to date!。

Homebrew、WinGet、apt、dnf、apk 默认不自动更新。手动命令：

brew upgrade claude-code

如果装的是 latest cask，把上面的包名换成 claude-code@latest。

winget upgrade Anthropic.ClaudeCode

sudo apt update && sudo apt upgrade claude-code

sudo dnf upgrade claude-code

apk update && apk upgrade claude-code

让 Claude Code 在 Homebrew 或 WinGet 上代为执行升级：把 CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE 设为 1。升级只针对 Claude Code 这一个包。WinGet 上如果 Claude Code 正在运行，Windows 会锁住可执行文件，这时改为显示手动命令。apt、dnf、apk 仍需手动升级，因为那些命令要更高权限。

发布通道用设置 autoUpdatesChannel："latest" 是默认，功能一发布就收到；"stable" 使用通常大约一周前的版本，并跳过有重大回归的发布。可以在 /config 里找 Auto-update channel，或写入 settings.json：

{
  "autoUpdatesChannel": "stable"
}

Homebrew 用 cask 名字选通道，不用这项设置。apt、dnf、apk 用仓库选通道。

只关后台检查、仍允许手动 claude update 和 claude install：

{
  "env": {
    "DISABLE_AUTOUPDATER": "1"
  }
}

在原生或 npm 安装上，用 claude doctor 确认 Auto-updates 一行显示 disabled (set by env: DISABLE_AUTOUPDATER)。要连手动更新一起挡住，文档写的是改设 DISABLE_UPDATES。

npm 升级用：

npm install -g @anthropic-ai/claude-code@latest

文档写明避免 npm update -g，因为它沿用当初安装的 semver 范围，不一定到最新版。

卸载

按当初的安装方式删除。删完 claude 还能运行，文档认为是还有第二份安装或旧的 shell 别名。

原生安装，macOS、Linux、WSL：

rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude

Windows PowerShell：

Remove-Item -Path "$env:USERPROFILE\.local\bin\claude.exe" -Force
Remove-Item -Path "$env:USERPROFILE\.local\share\claude" -Recurse -Force

brew uninstall --cask claude-code

latest cask 则是 brew uninstall --cask claude-code@latest。

winget uninstall Anthropic.ClaudeCode

npm uninstall -g @anthropic-ai/claude-code

apt、dnf、apk 的卸载命令，包括删仓库配置，在同一篇 setup 文档的 Uninstall 一节。

删除配置会去掉全部设置、允许的工具、MCP 服务器配置和会话历史。VS Code 扩展、JetBrains 插件和桌面应用也会写入 ~/.claude/。要连这些一起去掉，先卸扩展、插件和桌面应用，再删下面的文件。

macOS、Linux、WSL：

rm -rf ~/.claude
rm ~/.claude.json
rm -rf .claude
rm -f .mcp.json

后两行在项目目录里执行。Windows PowerShell：

Remove-Item -Path "$env:USERPROFILE\.claude" -Recurse -Force
Remove-Item -Path "$env:USERPROFILE\.claude.json" -Force
Remove-Item -Path ".claude" -Recurse -Force
Remove-Item -Path ".mcp.json" -Force

安装和登录报错

下表是安装与登录文档里出现频率较高的几类。运行中的 API Error: 500、529 等见 Claude Code 报错对照。

你看到的	文档给的方向
`command not found: claude` 或 `'claude' is not recognized`	把安装目录加进 PATH
`syntax error near unexpected token '<'`，或页面里出现 `App unavailable in region`	下载到的不是安装脚本
`'irm' is not recognized` 或 `The token '&&' is not a valid statement separator`	命令和当前 shell 不一致
`running scripts is disabled on this system`	npm 的 `.ps1` 被 PowerShell 执行策略拦住
`OAuth error: Invalid code`，或文档所称的 login loop	重新登录；账号问题走支持
`API Error: 403 Request not allowed`	核对订阅、Console 角色或公司代理
`This organization has been disabled`	多半是残留的 `ANTHROPIC_API_KEY`

command not found: claude

安装已经结束，但 shell 找不到命令。文档列出的原文：

平台	报错
macOS	`zsh: command not found: claude`
Linux	`bash: claude: command not found`
Windows CMD	`'claude' is not recognized as an internal or external command`
PowerShell	`claude : The term 'claude' is not recognized as the name of a cmdlet`

原生安装把程序放在 macOS/Linux 的 ~/.local/bin/claude，或 Windows 的 %USERPROFILE%\.local\bin\claude.exe。安装程序发现目录不在 PATH 里时，会在 Setup notes: 下写 Native installation exists but ~/.local/bin is not in your PATH.（Windows 上是你的用户目录下的 .local\bin）。它打印改法，但不会自己改 PATH。

只装了 VS Code 扩展时，扩展自带一份 CLI，不放到这个路径，也不会写入 PATH。要在终端里用 claude，需要再做独立安装。

先确认文件在不在：

ls -la ~/.local/bin/claude

文件存在、但 echo $PATH 里没有 $HOME/.local/bin 时，Zsh（macOS 默认）：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Linux 上的 Bash：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

macOS 上的 Bash 写入 ~/.bash_profile 再 source。若已有 ~/.bash_login 或 ~/.profile、且没有 ~/.bash_profile，把这一行放进已经存在的那个文件。

Windows PowerShell：

$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

改完后重新打开终端，再运行 claude --version。编辑器里的终端沿用编辑器启动时的 PATH，需要退出并重新打开编辑器。

echo 写配置时如果出现 zsh: permission denied 或 bash: ... Permission denied，文件不可写。属主是别人（例如 root）时，文档写 sudo chown $(whoami) ~/.zshrc（路径换成你的配置文件）。属主是你自己、只是只读时，chmod u+w 那个文件，然后再执行上面的两行 PATH 命令。

Windows 上如果是刚更新完就变成 'claude' is not recognized，文档另有一节：从备份恢复 claude.exe。那是更新后的情况，和首次安装的 PATH 不是同一条。

syntax error near unexpected token '<'

安装命令拿到的是网页、XML 或错误状态，不是安装脚本。Bash 或 Zsh 常见：

bash: line 1: syntax error near unexpected token `<'
bash: line 1: `<!DOCTYPE html>'

CMD 上可能是 < was unexpected at this time.，后面跟着 HTML。PowerShell 上可能是 iex 在解析 HTML，或 The term 'System.Xml.XmlDocument' is not recognized。没有任何页面、只有状态码时：

curl: (22) The requested URL returned error: 403

输出里如果出现 App unavailable in region，文档写明 Claude Code 在你所在的国家不可用，并指向支持国家名单open in new window。见 Claude 支持哪些国家和地区。没有正文的 403 也可能是同一原因，也可能是公司代理或防火墙拦住了下载。

人在支持国家、仍然 403 时，文档要求先做网络检查，再试别的安装方式，因为那些方式访问的是同一批主机。其他情况，文档列为网络问题、区域路由或暂时的服务中断。官方步骤：

过几分钟，用原来的命令再试一次。
改用 Homebrew 或 WinGet（这两种默认不会自己更新）：

brew install --cask claude-code

winget install Anthropic.ClaudeCode

然后 claude --version。若仍提示找不到 claude，新开一个终端。当前这个终端还留着旧的 PATH。

公司网络要走代理时，文档写明在安装前设置 HTTPS_PROXY 和 HTTP_PROXY，地址向 IT 索取。这是公司代理配置，不是地区限制的绕过办法。地区不可用以支持国家名单为准。

irm is not recognized 与 && 不能用

这些表示命令和当前 shell 不一致，或只运行了命令的前半段：

'irm' is not recognized：你在 CMD，不在 PowerShell。打开 PowerShell 运行 irm https://claude.ai/install.ps1 | iex，或留在 CMD 使用上面的 install.cmd 命令。
The token '&&' is not a valid statement separator：你在 PowerShell，却运行了 CMD 命令。改用 PowerShell 那条 irm 命令。
A parameter cannot be found that matches parameter name 'fsSL'：在 Windows PowerShell 里运行了 macOS/Linux 的 curl -fsSL ... | bash。PowerShell 把 curl 映射成 Invoke-WebRequest。改用 PowerShell 安装命令。
'bash' is not recognized as the name of a cmdlet：在 Windows 上运行了 macOS/Linux 安装命令。改用 PowerShell 安装命令。
命令把脚本文本打印出来、什么都没装：只运行了下载的那一半。PowerShell 必须接到 iex。CMD 必须使用带 -o install.cmd 并且接着执行的完整命令。

running scripts is disabled on this system

通过 npm 在 Windows 上安装或运行时，可能出现 SecurityError，原文包含：

npm : File C:\Program Files\nodejs\npm.ps1 cannot be loaded because running scripts is disabled on this system.

运行 claude 时，同一错误会点名 claude.ps1。这是 PowerShell 执行策略拦住了 npm 生成的 .ps1。策略只管脚本文件，不管 irm https://claude.ai/install.ps1 | iex，因为那条命令直接执行下载到的文本。

文档给的办法：

为当前用户允许本地创建的脚本，然后重试：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

改调 .cmd 启动器。npm.cmd 和 claude.cmd 做同样的事，执行策略不管它们。
改用 PowerShell 原生安装命令，装的是二进制，不是 .ps1。

原因还不清楚时，文档写清洁的重新认证能解决大多数登录失败：

运行 /logout，完全退出登录。
关闭 Claude Code。
再用 claude 启动，重新完成认证。

看到 OAuth error: Invalid code. Please make sure the full code was copied，表示登录码过期，或复制时被截断。文档的做法：按 Enter 重试，并在浏览器打开后尽快完成；浏览器没自动打开就按 c 复制完整 URL；远程或 SSH 会话里，浏览器可能开在错误的机器上，把终端里的 URL 复制到本机浏览器。

WSL2、SSH 或容器里，浏览器通常在另一台主机上打开，重定向回不到 Claude Code 的本地回调。登录后浏览器会显示一段登录码，而不是自动跳回。把这段码粘贴到终端的 Paste code here if prompted 提示处。WSL2 里浏览器完全不打开时，可以把 BROWSER 设为 Windows 浏览器路径，文档的例子是：

export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"
claude

交互提示里粘贴没有反应时，文档写改用 claude auth login，它从标准输入读码。这个回退在本机 Windows 或其他粘贴失败的终端上同样适用。

会话中途又要求登录，文档认为 OAuth token 可能过期，运行 /login。如果经常发生，检查系统时钟，因为 token 校验依赖正确的时间。

文档在「仍然卡住」里把 login loop、订阅未被识别、组织被停用，列为账号问题而不是安装问题：在 claude.aiopen in new window 登录（Console 用户用 platform.claude.comopen in new window），点击左下角姓名缩写，选择 Get help。说明见 How to get supportopen in new window。

API Error: 403 Request not allowed

登录之后如果看到 API Error: 403 Request not allowed：

Claude Pro/Max：到 claude.ai/settingsopen in new window 确认订阅处于有效状态。
Anthropic Console：确认账号有 “Claude Code” 或 “Developer” 角色。管理员在 platform.claude.com/settings/membersopen in new window 的 Members 页分配。
公司代理可能干扰 API 请求。文档指向网络配置，不在本文展开代理绕过。

另一句不同的原文是：登录页显示 Authorization failed，以及 Claude Code access has not been granted for this account. Contact your administrator. 文档写明，这是 Claude Enterprise 组织把角色设成了 Custom，且分配到你所在群组的自定义角色都不包含 Claude Code。在 Claude Code 里改设置不能消除这句。需要组织的 Owner 在角色设置open in new window里分配带 Claude Code 的自定义角色，或把角色从 Custom 改成 User 这类标准角色。改完后重新运行 claude 并登录。

This organization has been disabled

有有效订阅仍看到 API Error: 400 ... "This organization has been disabled" 时，安装文档写明是 ANTHROPIC_API_KEY 盖过了订阅。取消变量、从 shell 配置里删除，再用 /status 确认。完整原文和步骤见 Claude 账号被停用与申诉。

安装问题查完仍不行，文档还写了：到 GitHub 仓库open in new window 看已知问题，或附上操作系统、所用安装命令和完整错误输出再开 issue；claude --version 能用时运行 claude doctor；会话能打开时用 /feedback。

常见问题

claude --version 有版本号，claude doctor 是必须的吗？

不是安装完成的额外门槛。claude --version 用来确认命令可用。claude doctor 是不启动会话的只读诊断。文档在安装失败、自动更新失败或配置异常时使用它。

原生安装、Homebrew、WinGet，哪个会自己更新？

文档写明原生安装在后台自动更新。Homebrew、WinGet 以及 apt、dnf、apk 默认要手动升级。Homebrew 和 WinGet 可以把 CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE 设为 1，由 Claude Code 代跑升级命令。

免费账号能登录 Claude Code 吗？

安装文档写明，免费的 claude.aiopen in new window 计划不包含 Claude Code。需要 Pro、Max、Team、Enterprise 或 Console 账号，或文档列出的第三方 API。

安装时提示地区不可用，换安装命令有用吗？

输出里是 App unavailable in region 时，文档写明在该国家不可用，并指向支持国家名单。没有正文的 403 还可能是代理或防火墙。人在支持国家时，文档要求先做网络检查。名单见 Claude 支持哪些国家和地区。

参考来源（官方）

Claude Code · Advanced setup：https://code.claude.com/docs/en/setupopen in new window（查阅日期：2026-10-23）
Claude Code · Quickstart：https://code.claude.com/docs/en/quickstartopen in new window（查阅日期：2026-10-23）
Claude Code · Troubleshoot installation and login：https://code.claude.com/docs/en/troubleshoot-installopen in new window（查阅日期：2026-10-23）
Anthropic · Supported countries：https://www.anthropic.com/supported-countriesopen in new window（查阅日期：2026-10-23）
Claude 帮助中心 · How to get support：https://support.claude.com/en/articles/9015913-how-to-get-supportopen in new window（查阅日期：2026-10-23）

Claude Code 怎么安装、登录与更新（macOS / Linux / Windows / WSL）（2026）

# 一句话结论

# 系统要求

# 安装命令

# Windows 本机还是 WSL

# Alpine 与 musl

# 确认装好了

# 登录

# 更新

# 卸载

# 安装和登录报错

# command not found: claude

# syntax error near unexpected token '<'

# irm is not recognized 与 && 不能用

# running scripts is disabled on this system

# OAuth error: Invalid code 与 login loop

# API Error: 403 Request not allowed

# This organization has been disabled

# 常见问题

# claude --version 有版本号，claude doctor 是必须的吗？

# 原生安装、Homebrew、WinGet，哪个会自己更新？

# 免费账号能登录 Claude Code 吗？

# 安装时提示地区不可用，换安装命令有用吗？

# 相关阅读

# 参考来源（官方）

一句话结论

系统要求

安装命令

Windows 本机还是 WSL

Alpine 与 musl

确认装好了

登录

更新

卸载

安装和登录报错

command not found: claude

syntax error near unexpected token '<'

irm is not recognized 与 && 不能用

running scripts is disabled on this system

OAuth error: Invalid code 与 login loop

API Error: 403 Request not allowed

This organization has been disabled

常见问题

claude --version 有版本号，claude doctor 是必须的吗？

原生安装、Homebrew、WinGet，哪个会自己更新？

免费账号能登录 Claude Code 吗？

安装时提示地区不可用，换安装命令有用吗？

相关阅读

参考来源（官方）