环境准备指南目录§1 电脑情况确认开始前检查§2 安装 JDK 21§3 安装 Maven 3.9 配置阿里云镜像§4 安装 MySQL 8§5 安装 Node.js 24 LTS§6 安装 Git§7 安装 PostmanAPI 测试工具§8 注册 DeepSeek 实名 创建 API Key§9 一次性环境验证必做§10 安装 Claude Code CLI cc-switch 配置 DeepSeek10.1 安装 Claude Code CLI10.2 安装 cc-switch10.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 21LTS,Oracle 当前推荐的长期支持版本。⚠️ 不要装 JDK 8 / JDK 11 / JDK 17 等旧版本——用到的 SpringBoot 3.5.14 强制要求 JDK 17,直接装 JDK 21 一步到位。步骤1.下载页:**首选(国内镜像,快) **:https://repo.huaweicloud.com/java/jdk/2135/,选 jdk-21_windows-x64_bin.msi(约 160 MB)备用(甲骨文官网,需注册):https://www.oracle.com/java/technologies/downloads/#java21Mac: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.59-LTS-239) Java HotSpot(TM) 64-Bit Server VM (build 21.0.59-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。✅ 检查点 §2java -version 显示 21.xecho %JAVA_HOME% 输出非空,指向 JDK 21 目录§3 安装 Maven 3.9 配置阿里云镜像Maven 管理后端 Java 项目依赖(相当于前端的 npm)。必须配阿里云镜像,否则下载依赖会卡到怀疑人生。步骤下载:https://maven.apache.org/download.cgi,选Binary zip archive:apache-maven-3.9.9-bin.zip(约 9 MB)。解压到 D:\dev\maven(解压后路径 D:\dev\maven\apache-maven-3.9.9)。手动配环境变量(零经验同学请逐句看):桌面此电脑右键 → 属性 → 高级系统设置 → 环境变量 按钮弹出窗口分上下两栏:上用户变量(只对你账号生效);下系统变量(对所有账号生效)。统一用下方系统变量(避免多账号问题)在下方系统变量区域点 新建 → 弹出小窗口填:​ ① 变量名:MAVEN_HOME​ ② 变量值:D:\dev\maven\apache-maven-3.9.9(你解压的实际路径)点确定→ 回到环境变量窗口同一系统变量列表找 Path → 选中 → 点编辑→ 弹出新窗口 → 点新建→ 输入 %MAVEN_HOME%\bin → 一路确定配错了想重来:重新打开环境变量窗口 → 系统变量找 MAVEN_HOME → 选中 → 删除 → 重新建。Path 中多余的 %MAVEN_HOME%\bin 同样可在编辑窗口删⚠️ 关键:已打开的 cmd 窗口不会自动加载新环境变量,必须开新 cmd(下一步验证)配置阿里云镜像(关键,省 1 小时下载时间):打开 D:\dev\maven\apache-maven-3.9.9\conf\settings.xml,在 和 之间粘贴:mirror idaliyunmaven/id mirrorOf*/mirrorOf name阿里云公共仓库/name urlhttps://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 一致。✅ 检查点 §3mvn -version 显示 Maven 3.9.9mvn -version 显示 Java version 是 21.xsettings.xml 已加阿里云 mirror(搜 aliyunmaven 能找到)§4 安装 MySQL 8MySQL 8.0(最新稳定版),社区免费版完全够用。下载: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/双击安装:Setup Type:Server only(只装数据库本体)Authentication Method:Use Strong Password Encryption(默认)**MySQL Root Password:**⚠️ 设置一个你能记住的简单密码,如 123456 或 root1234。这个密码后面要填到项目配置文件,忘了就要重装。 安全提示:弱口令仅限本机开发用。生产环境必须强密码(≥12 位 大小写数字符号混合)。Phase 5 后端开发会专门讲生产密码与密钥管理。Windows Service:保持默认(开机自启)安装完成后 MySQL 已自动作为 Windows 服务启动。✅ 检查点 §4mysql -u root -p 输入密码后能进入 mysql 提示符记住 root 密码(写在草稿纸或备忘录)(可选) DBeaver 能连本机 MySQL§5 安装 Node.js 24 LTSNode.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.0Mac:brew install nvm → nvm install 24 → nvm use 24步骤下载: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**双击安装,**全部默认下一步(C:\Program Files\nodejs\ 路径无空格 OK)。⚠️ 出现 “Tools for Native Modules” 不要勾选(练习项目用不到,会下 4 GB 的 VS Build Tools)验证(打开新 cmd):node -v npm -v预期(node 是 20.x,npm 是 10.x):v24.11.0 10.8.2配置淘宝镜像(关键,省 90% 下载时间):npm config set registry https://registry.npmmirror.com npm config get registry 后者输出:https://registry.npmmirror.com/ Mac:brew install node20(推荐用 nvm install 20);淘宝镜像命令一致。§5.1 ⭐ 安装 pnpm(V4-D04 必做 · 替代 npm 作前端包管理器) 统一用 pnpm,不用 npm/yarn**快:**并行安装 硬链接,首次比 npm 快 2-3x,二次安装快 10x**省盘:**全局共享依赖(每个项目不再重复 100MB node_modules)**严:**严格依赖隔离,避免 npm 的幽灵依赖问题步骤**装 pnpm 10 LTS(**借用 npm 全局装,只用这一次 npm · ⚠️ 指定 LTS 版本避免装到 pnpm 11.x):npm install -g pnpm10 不指定 10 会装最新主版本(当前 11.x · 2026-05-09 发布) · pnpm 11 是纯 ESM SQLite 索引存储,大版本变更建议生产用 LTS 10。验证:pnpm --version预期输出 10.x.x(LTS · 当前 10.33.4)。配置淘宝镜像(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)。✅ 检查点 §5node -v 显示 v24.x.xnpm -v 显示 10.x.xnpm config get registry 显示淘宝镜像pnpm --version 显示 10.x.x(LTS · §5.1 必做)pnpm config get registry 显示淘宝镜像§6 安装 Git下载:https://git-scm.com/download/win国内镜像:https://npmmirror.com/mirrors/git-for-windows/双击安装,全部默认下一步。验证(新 cmd 或 Git Bash):git --version 预期:git version 2.47.x.windows.x配置用户信息(必做,提交代码用):git config --global user.name 你的姓名拼音 git config --global user.email 你的邮箱(与 Gitee 注册邮箱一致)⚠️ 关键提醒90% 新手坑点:“你的姓名拼音” 和 “你的邮箱…” 是占位符,必须替换成你自己的实际姓名邮箱。❌ 错误直接复制粘贴执行commit 作者会显示成你的姓名拼音验收时被一眼识破✅ 正确git config --global user.name “ZhangSan” git config --global user.email “zhangsanqq.com”⚠️ 这里的姓名/邮箱就是 commit 时显示的作者,配错了用 git config --global --replace-all user.name “新值” 覆盖即可。 Mac:macOS 通常自带(首次 git --version 弹安装框点确认),或 brew install git;git config 命令一致。✅ 检查点 §6git --version 显示 2.xgit config --global user.name 显示真实姓名(拼音可)git config --global user.email 显示邮箱§7 安装 Postman(API 测试工具)测试后端 API 用,比如我写了登录接口,怎么知道它对不对?——用 Postman 发个请求看返回数据就知道。下载:https://www.postman.com/downloads/不需要注册账号,下载完直接打开,选 Skip and go to the app(登录界面下方小字)国内访问慢可用 Apifox 替代(https://apifox.com/),中文界面,功能完全够用。✅ 检查点 §7Postman 或 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 复制公钥:: Windowstype %USERPROFILE%\.ssh\id_ed25519.pub输出形如(整段复制 · 包括开头 ssh-ed25519 和末尾邮箱):ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIxxxxxxx... 你的Gitee邮箱⚠️复制 id_ed25519.pub(公钥)而不是 id_ed25519(私钥)。私钥永远不能外发。§8.3.3 上传公钥到 Gitee登录 Gitee → 右上角头像 → 个人设置左侧导航 → SSH 公钥点 添加公钥:标题:你的电脑型号-日期(如 MyLaptop-2026-05-10,方便区分多台机器)公钥:粘贴 §8.6.2 复制的整段内容点 确定成功标志:返回 SSH 公钥列表能看到刚加的这一条,标未使用。§8.4.4 验证 SSH 连接ssh -T gitgitee.com首次连接会提示 Are you sure you want to continue connecting (yes/no)? → 输 yes 回车。 成功输出:Hi 你的用户名! Youve 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 KeyDeepSeek 当前性价比最高的国产大模型。用DeepSeek V4 Pro / V4 Flash 双模型 cc-switch 路由§9.1 注册账号(网页版自检)访问 https://chat.deepseek.com/国内手机号注册(建议用与 Gitee 不同的邮箱避免账号混乱)登录后发你好,看 AI 是否正常回复⚠️ 左下角或顶部模型选择应显示 “DeepSeek V4” 或 “DeepSeek-V4”(只显示 V3.2 → 账号还没切到 V4,过 1-2 天再试)§9.2 实名认证(创建 API Key 的前置)打开 https://platform.deepseek.com/⚠️ 网址是 platform.deepseek.com,不是 chat.deepseek.com用 §9.1 注册的 DeepSeek 账号登录平台政策:未实名不能创建 Key,先完成实名认证:左侧菜单 → 账号管理 / 实名认证选 个人实名 → 支付宝扫码 → ¥0.1 验证(自动退回)实名通过才能下一步⚠️ 实名页面打不开 → 多刷几次;高峰时段延迟 1-2 分钟§9.3 创建 API Key左侧菜单 → API keys点 创建 API key:名称:course-claude-code只显示一次(sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx)⚠️ 立即复制保存到记事本/备忘录,关掉对话框就再也看不到。 救法:如果没复制到 / 复制错 / 不小心关了对话框,回到 API keys 列表 → 选中这个 Key → 删除 → 重新创建一个新 Key,会再次完整显示。删除/重建次数无限,不扣额度。左侧菜单 → 用量 确认免费额度(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确认 Node.js 和 pnpm 已装(§5 应已完成):node --version # ≥ 24.x pnpm --version # ≥ 10.x全局安装 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-switchcc-switch 是一个本地 GUI 工具,负责把 claude 的请求路由到不同的 AI 服务商(本课程用 DeepSeek)。双击安装包,按提示完成安装启动 cc-switch(桌面图标或开始菜单),托盘出现 cc-switch 图标说明已运行§11.3 cc-switch 添加 DeepSeek 供应商点击 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]编辑通用配置 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.*) ] } }保存§11.4 启用 cc-switch Claude 路由cc-switch 设置 → 路由在 “本地路由” 区:服务地址:http://127.0.0.1:15721(不要改,默认即可)路由总开关:✅ 开启在 “路由启用” 区: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. 用 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)访问 https://open.bigmodel.cn/ 注册账号(国内手机号即可)实名认证(支付宝扫码 · ¥0.1 验证)进入 API Keys 页面 → 创建 API Key → 复制保存到本地记事本充值 ¥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)时:退出 Claude Code:在 claude 会话里输入 /exit(或 CtrlD)cc-switch GUI 切 active provider:托盘 cc-switch → 设置 → 供应商 → 把激活状态从 DeepSeek 切到 GLM重启 claude:在项目根目录运行 claude(此时 /model opus 会路由到 GLM 5.1)跑审核命令:如 /srs-reviewer 请审核 docs/PRD.md …审核完毕,切回 DeepSeek:再次 /exit 退出 → cc-switch 切回 DeepSeek → 重启 claude → 跑应用修复 / 下游生成命令§11.6.5 Hello World 验证(异源审核就绪)测试 GLM 5.1 通了:cc-switch 切到 GLM provider → 重启 claude在 claude 输入:请用一句话告诉我你是哪个模型预期 GLM 5.1 回复类似我是智谱清言 GLM 4.5/4.6(具体描述以 GLM 实际版本为准)输入 /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 里旧版本排在前面。解决:此电脑右键 → 属性 → 高级系统设置 → 环境变量双击系统变量 Path找到所有 xxx\jdk\bin 或 Common Files\Oracle\Java\javapath含 jdk21 的那条上移到顶部重启 cmd 重新验证⚠️ Mac 用户:~/.zshrc 或 ~/.bash_profile 检查 JAVA_HOME 配置。Q2: echo %JAVA_HOME% 输出空白原因:JDK 21 安装包应自动配 JAVA_HOME,但偶尔失败。解决:手动配环境变量 → 系统变量 → 新建变量名 JAVA_HOME,变量值 D:\dev\jdk21(实际路径,末尾不要带反斜杠)Path 中新建 %JAVA_HOME%\bin关闭所有 cmd 重新打开验证Q3: ‘mysql’ 不是内部或外部命令原因:MySQL 的 bin 目录不在 PATH。解决:找 MySQL 路径(通常 C:\Program Files\MySQL\MySQL Server 8.0\bin)加到系统 Path关闭 cmd 重新打开验证Q4: MySQL Access denied for user ‘root’‘localhost’原因:密码错或服务异常。解决:确认 MySQL 服务运行:Win R → services.msc → MySQL80 服务状态正在运行忘了密码:最直接重装 MySQL(学生项目数据可丢,重装比改密码省时间)高阶:跳过权限模式重置密码,参考MySQL 官方文档Q5: MySQL Communications link failure / Connection refused: localhost:3306原因:服务没启动 / 端口被占 / 防火墙拦截。解决按顺序排查:服务没启动最常见Win R → services.msc → 找 MySQL80 → 右键启动。装完不重启电脑常见此问题。3306 端口被占cmd 跑 netstat -ano | findstr :3306如果有别的进程占用不是 mysqld.exe→ 杀掉那个进程或修改 MySQL 端口到 3307修 my.ini 重启服务 后续 application.yml 也要改。防火墙拦截Windows Defender 防火墙 → 入站规则 → 找MySQL Server或新建规则放行 3306。DBeaver 能连但 SpringBoot 连不上检查 application.yml 的 url确保是 jdbc:mysql://localhost:3306/库名?useSSLfalseserverTimezoneAsia/Shanghai不是 127.0.0.1部分驱动版本对 IP 敏感。B 类:Node 与 npm 问题Q6: pnpm install 卡 5 分钟以上不动原因:大概率是网络问题——默认走 npm 官方源境外国内学生很容易卡。解决按顺序排查:优先确认已配淘宝镜像§5 步骤 4npm config get registry 应显示 https://registry.npmmirror.com/。没配 → 立即配 重新跑 pnpm install。已配仍卡CtrlC 中断 → 删 node_modules pnpm-lock.yaml → 重跑 pnpm installlock 文件可能锁定旧源 URL。分钟仍无 100% 进度但有滚动输出是正常的首次装大型项目 200 包 3-8 分钟只要终端有输出就别中断。判断标准能看到包名滚动 在装完全静止 卡死。彻底卡死≥10 分钟无输出换 cnpmpnpm add -g cnpm --registryhttps://registry.npmmirror.com → 之后用 cnpm install 代替 pnpm install。公司/学校有代理检查环境变量 HTTP_PROXY / HTTPS_PROXY 是不是错配指向已下线的代理服务器。Q7: pnpm error code EACCES / EPERM: operation not permitted原因:Windows 权限问题通常是 VS Code / 编辑器进程在锁定 node_modules 文件夹。解决:关闭 VS Code / 编辑器 → 重新跑 pnpm install仍报错 → 用管理员身份打开 cmd / PowerShell → cd 到项目目录 → 重跑不要用 --force 或 sudoMac 上 sudo pnpm 会埋后续权限坑D 类:Claude Code CLI 与 AI 调用问题Q14: claude 启动报 “Could not connect to cc-switch / connection refused”原因:cc-switch 没有在运行,或 cc-switch 的本地路由没启用。解决:检查 cc-switch 托盘图标是否存在(右下角任务栏 → 显示隐藏图标 → 找 cc-switch)没有 → 启动 cc-switch(开始菜单 → cc-switch)有图标但仍连不通 → 点托盘图标 → 设置 → 路由 → 确认路由总开关✅ 开启 “服务地址”http://127.0.0.1:15721路由Claude开关是否 ✅ 开启?未开启则 claude 走不到 DeepSeekQ15: claude 启动后卡死 / 长时间无响应原因:cc-switch 路由的 API Key 配错,或 DeepSeek API 端点不通。解决:检查 cc-switch → 设置 → 供应商 → DeepSeek 的 API Key 是否粘贴正确(沒前后空格、完整 sk- 开头)检查 cc-switch JSON 配置中 ANTHROPIC_BASE_URL 是否为 https://api.deepseek.com/anthropic(注意 /anthropic 后缀)检查网络:浏览器打开 https://platform.deepseek.com 能正常显示则 API 端点通临时方案:在 claude 交互模式按 CtrlC 退出,重启 cc-switch 后再 claudeQ16: cc-switch 中添加 DeepSeek 供应商保存后不生效原因:JSON 格式错误(中文引号、缺逗号)或路由开关没开。解决:cc-switch → 设置 → 供应商 → 编辑 DeepSeek → 检查 JSON 配置:所有引号必须是英文双引号 ,不能是中文 每个键值对后面要有逗号(除了最后一项)JSON 编辑器顶部应显示格式化按钮,点一下能自动检查格式JSON 检查通过仍不生效 → §11.4 启用路由(Claude 路由总开关 Claude 开关都要 ✅)3.仍不行 → 退出 cc-switch(右键托盘 → 退出)→ 重新启动 cc-switchQ17: AI 对话时不按规则文件来(用了错误的框架/写法)原因:Claude Code 没有读到项目模板根目录的 CLAUDE.md(AI 编码规则),或上下文已被旧对话污染。解决:确认你在项目工作目录下启动了 claude(目录里必须有 CLAUDE.md 文件 · ls CLAUDE.md 应能看到)在 claude 交互模式中输入 /clear 清空对话上下文(让 Claude Code 重新读 CLAUDE.md)对话中显式提醒 AI:“请遵守项目根目录 CLAUDE.md 中的全部规范”终极方案:CtrlC 退出 claude → 在项目根目录确认 CLAUDE.md 完整(包含 §一 项目基础 / §二 后端 / §三 前端 / §四 Git commit 四大节)→ 重新 claudeQ18: cc-switch 路由调用返回 401 Unauthorized原因:DeepSeek API Key 配错了,或粘贴到 cc-switch JSON 时多了空格 / 用错了字段。解决:检查 API Key 字段:cc-switch → 设置 → 供应商 → DeepSeek 的 JSON 配置里,ANTHROPIC_AUTH_TOKEN 必须是 sk- 开头的 DeepSeek API Key(不要把 zenmux / GLM 的 Key 粘错过来)检查 base URL:ANTHROPIC_BASE_URL 必须是 https://api.deepseek.com/anthropic(注意 /anthropic 后缀——这是 DeepSeek 官方提供的 Anthropic 兼容端点)复制空格:API Key 是不是复制时多了前后空格(前后空格是常见 bug · 删除重新粘贴)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 太长触发慢路径。解决:检查 base URL:cc-switch JSON 中 ANTHROPIC_BASE_URL 必须 https://api.deepseek.com/anthropic,少 /anthropic 会卡死无报错关闭代理:装 Clash / V2Ray 的同学,让 api.deepseek.com 走直连(不走代理)退出重启 claude:CtrlC 退出 claude 交互模式 → 重新 claude 启动prompt 太长:单次输入控制在 4000 字以内;超长任务分小块(让 AI 先列大纲再逐节展开)检查 cc-switch 路由日志:cc-switch → 设置 → 路由 → “启用日志记录” → 看请求是否到达 cc-switch、错误信息是什么Q18: cc-switch 路由调用返回 401 Unauthorized原因:DeepSeek API Key 配错了,或粘贴到 cc-switch JSON 时多了空格 / 用错了字段。解决:检查 API Key 字段:cc-switch → 设置 → 供应商 → DeepSeek 的 JSON 配置里,ANTHROPIC_AUTH_TOKEN 必须是 sk- 开头的 DeepSeek API Key(不要把 zenmux / GLM 的 Key 粘错过来)检查 base URL:ANTHROPIC_BASE_URL 必须是 https://api.deepseek.com/anthropic(注意 /anthropic 后缀——这是 DeepSeek 官方提供的 Anthropic 兼容端点)复制空格:API Key 是不是复制时多了前后空格(前后空格是常见 bug · 删除重新粘贴)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 太长触发慢路径。解决:检查 base URL:cc-switch JSON 中 ANTHROPIC_BASE_URL 必须 https://api.deepseek.com/anthropic,少 /anthropic 会卡死无报错关闭代理:装 Clash / V2Ray 的同学,让 api.deepseek.com 走直连(不走代理)退出重启 claude:CtrlC 退出 claude 交互模式 → 重新 claude 启动prompt 太长:单次输入控制在 4000 字以内;超长任务分小块(让 AI 先列大纲再逐节展开)检查 cc-switch 路由日志:cc-switch → 设置 → 路由 → “启用日志记录” → 看请求是否到达 cc-switch、错误信息是什么