Claude Code 使用指南

Claude Code 是一款直接在终端中运行的 AI 编程助手，它通过深度理解您的代码库，以自然语言指令帮助您加速编码、调试和项目管理。本指南将为您提供从安装、基础使用到高级集成的全方位介绍。

注意：Claude官方不支持中国大陆用户使用他们的服务，所以需要配置API中转的方式来使用，而且使用这种方式后不需要登录Claude账户，文末有介绍如何配置中转。

一、安装与配置

在开始之前，请确保您的系统满足基本要求。

1.1 系统要求

操作系统: macOS 10.15+, Ubuntu 20.04+/Debian 10+, 或 Windows 10+ (需使用 WSL 1/2)。
软件: 需要 Node.js 18 或更高版本。
硬件: 建议至少 4GB 内存。

1.2 安装步骤

Claude Code 提供了多种安装方式，最常用的是通过 npm (Node.js 包管理器) 进行全局安装。

通过 npm 安装： 在您的终端执行以下命令：

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

重要提示: 请勿使用 sudo 进行安装，这可能导致权限问题和安全风险。

原生二进制安装 (Beta): 对于 macOS、Linux 和 WSL 用户，也可以使用以下命令进行安装：

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

对于 Windows PowerShell 用户：

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

1.3 首次启动与认证

安装完成后，在您的项目根目录下启动 Claude Code：

1
2
cd /path/to/your/project
claude

首次运行时，系统会提示您登录。您可以选择通过 Claude.ai 账户（适用于Pro或Max订阅计划）或 Claude Console 账户（使用API积分）进行认证。登录成功后，您的凭证将被安全存储，无需重复登录。

二、基础使用

Claude Code 提供了两种主要的交互方式：交互模式和一次性命令。

2.1 交互模式 (REPL)

直接运行 claude 命令即可进入交互模式，您可以在此与 AI 进行连续对话，执行编码任务。

2.2 常用CLI命令

claude "修复这个bug": 启动交互模式并传入一个初始指令。
claude -p "解释这个函数": 运行一次性查询并立即退出，适用于快速获取信息。
claude commit: 使用 AI 辅助生成 Git 提交信息。
claude --resume 或 -r: 显示历史对话列表，方便您选择并继续之前的工作。
claude --continue 或 -c: 立即恢复最近一次的对话。

2.3 斜杠命令

在交互模式中，您可以使用内置的斜杠命令来执行特定操作：

/help: 查看所有可用命令。
/init: 自动分析项目并创建一个 CLAUDE.md 配置文件。
/clear: 清除当前对话历史，以避免上下文过长导致的干扰。
/login: 重新登录或切换账户。

三、 MCP (Model Context Protocol) 集成

MCP 是一个开源标准，允许 Claude Code 连接到外部工具和数据源，极大地扩展其功能。

3.1 什么是MCP？

通过 MCP，Claude Code 可以访问本地文件系统、查询数据库、调用 API、集成项目管理工具（如 Jira）和监控系统（如 Sentry）等。这使得 AI 能够执行更复杂的自动化工作流。

3.2 如何添加MCP服务器？

您可以通过命令行轻松添加和管理 MCP 服务器。

常用命令:

claude mcp add <名称> <命令>: 添加一个新的 MCP 服务器。
claude mcp list: 列出所有已配置的服务器。
claude mcp remove <名称>: 删除一个服务器。

示例：添加文件系统访问 这是最常用的 MCP 服务器之一，允许 Claude Code 直接读写您指定目录中的文件。

1
claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem ~/Documents

3.3 热门MCP服务器推荐

Sequential Thinking: 帮助 Claude 更好地进行链式思考，解决复杂问题。
Playwright / Puppeteer: 用于 Web 自动化测试和数据抓取。
PostgreSQL / Docker: 直接通过自然语言查询数据库或管理容器。

四、核心配置文件说明

Claude Code 使用分层配置系统，其中 .claude.json 和 CLAUDE.md 是核心。配置加载的优先级为：项目内的 .claude.json > 用户主目录的 .claude.json > 全局默认配置。

4.1 全局与项目级配置文件 `.claude.json`

.claude.json 文件允许您为特定项目或所有项目自定义 Claude Code 的行为。

文件位置:

项目级: 放在项目的根目录下 (/path/to/your/project/.claude.json)。这里的配置只对该项目生效。
全局 (用户级): 放在用户主目录的配置文件夹下 (~/.config/claude/.claude.json)。这里的配置会作为所有项目的默认设置。

常用配置项说明:

model: 指定默认使用的 Claude 模型。建议使用最新的强大模型以获得最佳体验。
temperature: 控制模型输出的“创造性”或“随机性”。值在 0 到 1 之间，0 表示更确定和一致的输出，1 表示更有创意的输出。对于编码任务，建议使用较低的值 (如 0.2)。
prompt: 添加一个自定义的系统提示 (System Prompt)，用于在每次对话开始时为 AI 设定角色、风格或提供特定指令。
commit: 自定义 claude commit 命令的行为，例如可以修改提示词模板。
mcp: 在配置文件中声明项目所需的 MCP 服务器，这样团队成员无需手动添加，保证环境一致性。

示例 .claude.json 文件:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
  // 指定默认使用的模型为 Claude 3 Opus
  "model": "claude-3-opus-20240229",

  // 设置一个较低的 temperature 以保证代码输出的准确性
  "temperature": 0.2,

  // 自定义系统提示，要求 AI 始终以高级软件工程师的身份回答
  "prompt": "You are an expert senior software engineer. Your responses should be clear, concise, and technically accurate. When providing code, always explain your reasoning.",

  // 自定义 claude commit 的行为
  "commit": {
    // 修改用于生成提交信息的提示词
    "prompt": "Based on the following git diff, generate a concise and descriptive commit message following the Conventional Commits specification. The message should be in Chinese."
  },

  // 为本项目自动配置 MCP 服务器
  "mcp": {
    "servers": [
      {
        // 为这个服务器命名为 "fs"
        "name": "fs",
        // 定义启动服务器的命令
        "command": "npx -y @modelcontextprotocol/server-filesystem .",
        // 标记为用户会话级服务器
        "scope": "user"
      }
    ]
  }
}

4.2 `CLAUDE.md`：项目的“说明书”

CLAUDE.md 是一个 Markdown 格式的文件，用于向 AI 提供关于项目的关键上下文信息。当 AI 对项目结构、技术栈或工作流程有疑问时，它会优先查阅此文件。

作用:

提供项目背景: 描述项目的技术栈、包管理器、代码规范等。
定义常用命令: 列出开发、测试和构建等常用命令，避免 AI 猜测。
规范工作流程: 说明 Git 分支命名规则、提交信息格式等团队协作规范。

创建方式:

自动创建: 在项目根目录运行 /init 命令，Claude Code 会自动分析您的项目并生成一个基础的 CLAUDE.md 文件。
手动创建: 您也可以在项目根目录、用户主目录 (~/.claude/CLAUDE.md) 或子目录中手动创建该文件。

示例 CLAUDE.md:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
# CLAUDE.md - My Awesome Project

## 项目概述
- **技术栈**: React + TypeScript + Vite
- **包管理器**: pnpm
- **代码规范**: ESLint + Prettier

## 常用命令
- `pnpm dev`: 启动开发服务器
- `pnpm test`: 运行单元测试
- `pnpm build`: 构建生产版本

## 代码风格约定
- 优先使用函数组件和 Hooks。
- 组件文件名使用 PascalCase (例如: `MyComponent.tsx`)。

## Git 工作流程
- 分支命名: `feature/TICKET-123-description`
- 提交信息请遵循 Conventional Commits 规范。

通过精心编写 .claude.json 和 CLAUDE.md，您可以极大地提升 Claude Code 理解项目意图的准确性和效率，使其成为您开发流程中更强大、更可靠的伙伴。

五、 API中转服务

Claude Code 支持的地区列表

目前 Claude Code 主要支持以下地区:

美国:所有州完全支持
英国:完整功能访问
加拿大:部分省份支持
欧盟国家:德国、法国、荷兰等主要国家
澳大利亚:有限功能支持

中国大陆、香港、澳门及部分东南亚国家目前无法直接访问 Claude Code 服务。

配置中转服务

大家可以在网上找一些中转服务，一般注册后，会提供 API Key 和 中转API地址。

Windows 系统: 配置中转服务
设置系统环境变量，添加 ANTHROPIC_AUTH_TOKEN 为上述的 API Key 和 ANTHROPIC_BASE_URL 为上述的 中转API地址
MacOS/Linux 系统: 配置中转服务
添加 ANTHROPIC_AUTH_TOKEN 为上述的 API Key 和 ANTHROPIC_BASE_URL 为上述的 中转API地址 到 ~/.bashrc 或 ~/.zshrc 文件中。
1 2
export ANTHROPIC_AUTH_TOKEN="API Key" export ANTHROPIC_BASE_URL="中转API地址"

测试

配置完成后，在命令行中就能够支持使用 Claude Code，而不需要提示授权登录，也不会提示无法访问