Claude Code 从安装到精通完全指南

引言

Claude Code 是 Anthropic 公司推出的一款命令行 AI 编程代&理工具，它能让开发者直接在终端中与 AI 对话，完成代码理解、修改、调试、Git 操作等各类软件工程任务。本指南将系统性地介绍 Claude Code 的核心概念、安装流程、操作技巧以及进阶用法，帮助你在 Windows 环境下快速上手，并与 CC Switch 等工具配合使用，实现高效免费的 AI 编程体验。

一、什么是 Claude Code？

Claude Code 不是 IDE 插件，而是一个运行在终端里的 AI 编程代&理。与传统的代码补全工具不同，它具备以下能力：

• 全面理解项目：自动索引整个代码库，跨文件理解逻辑关系。
• 自主执行任务：可读写文件、创建或删除目录、运行 Shell 命令、安装依赖、执行测试套件。
• 自然语言交互：用中文或英文直接描述需求，如“重构认证模块”或“修复所有失败的测试”。
• 安全可控：在执行删除文件、强制推送等危险操作前，会主动请求用户确认。
• Git 原生集成：可直接发起提交、创建分支、查看差异、解决合并冲突。
• 支持 MCP 协议：通过 Model Context Protocol 连接外部工具和数据源（如数据库、API），扩展能力边界。

简而言之，Claude Code 就像一个坐在你旁边的资深程序员，不仅能听懂你的需求，还能直接动手修改代码、执行命令，而你只需审查和确认。

二、收费与免费策略

Claude Code 本身并不完全免费，通常需要通过以下方式使用：

• Claude Pro / Max 订阅：订阅后可在终端中使用 Claude Code，每月包含一定免费计算额度。
• Anthropic API Key：直接调用 API，按 token 付费。新注册用户通常可获得少量免费额度（如 $5）。
• 企业版 / 团队版：提供更多管理功能和用量方案。

但通过本文后续介绍的 CC Switch 工具，你可以将 Claude Code 的底层模型替换为讯飞星辰 MaaS 平台提供的免费 Qwen 模型，从而在 2026 年 6 月 30 日前实现零成本使用。这使得个人开发者也能够无负担地体验顶级 AI 编程代&理的能力。

三、安装 Claude Code（Windows）

1. 安装 Node.js 环境

Claude Code 基于 Node.js 开发，要求版本 ≥ 18.0。

• 访问 Node.js 官方网站，下载 LTS 版本 的 Windows 安装包（.msi）。
• 运行安装程序，保持默认选项，务必勾选 “Add to PATH”。
• 安装完成后，打开命令提示符（cmd）或 PowerShell，输入以下命令验证：

node -v
npm -v

若均显示版本号，则表示 Node.js 安装成功。

2. 全局安装 Claude Code

在终端中执行：

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

如果遇到权限错误，可以尝试以管理员身份运行终端，或使用 --force 参数（不推荐但有效）。

安装完成后，运行 claude --version，若出现版本号说明安装成功。

注意：在使用 CC Switch 方案时，我们不需要设置 ANTHROPIC_API_KEY 环境变量，也不需要登录 Claude 账号。CC Switch 会接管所有 API 请求，所以请保持 Claude Code 处于“无 Key”状态，以免干扰转发逻辑。

四、基础使用方法

1. 启动交互模式

在终端中切换到你的项目目录，输入 claude 并回车，即可进入全屏对话界面。

cd D:my-project
claude

首次启动可能会尝试连接默认 API，若已配合 CC Switch 则会自动使用你配置的免费模型。

2. 单次执行模式

也可以直接在命令后附带任务描述，Claude Code 执行完即退出，适合脚本化或快速查询：

claude "解释 src/main.py 的功能"
claude --print "列出所有 TODO 项"   # 输出到标准输出后退出

3. 对话与指令

在交互界面中，直接用中文或英文描述你的需求。Claude Code 会自动读取相关文件、执行命令并展示结果。例如：

• 理解代码：“分析 auth.py 中的登录逻辑，指出潜在的安全问题。”
• 修改代码：“把所有 console.log 改为 logger.info，并添加合适的日志级别。”
• 运行测试：“运行 pytest，帮我把失败的测试修好。”
• Git 操作：“创建分支 feature/pagination，然后把最近 2 次提交压缩。”

对于高风险操作，Claude Code 会暂停并询问你是否同意，你可以选择 Approve（允许）、Deny（拒绝） 或 Always allow（总是允许）。

五、常用快捷键

快捷键	功能
Esc 或 Ctrl+C	退出当前对话（或中断长时间运行的操作）
Ctrl+D	发送消息（在某些终端配置下等效于 Enter）
Ctrl+L	清屏
Ctrl+Z	挂起 Claude Code 进程到后台（Unix 风格）
↑ / ↓ 方向键	浏览历史输入过的指令
Tab	自动补全文件路径、命令或模型建议

六、内部命令速查

在 Claude Code 对话中输入以 / 开头的命令，可以执行元操作：

命令	说明
/help	查看所有可用命令和帮助文档
/clear	清空当前对话上下文，但已修改的文件不受影响
/compact	压缩上下文，释放 token 消耗，适合长对话后重置
/cost	显示当前会话的 token 用量和费用估算（使用 CC Switch 时不准确）
/doctor	诊断系统环境（Node.js、网络、权限等）
/status	查看当前项目状态（已索引文件数、最近操作记录）
/add-dir	手动添加目录到工作区上下文
/ide	在 VS Code 等关联 IDE 中打开当前工作目录
/git	打开 Git 操作面板，可执行提交、分支管理等
/bash	在独立 Shell 中执行命令（等价于直接让 Claude 执行）
/init	在当前目录初始化 Claude Code 配置
/login / /logout	管理账号登录状态（使用 CC Switch 时无需登录）
/mcp	管理 MCP 服务器连接

七、典型工作流示例

1. 代码探索与理解

> 梳理整个项目的目录结构，简要说明各模块职责。
> 解释 services/data_fetcher.js 中的缓存机制。

2. 代码重构与优化

> 将 utils.js 中的所有回调函数改为 async/await 形式。
> 提取 auth.py 里的魔术数字为配置常量，并在配置文件中说明。

3. 测试与调试

> 为 models/user.rb 的 validations 生成 RSpec 测试。
> 运行 npm test，修复失败的用例，并说明原因。
> 这个错误堆栈是什么意思？请帮我定位并修复。

4. Git 工作流

> 创建一个新的 release/1.2.0 分支。
> 解决合并冲突，优先保留 main 分支的更改。
> 给最近一次提交补充详细 commit message。

5. 项目搭建

> 基于 Flask 创建一个 RESTful 用户管理后台，包含注册、登录、JWT 认证。
> 给项目添加 ESLint、Prettier 和 Husky 配置。

八、上下文与权限管理

1. 权限确认机制

Claude Code 在执行不可逆操作前会征求确认，包括：

• 删除文件或目录
• 强制推送（git push --force）
• 修改系统级配置
• 安装未知来源的依赖

你可以针对每一次操作选择 Approve 或 Deny，或使用 Always allow 允许后续同类型操作免打扰。

2. 控制上下文范围

• 当 Claude 未自动加载相关文件时，你可以直接指定：“请同时参考 config/settings.json 和 src/models/User.js。”
• 使用 /add-dir 命令手动添加整个目录。
• 创建 .claudeignore 文件，排除无需索引的日志、临时文件、第三方库等。

九、与 CC Switch 配合使用的注意事项

当使用 CC Switch 将模型替换为讯飞 Qwen 后，以下几点需要了解：

• 模型标识：Claude Code 界面仍显示“Claude”，但实际推理由 Qwen 完成。
• 费用显示：/cost 命令无法准确反映免费模型用量，可忽略。
• 功能兼容：文件操作、Shell 执行、Git 集成等功能与模型无关，完全可用。
• 思维链差异：极少数深度依赖 Claude 独特推理能力的场景可能效果略弱，但日常编程任务无感知。
• 网络依赖：必须保持 CC Switch 运行，且网络能连通讯飞 API 端点。

十、配置与自定义

Claude Code 的项目级配置存储在项目根目录的 .claude 文件夹中。高级用户可编辑 settings.json 进行调整：

{
  "maxTokens": 4096,
  "permissionMode": "default",
  "ignorePatterns": ["node_modules", "*.log"]
}

部分常用配置项：

• permissionMode：设为 "acceptEdits" 可自动接受文件修改，无需逐次确认。
• maxTokens：限制单次响应的最大 token 数，防止过长输出。
• .claudeignore：配置忽略文件规则，避免索引不必要的文件。

十一、常见问题与排错

问题	可能原因与解决方法
启动后提示“无法连接 API”	检查 CC Switch 是否运行；在 CC Switch 中测试模型连通性；确认 Claude Code 未设置 ANTHROPIC_API_KEY。
模型回复质量不佳	上下文过长时使用 /compact；确认 CC Switch 中填写的模型 ID 与讯飞平台一致。
无法读取某些文件	检查文件是否被 .gitignore 或 .claudeignore 排除；手动通过 /add-dir 或明确路径告诉 Claude。
执行命令权限不足	以管理员身份运行终端；或修改 .claude/settings.json 的权限模式。
中文输出乱码	在终端中执行 chcp 65001 将编码切换为 UTF-8。
CC Switch 关闭后 Claude Code 报错	正常现象，CC Switch 是请求转发的唯一通道。恢复使用需重新打开 CC Switch 或移除其代&理设置。

十二、总结

Claude Code 是当前命令行编程代&理的标杆产品，它打破了“只能补全、不能动手”的局限，真正让 AI 参与到软件工程的完整流程中。配合 CC Switch 和讯飞星辰 MaaS 的免费模型，国内开发者可以在零成本的前提下，体验这种未来已来的编程范式。

你现在已经拥有完整的知识体系和操作指南，从安装 Node.js、配置 Claude Code，到通过 CC Switch 接入免费大模型，再到熟练运用对话、权限、自定义配置，每一步都可以按图索骥。开始你的第一个指令，让 AI 成为你最可靠的编程搭档吧。