快速开始：环境搭建与基本使用

本文档将引导您完成 Claude Code CLI 的环境搭建和基本使用流程。Claude Code 是一个基于终端的 AI 编程助手，能够协助您完成文件编辑、命令执行、代码搜索等软件工程任务。该代码库镜像源于公开暴露的源代码快照，用于教育研究、安全分析和软件供应链审计。

系统要求与环境准备

Claude Code 对运行环境有明确的技术要求，确保您的系统满足以下条件是成功运行的前提。

支持的平台

Claude Code 主要针对以下平台进行了优化和测试：

Sources: platform.ts

核心依赖要求

Claude Code 基于 Bun 运行时构建，并使用 React + Ink 框架实现终端用户界面。系统必须满足以下最低要求：

• Node.js: 版本 18 或更高（在启动时会进行版本检查）
• Bun: 作为主要运行时环境
• TypeScript: 代码库采用 TypeScript 编写（~512,000 行代码）
• 网络连接: 需要访问 Anthropic API 服务

graph TD
    A[系统环境检查] --> B{Node.js ≥ 18?}
    B -->|否| C[❌ 启动失败]
    B -->|是| D[加载配置系统]
    D --> E{认证状态}
    E -->|未认证| F[OAuth/API Key 认证]
    E -->|已认证| G[加载项目上下文]
    F --> G
    G --> H[初始化 REPL 界面]
    H --> I[✅ 就绪]
    
    style C fill:#ff6b6b
    style I fill:#51cf66

Sources: setup.ts, main.tsx

环境变量配置

Claude Code 的配置系统采用多层次优先级机制，支持通过环境变量进行灵活配置：

Sources: envUtils.ts, env.ts

安装与初始化

Claude Code 提供了多种安装方式，您可以根据实际需求选择最合适的方案。

安装流程图

flowchart LR
    Start[开始安装] --> Check{已安装?}
    Check -->|否| Install[执行安装]
    Check -->|是| Update[检查更新]
    
    Install --> Method{选择安装方式}
    Method -->|推荐| Native[原生安装<br/>~/.local/bin/claude]
    Method -->|备选| Global[全局 npm 安装]
    
    Native --> Auth[认证配置]
    Global --> Auth
    
    Update --> Auth
    Auth --> OAuth{OAuth 认证}
    OAuth -->|成功| Ready[✅ 就绪]
    OAuth -->|失败| APIKey[使用 API Key]
    APIKey --> Ready
    
    style Ready fill:#51cf66
    style Native fill:#74c0fc

Sources: install.tsx

安装方式对比

首次启动与 Onboarding 流程

首次运行 Claude Code 时，系统会引导您完成初始化配置流程。该流程采用多步骤向导设计，确保用户能够正确设置环境：

stateDiagram-v2
    [*] --> Welcome: 启动 Claude Code
    Welcome --> Theme: 欢迎界面
    Theme --> Preflight: 选择主题
    Preflight --> Auth: 系统预检
    Auth --> OAuth: 认证方式选择
    OAuth --> Security: OAuth 登录
    Auth --> APIKey: 或使用 API Key
    APIKey --> Security
    Security --> TerminalSetup: 安全提示
    TerminalSetup --> Ready: 终端配置（可选）
    Ready --> [*]: 进入 REPL

Onboarding 核心步骤：

1. 主题选择: 设置终端配色方案（可通过 /theme 命令随时更改）
2. 系统预检: 检查依赖项、权限配置等关键环境因素
3. 认证配置: 支持 OAuth 2.0 或 API Key 两种认证方式
4. 安全提示: 展示使用注意事项和最佳实践
5. 终端设置: 可选的终端配置优化（如 shell 集成）

Sources: Onboarding.tsx

认证方式详解

Claude Code 支持两种认证机制，您可以根据使用场景灵活选择：

1. OAuth 2.0 认证（推荐）

OAuth 认证提供无缝的用户体验，支持自动令牌刷新和组织级功能：

# 首次运行时自动触发 OAuth 流程
claude

# 或使用显式登录命令
/login

OAuth 认证优势：

• 自动令牌刷新，无需手动维护
• 支持组织和团队协作功能
• 符合企业安全策略要求
• 可访问 Claude.ai 订阅功能

2. API Key 认证

适用于自动化场景或无法使用 OAuth 的环境：

# 设置环境变量
export ANTHROPIC_API_KEY="sk-ant-..."

# 或在首次启动时输入
# Onboarding 流程会提示输入 API Key

Sources: login.tsx

基本使用流程

完成安装和认证后，您即可开始使用 Claude Code 的核心功能。本节将介绍基本的使用模式和常用操作。

启动与界面概览

graph TB
    subgraph "Claude Code 启动流程"
        A[cli.tsx 入口] --> B{特殊标志?}
        B -->|--version| C[输出版本号]
        B -->|--dump-system-prompt| D[输出系统提示]
        B -->|正常启动| E[加载 main.tsx]
        
        E --> F[初始化系统]
        F --> G[加载配置]
        G --> H[预取认证信息]
        H --> I[启动 REPL 界面]
        
        I --> J[用户交互循环]
        J --> K{输入类型}
        K -->|斜杠命令| L[执行命令]
        K -->|自然语言| M[发送至 Claude]
        K -->|快捷键| N[触发绑定动作]
        
        L --> J
        M --> J
        N --> J
    end
    
    style I fill:#74c0fc
    style J fill:#51cf66

Sources: cli.tsx, main.tsx

核心交互模式

Claude Code 提供三种主要的交互模式，每种模式适用于不同的使用场景：

Sources: HelpV2.tsx

常用斜杠命令速查

以下是您在日常开发中最常使用的核心命令：

项目管理类命令

代码操作类命令

工具与服务类命令

Sources: README.md, init.ts

项目初始化最佳实践

使用 /init 命令可以快速为您的项目创建配置文件。该命令采用智能分析机制，能够自动检测项目类型、构建工具和代码风格：

sequenceDiagram
    participant U as 用户
    participant C as Claude Code
    participant A as 子代理
    participant F as 文件系统
    
    U->>C: /init
    C->>U: 询问配置范围<br/>(项目级/个人级/两者)
    U->>C: 选择配置类型
    C->>A: 启动代码库分析代理
    A->>F: 读取 manifest 文件<br/>(package.json, Cargo.toml 等)
    A->>F: 读取 README、构建配置
    A->>F: 检测现有规则文件<br/>(.cursor/rules, .github/copilot-instructions.md)
    A->>C: 返回分析结果
    C->>U: 询问缺失信息<br/>(构建命令、编码规范等)
    U->>C: 补充必要信息
    C->>U: 展示配置建议<br/>(hooks/skills/notes)
    U->>C: 确认或调整建议
    C->>F: 写入 CLAUDE.md<br/>可选: CLAUDE.local.md, hooks, skills
    F->>C: 确认写入成功
    C->>U: ✅ 初始化完成

/init 命令生成的核心文件：

1. CLAUDE.md（项目级，提交到版本控制）

   • 构建和测试命令
   • 代码架构概述
   • 编码规范和最佳实践
   • 非显而易见的配置说明

2. CLAUDE.local.md（个人级，添加到 .gitignore）

   • 您的角色和熟悉程度
   • 个人沙盒 URL 和测试账号
   • 工作流偏好设置

Sources: init.ts

环境诊断与故障排查

当遇到问题时，/doctor 命令是您的首选诊断工具。它会全面检查系统环境并生成详细报告：

graph LR
    A[/doctor 命令] --> B[系统信息收集]
    B --> C[依赖检查]
    C --> D[配置验证]
    D --> E[权限审查]
    E --> F[网络测试]
    F --> G{生成诊断报告}
    
    G --> H[✅ 所有检查通过]
    G --> I[⚠️ 警告信息]
    G --> J[❌ 错误详情]
    
    I --> K[显示修复建议]
    J --> K
    
    style H fill:#51cf66
    style I fill:#ffd43b
    style J fill:#ff6b6b

/doctor 检查的关键项目：

Sources: doctor.tsx, Doctor.tsx

配置系统详解

Claude Code 采用多层次的配置系统，支持从全局到项目级的细粒度控制。理解配置层次结构对于有效使用工具至关重要。

配置文件层次结构

graph TD
    A[配置加载顺序] --> B[1. 环境变量]
    B --> C[2. 托管设置<br/>managed-settings.json]
    C --> D[3. 全局设置<br/>~/.claude/.claude.json]
    D --> E[4. 项目设置<br/>.claude/settings.json]
    E --> F[5. 会话设置<br/>命令行参数]
    
    F --> G{配置合并}
    G --> H[最终有效配置]
    
    style B fill:#e7f5ff
    style C fill:#d0ebff
    style D fill:#a5d8ff
    style E fill:#74c0fc
    style F fill:#4dabf7
    style H fill:#51cf66

配置优先级规则：后加载的配置会覆盖先前的设置，但某些配置项采用合并策略而非完全覆盖（如 allowedTools 列表）。

Sources: settings.ts

关键配置文件位置

Sources: config.ts

常用配置示例

以下是几个典型场景的配置示例：

1. 配置自动格式化钩子

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "FileEditTool|FileWriteTool",
        "hooks": ["npm run format -- ${file}"]
      }
    ]
  }
}

2. 配置 MCP 服务器

// ~/.claude/claude_desktop_config.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
    }
  }
}

3. 配置权限模式

// .claude/settings.json
{
  "permissions": {
    "allow": ["BashTool(npm run *)", "FileReadTool(*)"],
    "deny": ["BashTool(rm -rf /*)"]
  }
}

Sources: config.ts

快速上手实战

通过一个实际的开发场景来熟悉 Claude Code 的基本操作流程。

场景：新项目初始化

假设您刚克隆了一个新的代码仓库，以下是推荐的初始化步骤：

journey
    title 新项目初始化流程
    section 环境检查
      运行 /doctor: 5: 用户
      检查依赖和配置: 5: Claude
      修复发现的问题: 4: 用户
    section 项目配置
      运行 /init: 5: 用户
      回答项目相关问题: 4: 用户, Claude
      生成 CLAUDE.md: 5: Claude
    section 开始开发
      描述开发任务: 5: 用户
      Claude 执行任务: 5: Claude
      审查和测试结果: 4: 用户

步骤详解：

1. 环境诊断

   claude
   > /doctor

   检查输出中的警告和错误，按照建议修复问题。

2. 项目初始化

   > /init

   按照向导提示，选择创建项目级和/或个人级配置文件。

3. 开始首次对话

   > 请帮我理解这个项目的架构，并找到入口文件

   Claude 会读取 CLAUDE.md 和项目文件，为您提供准确的分析。

4. 执行开发任务

   > 添加一个新的 API 端点，路径为 /api/health，返回服务状态

   Claude 会自动执行必要的文件编辑、测试运行等操作。

Sources: init.ts

高效使用技巧

以下是提升使用效率的关键技巧：

下一步学习

完成环境搭建和基本使用学习后，建议按照以下顺序深入探索：

1. 核心概念理解: 阅读 核心概念：工具、命令与会话生命周期，深入理解 Claude Code 的工作原理

2. 架构设计探索: 学习 整体架构：从 CLI 入口到 QueryEngine，掌握系统设计思想

3. 工具系统定制: 查看 工具架构：Tool 接口与权限模型，学习如何扩展工具能力

4. MCP 集成实践: 深入 MCPTool：Model Context Protocol 深度集成，连接外部工具和服务

5. 性能优化技巧: 参考 性能优化：启动性能与运行时优化技巧，提升使用体验

通过以上学习路径，您将全面掌握 Claude Code 的使用和定制能力，能够高效地将其集成到您的开发工作流中。