尚硅谷 Vibe Coding｜第三章(4) Claude Code深度使用与进阶技巧-常见问题排查，三种模式，案例实操

自传.

206人浏览 · 2026-07-01 16:00:53

自传. · 2026-07-01 16:00:53 发布

3.7 Claude Code 常见问题与排查（FAQ）

3.7.1 安装类问题

Q1：安装时报 ENOENT: no such file or directory

根因：npm 本地缓存文件损坏

修复方案：执行 npm cache clean --force 清理缓存，重新执行安装命令

Q2：安装成功，但终端输入 claude 提示命令不存在

根因：npm 全局安装目录未写入系统 PATH 环境变量

修复方案：运行 npm config get prefix 获取全局路径，将输出路径添加至系统 PATH

Q3：Windows 终端提示「无法加载文件，因为在此系统上禁止运行脚本」

根因：PowerShell 默认执行安全策略拦截脚本

修复方案：右键以管理员身份打开 PowerShell，执行 Set-ExecutionPolicy RemoteSigned

3.7.2 连接 / API 类问题

Q4：启动提示 Invalid API Key

根因：API Key 填写错误、密钥过期、环境变量未生效

修复方案：

核对环境变量 ANTHROPIC_API_KEY 是否正确配置；

Mac/Linux 验证命令：echo $ANTHROPIC_API_KEY；

Windows PowerShell 验证命令：echo $env:ANTHROPIC_API_KEY。

Q5：配置中转代理后出现连接超时

根因：中转服务地址填写错误、代理服务离线 / 不可访问

排查方向：核对代理地址、端口、鉴权配置，测试中转服务连通性

解决：

核对环境变量 ANTHROPIC_BASE_URL 配置是否正确

浏览器访问中转地址，确认服务正常运行

使用 curl 命令直接测试 API 连通性

Q6：提示 Rate limit exceeded

原因：短时间请求量超出密钥限流配额

解决：等待 1 分钟后重试；若频繁触发，升级 API 付费套餐

3.7.3 使用类问题

Q7：AI 修改了不该改动的文件

原因：需求描述模糊，AI 自行扩大修改范围

解决：

执行 git checkout . 撤销全部变更

重新下发需求，明确限定仅修改指定文件

在 CLAUDE.md 中写入文件禁区规则，永久拦截

Q8：AI 陷入「改 A 破坏 B、改 B 破坏 A」循环

原因：单次上下文缺少全局视角，修复一处缺陷引入新 bug

解决：

git checkout . 回退至稳定代码版本

执行 /clear 清空历史对话

一次性完整描述需求与全部约束，让 AI 全局统筹修改

Q9：对话过长 AI 遗忘早期需求

原因：上下文 token 窗口接近满载，早期内容被截断

解决：执行 /compact 压缩对话历史，或新建干净会话

Q10：AI 编造不存在的 npm 包、API 接口

原因：模型幻觉，生成未真实存在的代码依赖

解决：使用 AI 给出的包 / 接口前，前往 npmjs.com 检索核验是否真实存在

3.7.4 费用类问题

Q11：费用消耗过快

原因：当前使用高价 Opus 模型，或是对话上下文过长、token 持续累积

解决方案：

执行 /cost 指令查看当前会话费用明细

切换成本更低的模型降低单价

精简对话，减少无效轮次，定期用 /compact 压缩上下文

Q12：中转服务计费规则说明

计费逻辑：按实际消耗 Token 数量计费

终端单价 = Anthropic 官方基础单价 × 中转服务倍率

倍率区间：市面中转倍率普遍在 1.0x ~ 1.5x

提示：各中转服务商定价存在差异，以对应平台价格页面为准。

3.8 自定义斜杠命令（Custom Slash Commands）

一、功能说明

可自定义斜杠快捷指令，把高频标准化操作封装成一键执行脚本，简化重复操作。

二、创建目录与文件

在项目根目录新建文件夹：.claude/commands/

在该目录新建 Markdown 文件，文件名即为斜杠指令名

示例文件路径：.claude/commands/date.md

自定义的触发命令，放在cmmands文件夹下，仅对当前项目起效。如果想要全局，需要放在根目录下。

项目	commands/xxx.md（你的 date.md）	skills/xxx/（标准 Skill）
存放位置	.claude/commands/ 单 md 文件	.claude/skills/ 独立文件夹
触发方式	手动输入 /date 主动调用	两种触发：①手动 /xxx；②自然对话匹配自动激活，不用打斜杠
结构	仅 1 个 md，文件名就是命令名	文件夹 + SKILL.md，可附带脚本、模板、配置文件
用途	高频简短提示词快捷入口（查日期、生成注释、提交文案）	完整复杂工作流、领域能力（代码审计、需求拆解、规范校验）
归属关系	新版文档说明：Commands 已被整合进 Skills 大体系，是轻量版 Skill	完整模块化 Skill，权限 / 工具配置更丰富

3.9 Claude Code 使用模式：Plan Mode 与三种权限模式

前置说明

新手常见疑问：使用 Claude Code 应当先整体规划再执行，还是分模块逐步修改？

官方方案：内置 Plan Mode（规划模式），属于原生只读运行模式，并非提示词技巧，支持快捷键 / 斜杠命令随时切换，模式下 AI 仅能分析，无法修改代码。

3.9.1 三种官方互斥运行模式

模式	核心行为	适用场景	状态栏标识
Normal（默认模式）	每一次文件修改、命令执行均需手动确认	日常小需求、需要逐行审查变更	无特殊标记
Auto-Accept（自动接受）	跳过弹窗确认，直接执行放行列表内操作	已完整规划的批量任务、可信标准化操作	accept edits on
Plan Mode（规划模式）	仅只读检索，仅可分析代码、提问、输出改造方案，禁止任何修改写入	复杂重构、陌生代码库、架构方案评审	plan mode on

3.9.2 Plan Mode 能力边界

该模式仅能调用全部只读工具，禁用文件编辑、写入、高危 bash 修改类命令，仅用于前置方案勘探，无破坏性操作风险。

工具名	功能说明
Read	读取查看文件完整内容
Glob	通过通配符模式批量检索匹配文件
Grep	正则匹配检索文件内文本内容
LS	列出目录下文件与文件夹结构
WebSearch / WebFetch	联网检索、拉取网页参考资料
Task	启动只读子代理，执行大范围调研任务
AskUserQuestion	向用户提问、给出选项澄清需求边界

写入 / 修改文件、执行 Shell 命令、运行单元 / 集成测试、文件删除、代码提交推送等。

保障在你确认改造方案前，AI 不会改动项目任意代码，零误操作风险。

3.9.3 四种进入 Plan Mode 的方式

1.快捷键：Shift+Tab 连按两次（Windows 部分终端替代：Alt+M）

2.斜杠命令：/plan（Claude Code v2.1.0+）

3.启动参数：claude --permission-mode plan

4.全局永久配置：.claude/settings.json 设置 permissions.defaultMode = "plan"

方式一：键盘快捷键（最常用，临时切换）

连续敲击 Shift + Tab 循环切换三种模式：

第一次 Shift+Tab → Auto-Accept 自动模式，状态栏显示 accept edits on

第二次 Shift+Tab → Plan Mode 规划模式，状态栏显示 plan mode on

第三次 Shift+Tab → 切回 Normal 默认模式

Windows 终端兼容提示

部分 PowerShell 终端配置下，Shift+Tab 只能在 Normal / Auto-Accept 切换，无法进入 Plan Mode，改用快捷键 Alt + M 直接切入规划模式，该问题为官方已知兼容问题。

方式二：会话内斜杠命令（中途临时切换）

版本要求：Claude Code v2.1.0 及以上

在对话输入框执行：

> /plan

会话立刻切换至 Plan Mode，适合聊天到中途，临时需要整体梳理代码、做方案规划的场景。

方式三：启动命令直接进入 Plan Mode

适用于提前确定本次是复杂调研、重构任务，启动会话时直接切入只读规划模式，分两种使用场景：

1. 交互式终端会话

claude --permission-mode plan

2. 无头模式（CI 流水线、自动化脚本调用）

claude --permission-mode plan -p "分析认证模块并提出优化建议"

方式四：配置为项目永久默认模式

若该项目长期需要「先规划、再修改」流程，修改项目根目录 .claude/settings.json，设置全局默认权限模式：

{

  "permissions": {

    "defaultMode": "plan"

  }

}

配置生效规则：在该项目目录下任意执行 claude 启动会话，会自动进入 Plan Mode，无需每次手动切换

3.9.4 推荐完整标准工作流（复杂重构 / 新功能开发）

完整执行步骤

启动进入规划模式

claude --permission-mode plan

阶段 1：Explore 代码勘探

指令示例：读一下 src/auth 目录，梳理现有完整认证逻辑

作用：AI 仅只读检索，摸清目录结构、业务逻辑、现有边界。

阶段 2：Plan 方案输出

指令示例：输出完整改造计划，列明需修改文件、执行顺序、全部边界异常场景

作用：AI 输出完整变更方案，你人工审核、反复沟通打磨至方案满意。

切换执行模式

快捷键 Shift+Tab 切换至 Auto-Accept 自动放行模式，退出 Plan Mode。

阶段 3：Implement 落地实现

指令示例：按照上面确认好的完整改造计划执行代码修改

阶段 4：Commit 规范提交

指令示例：生成标准化commit描述并完成提交

实践建议

复杂业务重构、陌生代码库开发，务必从 Plan Mode...

3.9.5 何时启用 Plan Mode、何时不用

核心判断准则

一句话判定：能用一句话描述完整变更 diff 就不用规划；需求模糊、改动范围不可控，优先开 Plan Mode

兜底原则：分不清场景时，使用 Plan Mode 更安全，无代码误改风险。

任务类型	推荐模式	选用原因
新项目从零搭建	Plan Mode 优先	需要整体架构全盘考量
新增复杂功能（认证、订阅、软删除等）	Plan Mode 优先	改动牵连文件多，回滚成本极高
修复单一、定位明确的 Bug	Normal 默认模式	修改范围清晰，目标确定
简单修改：函数重命名、变量调整	Normal 默认模式	变更 diff 一句话即可说清
大型跨文件重构、模块迁移	Plan Mode 优先	必须提前评估全量影响范围
已有成熟方案，批量生成相似代码	Auto-Accept 自动模式	方案已确认，执行阶段避免频繁弹窗打断
阅读、梳理陌生新项目代码库	Plan Mode	纯只读调研场景，禁止任何写入操作

总结使用逻辑

简单小需求直接 Normal 快速处理；

复杂、大范围、未知代码库任务，先 Plan Mode 勘探出完整方案，审核通过再切 Auto-Accept 执行落地。

3.9.6 混合模型策略：Opus Plan + Sonnet Implement

一、参数别名 --model opusplan 机制

执行命令：

claude --model opusplan

该参数会自动分阶段切换模型，实现分层算力成本优化：

1.规划阶段（Plan）：使用 Opus 模型

优势：推理、架构分析、复杂逻辑推演能力更强；短板：单价更高、消耗 token 费用贵。

2.落地实现阶段（Implement）：自动切换 Sonnet 模型

优势：代码生成速度快、单位 token 计费更低，适合批量文件修改、代码填充等重复性编码工作。

二、策略定位

核心思路：高价强推理模型做方案思考，低价高效模型执行编码落地。

专为大型重构、复杂新功能开发等高成本任务设计，在保证方案严谨完整的前提下，大幅降低整体 token 消耗费用。

3.9.7 快捷决策树

3.10 案例实操：Web 记账工具（finance-cli）—— 热身练习

正式项目前，补充VS code安装，集成CLAUDE CODE，使用VS Code进行项目开发。

下载地址：https://code.visualstudio.com/

下载后进行安装即可，

切换成简体中文，下载后右下角重启即可

安装Claude code

可能会有一个登入页面，让你登入官方的网站，但是我们已经全局配置了，因此过一会加载完之后自动就会消失。

提问什么模型，可以正常回答，说明之前配置是生效的

3.10.1 项目简介

项目说明

本项目为使用 Claude Code 从零搭建的 Python Web 小型项目。在学习复杂商城项目前，可通过本案例熟悉完整开发流程与 /plan 规划模式使用方法。

核心业务功能

搭建带网页可视化界面的记账工具，浏览器端完成收支记录、数据统计，功能清单：

添加账目：表单录入金额、收支分类、日期、备注信息

记录列表查询：支持按月份、收支分类筛选，表格展示全部流水

分类数据统计：柱状可视化图表 + 汇总统计表

单条记录删除：输入记录 ID 即可完成删除

技术栈

Python + Streamlit（纯 Python Web 可视化框架）+ sqlite3（Python 内置零配置轻量数据库）

选型优势：Streamlit 仅依靠 Python 代码即可生成完整网页，无需学习 HTML/CSS/JavaScript。

完整项目目录结构

项目总文件仅 4 个，代码总量不足 350 行

finance-cli/

├─ pyproject.toml          # 项目配置、依赖包声明文件

└─ finance/                # Python业务包目录

   ├─ __init__.py          # 空文件，标识文件夹为Python包

   ├─ models.py            # 数据实体类定义（dataclass）

   ├─ database.py          # SQLite库：建表、增删改查、统计查询逻辑

   └─ web.py               # Streamlit 网页入口主程序

3.10.2 详细步骤-0基础也可完成

第0步：创建文件及文件夹

先创建3个文件夹/文件，

1.finance_cli

2.finance_cli/.claude

3.复制之前的setting.local.json文件

第1步：用/plan做架构设计

使用VS code打开对应项目文件夹，切换成/plan模式，

切换高级模型，高级模型做规划，低级模型写代码

输入以下提示词

我要做一个 Python web 记账工具，功能包括：

- 添加账目（金额、分类、日期、备注）——在网页表单里填写

- 查看列表（按月份和分类筛选）——表格展示

- 删除账目——输入 ID 删除

- 分类统计--柱状图 + 统计表

技术栈用 Python + streamlit + sqlite3。

预设 6 个分类：餐饮、交通、购物、娱乐、居住、其他。

我是编程新手，请先出方案再动手。

会给一些方案，可以选择适当的方案，或者不满意，也可以直接和它对话，提示词（所有的代码都在一个app.py中，不利于后续的管理和查看，请对代码进行模块化的拆分划分成不同的文件。）