Claude Code 安装指南

目录

  1. 前置要求
  2. 各操作系统安装方法
  3. IDE 扩展安装
  4. 桌面应用安装
  5. 首次使用配置
  6. 更新与卸载
  7. 常见问题
  8. CI/CD 环境安装

1. 前置要求

系统版本

操作系统 最低版本
macOS 13.0+ (Ventura 及以上)
Windows 10 1809+ / Server 2019+
Linux Ubuntu 20.04+, Debian 10+, Alpine 3.19+

硬件要求

项目 最低 推荐
处理器 x64 或 ARM64 —
内存 4 GB 8 GB+
磁盘 ~500 MB 1 GB
网络 需访问 Anthropic API —

软件依赖

推荐使用 Native 安装方式，无需额外安装 Node.js。

若使用 npm 方式安装：

组件 最低版本 推荐版本
Node.js 18.0.0 22.x LTS
npm 9.0+ 10.x+
Git 2.23+ 2.47+

验证命令：

node --version
npm --version
git --version

2. 各操作系统安装方法

🥇 macOS

方法一：官方安装脚本（✅ 推荐）
curl -fsSL https://claude.ai/install.sh | bash
  • 零外部依赖，自带运行时
  • 自动后台更新
  • 支持 GPG 签名验证
方法二：Homebrew
# 稳定通道（约滞后一周，跳过已知回归）
brew install --cask claude-code

# 最新通道（即时发布）
brew install --cask claude-code@latest

注意： Homebrew 安装不会自动更新，需手动 brew upgrade claude-code。如需自动更新：

export CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1
方法三：npm（已弃用，过渡期仍可用）
npm install -g @anthropic-ai/claude-code
macOS 安全提示处理

如果遇到 Gatekeeper 阻止，前往 系统设置 → 隐私与安全性 → 点击"仍要打开"，或执行：

xattr -dr com.apple.quarantine /opt/homebrew/bin/claude

🥈 Windows

方法一：PowerShell 安装脚本（✅ 推荐）
irm https://claude.ai/install.ps1 | iex

执行策略限制时先运行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
方法二：WinGet
winget install Anthropic.ClaudeCode
方法三：CMD 脚本
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
方法四：WSL2
curl -fsSL https://claude.ai/install.sh | bash

⚠️ Windows 重要提示：

  • 桌面版必须安装 Git for Windows，否则会报 "Git is required" 错误
  • WSL2 中确保 Linux 版 Node.js 优先于 Windows 版：export PATH="$HOME/.nvm/versions/node/$(nvm current)/bin:$PATH"

🥉 Linux

方法一：官方安装脚本（✅ 推荐）
curl -fsSL https://claude.ai/install.sh | bash

安装后将 ~/.local/bin 加入 PATH：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
方法二：Arch Linux AUR
yay -S claude-code
# 或
paru -S claude-code
方法三：npm（已弃用）
npm install -g @anthropic-ai/claude-code

💡 Linux 提示： 如果安装时遇到 Killed 错误，可能是内存不足被 OOM Killer 终止，建议增加 swap：

sudo fallocate -l 2G /swapfile && sudo swapon /swapfile

安装命令速查

平台 方式 命令
macOS 原生脚本 curl -fsSL https://claude.ai/install.sh | bash
macOS Homebrew stable brew install --cask claude-code
macOS Homebrew latest brew install --cask claude-code@latest
Windows PowerShell irm https://claude.ai/install.ps1 | iex
Windows WinGet winget install Anthropic.ClaudeCode
Windows CMD curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd
Linux 原生脚本 curl -fsSL https://claude.ai/install.sh | bash
Arch AUR yay -S claude-code

3. IDE 扩展安装

VS Code 扩展

前提条件： VS Code 1.98.0+

图形界面安装：

  1. 打开 VS Code → 扩展面板 (Ctrl+Shift+X / Cmd+Shift+X)
  2. 搜索 “Claude Code”，确认发布者为 Anthropic
  3. 点击 安装

命令行安装：

code --install-extension anthropic.claude-code

核心功能：

  • 专用聊天面板（侧边栏或编辑器标签页）
  • 内联 Diff 审查，支持逐行接受/拒绝
  • @ 提及文件和文件夹
  • 多会话并发（独立标签页/窗口）
  • Chrome 浏览器集成 (@browser)

键盘快捷键：

操作 macOS Windows/Linux
聚焦输入框 Cmd+Esc Ctrl+Esc
新标签页 Cmd+Shift+Esc Ctrl+Shift+Esc
新对话 Cmd+N Ctrl+N
插入 @ 文件 Option+K Alt+K

推荐 settings.json 配置：

{
  "claude-code.useTerminal": false,
  "claude-code.initialPermissionMode": "default",
  "claude-code.autosave": true,
  "claude-code.respectGitIgnore": true
}

JetBrains IDE 扩展

前提条件：

  • IntelliJ IDEA / PyCharm / WebStorm / GoLand 等较新版本
  • 必须先安装 Claude Code CLI（插件不捆绑 CLI）

安装步骤：

第一步 — 安装 CLI：

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

第二步 — 配置 PATH（关键！）：

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

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

验证：claude --version

第三步 — 安装插件：

  1. Settings → Plugins → Marketplace
  2. 搜索 “Claude Code [Beta]”，发布者为 Anthropic PBC
  3. 点击 Install → 完全重启 IDE

第四步 — 配置插件：

  • Settings → Tools → Claude Code [Beta]
  • 在 “Claude command” 中填入 claude 或完整路径如 /Users/用户名/.local/bin/claude

JetBrains 常见问题：

  • “Cannot launch Claude Code”：PATH 未配置，在插件设置中填写 CLI 完整路径
  • nvm 用户找不到 claude：IDE 不继承 shell PATH，填完整路径即可
  • ESC 键无法中断：Settings → Tools → Terminal → 取消 “Move focus to the editor with Escape”

4. 桌面应用安装

Anthropic 已发布 Claude Code Desktop 桌面应用。

平台 格式 状态
macOS .dmg 正式支持（Intel + Apple Silicon）
Windows .exe / .msi 正式支持（x64）
Linux — 不提供，仅 CLI

官方下载地址： https://claude.com/download

⚠️ 重要前提：

  1. 必须有付费订阅（Pro/Max/Team/Enterprise），免费账号无法使用 Code 选项卡
  2. Windows 用户必须安装 Git for Windows
  3. 桌面版自带运行时，无需单独安装 Node.js 或 CLI

三大选项卡：

选项卡 功能 文件访问
Chat 普通对话 不能
Cowork 长时间自主代理任务 云端虚拟机
Code 交互式编程，读写本地文件 能

桌面版核心特性：

  • 并行多会话 + Git Worktree 自动隔离
  • 可视化 Diff（逐行批注、Claude 自审）
  • 拖拽拼接面板（聊天、Diff、预览、终端、编辑器）
  • 应用预览（内嵌浏览器实时预览前端代码）
  • 三种运行环境：本地 / Anthropic 云端 / SSH 远程
  • Computer Use（Agent 截图、点击、控制桌面应用）

5. 首次使用配置

验证安装

claude --version
claude doctor          # 全面的健康检查

启动与认证

在项目目录中启动：

cd ~/your-project
claude

首次启动会触发认证，有两种方式：

方式一：OAuth 浏览器登录（推荐）
  1. 终端运行 claude，浏览器自动打开
  2. 在 claude.ai 授权即可
  3. SSH 远程环境：按 c 复制认证 URL，在本地浏览器打开后粘贴代码

适用于 Claude Pro/Max/Team/Enterprise 订阅用户。

方式二：API Key 认证
# 永久设置
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.zshrc
source ~/.zshrc

或在配置文件中设置：

// ~/.claude/settings.json
{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-..."
  }
}

适用于 Anthropic Console API 用户。API Key 优先级高于 OAuth，如果同时存在会按 API 用量计费而非订阅额度。

验证认证状态：

claude -p "hello" --print

基础配置

配置文件层级：

层级 路径 作用范围
全局用户 ~/.claude/settings.json 所有项目
全局本地 ~/.claude/settings.local.json 所有项目
项目级别 <project>/.claude/settings.json 当前项目
项目本地 <project>/.claude/settings.local.json 当前项目

settings.json 基本结构：

{
  "model": "sonnet",
  "effortLevel": "xhigh",
  "alwaysThinkingEnabled": false,
  "skipDangerousModePermissionPrompt": false,
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-..."
  },
  "permissions": {
    "allow": [
      "Bash(npm:*)",
      "Read(/tmp/**)"
    ],
    "deny": []
  },
  "autoUpdatesChannel": "stable"
}

初始化项目

在项目根目录运行 /init 命令可自动生成 CLAUDE.md 文件，帮助 Claude Code 更好地理解代码库。

6. 更新与卸载

更新

Native 安装（自动更新）：

# 查看自动更新状态
claude doctor

# 手动触发更新
claude update

# 指定版本
curl -fsSL https://claude.ai/install.sh | bash -s -- 2.1.100

可设置更新通道：

{
  "autoUpdatesChannel": "stable"   // "stable" 或 "latest"
}

禁用自动更新：

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

其他方式：

# Homebrew
brew upgrade claude-code

# WinGet
winget upgrade Anthropic.ClaudeCode

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

卸载

# Native 安装
rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude

# Homebrew
brew uninstall --cask claude-code

# WinGet
winget uninstall Anthropic.ClaudeCode

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

清除全部配置文件：

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

⚠️ 此操作会删除所有设置、已授权工具、MCP 配置和会话历史。

7. 常见问题

❌ “command not found” 找不到 claude

安装完成但 shell 找不到命令。

解决：

# macOS — 添加到 ~/.zshrc
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Linux — 添加到 ~/.bashrc
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Windows 用户关闭并重新打开终端。

❌ 多次安装冲突

同时存在 npm + native + Homebrew 多个版本导致混乱。

清理所有安装后重装：

npm uninstall -g @anthropic-ai/claude-code
brew uninstall --cask claude-code
winget uninstall Anthropic.ClaudeCode  # Windows

# 诊断当前状态
which -a claude
claude doctor

# 重新安装（推荐 native）
curl -fsSL https://claude.ai/install.sh | bash

❌ macOS Gatekeeper 阻止

"Claude Code" cannot be opened because the developer cannot be verified

解决： 系统设置 → 隐私与安全性 → 点击"仍要打开"，或：

xattr -dr com.apple.quarantine /opt/homebrew/bin/claude

❌ npm EACCES 权限被拒绝

npm ERR! code EACCES
npm ERR! Error: EACCES: permission denied

解决（推荐）： 改用 Native 安装器，完全不需要 npm：

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

❌ Windows “Git is required”

桌面版提示 “Git is required” 红色错误。

解决： 安装 Git for Windows 并重启应用。

❌ Windows 执行策略限制

无法加载文件，因为在此系统上禁止运行脚本

解决：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

❌ 网络相关问题

问题 解决方法
curl: (22) 返回 403 区域不支持或网络阻止，尝试 VPN
npm 安装超时 npm config set proxy http://proxy:port
TLS 连接错误 更新 CA 证书：sudo apt-get install ca-certificates
企业代理 SSL export NODE_EXTRA_CA_CERTS=/path/to/corp-ca.pem

❌ SSH 远程无法打开浏览器认证

终端运行 claude 后无法弹出浏览器。

解决： 在认证提示界面按 c 键，复制认证 URL 到本地浏览器打开，将授权码粘贴回终端即可。

8. CI/CD 环境安装

Docker

FROM node:22-alpine
RUN npm install -g @anthropic-ai/claude-code
ENV CLAUDE_CODE_CI_MODE=true
ENTRYPOINT ["claude", "-p"]

GitHub Actions

- name: Install Claude Code
  run: npm install -g @anthropic-ai/claude-code

- name: Run Code Review
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  run: |
    git diff origin/main...HEAD | claude -p \
      "Review this diff for bugs and security issues" \
      --output-format json > review.json

关键 CI 参数

参数 说明
-p "prompt" 非交互单次提示
--output-format json 结构化 JSON 输出
--dangerously-skip-permissions 跳过交互确认（仅 CI）
--max-turns N 限制代理迭代次数
--allowedTools "Read,Grep,Glob" 限制可用工具

📚 参考资料

  • 官方安装文档：https://code.claude.com/docs/en/setup
  • 桌面快速入门：https://code.claude.com/docs/en/desktop-quickstart
  • 官方故障排除：https://support.claude.com/en/articles/14552646
  • GitHub 仓库：https://github.com/anthropics/claude-code
# github # 开源软件
Logo
DeepSeek技术社区

欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。

更多推荐

cover

分不清 Trae、通义灵码、MarsCode、Cursor？按开发场景选，一步不踩坑

avatar DeepSeek技术社区
cover

你的 Agent 为什么总失忆？—— Memory 设计从入门到 Claude Code

avatar DeepSeek技术社区
cover

【案例分享】全网首个华三数据中心流量可视化实验，基于EVE-NG V7平台

avatar DeepSeek技术社区