Claude Code 完整安装攻略:手把手小白到精通

2026-07-24 11:46:34 AI老猿博士

摘要：本文是一份面向初学者的 Claude Code 安装与配置指南。Claude Code 是 Anthropic 推出的 AI 编程助手，可以通过命令行使用。本文详细介绍了从系统要求、账号注册、API Key 配置，到多种安装方式（推荐脚本安装）、环境变量设置、首次启动验证，再到 IDE 集成和进阶模型配置的全过程。核心目标是帮助读者快速、正确地完成 Claude Code 的安装与基础配置，并开始使用。

适用版本：v2.1.133（验证于 2026-06-10） | 安装方式：原生安装 + npm 标准安装并存

🎯 学习目标

通过本指南，你将能够：

理解 Claude Code 的核心概念：掌握 CLI、API Key、环境变量等关键术语
完成 Claude Code 的完整安装：根据你的操作系统选择最适合的安装方式
正确配置 API Key 和环境变量：确保 Claude Code 能够正常连接 Anthropic 服务
验证安装并成功启动：运行 Hello World 项目确认一切正常
集成到常用 IDE 中：在 VS Code、Cursor、JetBrains 等开发环境中使用 Claude Code
排查常见问题：遇到安装、配置、启动等问题时能够快速定位并解决

🗺️ 学习导航（思维导图）

以下是本指南的学习路径，建议按顺序阅读：

阶段	主要内容	预计耗时	关键产出
📚 准备阶段	了解系统要求注册 Anthropic 账号获取 API Key	10-15分钟	可用的 API Key
⚙️ 安装阶段	选择安装方式（推荐脚本安装）完成 Claude Code 安装配置 PATH 环境变量（Windows 用户必读）	5-10分钟	安装成功的 Claude Code
🔧 配置阶段	设置环境变量首次启动与初始化 Hello World 验证	5-10分钟	可正常运行的 Claude Code
🚀 进阶阶段	IDE 集成配置模型配置与选择权限管理与安全注意事项	10-20分钟	深度集成的开发环境
🛠️ 排错阶段	常见问题排查错误分析与解决性能优化建议	按需	问题解决能力

快速定位：

如果你是完全新手：请从「一、系统要求」开始，按顺序阅读
如果你已有 API Key：可直接跳到「四、Claude Code 安装步骤」
如果你安装后遇到问题：请查看「九、常见问题与排查」
如果你想集成到 IDE：请查看「七、IDE 集成配置」

术语表

术语	通俗解释
CLI	命令行界面，黑色/白色的文字输入窗口
原生安装器	Claude Code官方独立安装程序，无需其他依赖
Node.js	JavaScript运行环境；npm安装路径需 18+
npm	Node.js包管理器；标准安装路径之一
API Key	API密钥，类似“通行证”，证明使用权
Token	计费单位，约0.75个英文单词或1-2个汉字
环境变量	操作系统级配置项，程序读取但不写在代码里
PATH	系统环境变量，告诉电脑去哪里找可执行程序

一、系统要求

快速检查（核心3项）

检查项	最低要求	检查方法
操作系统	Windows 10 / macOS 10.15+ / Linux	查看系统版本
内存	4GB RAM	右键“此电脑”→属性
网络	能访问网	`ping api.anthropic.com`

详细兼容性

操作系统	最低版本	推荐版本
Windows	Windows 10	Windows 11（64位）
macOS	10.15 Catalina	macOS 13+（Intel/Apple Silicon均支持）
Linux	内核3.10+	5.x+（Ubuntu/Debian/Fedora等）

二、Anthropic 账号与 API Key 配置

注册流程

访问 https://console.anthropic.com/https://console.anthropic.com/https://console.anthropic.com/https://console.anthropic.com/
https://console.anthropic.com/
点击“Sign Up”（支持Google/GitHub/邮箱注册）
手机验证（不支持 +86 中国大陆号码）

API Key 获取

进入 App unavailable in region | Claude by Anthropic
点击“Create Key”，填写名称，选择“Full Access”
立即复制并保存
格式示例：sk-xxxxxxxxxxxxxxxx...

环境变量配置

Windows（PowerShell 7，推荐）：

# 永久添加用户环境变量
[System.Environment]::SetEnvironmentVariable('ANTHROPIC_API_KEY', 'sk-ant-api03-你的key', 'User')
验证
$env:ANTHROPIC_API_KEY
临时（仅当前终端）
$env:ANTHROPIC_API_KEY="sk-ant-api03-你的key"

macOS/Linux：

# 编辑配置文件（zsh用户编辑 ~/.zshrc，bash用户编辑 ~/.bashrc）
export ANTHROPIC_API_KEY="sk-ant-api03-你的key"
重新加载
source ~/.zshrc  # 或 source ~/.bashrc
验证
echo $ANTHROPIC_API_KEY

API中转站配置（可选up8ai.com）

# 同时配置 Key 和 Base URL
export ANTHROPIC_API_KEY="你的中转站Key"
export ANTHROPIC_BASE_URL="https://你的中转站地址"

三、安装方式对比

对比项	原生安装 ⭐	npm标准安装
需要Node.js	❌ 不需要	✅ 需要 18+
安装时间	⏱️ 3-5分钟	⏱️ 30-40分钟
自动更新	✅ 内置	⚠️ 需手动更新
PATH配置	✅ 自动	⚠️ 经常出错
稳定性	✅ 生产级	⚠️ 依赖环境

四、Claude Code 安装步骤

方式1：脚本安装（推荐）

macOS / Linux / WSL：

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

Windows PowerShell：

irm https://claude.ai/install.ps1 | iex

方式2：Homebrew安装（macOS/Linux）

brew install --cask claude-code
# 更新：brew upgrade claude-code
# 卸载：brew uninstall claude-code

方式3：WinGet安装（Windows 10/11）

winget install Anthropic.ClaudeCode
# 更新：winget upgrade Anthropic.ClaudeCode

方式4：npm安装（标准兼容路径）

# 前提：Node.js 18+
node --version
全局安装
npm install -g @anthropic-ai/claude-code
验证
claude --version  # 显示 (npm)

五、PATH 环境变量配置（Windows 必读）

安装位置

原生安装：C:\Users\<用户名>\.local\bin\
npm安装：C:\Users\<用户名>\AppData\Roaming\npm\

配置方法

PowerShell命令（推荐）：

[System.Environment]::SetEnvironmentVariable(
    'Path',
    [System.Environment]::GetEnvironmentVariable('Path', 'User') + ';' + "$env:USERPROFILE\.local\bin",
    'User'
)
# 必须重启终端生效！

图形界面：

Win+R → sysdm.cpl → 高级 → 环境变量
用户变量 → Path → 新建 → 添加 %USERPROFILE%\.local\bin
确定保存，重启终端

macOS/Linux（如未自动配置）：

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

验证安装

claude --version     # 预期：Claude Code v2.1.x (native)
claude --help        # 显示帮助信息
which claude         # 或 where claude (Windows)

六、首次启动与验证

启动方式

1. 标准交互模式：

claude

2. 单次命令模式：

claude "你的问题或指令"

3. 打印模式（脚本友好）：

claude -p "你的问题"

首次启动初始化流程

选择主题：Light / Dark / System
安全须知确认：理解权限模型（沙盒隔离、确认机制、只读优先、审计日志）
目录信任确认：选择是否信任当前目录
认证方式选择：
- API Key（环境变量，推荐）
- Claude App Login（Pro/Max订阅）
- 手动输入
- 第三方平台（v2.1.92+支持Bedrock交互式向导）

配置文件结构

~/.claude/                  ← 全局配置
├── config.json
├── auth-token.json
├── trusted-directories.json
├── cache/
└── logs/
项目目录/.claude/           ← 项目级配置
├── config.json
├── commands/
├── skills/
└── hooks/

--dangerously-skip-permissions参数（重要安全警告）

作用：跳过所有权限询问，AI直接执行操作（读/写/运行命令）。

风险数据（eesel AI研究）：32%误修改率。

使用建议：

✅ 个人学习项目、只读查询
❌ 公司项目、生产环境、首次使用、敏感数据

用法：

claude --dangerously-skip-permissions -p "分析这个项目的依赖关系"

Hello World 验证

mkdir ~/claude-hello-world && cd ~/claude-hello-world
git init
claude -p "请创建一个Python Hello World项目，包含：
hello.py - 打印 'Hello, Claude Code!'
README.md - 项目说明
.gitignore - Python标准忽略文件"
python hello.py  # 预期输出：Hello, Claude Code!

验证清单

claude --version                     # v2.1.x+ (native)
claude --help                        # 显示命令列表
echo $ANTHROPIC_API_KEY              # 显示完整Key
ping api.anthropic.com               # 有响应

七、常见问题与排查

在安装、配置和启动 Claude Code 的过程中，可能会遇到一些常见问题。下表列出了这些问题及其解决方案，帮助你快速排查。

安装问题

问题现象	可能原因	排查步骤	解决方案
`command not found: claude`	PATH 环境变量未正确配置	运行 `which claude`（macOS/Linux）或 `where claude`（Windows）检查输出路径是否在 PATH 中检查安装目录是否存在	Windows：按「五、PATH 环境变量配置」重新配置 PATH macOS/Linux：运行 `echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc` npm 安装：检查 Node.js 版本（需 18+）
脚本安装失败（curl/irm 错误）	网络连接问题或脚本下载失败	检查网络连接：`ping api.anthropic.com` 尝试手动下载脚本并运行检查防火墙/代理设置	使用代理或更换网络环境手动下载安装脚本： macOS/Linux：`curl -O https://claude.ai/install.sh && bash install.sh` Windows：浏览器下载 install.ps1，右键「使用 PowerShell 运行」尝试其他安装方式（Homebrew/WinGet）
Homebrew/WinGet 安装失败	包管理器未安装或版本过旧	检查包管理器：`brew --version` 或 `winget --version` 更新包管理器：`brew update` 或 `winget upgrade --all`	安装/更新包管理器使用脚本安装（推荐）检查系统是否满足最低要求

配置问题

问题现象	可能原因	排查步骤	解决方案
`Invalid API Key` 或认证失败	API Key 未设置、格式错误或已失效	检查环境变量：`echo $ANTHROPIC_API_KEY`（macOS/Linux）或 `$env:ANTHROPIC_API_KEY`（Windows）确认 Key 以 `sk-ant-api03-` 开头在 Anthropic 控制台检查 Key 状态	重新设置环境变量（参考「二、环境变量配置」）重启终端或电脑使环境变量生效在 Anthropic 控制台生成新 Key 并替换检查是否有空格或特殊字符
网络连接超时	无法访问 Anthropic API 服务器	运行 `ping api.anthropic.com` 检查代理设置尝试访问 `https://console.anthropic.com`	配置代理：设置 `HTTP_PROXY`/`HTTPS_PROXY` 环境变量使用 API 中转站（参考「API中转站配置」）检查防火墙设置尝试更换网络环境
权限不足错误	安装目录权限问题	检查安装目录权限：`ls -la ~/.local/bin/`（macOS/Linux）尝试以管理员/root 权限运行安装命令	macOS/Linux：`sudo bash install.sh` Windows：以管理员身份运行 PowerShell 手动修改目录权限

启动与运行问题

问题现象	可能原因	排查步骤	解决方案
启动后无响应或卡住	网络问题或 API 限流	检查网络连接查看日志：`~/.claude/logs/` 尝试 `claude --version` 测试基础功能	等待几分钟后重试检查 API 使用量是否超限使用 `claude -p "简单测试"` 测试单次命令模式重启 Claude Code
命令执行失败	权限设置或沙盒限制	检查当前目录是否在信任列表中查看权限确认日志尝试在非敏感目录测试	在启动时信任当前目录使用 `--dangerously-skip-permissions`（仅限个人项目）检查配置文件中的权限设置
版本不匹配错误	多版本冲突或缓存问题	运行 `claude --version` 查看当前版本检查是否有多个安装：`which -a claude` 清除缓存：`rm -rf ~/.claude/cache/`	卸载冲突版本：`npm uninstall -g @anthropic-ai/claude-code` 重新安装最新版本更新 PATH 环境变量指向正确版本

其他问题

问题现象	可能原因	排查步骤	解决方案
IDE 集成不工作	IDE 配置错误或 PATH 问题	在终端中测试 `claude` 命令是否可用检查 IDE 的终端配置确认 IDE 使用的终端类型	重启 IDE 使环境变量生效在 IDE 设置中配置正确的终端路径参考「七、IDE 集成配置」重新配置
模型切换无效	模型别名错误或权限不足	检查当前模型：`claude --model` 查看可用模型：参考「八、模型配置」检查 API Key 权限	使用正确的模型别名：`claude --model sonnet` 升级 API 套餐以获得更多模型访问权限检查配置文件中的模型设置
输出乱码或格式错误	终端编码问题或字体不支持	检查终端编码设置尝试不同的终端应用检查系统语言和区域设置	设置终端编码为 UTF-8 安装支持 Unicode 的字体（如 Cascadia Code）使用 `claude -p` 打印模式获取纯文本输出

如果以上方法都无法解决问题：

查看详细日志
在 Anthropic 官方文档或社区论坛搜索错误信息
尝试完全卸载后重新安装
联系 Anthropic 技术支持

八、IDE 集成配置

VS Code 配置

settings.json：

{
  "terminal.integrated.defaultProfile.windows": "PowerShell",
  "terminal.integrated.defaultProfile.osx": "zsh",
  "terminal.integrated.defaultProfile.linux": "bash",
  "terminal.integrated.profiles.windows": {
    "PowerShell": {
      "source": "PowerShell",
      "icon": "terminal-powershell",
      "path": "pwsh.exe"
    }
  },
  "files.associations": {
    "CLAUDE.md": "markdown"
  },
  "files.autoSave": "afterDelay",
  "files.autoSaveDelay": 1000
}

tasks.json（.vscode/tasks.json）：

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Claude Code: 启动交互模式",
      "type": "shell",
      "command": "claude",
      "presentation": {
        "echo": true,
        "reveal": "always",
        "focus": true,
        "panel": "dedicated",
        "clear": true
      }
    },
    {
      "label": "Claude Code: 审查当前文件",
      "type": "shell",
      "command": "claude \"Review ${relativeFile} and suggest improvements\""
    },
    {
      "label": "Claude Code: 解释当前文件",
      "type": "shell",
      "command": "claude \"Explain what ${relativeFile} does\""
    },
    {
      "label": "Claude Code: 生成测试",
      "type": "shell",
      "command": "claude \"Generate unit tests for ${relativeFile}\""
    }
  ]
}

keybindings.json：

[
  { "key": "ctrl+shift+c", "command": "workbench.action.tasks.runTask", "args": "Claude Code: 启动交互模式" },
  { "key": "ctrl+shift+r", "command": "workbench.action.tasks.runTask", "args": "Claude Code: 审查当前文件" },
  { "key": "ctrl+shift+e", "command": "workbench.action.tasks.runTask", "args": "Claude Code: 解释当前文件" }
]

Cursor 配置

配置与VS Code完全相同
settings.json位置：
- Windows: C:\Users\<用户名>\AppData\Roaming\Cursor\User\settings.json
- Mac: ~/Library/Application Support/Cursor/User/settings.json

JetBrains IDEs（WebStorm/PyCharm/IntelliJ）

Settings → Tools → External Tools → 点击 +
添加工具：
- Name: Claude Code
- Program: claude
- Working directory: $ProjectFileDir$
Settings → Keymap → 搜索 External Tools → 设置快捷键

九、模型配置（进阶）

可用模型别名

别名	含义	适用场景
`default`	系统默认模型	不想手动管版本
`best`	当前最强（等价于opus）	追求最强效果
`sonnet`	最新Sonnet	日常编码主力
`opus`	最新Opus	复杂推理、架构
`haiku`	更快更轻量	简单任务
`sonnet[1m]`	Sonnet + 1M上

到此这篇关于Claude Code 完整安装指南:手把手小白到精通的文章就介绍到这了,更多相关Claude Code安装指南内容请搜索脚本之家以前的文章或继续浏览下面的相关文章，希望大家以后多多支持脚本之家！