跳至主要內容

安装与版本管理

2026/6/27大约 5 分钟

安装与版本管理

本章覆盖系统要求、各平台安装、认证、更新通道与配置目录。首次使用建议配合官方 Quickstart 与 Terminal guide。

系统要求

项目要求
账号Pro / Max / Team / Enterprise / Console（免费 Claude.ai 计划不含 Claude Code）
操作系统macOS、Linux、WSL2、原生 Windows
WSL仅 WSL2；WSL1 不支持
Windows Bash推荐 Git for Windows；未安装时回退 PowerShell
Alpine/musl需额外安装 libgcc、libstdc++、ripgrep，并设 USE_BUILTIN_RIPGREP=0

安装方式

官方推荐 Native Install——后台自动更新，始终跟进最新版。

Native Install（推荐）

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

提示符 PS C:\> 是 PowerShell，用 .ps1；C:\> 是 CMD，用 .cmd。若出现 syntax error near unexpected token '<' 或 403，见 Troubleshoot installation。

Native Install 将 claude 加入 PATH（通常 ~/.local/bin），并在后台自动更新。

Windows：原生 vs WSL

场景建议
项目在 Windows 文件系统、需 Windows 工具链原生 Windows 安装
项目在 WSL Linux 文件系统、Linux 工具链WSL2 内运行 Linux 安装脚本
需要沙箱 BashWSL2 或 macOS/Linux（原生 Windows 沙箱不支持）

WSL 中在 WSL 终端里安装和启动 claude，不要从 PowerShell 跨边界调用。

Homebrew（macOS / Linux）

brew install --cask claude-code          # stable 通道，通常滞后约一周
brew install --cask claude-code@latest   # latest 通道，发布即得

Homebrew 不自动更新：

brew upgrade claude-code
# 或
brew upgrade claude-code@latest

可设 CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1，让 Claude Code 在检测到新版本时后台替你跑 brew upgrade 并提示重启。

WinGet（Windows）

winget install Anthropic.ClaudeCode
winget upgrade Anthropic.ClaudeCode

同样支持 CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1。

npm

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

若 npm 全局目录不可写，Claude Code 启动时会一次性提示；claude doctor 会列出修复方式。

Linux 包管理器

Debian（apt）、Fedora/RHEL（dnf）、Alpine（apk）等——详见 Setup - Linux package managers。

安装方式对比

方式平台自动更新推荐场景
Native Install全平台是日常开发首选
HomebrewmacOS / Linux否（可 opt-in 自动 upgrade）习惯 brew 的用户
WinGetWindows否（可 opt-in）Windows 包管理
npm全平台否已有 Node 环境
apt/dnf/apkLinux否企业批量部署

验证安装

claude --version   # 或 claude -v
claude doctor      # 安装、配置、MCP、上下文健康检查

command not found 时：重开终端；确认 ~/.local/bin 在 PATH；Windows 确认安装目录已加入 PATH。

认证方式

1. OAuth 登录（Claude 订阅 / Console，默认）

首次 claude 会打开浏览器完成 OAuth。支持 Pro、Max、Team、Enterprise、Anthropic Console。

无浏览器环境（WSL2、SSH、容器）：

claude auth login
# 将浏览器中的验证码粘贴到终端

2. 第三方 API 提供商

Claude Code 也可通过 Amazon Bedrock、Google Vertex AI、Microsoft Foundry 等运行。配置对应凭证与环境变量，详见各提供商文档。

当 ANTHROPIC_BASE_URL 指向 Anthropic 兼容 Gateway 时，/model 会自动列出 Gateway /v1/models 返回的模型。

3. API Key（Anthropic API）

export ANTHROPIC_API_KEY=sk-ant-xxx

API 用户可用 --betas 启用 Beta 功能。

动态 API Key（apiKeyHelper）

{
  "apiKeyHelper": "/bin/generate_temp_api_key.sh"
}

配合 CLAUDE_CODE_API_KEY_HELPER_TTL_MS 控制刷新间隔。脚本输出作为 X-Api-Key 与 Authorization: Bearer 发送。

衍生工具（社区）

配置切换用 CC Switch（桌面 GUI 或 cc-switch-cli）。会话复盘用 cc-session-viewer，跨会话统计 Read 次数用 cc-read，重复 WebFetch 文档可装 claude-webcache Plugin。分工见 附录 C · 衍生工具简介。

版本管理与更新

自动更新（Native Install）

  • 启动时与运行中定期检查
  • 后台下载安装，下次启动生效
  • claude doctor 查看最近一次更新结果

发布通道 autoUpdatesChannel

通道说明
latest（默认）最新发布
stable通常滞后约一周，跳过有重大回归的版本
/config autoUpdatesChannel stable

Homebrew 通过 cask 名选通道（claude-code = stable，claude-code@latest = latest），不读此 setting。

minimumVersion 与 Managed 版本范围

  • minimumVersion（用户/项目 settings）：自动更新和 claude update 不会降到此版本以下；切到 stable 也不会降级你已更新的 newer build
  • requiredMinimumVersion / requiredMaximumVersion（Managed）：超出范围则拒绝启动

手动更新

claude update

Homebrew/WinGet/npm/apt 用户若用 Native 的 claude update，会提示改用对应包管理器命令。

禁止更新

变量效果
DISABLE_AUTOUPDATER=1停止后台检查；claude update 仍可用
DISABLE_UPDATES=1阻断所有更新路径（企业自建分发时用）

高级：指定版本安装

Native 安装脚本可接受版本号或通道：

# 示例：安装 stable 通道（语法见官方 setup 文档）
curl -fsSL https://claude.ai/install.sh | bash -s stable

npm 回退：npm install -g @anthropic-ai/claude-code@2.1.100

卸载

Native Install 卸载步骤见 Setup - Uninstall。卸载不会自动删除 ~/.claude/ 中的会话与配置。

配置目录结构

首次启动后：

~/.claude/
├── settings.json          # 用户级设置
├── CLAUDE.md              # 用户级记忆
├── rules/                 # 用户级路径规则
├── agents/                # 用户级 Subagents
├── skills/                # 用户级 Skills
├── commands/              # 用户级自定义命令（与 skills 等价）
├── .claude.json           # OAuth、MCP、项目状态（注意文件名）
└── projects/              # 各项目会话记录、Auto Memory

项目/.claude/
├── settings.json          # 项目级（可提交 git）
├── settings.local.json    # 本地覆盖（应 gitignore）
├── CLAUDE.md
├── rules/
├── agents/
├── skills/
└── .mcp.json              # 项目级 MCP（或在根目录 .mcp.json）

Workspace trust：在目录首次使用 --worktree 或 project 级 autoMemoryDirectory 等敏感设置前，需先在该目录运行一次 claude 并接受 trust 对话框。

PATH 与常见问题

  1. macOS/Linux：确认 ~/.local/bin 在 PATH；重开终端
  2. Windows：确认安装目录在 PATH；PowerShell 与 CMD 使用对应安装命令
  3. 权限错误：安全软件拦截时检查终端错误输出；npm 全局目录权限见 claude doctor

资料来源：Setup、CLI reference、Troubleshoot installation