Claude Code 安装配置使用指南

bug制造者阿杜2026-04-17 16:59

Claude Code 安装配置使用指南

1. 什么是 Claude Code

Claude Code 是 Anthropic 推出的一款终端 AI 编程代理工具 ，与传统代码补全插件（如 Copilot）不同，它是任务驱动型的------你描述目标，它会自主规划步骤、读取项目代码、执行命令、修改文件。它直接运行在终端中，与开发者的原生工作流深度融合 。

核心能力：

  • 实时代码生成、解释与优化
  • 多语言支持（Python、JavaScript、Java、Go 等）
  • 可直接执行 Shell 命令、操作 Git
  • 支持 MCP 协议扩展，连接外部工具和数据源
  • 自然语言交互，无需依赖图形界面

2. 安装前的环境准备

2.1 系统要求

要求项 说明
操作系统 macOS 13+ / Ubuntu 20.04+ / Debian 10+ / Windows 10+（需 Git Bash 或 WSL）
Node.js 版本 ≥ 18.0
RAM 建议 8 GB 及以上
Git 2.23 及以上（推荐）

2.2 安装 Node.js

Claude Code 依赖 Node.js 运行环境。在终端中执行 node -v 检查是否已安装，若版本低于 18.0 或未安装，参考以下方式 ：

macOS（使用 Homebrew）：

bash 复制代码 
brew install node

Ubuntu/Debian：

bash 复制代码 
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

Windows： 访问 nodejs.org 下载 LTS 版本安装包，安装时勾选 "Add to PATH"。

3. 安装 Claude Code

3.1 方式一：原生安装脚本（推荐）

这是 Anthropic 官方推荐的安装方式，会自动处理依赖并支持后台自动更新 ：

bash 复制代码 
curl -fsSL https://claude.ai/install.sh | bash
claude --version  # 验证安装

3.2 方式二：npm 全局安装

bash 复制代码 
npm install -g @anthropic-ai/claude-code

安装完成后验证：

bash 复制代码 
claude --version

注意 ：Anthropic 已逐步弃用 npm 安装方式，建议优先使用原生安装脚本。若已用 npm 安装，可运行 claude install 迁移到原生版本 。

3.3 方式三：Homebrew 安装（macOS）

bash 复制代码 
brew install --cask claude-code

Homebrew 安装不会自动更新，需定期运行 brew upgrade claude-code 。

4. 配置 API 密钥

4.1 获取 API Key

  1. 访问 Anthropic 官网 Console
  2. 注册/登录账号，进入 API Keys 页面
  3. 点击 Create Key ，为密钥命名（如 claude-code-local）
  4. 立即复制保存------密钥仅显示一次，关闭页面后将无法再次查看
  5. 新账号通常有 5 美元免费额度

4.2 配置方式一：settings.json（推荐）

Claude Code 支持通过 settings.json 文件统一管理配置，更清晰、便于版本控制 。

创建全局配置文件 ~/.claude/settings.json：

bash 复制代码 
mkdir -p ~/.claude

编辑文件内容：

json 复制代码 
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-your-api-key-here",
    "ANTHROPIC_BASE_URL": "https://api.anthropic.com"
  },
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

密钥安全提示：

  • 使用 ANTHROPIC_AUTH_TOKEN 而非硬编码到代码中
  • 通过 permissions.deny 阻止 AI 读取 .env 等敏感文件
  • 不要将包含真实密钥的配置文件提交到 Git

项目级配置 （可选）：在项目根目录创建 .claude/settings.json，配置优先级高于全局配置 。

4.3 配置方式二：环境变量

若习惯使用环境变量，在 Shell 配置文件（~/.zshrc 或 ~/.bashrc）中添加：

bash 复制代码 
# Anthropic API 配置
export ANTHROPIC_AUTH_TOKEN="sk-your-api-key-here"
export ANTHROPIC_BASE_URL="https://api.anthropic.com"

保存后执行 source ~/.zshrc（或 source ~/.bashrc）使配置生效 。

4.4 使用第三方 API 兼容服务

国内用户或希望使用其他模型的开发者，可配置第三方兼容 Anthropic API 的服务 ：

服务商 Base URL 说明
七牛云 AI https://api.qnaigc.com 支持 Kimi、DeepSeek 等模型
硅基流动 https://api.siliconflow.cn/ 需注册获取 API Key
金山云星流 https://kspmas.ksyun.com 企业级 API 服务

配置示例（以七牛云为例）：

json 复制代码 
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-your-qiniu-key",
    "ANTHROPIC_BASE_URL": "https://api.qnaigc.com",
    "ANTHROPIC_MODEL": "moonshotai/kimi-k2-thinking"
  }
}

5. 启动与验证

5.1 首次启动

在终端中进入项目目录，运行：

bash 复制代码 
claude

首次启动时，Claude Code 会：

  • 请求当前目录的访问授权
  • 显示欢迎信息和配置状态
  • 进入交互式对话界面

5.2 验证配置

在 Claude Code 交互界面中输入 /status，检查：

  • ✅ Base URL 正确显示
  • ✅ API Key 状态为"已设置"
  • ✅ 模型配置正确

6. 核心命令与工具使用

6.1 高频斜杠命令

命令 用途 使用场景
/init 扫描项目生成 CLAUDE.md 新项目接入时首次使用，让 AI 理解项目结构
/model 切换使用的模型 简单任务切小模型节省 Token
/cost 查看本次会话费用 控制成本
/clear 清空对话历史 切换任务时避免上下文干扰
/compact 压缩当前对话上下文 对话过长时保持 AI 聚焦
/review 让 AI 做 Code Review 提交代码前检查
/mcp 管理 MCP 服务器 接入外部工具

6.2 交互前缀与修饰符

语法 作用 示例
@文件路径 引用文件作为上下文 请 review @src/utils/auth.ts
!命令 执行终端命令，输出作为上下文 ! npm run test
#信息 存入 AI 长期记忆 # 本项目使用 TypeScript 严格模式
think hard / ultrathink 扩展思考深度（复杂任务） ultrathink 帮我设计这个模块的架构

6.3 键盘快捷键

快捷键 功能
Ctrl + C 打断当前 AI 执行
Ctrl + O 切换详细输出，查看 AI 思考过程
Shift + Tab 切换权限模式（确认模式 ↔ 自动执行）
Esc + Esc 撤销上一次文件改动（救命键）
Shift + Enter 多行输入换行

6.4 三种交互模式

模式 切换方式 说明
Interactive 默认 每步操作需人工确认
Auto-accept Shift + Tab AI 自动执行，适合简单明确任务
Plan 连按两次 Shift + Tab 仅制定计划，不修改代码

7. 进阶功能配置

7.1 MCP 服务器：连接外部工具

MCP（Model Context Protocol）让 Claude Code 能调用数据库、API、浏览器等外部工具 。

添加 MCP 服务器示例（以 Context7 文档查询工具为例）：

bash 复制代码 
claude mcp add --transport http context7 https://api.context7.com

三种传输方式：

  • HTTP：适合远程服务调用
  • SSE：服务端推送，适合流式数据
  • Stdio：本地进程通信，最常用

7.2 自定义命令

在 ~/.claude/commands/（全局）或 .claude/commands/（项目级）创建 .md 文件，即可定义专属命令 。

示例：创建 ~/.claude/commands/optimize.md

markdown 复制代码 
分析这段代码的性能问题，并提出优化建议。重点关注：
- 算法效率
- 内存使用模式
- 数据库查询优化
- 缓存使用可能性

使用时直接输入 /optimize 即可调用。

7.3 Hooks 钩子：自动化工作流

在关键事件节点自动触发自定义脚本 ：

事件 触发时机
PreToolUse 工具调用前（如执行命令前做安全检查）
PostToolUse 工具调用后（如自动运行 eslint --fix）
SessionStart 会话启动时
PreCompact 上下文压缩前

8. VS Code 插件集成

8.1 安装与配置

  1. 在 VS Code 扩展商店搜索 Claude Code for VS Code（蓝色机器人图标）并安装
  2. 点击扩展齿轮图标 → Extension Settings
  3. 配置 API Key 和 Base URL（同 CLI 配置）
  4. 或在 settings.json 中添加：
json 复制代码 
{
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://api.anthropic.com" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-****" }
  ]
}

8.2 常用 VS Code 快捷键

快捷键 功能
Cmd/Ctrl + Esc 启动 Claude Code
Cmd/Ctrl + Option + K 将选中代码添加到 Claude 上下文

9. 常见问题排查

问题 可能原因 解决方案
Invalid API Key 密钥错误或未生效 检查是否含多余空格；重启终端；确认配置文件中 ANTHROPIC_AUTH_TOKEN 已正确设置
Model not found 模型名错误 使用 /status 检查配置；确认第三方服务的模型名称正确
终端显示 offline 网络检测服务不可达 不影响核心功能，只要能连接 API 地址即可
fetch failed 网络无法访问 Base URL 检查代理设置；尝试切换备用 Base URL
对话越来越慢 上下文过长 使用 /compact 压缩或 /clear 清空
Windows 下命令无效 缺少 Git Bash 安装 Git for Windows

10. 最佳实践总结

  1. 首次使用先 /init：让 AI 生成项目理解文件，后续交互更精准
  2. 复杂任务先规划 ：使用 Plan 模式或 ultrathink 让 AI 先出方案再执行
  3. 善用 # 长期记忆：将项目约定、技术栈等关键信息存入记忆
  4. 密钥不进 Git ：用环境变量或 settings.json，并在 .gitignore 中加入 .claude/
  5. 选对模型省成本：简单任务用 Haiku 或第三方高性价比模型，复杂推理再用 Sonnet/Opus
  6. Esc + Esc 是救命键：AI 改坏了代码双击 Esc 即可回退

参考资源

相关推荐
独隅1 小时前
Claude 高效使用指南与效果展示
claude·claude code
ZzT6 小时前
Claude Duet 安全设计拆解：替你回邮件、付账单的 agent，碰不到你的密码
ai编程·claude
小七-七牛开发者6 小时前
当 Agent 接手更多工作，我们还能把好关吗？
ai·openai·agent·claude
独隅6 小时前
Claude 高效使用指南深度评测
java·开发语言·claude·claude code
yjm0027 小时前
如何用 Claude Opus 5.5 做一支音乐 MV？代码逐帧渲染完整教程（2026）
ai编程·claude
独隅7 小时前
Claude 新手入门与高效调用指南
claude
独隅8 小时前
Claude 高效应用实战指南
android·java·开发语言·claude·claude code
技术小甜甜10 小时前
【Copilot】能选 Claude 和 GPT-6 了，Excel 分析该交给谁
gpt·excel·copilot·claude·microsoft365·gpt-6
lugiax1 天前
开着 Auto Mode 通宵让 AI 敲代码，为什么早上醒来还是卡在半夜？
ai编程·claude
热门推荐
01国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）02如何新建文件夹？ 电脑新建文件夹的4种方法03历年考研数学一、数学二、数学三真题试卷及答案PDF04GitHub 镜像站点05几个好用的ip纯净度检测网站06苹果iPA游戏软件资源下载网站07昇腾910B系列芯片完全指南：四款型号对比、服务器选型与大模型部署实战08ai安全工具:CyberStrikeAI安装部署与使用09蜘蛛磁力 搜索引擎大全，如何使用蜘蛛磁力查找磁力链接10Windows 10/11 如何退出微软账户并改用本地账户登录（含找不到选项的解决方法）