Claude Code 深度学习手册

主题

安装与认证（含 Bedrock/Vertex） ​

Claude Code 的系统要求、各平台安装/更新/卸载、版本通道与二进制校验，以及通过 claude 登录或改用 Bedrock/Vertex 等第三方 provider 的认证入口。

你的真实情况 ​

你已经装好并在跑：

  • native 安装，v2.1.158（~/.local/bin/claude → ~/.local/share/claude/versions/2.1.158）。
  • 自动更新正常：最近一次 2.1.157 → 2.1.158 成功（native 安装会后台自更，你不用管）。
  • 环境 HOME=/workspace（容器）。

对你有用的点 ​

  • 想锁版本/查健康：claude --version、claude doctor。
  • 不想自动更新：设 DISABLE_AUTOUPDATER=1（但 native 安装的好处就是自更，一般不用关）。
  • 组织铺开时可用 minimumVersion 强制最低版本——你单人用不到。

安装这关你已通过，本节其余（GPG 校验、各包管理器、企业分发）等团队部署再看。

官方文档要点 ​

以下为按官方文档整理的系统性参考。

是什么 ​

本模块基于 Claude Code 官方 "Advanced setup" 页面，讲清系统要求、各平台安装方式、版本管理（发布通道/版本下限/自动更新）、二进制完整性校验、认证入口与卸载。注意：该 setup 页面对认证只给入口（运行 claude 登录，账号类型见 /en/authentication），对 Amazon Bedrock、Google Vertex AI、Microsoft Foundry 仅提供链接（/en/amazon-bedrock、/en/google-vertex-ai、/en/microsoft-foundry），并未在本页给出 Bedrock/Vertex 的具体环境变量与配置。要讲透 Bedrock/Vertex 的 env var 细节，需另抓那几个专页（本次严格只依据 setup 页面，故此处不脑补其 env 名）。

怎么工作 ​

  • 原生安装与 npm 包安装的是同一个 native 二进制：npm 通过 per-platform 可选依赖（如 @anthropic-ai/claude-code-darwin-arm64）拉取二进制，postinstall 步骤把它链接到位；安装后的 claude 二进制本身不调用 Node。
  • 原生安装会在后台自动更新：启动时及运行期间周期性检查更新，更新在后台下载安装，下次启动 Claude Code 时生效；claude doctor 显示最近一次更新尝试的结果。
  • Homebrew/WinGet/apt/dnf/apk 默认不自动更新——Homebrew 按 cask 名选通道（claude-code=stable，claude-code@latest=latest）；其余走系统自身升级流程。
  • 发布通道两档：latest（默认，新功能一发布即可得）与 stable（约落后一周、跳过有重大回归的版本）。可用 /config → Auto-update channel 或 settings.json autoUpdatesChannel 设置。
  • minimumVersion 设定版本地板：后台自动更新和 claude update 拒绝安装低于该值的版本；从 latest 切到 stable 不会把已在更新版上的你降级。通过 /config 从 latest 切到 stable 会提示是保留当前版本（即把 minimumVersion 设为该版本）还是允许降级；切回 latest 会清除它。
  • Windows 上是否安装 Git for Windows 决定 shell 工具：装了用 Git Bash 走 Bash 工具，没装则用 PowerShell 工具；WSL 不需要 Git for Windows。
  • 二进制完整性：每个 release 发布含各平台 SHA256 校验和的 manifest.json，并用 Anthropic GPG key 对 manifest 签名，验证 manifest 签名即可传递性地验证它列出的每个二进制。Linux 二进制本身不单独 code-sign。
  • 认证：装好后运行 claude 按浏览器提示登录；需要 Pro/Max/Team/Enterprise/Console 账号，免费 Claude.ai 计划不含 Claude Code。也可改用第三方 API provider（Amazon Bedrock / Google Vertex AI / Microsoft Foundry）。

怎么配置 / 用法 ​

安装方式（任选其一，命令逐字引用）：

  • 原生安装（推荐，会自动后台更新）：
    • 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
  • Homebrew（不自动更新）：brew install --cask claude-code（stable）或 brew install --cask claude-code@latest（latest）；升级 brew upgrade claude-code
  • WinGet（不自动更新）：winget install Anthropic.ClaudeCode；升级 winget upgrade Anthropic.ClaudeCode
  • npm（需 Node.js 18+）：npm install -g @anthropic-ai/claude-code；升级用 npm install -g @anthropic-ai/claude-code@latest（不要用 npm update -g，更不要 sudo npm install -g）
  • Linux 包管理器 apt/dnf/apk（不通过 Claude Code 自动更新）

指定版本：curl -fsSL https://claude.ai/install.sh | bash -s stable 或 ... | bash -s 2.1.89（Windows 用 & ([scriptblock]::Create((irm https://claude.ai/install.ps1))) stable）

启动与验证：claude（在项目目录里运行启动）、claude --version、claude doctor、claude update（立即更新）、claude install

settings.json 关键配置示例：

  • 指定 Git Bash 路径：{ "env": { "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe" } }
  • Alpine/musl 关闭内置 ripgrep：{ "env": { "USE_BUILTIN_RIPGREP": "0" } }
  • 发布通道：{ "autoUpdatesChannel": "stable" }（默认 "latest"）
  • 版本下限：{ "autoUpdatesChannel": "stable", "minimumVersion": "2.1.100" }
  • 关闭后台自动更新：{ "env": { "DISABLE_AUTOUPDATER": "1" } }（彻底禁用一切更新用 DISABLE_UPDATES）

配置文件/路径：用户级 ~/.claude/、~/.claude.json；项目级 .claude、.mcp.json；apt 密钥 /etc/apt/keyrings/claude-code.asc、源 /etc/apt/sources.list.d/claude-code.list；dnf 源 /etc/yum.repos.d/claude-code.repo；apk 密钥 /etc/apk/keys/claude-code.rsa.pub、源写入 /etc/apk/repositories；原生安装二进制 ~/.local/bin/claude、数据 ~/.local/share/claude（Windows：$env:USERPROFILE\.local\bin\claude.exe、$env:USERPROFILE\.local\share\claude）。

什么时候用 ​

  • 想在终端用 Claude Code：用原生安装（推荐），自动后台更新省心。
  • 想要图形界面、不想用终端：用 Desktop app（macOS/Windows 可下载）。
  • 企业/团队要锁版本一致性：用 managed settings 强制 autoUpdatesChannel 与 minimumVersion。
  • 已有 Node 工具链且偏好 npm 管理：用 npm 全局安装（需 Node.js 18+），但不要用 sudo。
  • Windows：需要 Linux 工具链或沙箱命令执行用 WSL 2；纯 Windows 原生项目用 Native Windows（沙箱不支持）。
  • 不需要后台自动更新（如自分发渠道、要锁住版本）：设 DISABLE_AUTOUPDATER=1，要连手动更新也禁用则用 DISABLE_UPDATES。
  • 别用免费 Claude.ai 计划接 Claude Code——不含访问权限；也别用 sudo npm install -g（权限与安全风险）。

限制 / 坑 ​

  • 免费 Claude.ai 计划不包含 Claude Code 访问权限，必须 Pro/Max/Team/Enterprise/Console 账号或第三方 API provider。
  • 仅原生安装自动更新；Homebrew/WinGet/apt/dnf/apk 默认不自动更新，需手动升级。
  • DISABLE_AUTOUPDATER 只停后台检查，claude update 和 claude install 仍可用；要全部封堵需用 DISABLE_UPDATES。
  • npm 安装要求包管理器允许 optional dependencies，否则可能 native 二进制找不到；支持的 npm 平台为 darwin-arm64、darwin-x64、linux-x64、linux-arm64、linux-x64-musl、linux-arm64-musl、win32-x64、win32-arm64。
  • npm 升级避免 npm update -g（受原始安装 semver 范围限制，可能拿不到最新版）。
  • Alpine/musl 发行版原生安装需先装 libgcc、libstdc++、ripgrep，并设 USE_BUILTIN_RIPGREP=0。
  • Native Windows 与 WSL 1 不支持 sandboxing，只有 WSL 2 支持。
  • WinGet 升级在 Claude Code 运行中可能因 Windows 锁定 exe 而失败，会改显示手动命令；apt/dnf/apk 因需 elevated 权限始终需手动升级。
  • manifest 签名仅 2.1.89 起的 release 提供；更早 release 的 manifest.json 只有 checksum 没有分离签名。
  • 包管理器可能在新版尚未上架时就提示更新——升级失败应稍后重试。
  • 卸载后若 VS Code 扩展、JetBrains 插件或 Desktop app 仍在，会重新生成 ~/.claude/ 目录；删配置文件会丢失所有 settings、allowed tools、MCP 配置和会话历史。

硬事实速查（20 条） ​

  • 系统要求 OS：macOS 13.0+；Windows 10 1809+ 或 Windows Server 2019+；Ubuntu 20.04+；Debian 10+；Alpine Linux 3.19+。
  • 硬件：4 GB+ RAM，x64 或 ARM64 处理器；需联网；Shell 支持 Bash/Zsh/PowerShell/CMD。
  • npm 包名 @anthropic-ai/claude-code，需 Node.js 18 or later。
  • WinGet 包标识 Anthropic.ClaudeCode；Homebrew cask claude-code（stable）/ claude-code@latest（latest）。
  • 原生安装脚本 URL：https://claude.ai/install.sh、https://claude.ai/install.ps1、https://claude.ai/install.cmd。
  • 启动命令 claude；验证 claude --version、claude doctor；立即更新 claude update；另有 claude install。
  • settings env：CLAUDE_CODE_GIT_BASH_PATH、USE_BUILTIN_RIPGREP、DISABLE_AUTOUPDATER、DISABLE_UPDATES、CLAUDE_CODE_USE_POWERSHELL_TOOL（=1 opt in / =0 opt out）、CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE（=1 让 Homebrew/WinGet 自动升级）。
  • settings 字段：autoUpdatesChannel（"latest" 默认 / "stable"）、minimumVersion（例 "2.1.100"）。
  • 示例版本号：指定版本 2.1.89；minimumVersion 示例 2.1.100；manifest 签名自 2.1.89 起提供。
  • 配置/状态文件：~/.claude/、~/.claude.json、项目级 .claude 与 .mcp.json。
  • 原生安装位置：~/.local/bin/claude、~/.local/share/claude（Windows：$env:USERPROFILE.local\bin\claude.exe、$env:USERPROFILE.local\share\claude）。
  • GPG 指纹（apt/dnf 及 manifest 验证）：31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE；签名身份 "Anthropic Claude Code Release Signing <security@anthropic.com>"。
  • apk 公钥 SHA256：395759c1f7449ef4cdef305a42e820f3c766d6090d142634ebdb049f113168b6。
  • Linux 仓库密钥 URL：https://downloads.claude.ai/keys/claude-code.asc（apk 用 claude-code.rsa.pub）；release 桶 https://downloads.claude.ai/claude-code-releases。
  • Alpine 依赖安装命令 apk add libgcc libstdc++ ripgrep 后设 USE_BUILTIN_RIPGREP=0。
  • npm 支持平台：darwin-arm64、darwin-x64、linux-x64、linux-arm64、linux-x64-musl、linux-arm64-musl、win32-x64、win32-arm64；per-platform 可选依赖示例 @anthropic-ai/claude-code-darwin-arm64。
  • 认证账号类型：Pro、Max、Team、Enterprise、Console；第三方 provider：Amazon Bedrock（/en/amazon-bedrock）、Google Vertex AI（/en/google-vertex-ai）、Microsoft Foundry（/en/microsoft-foundry）。
  • Windows code sign 由 "Anthropic, PBC" 签名（验证 Get-AuthenticodeSignature .\claude.exe）；macOS 由 "Anthropic PBC" 签名并经 Apple notarize（验证 codesign --verify --verbose ./claude）。
  • 校验和命令：Linux sha256sum claude、macOS shasum -a 256 claude、Windows (Get-FileHash claude.exe -Algorithm SHA256).Hash.ToLower()；manifest 验证 gpg --verify manifest.json.sig manifest.json。
  • ripgrep 通常随 Claude Code 一起提供。

官方出处：https://code.claude.com/docs/en/setup