Skip to content
FunCoding

Search

Search docs, agents, posts, Skills and MCP servers

高级安装

系统要求、各平台安装方式、Windows 原生与 WSL 的取舍、Alpine 额外依赖、验证安装、认证、更新（通道、最低版本、禁用）、指定版本、Linux 包管理器、npm、二进制完整性与卸载。

本页讲系统要求、各平台的安装细节、更新和卸载。想要引导式的第一次会话，看快速上手。如果你从没用过终端，见官方的终端指南。下面的版本号、仓库 URL 和指纹来自官方文档核实时的状态，以官方为准。

系统要求

Claude Code 在以下平台和配置上运行：

  • 操作系统：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 支持的国家和地区

额外依赖：ripgrep 通常随 Claude Code 一起包含；如果搜索失败，见排障页的搜索与发现问题。

安装 Claude Code

更喜欢图形界面？桌面应用让你不用终端就能使用 Claude Code，可下载 macOS、Windows 或 Linux 版。

要安装 Claude Code，打开终端并运行适合你系统的命令。

原生安装（推荐）

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

安装程序完成后，打开新的终端窗口并运行 claude --version；正常的安装会打印版本号。如果你的 shell 说 claude 找不到或无法识别，说明安装目录还不在你的 PATH 上，见安装排障里的「修复你的 PATH」。

两个常见的误操作：看到 The token '&&' is not a valid statement separator，说明你在 PowerShell 里，而不是 CMD；看到 'irm' is not recognized as an internal or external command，说明你在 CMD 里，而不是 PowerShell。你的提示符在 PowerShell 里显示 PS C:\，在 CMD 里没有 PS 的 C:\。如果安装命令以 syntax error near unexpected token '<'、403 或其他 curl 错误失败，见「排查安装」，把错误对应到修复方法并了解其他安装方式。

原生 Windows 推荐安装 Git for Windows，让 Claude Code 能使用 Bash 工具；没有安装 Git for Windows 时，Claude Code 改用 PowerShell 作为 shell 工具；WSL 的设置不需要 Git for Windows。原生安装会在后台自动更新，让你保持在最新版本。

Homebrew

brew install --cask claude-code

Homebrew 提供两个 cask：claude-code 跟踪 stable 发布通道，通常比 latest 晚约一周并跳过有重大回归的发布；claude-code@latest 跟踪 latest 通道，新版本一发布就收到。Homebrew 安装不会自动更新：运行 brew upgrade claude-code 或 brew upgrade claude-code@latest（取决于你装的是哪个 cask）来获得最新功能和安全修复。

WinGet

winget install Anthropic.ClaudeCode

WinGet 安装不会自动更新：定期运行 winget upgrade Anthropic.ClaudeCode 来获得最新功能和安全修复。

你也可以在 Debian、Fedora、RHEL 和 Alpine 上用 apt、dnf 或 apk 安装（见下面「用 Linux 包管理器安装」）。安装完成后，在你想工作的项目里打开终端，启动 Claude Code：

claude

Claude Code 会在终端里打开交互会话。安装中遇到任何问题，见「排查安装与登录」。

在 Windows 上设置

你可以在 Windows 上原生运行 Claude Code，也可以在 WSL 里运行。根据你的项目所在位置和需要的功能选择：

方式要求沙箱适用场景
原生 Windows无；Git for Windows 可选不支持Windows 原生项目和工具
WSL 2启用 WSL 2支持Linux 工具链，或需要沙箱化命令执行
WSL 1启用 WSL 1不支持WSL 2 不可用时

选项 1：原生 Windows。 在 PowerShell 或 CMD 里运行安装命令，不需要以管理员身份运行。安装 Git for Windows 是可选的：它通过提供 Git Bash 来启用 Bash 工具。你从 PowerShell 还是 CMD 安装，只影响你运行哪条安装命令；PowerShell 里提示符显示 PS C:\Users\YourName>，CMD 里是没有 PS 的 C:\Users\YourName>。安装之后，从任何终端启动 claude。

  • 没有 Git for Windows 时，Claude Code 通过 PowerShell 工具运行 shell 命令。
  • 有 Git for Windows 时，Claude Code 为 Bash 工具使用 Git Bash。如果 Claude Code 找不到 Git Bash，在你的 settings.json 里设置路径：
{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

安装了 Git for Windows 时，PowerShell 工具与 Bash 并存可用：对 claude.ai 和 Console 账号默认开启，在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 会话里用 CLAUDE_CODE_USE_POWERSHELL_TOOL=1 启用；设为 0 关闭该工具。设置和限制见工具参考里的 PowerShell 工具。

选项 2：WSL。 打开你的 WSL 发行版，运行上面安装说明里的 Linux 安装程序。你要在 WSL 终端里安装并启动 claude，而不是从 PowerShell 或 CMD。

Alpine Linux 和基于 musl 的发行版

在 Alpine 和其他基于 musl/uClibc 的发行版上安装 Claude Code，安装命令需要 bash 和 curl，运行时需要 libgcc、libstdc++ 和 ripgrep。Alpine 默认不包含 bash 或 curl，所以在你装上它们之前，文档里的安装命令会以 not found 错误失败。用你发行版的包管理器安装这些包，然后设置 USE_BUILTIN_RIPGREP=0。这个例子在 Alpine 上安装所需的包：

apk add bash curl libgcc libstdc++ ripgrep

在 Alpine 上，ripgrep 在 community 仓库里。如果 apk 报告包缺失，把 community 仓库加到 /etc/apk/repositories（用你的 Alpine 版本）：

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

运行 apk update 刷新包索引，再重试 apk add 命令。然后在你的 settings.json 里把 USE_BUILTIN_RIPGREP 设为 0：

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

验证你的安装

安装之后，确认 Claude Code 在工作：

claude --version

正常的安装会打印 2.1.211 (Claude Code) 这样的版本号。如果失败并出现 command not found 或其他错误，见「排查安装与登录」。要更详细地检查你的安装和配置，运行 claude doctor：

claude doctor

claude doctor 不启动会话就打印只读的安装和设置诊断，包括安装健康状况、设置文件校验错误，以及带建议修复的任何警告。

认证

Claude Code 需要 Pro、Max、Team、Enterprise 或 Console 账号；免费的 claude.ai 套餐不包含 Claude Code 访问权。你也可以通过 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 这类第三方 API 提供商使用 Claude Code。安装之后，运行 claude 并按浏览器提示登录。如果设置了 ANTHROPIC_API_KEY 环境变量，Claude Code 会提示你一次批准该密钥，而不是打开浏览器。所有账号类型和团队设置选项见认证页。

更新 Claude Code

原生安装会在后台自动更新。你可以配置发布通道来控制是立即收到更新还是按延迟的 stable 节奏收到，或完全禁用自动更新。Homebrew、WinGet 和 Linux 包管理器安装默认需要手动更新。

自动更新

Claude Code 在启动时以及运行期间定期检查更新。更新在后台下载并安装，在你下次启动 Claude Code 时生效。运行 claude doctor 查看最近一次更新尝试的结果。

在 macOS 和 Linux 上，原生安装程序把 ~/.local/bin/claude 处的启动器作为指向 ~/.local/share/claude/versions/ 的符号链接来管理。如果你用自己的脚本或符号链接替换了这个启动器，自动更新和 claude update 会让它保持原位：新版本仍安装在 versions/ 目录下，由你的启动器决定运行哪个版本（v2.1.207 之前，自动更新器在每次更新时都会用它自己的符号链接替换该路径上的自定义启动器）。使用自定义启动器时，Claude Code 还会在磁盘上保留每个已安装的版本，因为它无法判断启动器需要哪个版本；claude doctor 会报告不是由原生安装程序创建的启动器。要让 Claude Code 重新管理启动器，删除 ~/.local/bin/claude 并运行 claude update。

如果 npm 全局安装因为 npm 全局目录不可写而无法自动更新，Claude Code 在启动时显示一次性通知，claude doctor 列出可用的修复，详见安装排障里的安装期间权限错误。

Homebrew、WinGet、apt、dnf 和 apk 安装默认不自动更新；要在 Homebrew 和 WinGet 上选择加入，设置 CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE 为 1，这样 Claude Code 在有新版本时在后台运行升级命令，成功时显示重启提示。该升级只针对 Claude Code 包，不影响你安装的其他软件。在 WinGet 上，因为 Windows 会锁定可执行文件，Claude Code 运行期间升级可能失败，这种情况下 Claude Code 改为显示手动命令。apt、dnf 和 apk 仍需手动升级，因为这些命令需要提升的权限。已知问题：Claude Code 可能在新版本在这些包管理器里可用之前就通知你有更新；如果升级失败，稍后再试。Homebrew 在升级后会在磁盘上保留旧版本，定期运行 brew cleanup 回收磁盘空间。

配置发布通道

用 autoUpdatesChannel 设置控制 Claude Code 为自动更新和 claude update 跟踪哪个发布通道：

  • "latest"（默认）：新功能一发布就收到。
  • "stable"：使用通常约一周前的版本，跳过有重大回归的发布。

通过 /config → Auto-update channel 配置，或把它加到你的 settings.json：

{
  "autoUpdatesChannel": "stable"
}

对企业部署，你可以用托管设置在整个组织强制统一的发布通道。Homebrew 安装按 cask 名选择通道而不是用这个设置：claude-code 跟踪 stable，claude-code@latest 跟踪 latest。

固定最低版本

minimumVersion 设置建立一个下限。后台自动更新和 claude update 拒绝安装低于该值的任何版本，所以如果你已经在更新的 "latest" 构建上，换到 "stable" 通道不会让你降级。通过 /config 从 "latest" 切到 "stable" 时，会提示你选择停留在当前版本还是允许降级；选择停留会把 minimumVersion 设为该版本，切回 "latest" 则清除它。把它加到你的 settings.json 以显式固定下限：

{
  "autoUpdatesChannel": "stable",
  "minimumVersion": "2.1.100"
}

在托管设置里，这会强制执行用户和项目设置无法覆盖的组织范围最低版本。minimumVersion 固定只约束更新；要让 Claude Code 在版本范围之外拒绝启动，改用托管设置 requiredMinimumVersion 和 requiredMaximumVersion，更新也遵守 requiredMaximumVersion 上限。

禁用自动更新

在你的 settings.json 的 env 键里把 DISABLE_AUTOUPDATER 设为 "1"：

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

在原生或 npm 安装上，运行 claude doctor 并检查 Auto-updates 一行显示 disabled (set by env: DISABLE_AUTOUPDATER) 而不是 enabled，确认改动生效。DISABLE_AUTOUPDATER 只停止后台检查；claude update 和 claude install 仍然有效。要阻止所有更新路径（包括手动更新），改设 DISABLE_UPDATES；当你通过自己的渠道分发 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!。

高级安装选项

这些选项用于固定版本、Linux 包管理器、npm 和验证二进制完整性。

安装特定版本

原生安装程序接受具体的版本号或发布通道（latest 或 stable）。你在安装时选的通道成为你自动更新的默认值。

安装最新版本（默认）：macOS、Linux、WSL 用 curl -fsSL https://claude.ai/install.sh | bash；Windows PowerShell 用 irm https://claude.ai/install.ps1 | iex；Windows CMD 用上面的 CMD 命令。

安装 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

安装特定版本号：

# macOS、Linux、WSL
curl -fsSL https://claude.ai/install.sh | bash -s 2.1.89
# Windows PowerShell
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 2.1.89
:: Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd 2.1.89 && del install.cmd

要确认装了哪个版本，运行 claude --version：命令打印你传入的确切版本，如 2.1.89 (Claude Code)。

用 Linux 包管理器安装

Claude Code 发布带签名的 apt、dnf 和 apk 仓库。每个仓库提供两个通道：stable 提供通常约一周前的版本并跳过有重大回归的发布，latest 在每个发布一出就提供。下面的命令配置适合大多数用户的 stable 通道；每个标签也展示了 latest 仓库的 URL。包管理器安装不会通过 Claude Code 自动更新，更新经由你正常的系统升级流程到达。所有仓库都用 Claude Code 发布签名密钥签名；在信任该密钥之前，按各自说明验证它。

apt（Debian 和 Ubuntu）：下面的安装命令用 curl 下载签名密钥并用 gpg 验证，全新的 Debian 和 Ubuntu 安装可能不含它们；如果任一命令报告 command not found，先安装两者：

sudo apt install curl gnupg

下载签名密钥：

sudo install -d -m 0755 /etc/apt/keyrings
sudo curl -fsSL https://downloads.claude.ai/keys/claude-code.asc \
  -o /etc/apt/keyrings/claude-code.asc

如果这次下载失败，之后的 apt update 会以 NO_PUBKEY BAA929FF1A7ECACE 失败。继续之前，确认密钥已下载且属于 Anthropic：

gpg --show-keys /etc/apt/keyrings/claude-code.asc

gpg 打印的指纹应是 31DDDE24DDFAB679F42D7BD2BAA929FF1A7ECACE；如果 gpg 报告文件无法打开或不含有效的 OpenPGP 数据，说明下载失败或返回了错误内容：确认你的网络能访问 downloads.claude.ai，再重新运行下载命令。在 stable 通道上注册仓库并安装：

echo "deb [signed-by=/etc/apt/keyrings/claude-code.asc] https://downloads.claude.ai/claude-code/apt/stable stable main" \
  | sudo tee /etc/apt/sources.list.d/claude-code.list
sudo apt update
sudo apt install claude-code

要改用 latest 通道，URL 路径和套件名都要变，用这条 deb 行：

echo "deb [signed-by=/etc/apt/keyrings/claude-code.asc] https://downloads.claude.ai/claude-code/apt/latest latest main" \
  | sudo tee /etc/apt/sources.list.d/claude-code.list

以后升级，运行 sudo apt update && sudo apt upgrade claude-code。

dnf（Fedora 和 RHEL）：下面的命令配置 stable 通道：

sudo tee /etc/yum.repos.d/claude-code.repo <<'EOF'
[claude-code]
name=Claude Code
baseurl=https://downloads.claude.ai/claude-code/rpm/stable
enabled=1
gpgcheck=1
gpgkey=https://downloads.claude.ai/keys/claude-code.asc
EOF
sudo dnf install claude-code

要改用 latest 通道，把 baseurl 设为 latest 仓库：baseurl=https://downloads.claude.ai/claude-code/rpm/latest。dnf 在首次安装时下载密钥并提示你确认指纹，接受之前验证它与 31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE 一致。以后升级，运行 sudo dnf upgrade claude-code。

apk（Alpine Linux）：下面的命令配置 stable 通道：

wget -O /etc/apk/keys/claude-code.rsa.pub \
  https://downloads.claude.ai/keys/claude-code.rsa.pub
echo "https://downloads.claude.ai/claude-code/apk/stable" >> /etc/apk/repositories
apk add claude-code

要切到 latest 通道，删除 stable 仓库行并添加 latest 仓库：

sed -i '\|downloads.claude.ai/claude-code/apk/stable|d' /etc/apk/repositories
echo "https://downloads.claude.ai/claude-code/apk/latest" >> /etc/apk/repositories

用 sha256sum /etc/apk/keys/claude-code.rsa.pub 验证下载的密钥，它应报告 395759c1f7449ef4cdef305a42e820f3c766d6090d142634ebdb049f113168b6。以后升级，运行 apk update && apk upgrade claude-code。

用 npm 安装

你也可以把 Claude Code 作为全局 npm 包安装。从 v2.1.198 起，npm 包要求 Node.js 22 或更高；在更旧的 Node.js 版本上，npm 在安装期间打印 EBADENGINE 警告而不是失败，安装会完成且 claude 仍能运行，因为该包下载的是原生二进制文件，运行时不使用你的 Node.js。

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

npm 包安装的是与独立安装程序相同的原生二进制文件：npm 通过每平台的可选依赖（如 @anthropic-ai/claude-code-darwin-arm64）把二进制拉进来，一个 postinstall 步骤把它链接到位；安装好的 claude 二进制本身不调用 Node。支持的 npm 安装平台是 darwin-arm64、darwin-x64、linux-x64、linux-arm64、linux-x64-musl、linux-arm64-musl、win32-x64 和 win32-arm64。你的包管理器必须允许可选依赖；如果安装后二进制缺失，见排障页。要升级 npm 安装，运行 npm install -g @anthropic-ai/claude-code@latest；避免用 npm update -g，它遵循原始安装的 semver 范围，可能不会让你升到最新发布。

注意：不要用 sudo npm install -g，这会导致权限问题和安全风险；如果遇到权限错误，见安装排障里的权限错误部分。

二进制完整性与代码签名

每个发布都发布一个 manifest.json，其中含每个平台二进制的 SHA256 校验和。该清单用 Anthropic 的 GPG 密钥签名，所以验证清单上的签名就传递地验证了它列出的每个二进制。

验证清单签名（步骤 1–3 需要带 gpg 和 curl 的 POSIX shell；在 Windows 上，在 Git Bash 或 WSL 里运行；步骤 4 含 PowerShell 选项）：

  1. 下载并导入公钥。 发布签名密钥发布在固定的 URL：

    curl -fsSL https://downloads.claude.ai/keys/claude-code.asc | gpg --import

    显示导入密钥的指纹：

    gpg --fingerprint security@anthropic.com

    确认输出包含这个指纹：

    31DD DE24 DDFA B679 F42D  7BD2 BAA9 29FF 1A7E CACE

  2. 下载清单和签名。 把 VERSION 设为你想验证的发布：

    REPO=https://downloads.claude.ai/claude-code-releases
VERSION=2.1.89
curl -fsSLO "$REPO/$VERSION/manifest.json"
curl -fsSLO "$REPO/$VERSION/manifest.json.sig"

  3. 验证签名。 对清单验证分离签名：

    gpg --verify manifest.json.sig manifest.json

    有效的结果报告 Good signature from "Anthropic Claude Code Release Signing <security@anthropic.com>"。gpg 对任何新导入的密钥还会打印 WARNING: This key is not certified with a trusted signature!，这是预期的：Good signature 一行确认密码学检查通过，步骤 1 的指纹比对确认密钥本身是真实的。

  4. 对照清单检查二进制。 把二进制的 SHA256 校验和与 manifest.json 里 platforms.<platform>.checksum 下列出的值比较。下面的命令假定当前目录里有 claude 二进制；要验证已安装的原生二进制，对 ~/.local/share/claude/versions/VERSION 运行命令，把 VERSION 换成你在步骤 2 里设的发布。

    sha256sum claude                      # Linux
shasum -a 256 claude                  # macOS
    (Get-FileHash claude.exe -Algorithm SHA256).Hash.ToLower()   # Windows PowerShell

注意：清单签名适用于 2.1.89 及之后的发布；更早的发布在 manifest.json 里发布校验和，但没有分离签名。

平台代码签名。 除了带签名的清单，各个二进制在受支持的地方还带有平台原生的代码签名：

  • macOS：由 "Anthropic PBC" 签名并经 Apple 公证；用 codesign --verify --verbose ./claude 验证。
  • Windows：由 "Anthropic, PBC" 签名；用 Get-AuthenticodeSignature .\claude.exe 验证。
  • Linux：二进制没有单独的代码签名。如果你直接从 claude-code-releases 存储桶下载或使用原生安装程序，用上面的清单签名验证完整性；如果你用 apt、dnf 或 apk 安装，包管理器会用仓库签名密钥自动验证签名。

卸载 Claude Code

要移除 Claude Code，按你的安装方式的说明操作。如果之后 claude 仍然能运行，你很可能有第二个安装，或来自旧安装程序的遗留 shell 别名；见安装排障里的「检查冲突的安装」找到并移除它。

原生安装：移除 Claude Code 二进制文件和版本文件。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

Homebrew 安装：移除你安装的 Homebrew cask。如果你装的是 stable cask：brew uninstall --cask claude-code；如果装的是 latest cask：brew uninstall --cask claude-code@latest。

WinGet 安装：winget uninstall Anthropic.ClaudeCode。

apt / dnf / apk：移除包和仓库配置：

# apt
sudo apt remove claude-code
sudo rm /etc/apt/sources.list.d/claude-code.list /etc/apt/keyrings/claude-code.asc

# dnf
sudo dnf remove claude-code
sudo rm /etc/yum.repos.d/claude-code.repo

# apk
apk del claude-code
sed -i '\|downloads.claude.ai/claude-code/apk|d' /etc/apk/repositories
rm /etc/apk/keys/claude-code.rsa.pub

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

删除配置文件

注意：删除配置文件会删除你所有的设置、允许的工具、MCP 服务器配置和会话历史。VS Code 扩展、JetBrains 插件和桌面应用也会写入 ~/.claude/；如果其中任何一个仍然安装着，该目录会在它下次运行时被重新创建。要彻底移除 Claude Code，在删除这些文件之前先卸载 VS Code 扩展、JetBrains 插件和桌面应用。

要移除 Claude Code 的设置和缓存数据，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