Claude Code 完整配置教程：从安装到国内使用（2026 保姆级指南）

适合人群

• 想在国内使用 Claude Code 进行 AI 编程的开发者
• 已有编程基础，想用 AI 提升开发效率的工程师
• 需要了解 Claude Code 安装、配置、MCP 接入的完整流程
• 遇到 Claude Code 报错不知道怎么解决的用户

准备清单

在开始之前，请确保你具备以下条件：

• 一台电脑（Windows / macOS / Linux 均可）
• Node.js 18+ 已安装（推荐 LTS 版本）
• 稳定的网络环境（国内用户需要代理）
• 一个 Anthropic Console 账号 或 Claude Pro/Max 订阅
• 终端/命令行基础操作能力

还没有 Claude 订阅？查看我们的 ChatGPT Plus 和 Claude Pro 开通指南，一站式解决 AI 工具订阅问题。

什么是 Claude Code？

Claude Code 是 Anthropic 推出的 AI 编程助手，直接运行在终端里。它能读懂你的整个代码库，帮你写功能、修 Bug、跑命令、提交代码——而且是全自动的。

与其他 AI 编程工具相比，Claude Code 的核心优势：

• 直接在终端运行，不依赖 IDE
• 能读取整个代码库上下文
• 支持多种部署方式（终端、VS Code、JetBrains、桌面端、浏览器）
• 支持第三方大模型接入（国内用户福音）
• 通过 MCP 协议连接外部工具

第一步：安装 Claude Code

macOS / Linux / WSL 安装

打开终端，执行官方一键安装脚本：

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

这个脚本会自动检测系统环境、下载最新版本、配置 PATH。

Windows 安装

PowerShell 方式（推荐）：

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

CMD 方式：

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

注意：如果报错 The token '&&' is not a valid statement separator，说明你在 PowerShell 里但用了 CMD 语法。反之，如果 'irm' is not recognized，说明你在 CMD 里用了 PowerShell 语法。 提示：PowerShell 窗口显示 PS C:\，CMD 窗口只显示 C:\（没有 PS）。

Windows 原生安装需要先安装 Git for Windows。 如果你用 WSL 则不需要额外安装 Git。

通过 npm 安装（备选方案）

如果你已经安装了 Node.js，也可以通过 npm 安装：

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

验证安装

claude --version

如果显示版本号，说明安装成功。

第二步：首次登录

进入你的项目目录，启动 Claude Code：

cd your-project
claude

首次运行会引导你登录。有两种认证方式：

方式一：Claude 订阅账号登录

如果你有 Claude Pro、Max 或 Team 订阅，直接通过浏览器 OAuth 登录即可。

方式二：Anthropic Console API Key

如果你是开发者，使用 API Key 认证：

export ANTHROPIC_API_KEY="sk-ant-xxxxx"

将 API Key 添加到你的 shell 配置文件（~/.bashrc 或 ~/.zshrc）中使其永久生效：

echo 'export ANTHROPIC_API_KEY="sk-ant-xxxxx"' >> ~/.bashrc
source ~/.bashrc

第三步：国内用户网络配置（关键！）

国内用户直接使用 Claude Code 会遇到网络连接问题，需要进行代理配置。

方法一：配置 HTTP 代理

如果你有代理服务，设置环境变量：

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

将端口号替换为你实际的代理端口。常见代理软件端口：

• Clash: 7890
• V2Ray: 10808 或 1080
• SSR: 1080

方法二：使用第三方 API 中转

如果你有 OpenAI 兼容的 API 中转服务（如国内大模型 API），可以配置 Claude Code 使用第三方提供商：

export ANTHROPIC_BASE_URL="https://your-api-proxy.com"
export ANTHROPIC_API_KEY="your-api-key"

方法三：接入国内大模型

Claude Code 支持通过 OpenAI 兼容接口接入国内大模型。配置方法：

# 以 DeepSeek 为例
export OPENAI_BASE_URL="https://api.deepseek.com/v1"
export OPENAI_API_KEY="your-deepseek-api-key"

支持的国内模型包括：

• DeepSeek（推荐，代码能力强）
• 通义千问（阿里）
• GLM-4（智谱）
• MiniMax
• 月之暗面（Moonshot/Kimi）

注意：第三方模型的代码能力可能与 Claude 原生模型有差距，建议优先使用 Claude 原生模型 + 代理的方式。

第四步：配置 MCP 服务器

MCP（Model Context Protocol）是 Claude Code 连接外部工具的协议。通过 MCP，你可以让 Claude Code 访问数据库、调用 API、操作文件等。

在项目根目录创建 MCP 配置

创建 .claude/mcp.json 文件：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token"
      }
    }
  }
}

常用 MCP 服务器

验证 MCP 配置

启动 Claude Code 后，输入：

/mcp

可以查看已连接的 MCP 服务器状态。

第五步：CLAUDE.md 配置 — 让 Claude 更懂你的项目

在项目根目录创建 CLAUDE.md 文件，给 Claude 写项目说明：

# 项目说明

这是一个 React + TypeScript 项目。

## 技术栈
- React 18
- TypeScript 5
- TailwindCSS
- Vite

## 代码规范
- 使用函数式组件
- 使用 TypeScript 严格模式
- CSS 使用 TailwindCSS 类名

## 目录结构
- src/components/ — UI 组件
- src/hooks/ — 自定义 Hooks
- src/utils/ — 工具函数
- src/api/ — API 调用

Claude Code 会自动读取这个文件，了解你的项目背景。

多级 CLAUDE.md

Claude Code 支持多层级的配置文件：

第六步：常用命令和快捷操作

启动和基本操作

# 启动 Claude Code
claude

# 非交互模式（管道输入）
echo "解释这个函数的作用" | claude

# 指定模型
claude --model claude-sonnet-4-20250514

# 继续上一次对话
claude --continue

权限模式

Claude Code 有三种权限模式：

通过 /mode 命令切换。

常用斜杠命令

第七步：Claude Code Skills 配置

Skills 是 Claude Code 的可复用工作流。你可以创建自定义 Skills 来自动化常见任务。

创建 Skill

在 .claude/skills/ 目录下创建 Markdown 文件：

---
name: code-review
description: 代码审查工作流
---

# 代码审查工作流

## 步骤
1. 读取 git diff 获取变更内容
2. 分析代码质量、安全性、性能
3. 给出改进建议
4. 生成审查报告

使用 Skill

在 Claude Code 中输入：

/skill code-review

常见问题

Q: 安装时报错 "command not found: claude"

A: 检查以下几点：

1. 安装脚本是否执行成功
2. PATH 是否包含 Claude Code 安装路径
3. 尝试重新打开终端窗口
4. 手动添加 PATH：export PATH="$HOME/.claude/bin:$PATH"

Q: 连接超时 / 网络错误

A: 国内用户常见问题：

1. 确认代理是否正常运行
2. 检查 HTTP_PROXY 和 HTTPS_PROXY 环境变量是否设置正确
3. 尝试 curl -I https://api.anthropic.com 测试连通性
4. 如果使用 API 中转，确认 ANTHROPIC_BASE_URL 配置正确

Q: 401 认证失败

A: 可能的原因：

1. API Key 过期或无效 — 去 Anthropic Console 重新生成
2. API Key 有多余空格 — 检查环境变量是否包含引号或空格
3. 使用了错误的 Base URL — 确认 API 端点地址

Q: Token 花费太快怎么办？

A: 省钱技巧：

1. 使用 /compact 命令压缩上下文
2. 在 CLAUDE.md 中明确项目规范，减少重复解释
3. 使用 --model 指定更便宜的模型（如 Haiku）
4. 避免粘贴超大文件，用 @文件名 引用

Q: Claude Code 和 Cursor、GitHub Copilot 有什么区别？

A:

• Claude Code：终端原生、理解完整代码库、支持 MCP 扩展、可自动化复杂任务
• Cursor：IDE 内集成、实时补全、可视化操作
• GitHub Copilot：IDE 插件、实时补全、集成 GitHub

Claude Code 更适合处理复杂的多步骤任务和自动化工作流。

参考来源

• Claude Code 官方文档
• Claude Code 第三方集成指南
• MCP 协议官方文档
• Anthropic API 文档
• Claude Code GitHub
• Claude 定价页面

下一步建议

• 阅读 Claude Code 最佳实践，提升使用效率
• 探索 MCP 工具生态，连接更多工具
• 尝试 Claude Code VS Code 扩展，在 IDE 中使用
• 了解 Claude Code Agent SDK，构建自定义 Agent