---
title: "第 1 周上机：报错速查手册"
---

# 第 1 周上机：报错速查手册

> 适用：《经济金融 AI 智能体设计与开源》第一次课现场装机
> 装机内容（按[《手册_环境安装》](/materials/2026-autumn/w01/installation)顺序）：macOS 底座（Xcode 命令行工具 + Homebrew）、Node.js、Git、Claude Code（npm 安装）、DeepSeek API、CC Switch、VS Code
> 整理日期：2026-09-07。网络数据为当天在广州国内网络实测，校园网可能不同。

## 怎么用这份文档

1. **先搜报错原文**。按 Ctrl+F（Mac 是 Cmd+F），把终端里报错的关键词粘进去搜，例如 `not recognized`、`401`、`Retrying`、`粘贴`。每条都尽量抄了报错原文，方便你对上号。
2. **看星号**。★ 越多越常见。卡住时先看 ★★★★ 以上的条目。
3. **可以先问 AI 辅助排查**。把终端里从命令到报错的整段文字复制下来，删去密钥和个人信息后，发给能使用的 AI。逐步检查建议，每一步把新的输出再发回去。
4. **复制文字，不要截图**。课上接入的 DeepSeek V4-Pro 是纯文本模型，看不见图片（见 7.8）。文字比截图有效得多。
5. 部分系统或界面可能与示例不同；文中注明未实测或需要助教协助的步骤，请先联系助教确认。
6. 章节顺序与[《手册_环境安装》](/materials/2026-autumn/w01/installation)一致：0 通用 → 1 macOS 底座（Windows 跳过）→ 2 Node.js → 3 Git → 4 Claude Code → 5 DeepSeek → 6 CC Switch → 7 接通后 → 8 VS Code。

**提问模板（复制即用）**

```txt
我在装 Claude Code 课程环境时遇到问题，请帮我逐步排查。
【环境】Windows 11 / macOS（版本）；Node v__；Claude Code v__；用 CC Switch 接 DeepSeek
【我想做什么】（一句话）
【报错原文】（把终端从命令到报错的整段粘在这里；先删去密钥和个人信息）
【已试过】（列出）
请：①判断是网络、权限、版本还是配置问题；②给出可直接复制的命令，分步骤；③每步可能再报错的话提前说明。
```

**装机顺序与自检**：每装完一项就在终端验证，能出版本号或进入对话框就是成功。

| 步骤 | 验证命令 | 成功标志 |
|:--|:--|:--|
| 1 macOS 底座（仅 Mac） | `git --version` 和 `brew --version` | 有 git 版本号；显示 `Homebrew 4.x.x` |
| 2 Node.js | `node -v` 和 `npm -v` | 显示版本号（Node 应为 v24.x） |
| 2 npm 换源 | `npm config get registry` | 输出 <https://registry.npmmirror.com/> |
| 3 Git | `git --version` | 形如 `git version 2.5x.x` |
| 4 Claude Code | `claude --version` | 形如 `2.1.263 (Claude Code)` |
| 5–6 DeepSeek + CC Switch | 终端输入 `claude`，说「你好」 | 有回复，且没让你登录 |
| 8 VS Code | 能打开 | — |

---

## 0 通用：终端、PowerShell、粘贴、重开

### 0.1 ★★★★★ 怎么打开终端

**Windows**：按 Win+X，在菜单里选「Windows PowerShell」或「终端」；或在开始菜单搜 PowerShell。开始菜单里若有两个 PowerShell，选**不带 `(x86)`** 的那个。
**macOS**：按 Cmd+空格，输入 `Terminal`，回车。

### 0.2 ★★★★★ 分不清 PowerShell 和 CMD，命令报 `'irm' is not recognized` / `The token '&&' is not a valid statement separator` / `A parameter cannot be found that matches parameter name 'fsSL'` / `'bash' is not recognized`

**症状**：Windows 上两个黑框看着一样，粘一条命令进去就报上面某一条。
**原因**：复制了另一个 shell 的命令。看提示符：开头是 `PS C:\Users\你的名字>` 是 PowerShell；开头没有 `PS`、直接是 `C:\Users\你的名字>` 是 CMD。`curl -fsSL ...`、`bash` 是 macOS/Linux 命令，在 Windows 上都不能用。
**解决**：本课程 Windows 一律用 PowerShell。关掉当前窗口，按 0.1 重新打开，确认提示符带 `PS` 再粘命令。本手册给 Windows 的命令都是 PowerShell 写法。

### 0.3 ★★★★ 关掉终端重开（PATH 未生效）

**症状**：刚装完 Node 或 Claude Code，终端里 `node -v` / `claude --version` 提示找不到命令。
**原因**：安装程序已经把命令加进 PATH，但当前这个终端窗口是装之前开的，没有重新读取。
**解决**：关掉所有终端窗口，重新开一个再试。这是必要步骤，不是可选动作。VS Code 里的终端同理，要关掉 VS Code 重开。

### 0.4 ★★★★ PowerShell 里 Ctrl+V 粘不进去

**症状**：复制了命令或 API Key，在 PowerShell 里按 Ctrl+V 没反应。
**原因**：Win10 旧版 PowerShell（5.1 及更早）默认不支持 Ctrl+V。
**解决**：在窗口里**点右键**即粘贴；或用 Ctrl+Shift+V。装了 Windows Terminal（微软商店，<https://apps.microsoft.com/detail/9n0dx20hk701>）之后 Ctrl+V 可用。临时办法：右键标题栏 → 属性 → 选项 → 勾选「使用 Ctrl+Shift+C/V 作为复制/粘贴」。

### 0.5 ★★★ 输入命令后「没反应」

**症状**：输入 `claude` 回车，光标闪着不动，或者只显示了一行路径。
**原因**：多数时候是命令正在启动，或需要再按一次回车。
**解决**：先多按一次回车，等 5–10 秒。仍无反应就关掉终端重开（0.3）。

### 0.6 ★★★ `Windows protected your PC` / SmartScreen 拦截安装程序

**症状**：双击安装包弹出蓝色窗口「Windows 已保护你的电脑」。
**原因**：对未签名或不常见程序的常规提示，不是病毒。
**解决**：点「更多信息（More info）」→「仍要运行（Run anyway）」。

### 0.7 ★★ 误开了 `Windows PowerShell (x86)`：`Claude Code does not support 32-bit Windows`

**症状**：机器明明是 64 位，却报 32 位不支持。
**原因**：开始菜单里有两个 PowerShell，你开的是带 `(x86)` 的 32 位版本。
**解决**：在报错的窗口里运行 `[Environment]::Is64BitOperatingSystem`，返回 `True` 说明系统没问题。关掉这个窗口，打开不带 `(x86)` 的「Windows PowerShell」重来。

### 0.8 ★★ 安装路径或项目路径含中文

**症状**：各种说不清的报错，路径里有中文或空格。
**原因**：官方排错文档未提到中文路径会失败，缺少可靠复现依据。遇到涉及路径的报错时，需要结合具体命令排查。
**解决**：稳妥做法是把练习项目放在纯英文路径下，例如 `C:\Users\你的英文用户名\projects\`。Windows 用户名本身是中文的，暂时不用改，先装上再说，遇到问题再问助教。

### 0.9 ★★★ 开着代理/梯子

**症状**：DeepSeek 连不上、一直 Retrying、下载忽快忽慢。
**原因**：本次课全部走国内服务（npmmirror、DeepSeek），代理软件反而会把请求带到境外，或在长连接中途断掉（`Connection closed mid-response`）。
**解决**：装机和使用期间关掉代理软件，关掉后重开终端。

---

## 1 macOS 底座：Xcode 命令行工具与 Homebrew

**Windows 用户跳过本节。** 本节命令与[《手册_环境安装》](/materials/2026-autumn/w01/installation)第 1 节、教材 3.2 B–C 一致。

### 1.1 ★★★★ `xcode-select --install` 提示已经安装

**症状**：运行 `xcode-select --install` 后没有弹出安装对话框，而是提示命令行工具已安装（英文提示含 `already installed`）。
**原因**：这台电脑之前装过 Xcode 命令行工具。
**解决**：不用再装，直接进入下一步。运行 `git --version`，看到类似 `git version 2.39.3 (Apple Git-146)` 的输出就说明工具在。

### 1.2 ★★★ Xcode 命令行工具下载很慢或失败

**症状**：点「安装」后进度条长时间不动，或提示下载失败。
**原因**：安装包约 740 MB，从苹果服务器下载，正常要 5–20 分钟；校园网高峰期可能更慢。
**解决**：
1. 耐心等完 20 分钟再判断。中途不要点「获取 Xcode」，那是十几 GB 的完整 Xcode，本课程不需要。
2. 提示失败就关掉对话框，换网络（手机热点）后重新运行 `xcode-select --install`。
3. 卡在这一步时，先跳过去做第 5 节的 DeepSeek 注册，回头再装。

### 1.3 ★★★★ Homebrew 清华镜像安装脚本报错

**症状**：把手册里那整段（从 `export HOMEBREW_BREW_GIT_REMOTE=...` 到 `rm -rf brew-install`）粘进终端后，报 `git: command not found`、`fatal: destination path 'brew-install' already exists`，或 `git clone` 那一行长时间无进度。
**原因**：按可能性排序：
1. 还没装 Xcode 命令行工具，`git clone` 那行没有 git 可用。
2. 上次跑到一半中断，当前目录里留下了 `brew-install` 文件夹，再跑时 `git clone` 拒绝覆盖。
3. 复制时漏了前面几行 `export`，脚本没走镜像，退回去连 GitHub，国内慢。
4. 用的是官网命令 `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"`，它走 GitHub，课堂上多半超时。
**解决**：
1. 先运行 `git --version` 确认第 1.1 步已完成。
2. 运行 `rm -rf brew-install` 清掉残留。
3. 从手册重新复制**整段**命令（8 行都要），粘进终端一次执行。不要用官网那条 `curl` 命令。
4. 仍失败就把终端里从命令到报错的整段复制问 AI 或助教。

### 1.4 ★★★ 输密码时屏幕不显示任何字符

**症状**：装 Homebrew 中途要求输入密码，敲键盘却什么都不显示，以为键盘坏了。
**原因**：macOS 输密码时不显示星号也不显示小黑点，这是正常的安全设计。
**解决**：输入登录这台电脑的开机密码，敲完直接按回车。输错了会再问一次。安装软件时反复要密码也是正常的。

### 1.5 ★★★★★ Apple 芯片的 Mac 装完 Homebrew，`brew` 找不到命令：`zsh: command not found: brew`

**症状**：安装脚本已跑完，输入 `brew --version` 报 `command not found`。
**原因**：M1–M4 芯片的 Mac 上 Homebrew 装在 `/opt/homebrew/`，这个目录默认不在终端的 PATH 里。安装脚本结尾会提示要加两行配置，多数人没看到。不知道自己是什么芯片：左上角苹果图标 → 关于本机，看「芯片」一栏，显示 Apple M1/M2/M3/M4 就是 Apple 芯片。
**解决**：在终端运行手册里的这两行：

```bash
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
source ~/.zprofile
```

然后关掉终端重开，运行 `brew --version`，看到 `Homebrew 4.x.x` 即可。也可以运行 `brew doctor`，看到 `Your system is ready to brew.` 说明正常。Intel 芯片的 Mac 不需要这两行，找不到 `brew` 就先重开终端（0.3）。

### 1.6 ★★★ `brew install` 很慢或超时

**症状**：`brew install node` 或 `brew install --cask visual-studio-code` 卡在下载，速度只有几十 KB/s，或报连接超时。
**原因**：装 Homebrew 时用的镜像变量只在那一个终端窗口里有效。没把镜像写进 `~/.zprofile` 的话，以后每次 `brew install` 还是走境外服务器。
**解决**：运行手册里的这几行（做一次即可，以后每次开终端自动生效）：

```bash
echo 'export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git"' >> ~/.zprofile
echo 'export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git"' >> ~/.zprofile
echo 'export HOMEBREW_API_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api"' >> ~/.zprofile
echo 'export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles"' >> ~/.zprofile
source ~/.zprofile
```

然后重跑安装命令。仍慢就检查是否开着代理（0.9）。详细说明见清华镜像帮助页 <https://mirrors.tuna.tsinghua.edu.cn/help/homebrew/>。

### 1.7 ★★ 打开下载的软件提示「无法验证开发者」/「已损坏」

**症状**：双击 `.dmg` 或应用图标，macOS 弹窗说无法打开。
**原因**：macOS 对非 App Store 应用的常规安全提示。
**解决**：打开「系统设置 → 隐私与安全性」，在「安全性」部分找到被拦截的那个应用，点「仍要打开」。CC Switch v3.20.1 已过苹果公证，一般不会弹；弹了也按这个办法处理（6.2）。

---

## 2 Node.js 与 npm 换源

### 2.1 ★★★★ Node.js 官网下载慢 / 装错版本

**症状**：`nodejs.org` 下载慢；或装成了 26.x 版本。
**原因**：官网在境外。当前 LTS 是 **v24.20.0**，Current 线是 26.x，不要装 26。
**解决**：用淘宝 npmmirror CDN（2026 年 9 月 7 日实测 5.2 MB/s）：

| 平台 | 下载地址 |
|:--|:--|
| Windows x64 安装包 | <https://cdn.npmmirror.com/binaries/node/v24.20.0/node-v24.20.0-x64.msi> |
| macOS 安装包（Intel 与 M 芯片共用同一个） | <https://cdn.npmmirror.com/binaries/node/v24.20.0/node-v24.20.0.pkg> |

备选：中科大 <https://mirrors.ustc.edu.cn/node/v24.20.0/node-v24.20.0-x64.msi>。
**不要用清华 TUNA**：它的 Node 镜像已停止同步，v24.20.0 返回 404，网上旧教程推荐它的一律不照抄。
32 位 Windows 没有 Node 24 安装包；ARM 版 Windows 的 `node-v24.20.0-arm64.msi` 未经本课程实测，请联系助教确认适用版本。

### 2.2 ★★ Mac 要选 Intel 版还是 Apple Silicon 版

**解决**：不用选。Node 的 macOS `.pkg` 是通用包，一个文件两种芯片都能装。

### 2.3 ★★ 装完 Node 点 Finish 后自动弹窗装一堆东西

**症状**：安装最后一步之后，冒出一个窗口开始装 chocolatey、Build Tools 等。
**原因**：Node 安装向导可选的「自动安装必要工具」，本课程不需要。
**解决**：可以直接关掉那个窗口，不影响 `node -v` / `npm -v`。

### 2.4 ★★★★ `node` / `npm` 不是内部或外部命令，也不是可运行的程序

**症状**：`node -v` 报 `'node' is not recognized ...` 或「不是内部或外部命令」。
**原因**：多半是终端没重开（0.3）。少数是安装时没勾「Add to PATH」。
**解决**：
1. 关掉所有终端重开。
2. 仍不行：Windows 运行 `where node`（Mac 用 `which node`），为空说明没进 PATH，卸载 Node 重装，安装时留意 PATH 相关选项。
3. 复制报错问 AI：「帮我配置环境变量，让 node 和 npm 命令可在终端中使用」。

### 2.5 ★★★★★ npm 换成国内源（必做）

**解决**：装完 Node 后在终端运行：

```txt
npm config set registry https://registry.npmmirror.com
```

验证：

```txt
npm config get registry
```

应输出 <https://registry.npmmirror.com/>。再跑一条同时验证网络和镜像：

```txt
npm view @anthropic-ai/claude-code version
```

能秒出版本号（2026 年 9 月 7 日为 `2.1.263`）说明通了。旧地址 `registry.npm.taobao.org` 早已废弃，不要用。

### 2.6 ★★★ npm 报 `Unexpected token '<'` / `is not valid JSON` / 一直转圈不动

**症状**：`npm install` 时报上面的错，或几分钟没有进度。
**原因**：npm 下载源出错，拿到的是网页而不是包信息；或源没换成功。
**解决**：

```txt
npm cache clean --force
npm config set registry https://registry.npmmirror.com
```

然后重跑安装命令。2026 年 9 月 7 日实测 `registry.npmmirror.com` 响应 0.10 秒，如果换源后仍卡，检查是否开着代理（0.9）。

### 2.7 ★★★ `running scripts is disabled on this system`（SecurityError / 无法加载文件 ... 因为在此系统上禁止运行脚本）

**症状**：PowerShell 里运行 `npm` 或 `claude` 报这条。
**原因**：PowerShell 执行策略拦截了 npm 生成的 `.ps1` 启动脚本。
**解决**：在 PowerShell 里运行：

```txt
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
```

运行后没有任何输出是正常的，说明成功了。注意 `RemoteSigned` 和 `-Scope` 之间有空格，别拼成 `Remotesiged`。若弹出确认，输入 `Y` 回车。改不了策略时可改用 `npm.cmd` / `claude.cmd` 调用。

### 2.8 ★ 安装时出现 `EBADENGINE` 警告

**症状**：`npm install -g @anthropic-ai/claude-code` 过程中打印 `npm WARN EBADENGINE`。
**原因**：Claude Code 的 npm 包要求 Node 22 以上，你的 Node 低于 22。
**解决**：只是警告，安装照常完成，`claude` 照常运行。按 2.1 装 v24 就不会出现。

### 2.9 ★ macOS 报 `EACCES: permission denied`

**症状**：`npm install -g` 时报权限不足。
**原因**：npm 全局目录不可写。
**解决**：**不要用 `sudo npm install -g`**（官方明确不建议）。先把 `npm config get prefix` 的输出发给助教，由助教协助确认目录和 PATH 设置，再重开终端后重装。

---

## 3 Git

本节命令与[《手册_环境安装》](/materials/2026-autumn/w01/installation)第 3 节、教材 3.3 C–D 一致。Git 第 3 周正式讲，今天装上就行。

### 3.1 ★★★★ Windows 装完 Git，`'git' 不是内部或外部命令` / `'git' is not recognized`

**症状**：安装向导已经 Finish，PowerShell 里 `git --version` 找不到命令。
**原因**：九成是 PowerShell 没重开，旧窗口没有重新读取 PATH（0.3）。少数是安装时 PATH 那一页选错了。
**解决**：
1. 关掉所有 PowerShell 窗口，重新开一个再输 `git --version`。是关掉重开，不是刷新。
2. 仍不行：重新运行安装程序，走到「Adjusting your PATH environment」那一页，确认选的是第二项「Git from the command line and also from 3rd-party software」。这一项是默认值，没改过就不会错。
3. 装完再次关掉 PowerShell 重开验证。

### 3.2 ★★★ 安装向导页太多，不知道该选什么

**症状**：Git 安装向导有十来页选项，编辑器、分支名、换行符……每页都不认识。
**原因**：这些选项面向开发者，本课程用默认值即可。
**解决**：**所有选项保持默认**，一路点 Next，最后 Install、Finish。弹出「用户账户控制」点「是」。唯一值得看一眼的是 PATH 那一页（3.1），默认已是正确选项。

### 3.3 ★★★ Git 官网下载慢或打不开

**症状**：`git-scm.com` 下载页打不开，或下载速度很慢。
**原因**：官网下载走境外服务器。
**解决**：用淘宝镜像的安装包（v2.55.0，约 65 MB）：

```txt
https://cdn.npmmirror.com/binaries/git-for-windows/v2.55.0.windows.5/Git-2.55.0.5-64-bit.exe
```

下载的文件名是 `Git-2.55.0.5-64-bit.exe`，双击安装（3.2）。官网 <https://git-scm.com/downloads/win> 能打开的话也可以用，版本号略有不同不影响。装完 `git --version` 显示 `git version 2.5x.x` 即可。

### 3.4 ★★★ macOS 输入 `git --version` 弹出对话框要求安装命令行工具

**症状**：Mac 上运行 `git --version`，没出版本号，而是弹出「需要安装命令行开发者工具」之类的对话框。
**原因**：macOS 的 git 由 Xcode 命令行工具提供，第 1 节没装或没装完就会弹这个。
**解决**：点「安装」，等它装完（5–20 分钟，见 1.2），再运行 `git --version`，看到类似 `git version 2.39.3 (Apple Git-146)` 即可。Mac 不需要单独下载 Git 安装包。

### 3.5 ★ 要不要现在配置 Git 用户名和邮箱

**症状**：网上教程说装完 Git 要先 `git config`，不确定今天要不要做。
**解决**：第 3 周之前不需要做任何配置。想先配也可以，在终端运行两条（引号里换成自己的）：

```txt
git config --global user.name "你的名字"
git config --global user.email "你的邮箱@example.com"
```

执行后没有输出就是成功。`git config --global --list` 能看到这两项。名字和邮箱中英文都行，邮箱建议用常用的，以后连 GitHub 会用到。

---

## 4 Claude Code 安装

### 4.1 ★★★★★ 不要用官方一键安装命令

**症状**：运行 `irm https://claude.ai/install.ps1 | iex`（Windows）或 `curl -fsSL https://claude.ai/install.sh | bash`（Mac）后：长时间无响应；`Failed to fetch version from downloads.claude.ai`；`Could not resolve host`；`403`；`syntax error near unexpected token '<'`；屏幕上出现 `<!DOCTYPE html>`、`Just a moment...`；「参数列表中缺少参量」。
**原因**：2026 年 9 月 7 日在广州国内网络实测，`claude.ai/install.sh` 与 `downloads.claude.ai` 不通，二进制下载源超时。这两条命令在课堂上会失败。官方文档也写明中国大陆不在支持地区名单内。
**解决**：不要再试这两条。改用 npm 安装（4.2）。

### 4.2 ★★★★★ 标准安装命令（唯一路径）

PowerShell（Windows）或终端（Mac）里运行：

```txt
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com
```

装完**关掉终端重开**（0.3），然后验证：

```txt
claude --version
```

打印形如 `2.1.263 (Claude Code)` 的版本号即成功。版本号迭代很快，只要是 `2.1.x` 就行。

网上有教程说「npm 方式已被官方废弃」「Windows 必须先装 Git Bash」，都是过时说法。npm 仍是官方列出的安装方式；Windows 上没有 Git 时 Claude Code 会改用 PowerShell 执行命令，两种都能用。

### 4.3 ★★★★ `'claude' is not recognized` / `command not found: claude`

**症状**：装完后 `claude --version` 找不到命令。
**原因**：九成是终端没重开。少数是 npm 全局目录没进 PATH。
**解决**：
1. 关掉所有终端窗口重开。
2. Windows 仍不行：打开 `C:\Users\<用户名>\AppData\Roaming\npm`，确认里面有 `claude.cmd`。有的话把这个目录加入用户 PATH：此电脑 → 属性 → 高级系统设置 → 环境变量 → 用户变量 Path → 新建 → 粘贴路径。然后关闭所有 PowerShell 重开。
3. Mac 仍不行：把报错和 `npm config get prefix` 的输出一起发给助教，确认适合当前系统的修复步骤。
4. 如果你是 VS Code 扩展用户，见 8.4。

### 4.4 ★★★ 输入 `claude` 后要求登录 / 跳转到浏览器 / `Not logged in. Please run /login`

**症状**：第一次运行 `claude`，让你选主题之后要登录 Claude 账号，或跳出浏览器网页。
**原因**：这是 Claude 官方账号入口，本课程不走它。免费的 Claude.ai 账号不含 Claude Code 权限，付费订阅在国内也无法直接用。
**解决**：按 Ctrl+C 退出。先去第 5、6 节把 DeepSeek 和 CC Switch 配好，再回来运行 `claude`。配好后不会再弹登录；如果还弹，说明 CC Switch 没生效（6.7）。

### 4.5 ★★ 启动时卡在连接 `api.anthropic.com` 或登录校验

**症状**：DeepSeek 已配好，`claude` 启动时仍尝试连 `api.anthropic.com` 报错。
**原因**：部分接入配置涉及 `~/.claude.json`（注意是家目录下的文件，不在 `.claude/` 文件夹里）的 `"hasCompletedOnboarding": true` 设置。是否需要手动调整取决于当前安装状态，请由助教检查。
**解决**：先重开终端再试；仍不行找助教，助教会帮你改这个文件。不要自己动手改 JSON，改坏了 Claude Code 起不来（见 7.13）。

### 4.6 ★★★ `Do you trust the files in this folder?`

**症状**：进入对话前弹出这个问题。
**原因**：Claude Code 会读写当前文件夹里的文件，先问一次授权。
**解决**：确认当前文件夹是自己的课程工作区后，选「Yes, proceed」。如果再次出现，先核对文件夹路径，再决定是否授权。

### 4.7 ★★ `claude` 打开的是 Claude 桌面应用，不是终端程序

**症状**：输入 `claude` 弹出一个图形界面应用。
**原因**：旧版 Claude Desktop 在系统目录注册了一个 `Claude.exe`，PATH 优先级更高。
**解决**：把 Claude Desktop 更新到最新版，或先卸载它，本课程不需要桌面版。

### 4.8 ★ `Claude Code on Windows requires either Git for Windows (for bash) or PowerShell`

**症状**：启动时报这条。
**原因**：PowerShell 和 Git Bash 都找不到。正常 Windows 10/11 自带 PowerShell，很少出现。
**解决**：按 0.1 用 PowerShell 启动；仍报错就复制报错问 AI。

### 4.9 ★★ 装到一半坏了，怎么从头重装

**解决**：Windows 以管理员身份打开 PowerShell，依次运行：

```txt
Get-Process claude,node -ErrorAction SilentlyContinue | Stop-Process -Force
npm uninstall -g @anthropic-ai/claude-code
Remove-Item "$env:APPDATA\npm\node_modules\@anthropic-ai\claude-code" -Recurse -Force -ErrorAction SilentlyContinue
npm cache clean --force
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com
```

macOS 不运行上述 PowerShell 命令；如需重装，请联系助教确认适合当前安装方式的步骤。

### 4.10 ★ 安装路径报错

**症状**：安装或运行时报错，报错信息里出现带中文的路径。
**解决**：见 0.8。

---

## 5 DeepSeek 注册、充值、Key

### 5.1 ★★★★ 注册与实名

**平台地址**：<https://platform.deepseek.com>。
**流程**：按开放平台页面提供的方式注册或登录，并按提示完成实名认证。遇到困难可先完成软件安装，再处理账号。
**打开页面报 429 / 请求过于频繁**：同一网络出口短时间访问太多，等一两分钟，或用手机热点打开。

### 5.2 ★★★★ 我有 DeepSeek 网页版账号，还要 API Key 吗

**要**。网页版聊天和 API 是两套东西。Claude Code 用的是 API Key，按 token 计费，需要单独充值。会员或网页版余额不能用在这里。

### 5.3 ★★★ 充值多少、怎么付

**解决**：在平台充值页查看可选支付方式，按自己的预算小额充值，再根据平台显示的实际消耗补充。套餐与单价见[《模型平台套餐与官方链接》](/materials/2026-autumn/w01/model-plans)。
最低充值金额和新用户赠送额度以账户页面为准，不要把赠送额度视为固定可用预算。
**价格提醒**：DeepSeek 按峰谷计价，北京时间周一至周五 9:00–12:00、14:00–18:00 是高峰，单价是其他时段的两倍。作业尽量放晚上或周末做。

### 5.4 ★★★★★ 创建 API Key，且它只显示一次

**位置**：<https://platform.deepseek.com/api_keys>。
**步骤**：进入「API keys」，按页面提示创建密钥；按钮名称以当前页面为准。
**坑**：Key 以 `sk-` 开头，**只在创建时完整显示这一次**，关掉窗口就再也看不到。
**解决**：先打开记事本，再点创建，立刻把 Key 粘到记事本里。丢了就删掉这个 Key 重新建一个，旧的作废。

### 5.5 ★★★ Key 粘不进 CC Switch 或终端

**解决**：在网页上点 Key 旁边的复制小图标，不要手动选中复制（容易少字符）。终端里粘贴见 0.4。粘完检查开头是 `sk-`、末尾没有多余空格。

### 5.6 ★★★ Key 保密

**原因**：Key 是明文存在 `~/.claude/settings.json` 里的。谁拿到 Key 谁就能花你的钱。
**解决**：不要发到群里、不要截图发别人、不要提交到 GitHub。怀疑泄露就到平台删掉重建。有条件的话在平台开余额预警。

---

## 6 CC Switch

### 6.1 ★★★★★ 安装包从哪里拿：飞书群，不要自己去 GitHub

**症状**：GitHub Releases 页面下载几乎不动。
**原因**：2026 年 9 月 7 日实测 GitHub Release 下载只有 53 KB/s，100 人同时下会有人失败。
**解决**：老师在飞书群里发安装包。文件名：Windows 是 `CC-Switch-v3.20.1-Windows.msi`，Mac 是 `CC-Switch-v3.20.1-macOS.dmg`。

要自己下的话，只认两个官方入口：<https://github.com/farion1231/cc-switch/releases> 和 <https://ccswitch.io>。CC Switch 是免费开源软件，任何要你付费、充值或输入账号密码的「CC Switch」网站都是假冒。

### 6.2 ★★ 安装时被拦截

**Windows**：可能被 SmartScreen 拦一下，点「更多信息」→「仍要运行」（0.6）。
**macOS**：v3.20.1 已通过苹果签名和公证，双击即可打开。网上旧教程说会提示「未知开发者」是旧版本的情况。真弹了按 1.7 处理。

### 6.3 ★★★★★ 在 CC Switch 里接 DeepSeek 的步骤

按钮名称与位置可能随版本变化，以当前界面及课堂演示为准。操作流程：

1. 打开 CC Switch，顶部应用栏选 **Claude Code**。
2. 点右上角「+」（添加供应商），在预设供应商列表里选 **DeepSeek**。**不要选 default**。
3. 把你的 DeepSeek API Key（`sk-` 开头，见 5.4）粘进 API Key 框。
4. 把模型名改成带 `[1m]` 的版本（见 6.4，这一步预设是错的）。
5. 点「启用」。
6. 打开一个新终端，输入 `claude`，说「你好」，有回复且没让登录即成功。

### 6.4 ★★★★ 隐性坑：预设模型名缺 `[1m]`，上下文被砍短但不报错

**症状**：能正常对话，但很快提示上下文满、要压缩，或长任务做到一半忘了前面。不报任何错。
**原因**：CC Switch 内置 DeepSeek 预设写的模型名是 `deepseek-v4-pro`，DeepSeek 官方文档给 Claude Code 用的是 `deepseek-v4-pro[1m]`。`[1m]` 后缀表示请求 1M 上下文版本，不加就只有默认大小。
**解决**：在 CC Switch 的 DeepSeek 供应商配置里，把三个字段手动改成：

| 字段 | 值 |
|:--|:--|
| `ANTHROPIC_MODEL` | `deepseek-v4-pro[1m]` |
| `ANTHROPIC_DEFAULT_OPUS_MODEL` | `deepseek-v4-pro[1m]` |
| `ANTHROPIC_DEFAULT_SONNET_MODEL` | `deepseek-v4-pro[1m]` |
| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | `deepseek-v4-flash`（保持不变） |

改完重新点「启用」，模型名以 DeepSeek 官方接入文档为准。

### 6.5 ★★ 模型名大小写

**症状**：CC Switch 启用后连接一直报错。
**原因**：从网页复制的模型名可能被改成全小写或多了空格，与服务端不匹配。
**解决**：逐字核对 `deepseek-v4-pro[1m]` 和 `deepseek-v4-flash`，重新生成 Key 再试一次。老版本 CC Switch 卸载后装 v3.20.1。

### 6.6 ★★ 点「打开终端」一直让选文件夹

**解决**：不需要通过 CC Switch 启动终端。配好并「启用」后，直接按 0.1 打开 PowerShell/终端输入 `claude`。CC Switch 只是配置管理器。

### 6.7 ★★★★ 启用了，但 `claude` 还是弹登录 / 还是连不上

**症状**：CC Switch 显示已启用 DeepSeek，终端里 `claude` 仍要求登录，或报 401。
**原因**：CC Switch 没写进配置，或者配置被别的东西覆盖了（7.2）。
**解决**：
1. 关掉终端重开再试。
2. 打开 `~/.claude/settings.json`（Windows 在 `C:\Users\<用户名>\.claude\settings.json`），看 `env` 块里是否有 `ANTHROPIC_BASE_URL` 为 <https://api.deepseek.com/anthropic>、`ANTHROPIC_AUTH_TOKEN` 为你的 Key。没有就回 CC Switch 重新点「启用」。
3. 有 `ANTHROPIC_API_KEY` 这一项的话，见 7.2。
4. 在 `claude` 会话里输入 `/status`，看当前生效的 Base URL 和模型。

### 6.8 ★ 「未找到可用的模型列表端点，请检查 Base URL」

**症状**：保存供应商时弹这个警告。
**原因**：CC Switch 保存时会探测 `/v1/models` 接口，有些端点不提供。阿里云百炼文档明确说这个提示可以忽略；DeepSeek 预设自带模型列表地址，一般不出现。
**解决**：忽略，直接启用测试。

### 6.9 ★ CC Switch 到底改了什么

它把供应商配置写进 `~/.claude/settings.json` 的 `env` 块，自己的数据存在 `~/.cc-switch/`（数据库、自动备份）。不设系统环境变量。所以不装 CC Switch、手写这个文件也能达到同样效果——但对无编程基础的同学，点按钮比改 JSON 稳。

---

## 7 接通后的问题

### 7.1 ★★★★ `401` / `Authentication Fails, Your api key: ****xxxx is invalid` / `authentication_error`

**症状**：`claude` 里发消息后报 401。
**原因**：按可能性排序：Key 复制不全或有空格；Key 已在平台删除；填错字段（用了 `ANTHROPIC_API_KEY` 而不是 `ANTHROPIC_AUTH_TOKEN`）；旧配置残留把新配置盖掉了（7.2）。
**解决**：
1. 回 CC Switch 重新粘一遍 Key，点「启用」，重开终端。
2. 到 <https://platform.deepseek.com/api_keys> 确认这个 Key 还在。
3. 打开 `~/.claude/settings.json` 检查 `env` 块，认证字段必须是 `ANTHROPIC_AUTH_TOKEN`。
4. 仍 401 就删 Key 重建。

### 7.2 ★★★★ 隐性坑：`settings.json` 里的 `env` 会覆盖终端设的变量；`ANTHROPIC_API_KEY` 压过一切

**症状**：照着教程在终端里 `export` 或 `$env:` 设了变量，`claude` 却像没看见一样；或者明明配了 DeepSeek，却在连别的地方。
**原因**：Claude Code 读配置的规则是：`~/.claude/settings.json` 的 `env` 块**优先于**终端环境变量，同名时以文件为准。另外只要设了 `ANTHROPIC_API_KEY`（不论在文件还是终端），它会压过其他认证方式。之前装过别的教程、用过别的模型的电脑，最容易留下这种残留。
**解决**：
1. 打开 `~/.claude/settings.json`，`env` 块里只保留 CC Switch 写的 DeepSeek 那几项。看到 `ANTHROPIC_API_KEY` 就删掉这一行，认证字段用 `ANTHROPIC_AUTH_TOKEN`。
2. 改完重开终端，`claude` 里输入 `/status` 确认 Base URL 是 <https://api.deepseek.com/anthropic>。
3. 自己不敢改 JSON 的，让助教改；改坏了见 7.13。
4. 终端里之前 `export` 过的变量，文件里设成空字符串 `""` 可以让它失效（无法通过文件直接删除终端变量）。

### 7.3 ★★★★ 隐性坑：昨天能用，今天打开又要登录 / 又连不上

**症状**：上次课配好了，重启电脑或换个终端窗口后 `claude` 又弹登录或报 401。
**原因**：如果上次是在 PowerShell 里用 `$env:ANTHROPIC_BASE_URL=...` 这类命令配的，`$env:` 只在当前窗口有效，关掉窗口配置就没了。Mac 的 `export` 同理。
**解决**：正解是把配置写进 `~/.claude/settings.json`，这样每次启动都生效。CC Switch 干的就是这件事，所以本课程用 CC Switch 配，不在终端里手敲变量。已经在终端里设过的，去 CC Switch 点一次「启用」即可覆盖。

### 7.4 ★★★ 一直 `Retrying...` / `403` / `Your API key has expired`

**解决**：逐项排查：
1. 确认用的是自己创建的真实 Key（不是教程里的示例 Key），账户有余额。到 DeepSeek 平台看余额和用量。
2. 关掉代理/梯子，重开终端（0.9）。
3. 在 CC Switch 里核对 Key、Base URL、模型名。
4. 换网络（手机热点）试一次，排除校园网问题。

### 7.5 ★★ `429` / 限流 / 请求过于频繁

**症状**：发消息后报 429 或 rate limit 相关文字。
**原因**：可能触发并发或账户速率限制；具体额度与恢复时间以平台提示为准。
**解决**：等几十秒重试。反复出现就把主模型临时换成 `deepseek-v4-flash`（在 CC Switch 里改 `ANTHROPIC_MODEL`）。

### 7.6 ★★★ 模型名写错：`deepseek-chat ... may not exist`，或者「模型好笨」但不报错

**症状**：报模型不存在；或者没报错，但回答质量明显差。
**原因**：`deepseek-chat` 是已停用的旧名字。更隐蔽的是：DeepSeek 端点收到不认识的模型名时**不报错**，静默降级到 `deepseek-v4-flash`。
**解决**：模型名只有两个合法值：主模型 `deepseek-v4-pro[1m]`，Haiku 槽位与子智能体 `deepseek-v4-flash`。在 CC Switch 里逐字核对（6.4），在 `claude` 里输入 `/status` 查看当前模型。

### 7.7 ★★★ 上下文很快就满 / 频繁提示压缩

**原因**：最常见是缺 `[1m]` 后缀（6.4）。其次是对话太长。
**解决**：先按 6.4 改模型名。日常用法：换一个任务就输入 `/clear` 清空重来；同一任务想继续但快满了，用 `/compact` 压缩，它会保留关键信息和计划。上下文越长，每一轮重发的 token 越多，费用也越高，勤 `/clear` 省钱。

### 7.8 ★★★ 把截图发给它，它说看不见 / 回答文不对题

**症状**：粘贴截图或图片路径，模型回复像没收到图。
**原因**：DeepSeek V4-Pro 是纯文本模型，Claude Code 发图片时它只收到一个 `[Image #1]` 占位符。
**解决**：把报错**文字**复制进去，不要截图。要让 AI 看某个文件，直接告诉它文件路径让它自己读。

### 7.9 ★★ `API Error 400 ... unknown variant 'system'`

**症状**：发消息后报 400，报错里有 `unknown variant 'system'`。
**原因**：可能与模型端点和工具版本之间的消息格式兼容性有关，需要结合当前版本排查。
**解决**：先运行 `claude --version` 记下版本，把报错和版本号发给助教，确认后再调整版本。

### 7.10 ★★ 长任务超时 / `Connection closed mid-response`

**原因**：复杂任务响应时间长；代理软件会在中途掐断长连接。
**解决**：检查代理与网络设置（0.9）。把任务拆小、分阶段做；仍超时请联系助教。

### 7.11 ★★★ 每做一步都问我 Yes/No

**症状**：Claude Code 改文件、跑命令前都要我确认。
**原因**：第一次会话的默认权限模式，正常现象。每次都问是为了让你看到它在做什么。
**解决**：选 Yes 继续。按 Shift+Tab 可切换权限模式。**不要**用 `--dangerously-skip-permissions` 或 `bypassPermissions` 模式，零基础加绕过所有确认等于事故。

### 7.12 ★★ 我在用哪个模型、哪个 Key？怎么确认

**解决**：在 `claude` 会话里输入 `/status`，能看到当前的 Base URL、模型和加载了哪些设置文件。在普通终端（不是 `claude` 里面）运行 `claude doctor`，会列出安装健康状况和设置文件里被拒绝的配置项。

### 7.13 ★★ 改了 `settings.json` 之后 Claude Code 起不来 / `Settings Error`

**症状**：手改配置文件后启动报错。
**原因**：设置文件是严格 JSON：不能写 `//` 注释，最后一项后面不能有逗号，引号必须成对。
**解决**：先把 API Key 等敏感值替换为占位符，再把配置内容和报错发给 AI 检查 JSON 语法；不确定时请助教协助。也可以回 CC Switch 重新点「启用」，再检查配置是否恢复。

### 7.14 ★ 终端里中文乱码

**解决**：多数是终端窗口尺寸或字体渲染问题，拖大窗口或重开终端。反复出现的话装 Windows Terminal（0.4）。

### 7.15 ★ 报错手册里没有

按文档开头的提问模板问 AI。三轮之内还没解决，精简成一句话（系统 + 做什么 + 报什么错 + 已试什么）发群里或找助教。

---

## 8 VS Code

### 8.1 ★★★ 官网下载慢或打不开

**症状**：`code.visualstudio.com` 下载按钮点了没反应，或速度很慢。
**原因**：偶发。2026 年 9 月 7 日实测官方下载链路（`vscode.download.prss.microsoft.com`）在国内 23 MB/s，正常情况下不需要镜像。
**解决**：用下面的直链，它们永远指向最新稳定版：

| 平台 | 直链 |
|:--|:--|
| Windows x64（多数同学） | <https://update.code.visualstudio.com/latest/win32-x64-user/stable> |
| macOS Apple Silicon（M 芯片） | <https://update.code.visualstudio.com/latest/darwin-arm64/stable> |
| macOS Intel | <https://update.code.visualstudio.com/latest/darwin/stable> |
| macOS 通用包 | <https://update.code.visualstudio.com/latest/darwin-universal/stable>（未经本课程实测，请联系助教确认适用版本） |
| Windows ARM64 | <https://update.code.visualstudio.com/latest/win32-arm64-user/stable>（未经本课程实测，请联系助教确认适用版本） |

网上流传的「把域名换成 `vscode.cdn.azure.cn`」技巧，在 2026 年 9 月 7 日实测已不可用，不要照抄。实在下不动，向老师要安装包。

### 8.2 ★★ 已经装过 VS Code，要不要重装

**解决**：不用删，直接升级：菜单「帮助 → 检查更新」。VS Code 通常会自动更新。

### 8.3 ★★ 扩展安装失败、一直转圈或超时

**症状**：扩展面板（Ctrl+Shift+X，Mac 是 Cmd+Shift+X）点 Install 后卡住。
**原因**：扩展市场在国内能连上但慢，100 人同时装同一个扩展容易超时。
**解决**：
1. 等一会儿再点一次；完整退出 VS Code 再开。
2. Windows 上右键 VS Code 图标 →「以管理员身份运行」再装。
3. 仍失败：进入 `C:\Users\用户名\.vscode\extensions\`，删除 `.obsolete` 文件和对应扩展的残留文件夹后重试。
4. 离线安装：向老师要 `.vsix` 文件，扩展面板右上角「…」→「Install from VSIX...」选文件；或在终端运行 `code --install-extension 文件路径.vsix`。
   中文语言包直链：<https://marketplace.visualstudio.com/_apis/public/gallery/publishers/MS-CEINTL/vsextensions/vscode-language-pack-zh-hans/latest/vspackage>
   注意：下载到的文件是 gzip 压缩过的，多数情况 VS Code 能直接装；报错的话需要先解压一次再改回 `.vsix` 后缀。

### 8.4 ★★★ 装了 VS Code 的 Claude Code 扩展，终端里却 `claude` 不存在

**症状**：扩展面板里能看到 Claude Code 聊天面板，但在终端输入 `claude` 报找不到命令。
**原因**：扩展自带一份私有 CLI 供聊天面板使用，不会加入 PATH。终端里要用 `claude`，必须另外用 npm 装 CLI（第 4 节）。
**解决**：按第 4 节装 CLI。两者共用同一份 `~/.claude/settings.json`，所以 CC Switch 配好 DeepSeek 后扩展和终端都能用。

### 8.5 ★★ VS Code 里的 Claude Code 扩展一直要求登录

**症状**：终端里的 `claude` 已接上 DeepSeek，但 VS Code 扩展面板还是弹「Sign in」。
**原因**：扩展面板走的是 Claude 官方账号登录；本课程不登录官方账号。如果你是在终端里用 `$env:` 临时设的变量，VS Code 不会继承。
**解决**：本周只用终端里的 `claude`，不用扩展的聊天面板。配置写进 `settings.json`（CC Switch 干的就是这事）之后，两边共用；仍弹登录就从终端用 `code .` 启动 VS Code 再试。