环境准备指南

目录

§1 电脑情况确认（开始前检查）
§2 安装 JDK 21
§3 安装 Maven 3.9 + 配置阿里云镜像
§4 安装 MySQL 8
§5 安装 Node.js 24 LTS
§6 安装 Git
§7 安装 Postman（API 测试工具）
§8 注册 DeepSeek + 实名 + 创建 API Key
§9 一次性环境验证（必做）
§10 安装 Claude Code CLI + cc-switch 配置 DeepSeek
10.1 安装 Claude Code CLI
10.2 安装 cc-switch
10.3 cc-switch 添加 DeepSeek 供应商
10.4 启用 cc-switch Claude 路由
10.5 Hello World 验证
§11 故障 FAQ（环境 + Claude Code CLI + AI 类）
§12 求助路径

⚠️ 整个文档以 Windows 10/11 为主。Mac 版本的差异处会单独说明。
⚠️ 全程关闭 360 / 腾讯电脑管家,它们会拦截 JDK / Node / Claude Code CLI 的安装文件。
⚠️ 不要把工具装到含中文或空格的路径 【D:\我的工具\jdk ❌、D:\Program Files\jdk ❌】,统一推荐 【D:\dev\】 这种全英文短路径。

§1 电脑情况确认（开始前检查）

⚠️ 如果硬盘剩余 < 20 GB,先清理:① 微信文件 ② 下载目录 ③ 回收站。环境安装完会占 8-12 GB。

§2 安装 JDK 21

我们用 JDK 21（LTS）,Oracle 当前推荐的长期支持版本。
⚠️ 不要装 JDK 8 / JDK 11 / JDK 17 等旧版本——用到的 SpringBoot 3.5.14 强制要求 JDK 17+,直接装 JDK 21 一步到位。

步骤

1.下载页:

• **首选(国内镜像,快) **:https://repo.huaweicloud.com/java/jdk/21+35/,选 jdk-21_windows-x64_bin.msi(约 160 MB)

• 备用(甲骨文官网,需注册):https://www.oracle.com/java/technologies/downloads/#java21

• Mac:jdk-21_macos-aarch64_bin.dmg(M 系列)或 jdk-21_macos-x64_bin.dmg(Intel)

2.双击 .msi,修改安装路径为 D:\dev\jdk21\ (不要装到默认 C:\Program Files\Java,路径有空格容易踩坑)。

**3.**安装完成后,Windows 安装包会自动配置 PATH 和 JAVA_HOME。

4.必做:验证安装。Win + R 输入 cmd 回车:

java -version

预期输出(关键看版本号是 21.x):

java version "21.0.5" 2024-10-15 LTS
Java(TM) SE Runtime Environment (build 21.0.5+9-LTS-239)
Java HotSpot(TM) 64-Bit Server VM (build 21.0.5+9-LTS-239, mixed mode, sharing)

⚠️ 显示 JDK 1.8 / JDK 11 等旧版本:多个 JDK,PATH 优先匹配旧的。看 §12 FAQ Q1。

**5.**再验证:

echo %JAVA_HOME%

预期结果:

D:\dev\jdk21\

输出空白去看 §12 FAQ Q2。

✅ 检查点 §2

java -version 显示 21.x

echo %JAVA_HOME% 输出非空,指向 JDK 21 目录

§3 安装 Maven 3.9 + 配置阿里云镜像

Maven 管理后端 Java 项目依赖(相当于前端的 npm)。必须配阿里云镜像,否则下载依赖会卡到怀疑人生。

步骤

1. 下载:https://maven.apache.org/download.cgi,选 Binary zip archive:apache-maven-3.9.9-bin.zip(约 9 MB)。

2. 解压到 D:\dev\maven(解压后路径 D:\dev\maven\apache-maven-3.9.9)。

3. 手动配环境变量(零经验同学请逐句看):

• 桌面"此电脑"右键 → 属性 → 高级系统设置 → 环境变量 按钮

• 弹出窗口分上下两栏:上=用户变量(只对你账号生效);下=系统变量(对所有账号生效)。统一用下方"系统变量"(避免多账号问题)

• 在下方"系统变量"区域点 新建 → 弹出小窗口填:

​ ① 变量名:MAVEN_HOME

​ ② 变量值:D:\dev\maven\apache-maven-3.9.9(你解压的实际路径)

• 点 确定 → 回到环境变量窗口

• 同一系统变量列表找 Path → 选中 → 点 编辑 → 弹出新窗口 → 点 新建 → 输入 %MAVEN_HOME%\bin → 一路 确定

• 🆘 配错了想重来:重新打开环境变量窗口 → 系统变量找 MAVEN_HOME → 选中 → 删除 → 重新建。Path 中多余的 %MAVEN_HOME%\bin 同样可在编辑窗口删

• ⚠️ 关键:已打开的 cmd 窗口不会自动加载新环境变量,必须开新 cmd(下一步验证)

4. 配置阿里云镜像(关键,省 1 小时下载时间):打开 D:\dev\maven\apache-maven-3.9.9\conf\settings.xml,在 和 之间粘贴:

<mirror>
    <id>aliyunmaven</id>
    <mirrorOf>*</mirrorOf>
    <name>阿里云公共仓库</name>
    <url>https://maven.aliyun.com/repository/public</url>
</mirror>

保存。

验证(开新 cmd):

mvn -version

预期(关键第三行 Java version 必须是 21.x):

Apache Maven 3.9.9 (...)
Maven home: D:\dev\maven\apache-maven-3.9.9
Java version: 21.0.5, vendor: Oracle Corporation

不是 21.x → JAVA_HOME 没配对。

🍎 Mac 差异:brew install maven(自动配 PATH);镜像配置文件 ~/.m2/settings.xml(不存在则手动创建),内容与 Windows 一致。

✅ 检查点 §3

mvn -version 显示 Maven 3.9.9

mvn -version 显示 Java version 是 21.x

settings.xml 已加阿里云 mirror(搜 aliyunmaven 能找到)

---

§4 安装 MySQL 8

MySQL 8.0(最新稳定版),社区免费版完全够用。

1. 下载:https://dev.mysql.com/downloads/installer/

• 选 mysql-installer-community-8.0.40.0.msi(约 600 MB)

• 国内镜像:https://mirrors.tuna.tsinghua.edu.cn/mysql/downloads/MySQL-8.0/

2. 双击安装:

• Setup Type:Server only(只装数据库本体)

• Authentication Method:Use Strong Password Encryption(默认)

• **MySQL Root Password:**⚠️ 设置一个你能记住的简单密码,如 123456 或 root1234。这个密码后面要填到项目配置文件,忘了就要重装。

🔐 安全提示:弱口令仅限本机开发用。生产环境必须强密码(≥12 位 + 大小写数字符号混合)。Phase 5 后端开发会专门讲生产密码与密钥管理。

• Windows Service:保持默认(开机自启)

3. 安装完成后 MySQL 已自动作为 Windows 服务启动。

✅ 检查点 §4

mysql -u root -p 输入密码后能进入 mysql> 提示符

记住 root 密码(写在草稿纸或备忘录)

(可选) DBeaver 能连本机 MySQL

§5 安装 Node.js 24 LTS

Node.js 24.x LTS(代号 Krypton · 2025-10-28 发布 · 维护至 2028-04-30,)。
⚠️ 不要装 Node 26(Current 版,2026-10 才转 LTS)/ Node 22 / Node 20 / Node 18。Node 20 LTS 已于 2026-10 结束活跃支持;Node 22 LTS 仍维护期但课程基线统一选 24。

💡 已装 Node 22 / Node 20 / Node 18 的同学:用 nvm 切换:

• Windows:nvm-windows → nvm install 24.11.0 → nvm use 24.11.0

• Mac:brew install nvm → nvm install 24 → nvm use 24

步骤

1. 下载:https://nodejs.org/zh-cn/download,选 Windows 安装程序 (.msi) 64-bit 20.x LTS 版本(页面有 “LTS” 标签)

• 国内镜像:https://npmmirror.com/mirrors/node/ → v24.11.x → node-v24.11.x-x64.msi

2. **双击安装,**全部默认下一步(C:\Program Files\nodejs\ 路径无空格 OK)。

• ⚠️ 出现 “Tools for Native Modules” 不要勾选(练习项目用不到,会下 4 GB 的 VS Build Tools)

3. 验证(打开新 cmd):

node -v
npm -v

预期(node 是 20.x,npm 是 10.x):

v24.11.0
10.8.2

4. 配置淘宝镜像(关键,省 90% 下载时间):

npm config set registry https://registry.npmmirror.com
npm config get registry

 后者输出:https://registry.npmmirror.com/

🍎 Mac:brew install node@20(推荐用 nvm install 20);淘宝镜像命令一致。

§5.1 ⭐ 安装 pnpm(V4-D04 必做 · 替代 npm 作前端包管理器)

🚨 统一用 pnpm,不用 npm/yarn

• **快:**并行安装 + 硬链接,首次比 npm 快 2-3x,二次安装快 10x+

• **省盘:**全局共享依赖(每个项目不再重复 100MB+ node_modules)

• **严:**严格依赖隔离,避免 npm 的"幽灵依赖"问题

步骤

1. **装 pnpm 10 LTS(**借用 npm 全局装,只用这一次 npm · ⚠️ 指定 LTS 版本避免装到 pnpm 11.x):

npm install -g pnpm@10

💡 不指定 @10 会装最新主版本(当前 11.x · 2026-05-09 发布) · pnpm 11 是纯 ESM + SQLite 索引存储,大版本变更建议生产用 LTS 10。

2. 验证:

pnpm --version

预期输出 10.x.x(LTS · 当前 10.33.4)。

3. 配置淘宝镜像(pnpm 用同一套 registry):

pnpm config set registry https://registry.npmmirror.com
pnpm config get registry

输出 https://registry.npmmirror.com/ 即正确。

💡 后续 frontend 项目统一用 pnpm install(不是 npm install)、pnpm dev(不是 npm run dev)、pnpm build(不是 npm run build)。

✅ 检查点 §5

node -v 显示 v24.x.x

npm -v 显示 10.x.x

npm config get registry 显示淘宝镜像

pnpm --version 显示 10.x.x(LTS · §5.1 必做)

pnpm config get registry 显示淘宝镜像

§6 安装 Git

1. 下载:https://git-scm.com/download/win

• 国内镜像:https://npmmirror.com/mirrors/git-for-windows/

2. 双击安装,全部默认下一步。

3. 验证(新 cmd 或 Git Bash):

git --version

 预期:git version 2.47.x.windows.x

4. 配置用户信息(必做,提交代码用):

git config --global user.name "你的姓名拼音"
git config --global user.email "你的邮箱(与 Gitee 注册邮箱一致)"

⚠️ 关键提醒（90% 新手坑点）:“你的姓名拼音” 和 “你的邮箱…” 是占位符,必须替换成你自己的实际姓名+邮箱。

• ❌ 错误：直接复制粘贴执行（commit 作者会显示成"你的姓名拼音"，验收时被一眼识破）

• ✅ 正确：git config --global user.name “ZhangSan” + git config --global user.email “zhangsan@qq.com”

⚠️ 这里的姓名/邮箱就是 commit 时显示的作者,配错了用 git config --global --replace-all user.name “新值” 覆盖即可。

🍎 Mac:macOS 通常自带(首次 git --version 弹安装框点确认),或 brew install git;git config 命令一致。

✅ 检查点 §6

git --version 显示 2.x

git config --global user.name 显示真实姓名(拼音可)

git config --global user.email 显示邮箱

§7 安装 Postman(API 测试工具)

测试后端 API 用,比如"我写了登录接口,怎么知道它对不对?"——用 Postman 发个请求看返回数据就知道。

1. 下载:https://www.postman.com/downloads/

不需要注册账号,下载完直接打开,选 Skip and go to the app(登录界面下方小字)

2. 国内访问慢可用 Apifox 替代(https://apifox.com/),中文界面,功能完全够用。

✅ 检查点 §7

Postman 或 Apifox 已安装并能打开

§8 ⭐ 项目工作目录准备

§8.1 父级目录命名硬要求(V4-D03 关键)

你将在 D:\xxx\xxx<项目根目录>\ 下放整个项目。D:\xxx\xxx\ 这一段(所有父级目录) 必须满足:

要求	错误示例 ❌	正确示例 ✅
全英文	D:\课程\ / D:\我的代码\	D:\code\ / D:\dev\
无空格	D:\My Code\ / D:\Course Project\	D:\code\ / D:\my-code\
无中文	C:\Users\张三\桌面\课程\	C:\Users\zhangsan\Desktop\code\ 或直接换 D:\code\
无特殊字符	D:\code(2026)\ / D:\code#2\	D:\code\ / D:\code-2026\

⚠️ **特别警告:**Windows 默认的 桌面 路径(C:\Users<你的中文名>\Desktop)如果用户名是中文 → 整条路径都是中文 → Java 编译会爆 MalformedInputException,pnpm install 部分依赖会失败。强烈建议直接在 D 盘根目录建 D:\code\ 工作区,避开桌面/文档/下载等系统目录。

💡 快速验证你的路径:在 cmd 里跑 cd /d D:\code 不报错就 OK。如果你打算用 D:\我的代码\xxx,跑 cd /d D:\我的代码 看报不报错(可能不报错但后续会出问题,建议直接换全英文)。

§8.2 创建项目工作区(一次性)

打开 cmd 或 PowerShell:

mkdir D:\code
cd /d D:\code

或用文件资源管理器:

打开 D 盘 → 右键空白处 → 新建 → 文件夹 → 命名 code

✓ 此时 D:\code\ 已就绪,后续所有项目都放这下面。

§8.3 ⭐ 配置 Gitee SSH key

§8.3.1 生成 SSH key

打开 cmd 或 PowerShell:

ssh-keygen -t ed25519 -C "你的Gitee邮箱"

提示输入文件路径直接回车(默认 ~/.ssh/id_ed25519),提示密码也直接回车 2 次(不设 passphrase,简化使用)。

成功标志:看到提示 Your public key has been saved in …id_ed25519.pub。

§8.3.2 复制公钥

:: Windows

type %USERPROFILE%\.ssh\id_ed25519.pub

输出形如(整段复制 · 包括开头 ssh-ed25519 和末尾邮箱):

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIxxxxxxx... 你的Gitee邮箱

⚠️ 复制 id_ed25519.pub(公钥)而不是 id_ed25519(私钥)。私钥永远不能外发。

§8.3.3 上传公钥到 Gitee

1. 登录 Gitee → 右上角头像 → 个人设置

2. 左侧导航 → SSH 公钥

3. 点 添加公钥:

• 标题:<你的电脑型号>-<日期>(如 MyLaptop-2026-05-10,方便区分多台机器)

• 公钥:粘贴 §8.6.2 复制的整段内容

4. 点 确定

成功标志:返回 SSH 公钥列表能看到刚加的这一条,标"未使用"。

§8.4.4 验证 SSH 连接

ssh -T git@gitee.com

首次连接会提示 Are you sure you want to continue connecting (yes/no)? → 输 yes 回车。

成功输出:Hi <你的用户名>! You've successfully authenticated, but GITEE.COM does not provide shell access.

返回 SSH 公钥列表刷新,刚才那条变成"已使用"——配置成功。

⚠️ 常见踩坑:

公钥内容粘错(选了私钥而不是 .pub) → 验证步骤报 Permission denied (publickey)

不同电脑要分别生成 + 上传(每台一个公钥)

macOS / Linux 命令换为 cat ~/.ssh/id_ed25519.pub

§9 注册 DeepSeek + 实名 + 创建 API Key

DeepSeek 当前性价比最高的国产大模型。用 DeepSeek V4 Pro / V4 Flash 双模型 + cc-switch 路由

§9.1 注册账号(网页版自检)

1. 访问 https://chat.deepseek.com/

2. 国内手机号注册(建议用与 Gitee 不同的邮箱避免账号混乱)

3. 登录后发"你好",看 AI 是否正常回复

4. ⚠️ 左下角或顶部模型选择应显示 “DeepSeek V4” 或 “DeepSeek-V4”(只显示 V3.2 → 账号还没切到 V4,过 1-2 天再试)

§9.2 实名认证(创建 API Key 的前置)

1. 打开 https://platform.deepseek.com/

• ⚠️ 网址是 platform.deepseek.com,不是 chat.deepseek.com

2. 用 §9.1 注册的 DeepSeek 账号登录

3. 平台政策:未实名不能创建 Key,先完成实名认证:

• 左侧菜单 → 账号管理 / 实名认证

• 选 个人实名 → 支付宝扫码 → ¥0.1 验证(自动退回)

• 实名通过才能下一步

• ⚠️ 实名页面打不开 → 多刷几次;高峰时段延迟 1-2 分钟

§9.3 创建 API Key

1. 左侧菜单 → API keys

2. 点 创建 API key:

• 名称:course-claude-code

• 只显示一次(sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx)

• ⚠️ 立即复制保存到记事本/备忘录,关掉对话框就再也看不到。

• 🆘 救法:如果没复制到 / 复制错 / 不小心关了对话框,回到 API keys 列表 → 选中这个 Key → 删除 → 重新创建一个新 Key,会再次完整显示。删除/重建次数无限,不扣额度。

3. 左侧菜单 → 用量 确认免费额度(500 万 tokens)

✅ 检查点 §9

已注册 DeepSeek 账号(网页版能正常发消息收回复 · 模型版本 V4 或 V3.2 几天会自动升 V4)

已完成实名认证(支付宝 ¥0.1 验证)

DeepSeek API Key 已创建并保存到本地(记事本/备忘录)

已确认免费额度 500 万 tokens(用量页面可见)

§10 一次性环境验证(必做)

⚠️ 把以下命令全部跑一遍,对照"预期"看是否正确。有一条不对就回去看对应小节。

打开新 cmd 窗口,逐条粘贴:

java -version
mvn -version
mysql --version
node -v
npm -v
git --version
echo %JAVA_HOME%
echo %MAVEN_HOME%

预期输出(每行只看关键版本号):

java version "21.0.x" ...           ← 必须 21.x
Apache Maven 3.9.x                   ← 必须 3.9.x,且 Java version 显示 21.x
mysql  Ver 8.0.x ...                 ← 必须 8.0.x
v24.x.x                              ← 必须 24.x
10.x.x                               ← 必须 10.x
git version 2.x ...                  ← 必须 2.x
D:\dev\jdk21\                        ← 必须有,路径正确
D:\dev\maven\apache-maven-3.9.9      ← 必须有,路径正确

✅ 第 §1-§11 总检查点

8 条命令的输出全部符合预期

DeepSeek 账号已注册 + 实名认证 + API Key 已保存到本地

🎉 完成第一阶段,你已经搞定 50% 的工作量。下一步是安装 Claude Code CLI + cc-switch 配置 DeepSeek(见 §11)。

---

§11 安装 Claude Code CLI + cc-switch 配置 DeepSeek

🎯 统一方案:用 Claude Code CLI(业界最强 AI 编码 CLI)+ cc-switch(多 Provider 路由代理)+ DeepSeek V4 Pro/Flash API(性价比国产模型)。

§11.1 安装 Claude Code CLI

1. 确认 Node.js 和 pnpm 已装(§5 应已完成):

node --version       # ≥ 24.x
pnpm --version       # ≥ 10.x

2. 全局安装 Claude Code CLI:

pnpm add -g @anthropic-ai/claude-code

验证:

claude --version

⚠️ 暂不要直接运行 claude——必须先装 cc-switch 并配置 DeepSeek 供应商(§11.2-§11.4),否则 claude 默认会去连 Anthropic 官方端点而失败。

§11.2 安装 cc-switch

cc-switch 是一个本地 GUI 工具,负责把 claude 的请求路由到不同的 AI 服务商(本课程用 DeepSeek)。

1. 双击安装包,按提示完成安装

2. 启动 cc-switch(桌面图标或开始菜单),托盘出现 cc-switch 图标说明已运行

§11.3 cc-switch 添加 DeepSeek 供应商

1. 点击 cc-switch 托盘图标 → 打开主界面 → 点击右上角的按钮添加供应商

2.选自定义配置→ 填写基本字段:

供应商名称:DeepSeek

官网链接:https://platform.deepseek.com

API Key:粘贴 §9.3 保存的 sk-xxx...

请求地址:https://api.deepseek.com/anthropic

高级选项：

主模型：deepseek-v4-pro[1m]

Haiku默认模型：deepseek-v4-flash

Sonnet默认模型：deepseek-v4-pro[1m]

Opus默认模型：deepseek-v4-pro[1m]

3. 编辑通用配置 JSON(勾选"写入通用配置")·:

{

  "env": {

    "API_TIMEOUT_MS": "3000000",
    
    "CLAUDE_CODE_USE_POWERSHELL_TOOL": "1"

  },

  "defaultShell": "powershell",

  "autoUpdatesChannel": "latest",

  "model": "claude-opus-4-7",

  "permissions": {

    "allow": [
    
      "Read",
    
      "Grep",
    
      "Glob",
    
      "LS",
    
      "Edit",
    
      "Write",
    
      "Bash(git diff:*)",
    
      "Bash(git status:*)",
    
      "Bash(git log:*)",
    
      "Bash(git add:*)",
    
      "Bash(git commit:*)",
    
      "Bash(npm test:*)",
    
      "Bash(npm run:*)",
    
      "Bash(pnpm:*)",
    
      "Bash(yarn:*)",
    
      "Bash(node:*)",
    
      "Bash(python:*)",
    
      "Bash(pytest:*)"
    
    ],
    
    "deny": [
    
      "Bash(rm -rf *)",
    
      "Bash(rm -rf /)",
    
      "Bash(rm -rf ~)",
    
      "Bash(rm -rf ~/*)",
    
      "Bash(git push --force*)",
    
      "Bash(git push -f*)",
    
      "Bash(git reset --hard*)",
    
      "Bash(npm publish*)",
    
      "Bash(pnpm publish*)",
    
      "Bash(yarn publish*)",
    
      "Bash(sudo:*)",
    
      "Bash(curl * | sh)",
    
      "Bash(curl * | bash)",
    
      "Bash(wget * | sh)",
    
      "Read(.env)",
    
      "Read(.env.*)",
    
      "Read(**/secrets/**)",
    
      "Read(**/*.pem)",
    
      "Read(**/*.key)",
    
      "Write(.env)",
    
      "Write(.env.*)"
    
    ]

  }

}

4. 保存

§11.4 启用 cc-switch Claude 路由

1. cc-switch 设置 → 路由

2. 在 “本地路由” 区:

• 服务地址:http://127.0.0.1:15721(不要改,默认即可)

• 路由总开关:✅ 开启

3. 在 “路由启用” 区:

• Claude:✅ 开启

• Codex / Gemini:关闭(本课程不用)

以管理员身份重新打开 PowerShell，逐行执行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser -Force



# 1. API 超时：50 分钟（3000000 毫秒）

[Environment]::SetEnvironmentVariable("API_TIMEOUT_MS", "3000000", "User")



# 2. 启用 PowerShell 工具模式

[Environment]::SetEnvironmentVariable("CLAUDE_CODE_USE_POWERSHELL_TOOL", "1", "User")



# 3. Git Bash 路径（用于 Claude Code 的 bash 工具）

[Environment]::SetEnvironmentVariable("CLAUDE_CODE_GIT_BASH_PATH", "C:\Program Files\Git\bin\bash.exe", "User")



# 4. cc-switch 本地代理地址

[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "http://127.0.0.1:15721", "User")



# 5. cc-switch 占位 Token（真实 Key 存在 cc-switch 里）

[Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "sk-cc-switch-local", "User")



# 6. 清理旧的官方 API Key，防止 Claude Code 优先读取它而跳过 cc-switch

[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "", "User")



# 7. 如果之前设置过，一并清理

[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", $null, "User")

在新打开的 PowerShell 中执行以下命令，创建/编辑配置文件：

# 如果配置文件不存在则创建

if (!(Test-Path $PROFILE)) {

    New-Item -ItemType File -Path $PROFILE -Force

}

# 打开配置文件编辑

notepad $PROFILE

将以下内容完整复制粘贴进去，保存并关闭：

# ============================================

# Claude Code + cc-switch 环境配置

# ============================================



# --- 基础代理配置（双重保险，确保当前会话即时生效）---

$env:ANTHROPIC_BASE_URL     = "http://127.0.0.1:15721"

$env:ANTHROPIC_AUTH_TOKEN   = "sk-cc-switch-local"



# --- 清理旧的官方 API Key（防止 Claude Code 优先读取官方 Key 而跳过 cc-switch）---

$env:ANTHROPIC_API_KEY      = ""



# --- API 超时：50 分钟（处理大文件分析）---

$env:API_TIMEOUT_MS         = "3000000"



# --- 启用 PowerShell 工具模式 ---

$env:CLAUDE_CODE_USE_POWERSHELL_TOOL = "1"



# --- Git Bash 路径 ---

$env:CLAUDE_CODE_GIT_BASH_PATH = "C:\Program Files\Git\bin\bash.exe"



# --- 强制 UTF8 编码，防止中文输出乱码 ---

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8

$OutputEncoding = [System.Text.Encoding]::UTF8

§11.5 Hello World 验证

打开 cmd / PowerShell,新建一个测试目录:

mkdir D:\code\hello-claude-code
cd D:\code\hello-claude-code
claude

进入 Claude Code 交互模式后,输入:

请帮我写一个 Java Hello World 程序,要求:

1. 1. 用 JDK 21 的语法
   2. 输出 "Hello, Claude Code + DeepSeek V4!"
   3. 在代码顶部加一行注释,写明你是哪个模型
   

预期:5-15 秒内 Claude Code 调用 cc-switch 路由到 DeepSeek V4 Flash,返回类似:

// 由 DeepSeek V4 Flash 通过 cc-switch 路由生成
public class Hello {
    public static void main(String[] args) {
        System.out.println("Hello, Claude Code + DeepSeek V4!");
    }
}

---

§11.6 ⭐ 可选拓展:配置 GLM 5.1 实现异源审核(双品牌保险 · 学有余力)

⚠️ 可选 · 不做不影响项目跑通。本节给有 GLM 5.1 API key 且追求双模型质量保险的同学。没 GLM key 的同学跳过本节即可,审核类命令会自动用 V4 Pro 同源自审。

§11.6.1 为什么要异源审核?

本课程的"审核类"命令(R-XX 系列:srs-reviewer / db-reviewer / api-reviewer / page-reviewer / tech-reviewer / scoping-reviewer / code-reviewer-be / code-reviewer-fe / code-reviewer-full / security-reviewer)会让 AI 回看自己刚生成的内容(SRS / TECH_DESIGN / 代码等)找问题。

问题:如果生成和审核都用同一个模型(都走 DeepSeek V4 Pro),AI 容易"自审通过"——它倾向于认可自己的输出,漏掉真问题。

双模型保险:让另一个品牌的强模型(如智谱 GLM 5.1 / Anthropic Claude Sonnet 等)做审核,两个不同公司训练的模型从不同角度审同一份产物,漏检率明显下降。

💡 工业界对应实践:大型代码 review 会让"另一个程序员审"而不是"自审" · 本节是 AI 时代的等价做法。

§11.6.2 申请 GLM API key(智谱清言 BigModel)

1. 访问 https://open.bigmodel.cn/ 注册账号(国内手机号即可)

2. 实名认证(支付宝扫码 · ¥0.1 验证)

3. 进入 API Keys 页面 → 创建 API Key → 复制保存到本地记事本

4. 充值 ¥10 即可跑完整个课程项目(GLM 5.1 输入约 ¥0.5/百万 tokens · 输出约 ¥2/百万 tokens · 审核类总用量约 100 万 token 内)

§11.6.3 在 cc-switch 添加 GLM 5.1 供应商

⚠️ 此时不要激活 GLM provider:DeepSeek 仍是默认 active provider(用于大部分命令)· GLM 只在跑审核类命令时临时切换。

§11.6.4 异源审核操作流程

跑审核类命令(R-XX)时:

1. 退出 Claude Code:在 claude 会话里输入 /exit(或 Ctrl+D)

2. cc-switch GUI 切 active provider:托盘 cc-switch → 设置 → 供应商 → 把激活状态从 DeepSeek 切到 GLM

3. 重启 claude:在项目根目录运行 claude(此时 /model opus 会路由到 GLM 5.1)

4. 跑审核命令:如 /srs-reviewer 请审核 docs/PRD.md …

5. 审核完毕,切回 DeepSeek:再次 /exit 退出 → cc-switch 切回 DeepSeek → 重启 claude → 跑应用修复 / 下游生成命令

§11.6.5 Hello World 验证(异源审核就绪)

测试 GLM 5.1 通了:

1. cc-switch 切到 GLM provider → 重启 claude

2. 在 claude 输入:请用一句话告诉我你是哪个模型

3. 预期 GLM 5.1 回复类似"我是智谱清言 GLM 4.5/4.6"(具体描述以 GLM 实际版本为准)

4. 输入 /exit 退出 → cc-switch 切回 DeepSeek → 重启 claude → 输入同样问题 → 预期 DeepSeek V4 回复

✅ 检查点 §11.6(可选)

GLM API key 已申请并保存到本地

cc-switch 已添加 GLM 供应商配置(JSON 已填好)

DeepSeek 与 GLM 两个 provider 都可成功切换 · 各自回答"你是哪个模型"测试通过

记住异源审核切换流程(/exit → cc-switch 切 provider → 重启 claude)

🎉 完成 §11.6 = 你具备进阶能力:跑 R-XX 审核类命令时启用异源双模型保险(质量更稳)· 审核报告里漏检率明显下降

§12 故障 FAQ(环境 + Claude Code CLI + AI 类)

按"报错关键词"查找。先用 Ctrl + F 搜你看到的报错信息,90% 能找到。

A 类:环境变量与版本问题

Q1: java -version 显示 JDK 8 / JDK 11 / 旧版本

原因:多个 JDK,PATH 里旧版本排在前面。

解决:

1. 此电脑右键 → 属性 → 高级系统设置 → 环境变量

2. 双击系统变量 Path

3. 找到所有 xxx\jdk\bin 或 Common Files\Oracle\Java\javapath

4. 含 jdk21 的那条上移到顶部

5. 重启 cmd 重新验证

⚠️ Mac 用户:~/.zshrc 或 ~/.bash_profile 检查 JAVA_HOME 配置。

Q2: echo %JAVA_HOME% 输出空白

原因:JDK 21 安装包应自动配 JAVA_HOME,但偶尔失败。

解决:手动配

1. 环境变量 → 系统变量 → 新建

2. 变量名 JAVA_HOME,变量值 D:\dev\jdk21(实际路径,末尾不要带反斜杠)

3. Path 中新建 %JAVA_HOME%\bin

4. 关闭所有 cmd 重新打开验证

Q3: ‘mysql’ 不是内部或外部命令

原因:MySQL 的 bin 目录不在 PATH。

解决:

1. 找 MySQL 路径(通常 C:\Program Files\MySQL\MySQL Server 8.0\bin)

2. 加到系统 Path

3. 关闭 cmd 重新打开验证

Q4: MySQL Access denied for user ‘root’@‘localhost’

原因:密码错或服务异常。

解决:

1. 确认 MySQL 服务运行:Win + R → services.msc → MySQL80 服务状态"正在运行"

2. 忘了密码:最直接重装 MySQL(学生项目数据可丢,重装比改密码省时间)

3. 高阶:跳过权限模式重置密码,参考MySQL 官方文档

Q5: MySQL Communications link failure / Connection refused: localhost:3306

原因:服务没启动 / 端口被占 / 防火墙拦截。

解决（按顺序排查）:

1. 服务没启动（最常见）：Win + R → services.msc → 找 MySQL80 → 右键启动。装完不重启电脑常见此问题。

2. 3306 端口被占：cmd 跑 netstat -ano | findstr :3306，如果有别的进程占用（不是 mysqld.exe）→ 杀掉那个进程，或修改 MySQL 端口到 3307（修 my.ini + 重启服务 + 后续 application.yml 也要改）。

3. 防火墙拦截：Windows Defender 防火墙 → 入站规则 → 找"MySQL Server"或新建规则放行 3306。

4. DBeaver 能连但 SpringBoot 连不上：检查 application.yml 的 url，确保是 jdbc:mysql://localhost:3306/<库名>?useSSL=false&serverTimezone=Asia/Shanghai，不是 127.0.0.1（部分驱动版本对 IP 敏感）。

B 类:Node 与 npm 问题

Q6: pnpm install 卡 5 分钟以上不动

原因:大概率是网络问题——默认走 npm 官方源（境外），国内学生很容易卡。

解决（按顺序排查）:

1. 优先：确认已配淘宝镜像（§5 步骤 4）：npm config get registry 应显示 https://registry.npmmirror.com/。没配 → 立即配 + 重新跑 pnpm install。

2. 已配仍卡：Ctrl+C 中断 → 删 node_modules + pnpm-lock.yaml → 重跑 pnpm install（lock 文件可能锁定旧源 URL）。

3. 分钟仍无 100% 进度但有滚动输出：是正常的（首次装大型项目 200+ 包 = 3-8 分钟），只要终端有输出就别中断。判断标准：能看到包名滚动 = 在装；完全静止 = 卡死。

4. 彻底卡死（≥10 分钟无输出）：换 cnpm：pnpm add -g cnpm --registry=https://registry.npmmirror.com → 之后用 cnpm install 代替 pnpm install。

5. 公司/学校有代理：检查环境变量 HTTP_PROXY / HTTPS_PROXY 是不是错配指向已下线的代理服务器。

Q7: pnpm error code EACCES / EPERM: operation not permitted

原因:Windows 权限问题，通常是 VS Code / 编辑器进程在锁定 node_modules 文件夹。

解决:

1. 关闭 VS Code / 编辑器 → 重新跑 pnpm install

2. 仍报错 → 用管理员身份打开 cmd / PowerShell → cd 到项目目录 → 重跑

3. 不要用 --force 或 sudo（Mac 上 sudo pnpm 会埋后续权限坑）

D 类:Claude Code CLI 与 AI 调用问题

Q14: claude 启动报 “Could not connect to cc-switch / connection refused”

原因:cc-switch 没有在运行,或 cc-switch 的本地路由没启用。

解决:

1. 检查 cc-switch 托盘图标是否存在(右下角任务栏 → 显示隐藏图标 → 找 cc-switch)

2. 没有 → 启动 cc-switch(开始菜单 → cc-switch)

3. 有图标但仍连不通 → 点托盘图标 → 设置 → 路由 → 确认"路由总开关"=✅ 开启 + “服务地址”=http://127.0.0.1:15721

4. 路由"Claude"开关是否 ✅ 开启?未开启则 claude 走不到 DeepSeek

Q15: claude 启动后卡死 / 长时间无响应

原因:cc-switch 路由的 API Key 配错,或 DeepSeek API 端点不通。

解决:

1. 检查 cc-switch → 设置 → 供应商 → DeepSeek 的 API Key 是否粘贴正确(沒前后空格、完整 sk- 开头)

2. 检查 cc-switch JSON 配置中 ANTHROPIC_BASE_URL 是否为 https://api.deepseek.com/anthropic(注意 /anthropic 后缀)

3. 检查网络:浏览器打开 https://platform.deepseek.com 能正常显示则 API 端点通

4. 临时方案:在 claude 交互模式按 Ctrl+C 退出,重启 cc-switch 后再 claude

Q16: cc-switch 中添加 DeepSeek 供应商保存后不生效

原因:JSON 格式错误(中文引号、缺逗号)或路由开关没开。

解决:

1. cc-switch → 设置 → 供应商 → 编辑 DeepSeek → 检查 JSON 配置:

• 所有引号必须是英文双引号 ",不能是中文 " "

• 每个键值对后面要有逗号(除了最后一项)

• JSON 编辑器顶部应显示"格式化"按钮,点一下能自动检查格式

2. JSON 检查通过仍不生效 → §11.4 启用路由(Claude 路由总开关 + Claude 开关都要 ✅)

3.仍不行 → 退出 cc-switch(右键托盘 → 退出)→ 重新启动 cc-switch

Q17: AI 对话时不按规则文件来(用了错误的框架/写法)

原因:Claude Code 没有读到项目模板根目录的 CLAUDE.md(AI 编码规则),或上下文已被旧对话污染。

解决:

1. 确认你在项目工作目录下启动了 claude(目录里必须有 CLAUDE.md 文件 · ls CLAUDE.md 应能看到)

2. 在 claude 交互模式中输入 /clear 清空对话上下文(让 Claude Code 重新读 CLAUDE.md)

3. 对话中显式提醒 AI:“请遵守项目根目录 CLAUDE.md 中的全部规范”

4. 终极方案:Ctrl+C 退出 claude → 在项目根目录确认 CLAUDE.md 完整(包含 §一 项目基础 / §二 后端 / §三 前端 / §四 Git commit 四大节)→ 重新 claude

Q18: cc-switch 路由调用返回 401 Unauthorized

原因:DeepSeek API Key 配错了,或粘贴到 cc-switch JSON 时多了空格 / 用错了字段。

解决:

1. 检查 API Key 字段:cc-switch → 设置 → 供应商 → DeepSeek 的 JSON 配置里,ANTHROPIC_AUTH_TOKEN 必须是 sk- 开头的 DeepSeek API Key(不要把 zenmux / GLM 的 Key 粘错过来)

2. 检查 base URL:ANTHROPIC_BASE_URL 必须是 https://api.deepseek.com/anthropic(注意 /anthropic 后缀——这是 DeepSeek 官方提供的 Anthropic 兼容端点)

3. 复制空格:API Key 是不是复制时多了前后空格(前后空格是常见 bug · 删除重新粘贴)

4. API Key 失效:回到 https://platform.deepseek.com/ → API Keys 列表 → 看你的 Key 是否被删除或过期 → 必要时删除重建

Q19: DeepSeek API 调用返回 429 Rate Limit

原因:DeepSeek 免费额度速率限制(每分钟请求数)。

解决:等 1 分钟再试。频繁出现说明你正在做密集调用(比如让 AI 一次生成几千行代码),任务分小块做即可。

Q19b: claude 调用 60 秒以上无响应(不是 429,是单纯卡死)

原因:网络抖动、Claude Code 与 DeepSeek 链路超时、prompt 太长触发慢路径。

解决:

1. 检查 base URL:cc-switch JSON 中 ANTHROPIC_BASE_URL 必须 https://api.deepseek.com/anthropic,少 /anthropic 会卡死无报错

2. 关闭代理:装 Clash / V2Ray 的同学,让 api.deepseek.com 走直连(不走代理)

3. 退出重启 claude:Ctrl+C 退出 claude 交互模式 → 重新 claude 启动

4. prompt 太长:单次输入控制在 4000 字以内;超长任务分小块(让 AI 先列大纲再逐节展开)

5. 检查 cc-switch 路由日志:cc-switch → 设置 → 路由 → “启用日志记录” → 看请求是否到达 cc-switch、错误信息是什么

Q18: cc-switch 路由调用返回 401 Unauthorized

原因:DeepSeek API Key 配错了,或粘贴到 cc-switch JSON 时多了空格 / 用错了字段。

解决:

1. 检查 API Key 字段:cc-switch → 设置 → 供应商 → DeepSeek 的 JSON 配置里,ANTHROPIC_AUTH_TOKEN 必须是 sk- 开头的 DeepSeek API Key(不要把 zenmux / GLM 的 Key 粘错过来)

2. 检查 base URL:ANTHROPIC_BASE_URL 必须是 https://api.deepseek.com/anthropic(注意 /anthropic 后缀——这是 DeepSeek 官方提供的 Anthropic 兼容端点)

3. 复制空格:API Key 是不是复制时多了前后空格(前后空格是常见 bug · 删除重新粘贴)

4. API Key 失效:回到 https://platform.deepseek.com/ → API Keys 列表 → 看你的 Key 是否被删除或过期 → 必要时删除重建

Q19: DeepSeek API 调用返回 429 Rate Limit

原因:DeepSeek 免费额度速率限制(每分钟请求数)。

解决:等 1 分钟再试。频繁出现说明你正在做密集调用(比如让 AI 一次生成几千行代码),任务分小块做即可。

Q19b: claude 调用 60 秒以上无响应(不是 429,是单纯卡死)

原因:网络抖动、Claude Code 与 DeepSeek 链路超时、prompt 太长触发慢路径。

解决:

1. 检查 base URL:cc-switch JSON 中 ANTHROPIC_BASE_URL 必须 https://api.deepseek.com/anthropic,少 /anthropic 会卡死无报错

2. 关闭代理:装 Clash / V2Ray 的同学,让 api.deepseek.com 走直连(不走代理)

3. 退出重启 claude:Ctrl+C 退出 claude 交互模式 → 重新 claude 启动

4. prompt 太长:单次输入控制在 4000 字以内;超长任务分小块(让 AI 先列大纲再逐节展开)

5. 检查 cc-switch 路由日志:cc-switch → 设置 → 路由 → “启用日志记录” → 看请求是否到达 cc-switch、错误信息是什么