附录4：CC完整安装与配置教程

Claude Code 完整安装与配置教程

适用对象：完全新手 最后更新：2025年10月 难度等级：⭐⭐ (简单)

📋 目录

1. 简介

2. 前置要求检查

3. 环境准备

4. 安装步骤

5. 配置步骤

6. 验证安装

7. 第一个示例项目

8. 常见问题排查

9. 有用的资源

🌟 简介

什么是 Claude Code？

• 🚀 自动生成完整的项目代码

• 🔧 智能调试和优化代码

• 📝 编写技术文档

• 🧪 创建测试用例

• 💡 提供编程建议和最佳实践

为什么选择 Claude Code？

• 强大的理解能力：Claude 能够理解复杂的需求并生成高质量代码

• 多语言支持：支持 Python、JavaScript、Java、C++ 等主流编程语言

• 工作流集成：通过 ZCF 工具可以快速配置专业的开发工作流

• MCP 生态系统：支持 Model Context Protocol，可以连接各种外部工具和数据源

开发效率对比

1. 需求分析 → 2. 架构设计 → 3. 编码实现 → 4. 调试测试 → 5. 文档编写 （预计时间：数小时到数天）

1. 告诉 AI 你的需求 → 2. AI 自动生成并测试 → 3. 迭代优化（可选） （预计时间：几分钟到数十分钟）

✅ 前置要求检查

硬件要求

• ✅ 操作系统：Windows 10/11、macOS 10.15+、或 Linux

• ✅ 内存：至少 4GB RAM（推荐 8GB+）

• ✅ 磁盘空间：至少 2GB 可用空间

• ✅ 网络：稳定的互联网连接

软件要求

• ✅ VSCode：1.80 或更高版本

• ✅ Node.js：18.0 或更高版本（推荐 LTS 版本）

账号要求

• ✅ Claude API 密钥（可从推荐渠道购买套餐）

💡 提示：如果您不确定是否已安装某些软件，可以继续阅读，后续步骤会教您如何检查和安装。

🛠️ 环境准备

步骤 1：安装 Visual Studio Code

Windows 用户

1. 访问 VSCode 官网

2. 点击 "Download for Windows" 下载安装包

3. 运行下载的 .exe 文件

4. 按照安装向导完成安装（建议勾选以下选项）：
• ✅ 添加到 PATH（重要！）
• ✅ 添加"通过 Code 打开"操作到 Windows 资源管理器上下文菜单
• ✅ 将 Code 注册为支持的文件类型的编辑器

验证 VSCode 安装

code --version

步骤 2：安装 VSCode 扩展 - Claude Code for VSCode

方法一：通过 VSCode 扩展市场安装（推荐）

1. 打开 VSCode

2. 点击左侧活动栏的扩展图标（或按 Ctrl+Shift+X / Cmd+Shift+X）

3. 在搜索框中输入 "Claude Code"

4. 找到官方扩展（发布者应为 Anthropic）

5. 点击 "Install" 按钮

方法二：通过命令行安装

code --install-extension anthropic.claude-code

验证扩展安装

步骤 3：安装 Node.js

下载和安装

1. 访问官网：https://nodejs.org/zh-cn/download

2. 选择版本：下载 LTS（长期支持）版本
• 🟢 推荐版本：点击下载 LTS 22.20.0版本
• ⚠️ 不推荐：Current（最新但不稳定）版本

3. 安装步骤：
• Windows：运行下载的 .msi 文件，按照向导安装

Windows 安装详细步骤

# 1. 下载安装包后，双击运行
# 2. 在安装向导中，确保勾选以下选项：
#    - Node.js runtime
#    - npm package manager
#    - Add to PATH
# 3. 点击 "Install" 完成安装

验证 Node.js 安装

# 检查 Node.js 版本
node --version
# 应该显示类似：v20.x.x 或 v22.x.x

# 检查 npm 版本
npm --version
# 应该显示类似：10.x.x

# 检查 npx（Node 包执行器）
npx --version
# 应该显示类似：10.x.x

⚠️ 重要提示：

1、需在cmd执行以上3个命令，保证均安装完整

2、如果显示"命令未找到"，说明 PATH 环境变量未正确配置，需要重新安装 Node.js 并确保勾选"Add to PATH"选项。

步骤 4：安装 Git

下载和安装

1. 访问官网：https://git-scm.com/downloads/win

2. 选择版本：
• 🟢 推荐版本：点击下载

3. 安装步骤：
• Windows：运行下载的 .exe 文件，按照向导安装

验证 Git安装

# 检查 Git 版本
git version
# 应该显示类似：git version 2.xx.0.windows.x

⚠️ 重要提示： 如果显示"命令未找到"，说明 PATH 环境变量未正确配置，需要重新安装Git 并确保勾选"Add to PATH"选项。

🚀 基于ZCF的Claude CLI安装

步骤 1：使用 ZCF 一键安装Claude和配置

• ✅ 安装 Claude Code CLI 命令行工具

• ✅ 配置开发工作流

• ✅ 配置 MCP 服务器

• ✅ 设置 API 密钥

启动 ZCF

npx zcf

💡 说明：首次运行时，npm 会询问是否安装 zcf 包，输入 y 确认。

ZCF 启动界面

╔════════════════════════════════════════╗
║            ZCF                         ║
║     Zero-Config Code Flow              ║
║        for Claude Code                 ║
╚════════════════════════════════════════╝

Version: 3.1.3 | <https://github.com/lfoMiao/zcf>

请选择功能：
───────── Claude Code ─────────
1. 完整初始化 - 安装 Claude Code + 导入工作流 + 配置 API 或 CCR 代理 + 配置 MCP 服务
2. 导入工作流 - 仅导入/更新工作流相关文件
3. 配置 API 或 CCR 代理 - 配置 API URL、认证信息或 CCR 代理
4. 配置 MCP - 配置 MCP 服务（含 Windows 修复）
5. 配置默认模型 - 设置默认模型（opus/sonnet/sonnet lm/自定义）
6. 配置 Claude 全局记忆 - 配置 AI 输出语言和输出风格
7. 导入推荐环境变量和权限配置 - 导入隐私保护环境变量和系统权限配置

───────── 其他工具 ─────────
R. CCR - 配置 Claude Code Router 以使用多个 AI 模型
U. ccusage - Claude Code 用量分析
L. CCometixLine - 基于 Rust 的高性能 Claude Code 状态栏工具，集成 Git 信息和实时使用量跟踪

───────── ZCF ─────────
0. 更改显示语言 / Select display language - 更改 ZCF 界面语言
S. 切换代码工具 - 在支持的代码工具之间切换（Claude Code、Codex）
C. 卸载和删除配置 - 从系统中删除 Claude Code 配置和工具
+. 检查更新 - 检查并更新 Claude Code、CCR 和 CCometixLine 的版本
Q. 退出

请输入选项，回车确认（不区分大小写）

步骤 2：执行完整初始化

选择选项 1 - 完整初始化

配置过程详解

1. 语言选择

AI 将使用此语言回复你的问题
选择 AI 输出语言：1. 简体中文

2. 输出风格选择

选择输出风格（空格选择，a全选，i反选，回车确认）
□ 1. 工程师专业版

• 1. 工程师专业版：适合专业开发者，代码质量高，遵循最佳实践

• 其他选项：根据您的技术水平选择

3. 工作流类型选择

选择要安装的工作流类型（空格选择，a全选，i反选，回车确认）
□ 通用工具（层级日志初始化 + 通用agents）
□ 六步工作流（workflow）
□ 功能规划和 UX 设计（feat + planner + ui-ux-designer）
□ Git 指令（commit + rollback + cleanBranches + worktree）
□ BMAD-Method 扩展装载器（支持敏捷开发工作流）

• ✅ 通用工具

• ✅ 六步工作流（专业开发工作流：研究→构思→计划→执行→优化→评审）

4. MCP 服务选择

选择要安装的 MCP 服务（空格选择，a全选，i反选，回车确认）
□ Context7 - 文档查询，查询最新的库文档和代码示例
□ open-websearch - 使用 DuckDuckGo、Bing 和 Brave 搜索引擎进行网页搜索
□ Spec 工作流 - 规范化特性开发工作流程，从需求到实现的系统化方法
□ DeepWiki - 查询 GitHub 仓库文档和示例
□ Playwright - 浏览器控制
□ Exa AI 搜索 - 使用 Exa AI 进行网页搜索

• ✅ Context7：查询最新的技术文档

• ✅ open-websearch：网页搜索能力（无需 API Key）

• ✅ Spec 工作流：规范化开发流程

• ✅ DeepWiki 工作流：查询 GitHub 仓库文档和示例

• ✅ Playwright 浏览控制：浏览器自动操作，辅助检索

💡 提示：部分 MCP 服务需要 API Key，如果选择，后续会提示输入。

步骤 3：安装 Claude Code CLI

正在更新 Claude Code 记忆文件...
Claude Code 更新成功！

步骤 4：配置工作流

正在安装工作流：通用工具（层级日志初始化 + 通用agents）...
正在安装工作流：六步工作流（workflow）...
六步工作流（workflow）工作流安装成功

步骤 5：配置 MCP 服务

正在安装工作流：MCP...
已备份所有配置文件到：C:/Users/你的用户名/.claude/backup/claude_json.backup_2025-10-08_17-38-18
Windows MCP 配置已修复
正在安装 MCP 配置...
MCP 服务已配置

请输入 Exa API Key（输入会被隐藏）

🔐 安全提示：API Key 输入时不会显示，输入完成后按回车即可。

🔧 Claude 配置

步骤 1：配置 Claude API与KEY

方法一：通过 CC Switch 配置（优先推荐）

• Windows：运行下载的 .msi 文件，按照向导安装 启动即可

• 点击"添加供应商"

• 输入供应商名称（如 "88code"）

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "88_xxxxxxxxxx",
    "ANTHROPIC_BASE_URL": "https://www.88code.org/api",
    "API_TIMEOUT_MS": "600000",
    "BASH_DEFAULT_TIMEOUT_MS": "600000",
    "BASH_MAX_TIMEOUT_MS": "600000",
    "CLAUDE_API_TIMEOUT": "600000",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "32000",
    "DISABLE_ERROR_REPORTING": "1",
    "DISABLE_TELEMETRY": "1",
    "MCP_TIMEOUT": "30000",
    "MCP_TOOL_TIMEOUT": "600000"
  },
  "hooks": {},
  "includeCoAuthoredBy": false,
  "outputStyle": "engineer-professional",
  "permissions": {
    "allow": [
      "Bash",
      "LS",
      "Read",
      "Agent",
      "Write",
      "Edit",
      "MultiEdit",
      "Glob",
      "Grep",
      "WebFetch",
      "WebSearch",
      "TodoWrite",
      "NotebookRead",
      "NotebookEdit",
      "mcp__ide",
      "mcp__exa",
      "mcp__context7",
      "mcp__mcp-deepwiki",
      "mcp__Playwright",
      "mcp__spec-workflow",
      "mcp__open-websearch"
    ],
    "deny": []
  },
  "statusLine": {
    "command": "%USERPROFILE%\\.claude\\ccline\\ccline.exe",
    "padding": 0,
    "type": "command"
  }
}

• 在供应商列表中选择要使用的供应商

• 点击"启用"

• CC Switch 会自动更新配置

方法二：通过 ZCF 配置

1. 在 ZCF 主菜单选择 3. 配置 API 或 CCR 代理

2. 输入 API URL（通常由服务提供商提供）

例如：<https://www.88code.org/api>

3. 输入您的 API Key

4. ZCF 会自动配置并测试连接

方法三：手动编辑配置文件

1. 打开配置文件：
• Windows: C:\\Users\\你的用户名\\.claude\\.zcf-config.json
• macOS/Linux: ~/.claude/.zcf-config.json

2. 编辑配置：

{
  "api": {
    "baseUrl": "<https://www.88code.org/api>",
    "apiKey": "你的API密钥"
  }
}

3. 保存文件

验证 API 配置

claude auth status

✅ Authenticated
API endpoint: <https://www.88code.org/api>

步骤 2：配置 Claude 全局执行准则（CLAUDE.md）

什么是 CLAUDE.md？

• 如何回复用户（语言、风格）

• 如何处理任务（工作流程）

• 如何保证代码质量（测试、安全）

• 项目特定的规则和约束

层级结构

1. 全局级别：~/.claude/CLAUDE.md - 适用于所有项目

2. 项目级别：项目根目录/CLAUDE.md - 仅适用于当前项目

💡 项目级别的 CLAUDE.md 会覆盖全局配置。

创建全局 CLAUDE.md

1. 定位到 .claude 目录：
• Windows: C:\\Users\\你的用户名\\.claude\\

2. 创建或编辑 CLAUDE.md 文件，添加以下内容： 点击访问 -> 参考配置 ，将 完整内容 复制到本地文件 C:\\Users\\你的用户名\\.claude\\CLAUDE.md

3. 保存文件

⚠️ 重要：这个文件会影响 Claude Code 在所有项目中的行为，请谨慎修改。

步骤 3：配置默认模型

模型对比

配置方法

选择默认模型：
1. opus
2. sonnet
3. haiku
4. 自定义

✔️ 验证安装

验证 1：检查 Claude Code CLI

# 检查 Claude Code 版本
claude --version

# 检查认证状态
claude auth status

Claude Code CLI v1.x.x
✅ Authenticated

验证 2：检查 MCP 配置

# 查看 MCP 配置（Windows）
type "%USERPROFILE%\\.claude\\.zcf-config.json"

# 查看 MCP 配置（macOS/Linux）
cat ~/.claude/.zcf-config.json

验证 3：在 VSCode 中测试

1. 打开 VSCode

2. 点击左侧活动栏的 Claude 图标（橙色星花）

3. 您应该看到 Claude Code 界面

4. 在输入框输入一个简单的问题：

你好，请介绍一下你自己

5. Claude 应该用中文回复

🎯 第一个示例项目

示例：API 测试工具

步骤 1：创建项目目录

# 创建项目文件夹
mkdir API-Check
cd API-Check

# 用 VSCode 打开
code .

步骤 2：与 Claude Code 对话

在API-Check目录下开发一个测试AI模型有效性的网页工具。功能如下：

1. 用户配置 BASE URL 和有效的 API Key
2. 工具读取模型列表，让用户选择待测试模型
3. 用户点击"开始测试"
4. 收集被测模型的响应时间，流式或者非流式，等核心信息
5. 形成详细的报告表格，可以用户查询和对比

步骤 3：观察 Claude 工作

1. 📋 分析需求：理解您想要什么

2. 🗂️ 创建文件结构：自动创建必要的文件和目录

3. 💻 编写代码：生成 HTML、CSS、JavaScript 代码

4. 🧪 测试功能：确保代码可以运行

5. 📝 生成文档：创建 README 和使用说明

步骤 4：运行项目

# Claude 会生成一个完整的 Web 应用
# 通常可以直接在浏览器中打开 index.html

# 或者使用简单的 HTTP 服务器
npx http-server .

预期结果

• ✅ 美观的用户界面

• ✅ API 配置功能

• ✅ 模型列表读取

• ✅ 测试执行和结果展示

• ✅ 数据对比功能

第二个示例：数据分析脚本

创建一个 Python 脚本，读取 CSV 文件，进行数据清洗和可视化分析

• 创建 Python 脚本

• 使用 pandas 进行数据处理

• 使用 matplotlib 生成可视化图表

• 添加完整的注释和文档

🔧 常见问题排查

问题 1：npx zcf 命令无法找到

'npx' 不是内部或外部命令，也不是可运行的程序

1. 确认 Node.js 已正确安装：

node --version

2. 如果未安装，重新安装 Node.js

3. 如果已安装但仍然报错，检查 PATH 环境变量：
• Windows: 搜索"环境变量" → 编辑系统环境变量 → 检查 PATH 中是否包含 Node.js 路径
• macOS/Linux: 检查 ~/.bashrc 或 ~/.zshrc

问题 2：Claude Code 无法连接到 API

❌ Authentication failed

1. 检查 API Key 是否正确

2. 检查网络连接

3. 确认 API 服务器地址正确

4. 查看余额是否充足（登录服务提供商网站查看）

问题 3：VSCode 扩展未显示

• 安装了扩展但左侧没有 Claude 图标

1. 重启 VSCode

2. 检查扩展是否已启用：
• Ctrl+Shift+X 打开扩展
• 搜索 Claude Code
• 确保显示"禁用"而不是"启用"（说明已启用）

3. 如果仍然不显示，尝试重新安装扩展

问题 4：Claude 回复的不是中文

• Claude 用英文回复

1. 检查全局 CLAUDE.md 文件是否存在

2. 确认文件中包含 "必须使用中文回复"

3. 在 ZCF 中重新配置：选择 6. 配置 Claude 全局记忆 → 选择 1. 简体中文

问题 5：MCP 服务无法使用

MCP service 'open-websearch' not found

1. 在 ZCF 中选择 4. 配置 MCP

2. 重新安装需要的 MCP 服务

3. 对于 Windows 用户，确保选择了"修复 Windows MCP 配置"

问题 6：代码生成质量不理想

• 生成的代码有 bug

• 代码不符合需求

1. 更详细地描述需求：
• ❌ 不好的需求："创建一个网站"
• ✅ 好的需求："创建一个响应式的个人博客网站，使用 HTML5、CSS3 和 JavaScript，包含首页、文章列表页、文章详情页，支持暗黑模式切换"

2. 分步骤迭代：
• 先创建基础结构
• 然后逐步添加功能
• 最后优化和美化

3. 提供示例：
• 如果有参考设计，可以描述或提供截图

4. 使用正确的模型：
• 复杂任务使用 opus
• 日常任务使用 sonnet

📚 有用的资源

官方文档

• Claude 官网：https://claude.ai/

• Claude API 文档：https://docs.anthropic.com/

• MCP 官方文档：https://modelcontextprotocol.io/

• MCP Registry（Github）：https://github.com/mcp

推荐服务商

• 88Code：https://www.88code.org/
• Claude Code 使用教程：https://docs.88code.org/ClaudeCode/Windows.html
• Codex 使用教程：https://docs.88code.org/Codex/Windows.html

工具和扩展

• ZCF (Zero-Config Code Flow)：https://github.com/lfoMiao/zcf

• CC Switch：https://github.com/farion1231/cc-switch

• VSCode：https://code.visualstudio.com/

• Node.js：https://nodejs.org/

社区和支持

• Claude Code 论坛：搜索 "Claude Code 中文社区"

• 88Code 文档中心：查看常见问题和最佳实践

💡 最佳实践

1. 清晰的需求描述

创建一个 Todo List Web 应用：
- 使用纯 HTML、CSS、JavaScript（不使用框架）
- 功能：添加、删除、标记完成、筛选（全部/进行中/已完成）
- 数据持久化：使用 localStorage
- 样式：简洁现代，支持响应式（手机和桌面）
- 交互：添加任务时有淡入动画，删除时有淡出动画

2. 迭代式开发

1. 第一步：创建基础结构和核心功能

2. 第二步：添加用户界面美化

3. 第三步：添加高级功能（动画、数据持久化等）

4. 第四步：优化性能和用户体验

3. 善用 MCP 工具

• 需要最新技术文档时，让 Claude 使用 Context7 或 open-websearch

• 需要 GitHub 仓库信息时，使用 DeepWiki

• 需要自动化浏览器测试时，使用 Playwright

4. 版本控制

# 初始化 Git 仓库
git init

# Claude 可以帮您生成 .gitignore
# 提示：创建适合 [你的技术栈] 的 .gitignore 文件

# Claude 可以帮您编写 commit message
# 使用 ZCF 的 git-commit 工作流

5. 文档优先

• 项目结构说明

• API 设计文档

• 数据模型定义

🎉 恭喜！

• ✅ 成功安装了 VSCode、Node.js 和 Claude Code

• ✅ 配置了 ZCF、工作流和 MCP 服务

• ✅ 设置了 API 密钥和全局准则

• ✅ 创建了第一个 AI 辅助开发的项目

• ✅ 了解了常见问题和解决方案

• ✅ 掌握了最佳实践和进阶技巧

• 💡 清晰地表达需求

• 🔄 迭代式开发

• 📚 不断学习和实践

• 🤝 参与社区交流

📝 更新日志

• 2025-10-13：创建初始版本
• 添加完整的安装步骤
• 添加 ZCF 配置指南
• 添加常见问题排查
• 添加示例项目