企业官网建设流程全解析

本教程面向初次接触 AI 编程助手的开发者，涵盖安装、认证配置、多种使用方式、终端技巧、Skills 自定义，以及常见问题解答。Wiki 风格编写，可按章节跳转。

本文适合谁

• 第一次听说 Claude Code，想从零跑通
• 已安装但卡在 API Key、Base URL、401/404 报错
• 想系统了解终端斜杠命令、/唤醒 Skill、CC Switch 多 Provider 切换

你将学到什么

• 如何安装 Claude Code 并做健康检查
• 三种认证方式如何选择（官方登录 / CC Switch / 手动 settings.json）
• 终端、VS Code 插件、Desktop 等多种用法
• 斜杠命令与 Skills 的入门与自定义
• 常见报错的排查步骤

目录

1. 简介

本章目标：理解 Claude Code 的定位，知道它适合解决什么问题。

Claude Code 是什么？

Claude Code 是 Anthropic 推出的AI 编程助手，运行在本地终端（或 VS Code 等 IDE）中。与普通网页聊天不同，它会在当前项目目录下工作：读取文件结构、分析代码、修改 Bug、生成页面、写测试、产出文档。

一句话对比：

典型使用场景

1. 分析陌生项目的目录结构和技术栈
2. 阅读并解释某段代码的逻辑
3. 生成前端页面或 API 接口代码
4. 定位并修复 Bug
5. 重构函数或组件
6. 编写 README、测试用例
7. 提交前做代码审查（/code-review）

官方文档

最新安装方式、环境变量、命令列表以官方为准：

• 文档首页：Overview - Claude Code Docs
• 设置说明：Claude Code settings - Claude Code Docs
• 环境变量：Environment variables - Claude Code Docs
• 命令参考：Commands - Claude Code Docs

2. 安装与环境检查

本章目标：在本机安装 Claude Code，确认claude命令可用。

前置条件

Claude Code 通过 npm 全局安装，需要先安装Node.js（自带 npm）。

检查版本：

node -v npm -v

若能正常输出版本号（建议 Node.js 18+），即可继续。

安装

npm install -g @anthropic-ai/claude-code

验证安装

claude --version

进入交互界面：

claude

成功标志：出现 Claude Code 的输入提示符，可输入自然语言或/命令。

健康检查（安装后第一件事）

在交互界面输入：

/doctor

或在终端直接运行：

claude doctor

/doctor会检查安装、配置、网络等项，并按状态图标列出结果。有问题时可按f让 Claude 尝试自动修复。

Windows 用户注意

若提示claude 不是内部或外部命令：

1. 确认 Node.js 和 npm 已安装
2. 查看 npm 全局路径：npm config get prefix
3. 将该路径下的bin（或 Windows 下的根目录）加入系统PATH
4. 关闭并重新打开PowerShell 或终端

若经常做开发，也可考虑在WSL中安装，行为更接近 Linux/macOS 环境。

更新到最新版

npm update -g @anthropic-ai/claude-code

更新后可在会话内运行/release-notes查看变更，再运行/help确认新命令是否可用。

3. 认证方式对比

本章目标：选择适合自己的登录/接入方式，避免在 Key 和 Base URL 上反复踩坑。

Claude Code 需要能访问 Anthropic 模型服务。国内用户常见三种配置方式：

新手推荐路径

建议按此顺序操作，15 分钟内可完成首次跑通：

1. 完成 第 2 章 安装，运行/doctor
2. 有 Claude 订阅→ 进入 第 4 章 使用/login
3. 无订阅、使用第三方 API→ 进入 第 5 章 安装 CC Switch 添加 Provider
4. 熟悉后如需细调，再阅读 第 6 章 了解底层配置文件

4. 方式 A：官方登录

本章目标：使用 Anthropic 官方账号订阅，无需手写 API 配置。

操作步骤

1. 在终端进入任意目录，运行claude

2. 输入/login，或在启动引导中选择登录

3. 按提示在浏览器中完成 Anthropic 账号授权

4. 返回终端，发送测试消息：

   请用一句话回复：Claude Code 已正常工作。

成功标志：收到正常回复，且/doctor无认证相关报错。

相关命令

说明

• 官方登录不需要配置ANTHROPIC_BASE_URL或ANTHROPIC_AUTH_TOKEN
• 若同时使用 CC Switch 或 settings.json，注意避免 env 变量冲突；一般选一种主认证方式即可

5. 方式 B：CC Switch

本章目标：用 CC Switch 可视化管理 API Provider，适合第三方 API 与多模型切换。

CC Switch 是什么？

CC Switch 是一款开源桌面应用，统一管理 Claude Code、Codex、Gemini CLI、OpenCode 等 AI 编程 CLI 的 Provider 配置。源码：https://github.com/farion1231/cc-switch

为什么值得学：

• 不用手改 JSON，降低填错 Base URL 的概率
• 内置 50+ Provider 预设，也可自定义
• Claude Code 支持热切换：切换 Provider 后通常无需重启终端（其他 CLI 多数需重启）
• 可统一管理 MCP、Skills、Prompts、会话与用量统计

安装

1. 打开官网：CC Switch 官方网站 - AI 编程 CLI 统一管理工具
2. 进入 Releases 下载对应系统安装包（Windows / macOS / Linux）
3. 按安装向导完成安装（macOS 推荐.dmg，已签名公证）

首次使用流程

1. 启动 CC Switch，在 Claude Code 工具页点击「添加 Provider」
2. 选择内置预设（如你的 API 中转平台）或「自定义」
3. 填入：
   • API Key（如sk-xxxxxxxx，勿泄露真实 Key）
   • Base URL（以 Provider 文档为准，见 Base URL 陷阱）
   • 模型名称（从平台后台复制完整 ID，不要猜claude或sonnet）
4. 保存后，将该 Provider设为当前生效
5. 打开终端，进入测试目录，运行claude，发送一句话测试

成功标志：Claude Code 正常回复，CC Switch 中可见请求/用量（若已开启统计）。

[待补图：CC Switch 添加 Provider 界面]

进阶功能（入口即可）

与手动 settings.json 的关系

CC Switch 会将 Provider 信息写入 Claude Code 使用的配置（如~/.claude/settings.json或相关 env）。若你曾手改文件，可在 CC Switch 中「从当前 Provider 提取」同步回来，避免两套配置不一致。

CC Switch 常见问题

切换 Provider 后 Claude Code 仍用旧配置？

• 确认 CC Switch 中已将该 Provider 设为当前
• Claude Code 会话若已打开，可新开终端再试；多数情况支持热切换

切换 Provider 后插件/MCP 配置丢失？

• 使用「共享配置片段」功能，创建新 Provider 时勾选「写入共享配置」

6. 方式 C：手动 settings.json

本章目标：理解底层配置文件，适合进阶用户或无法使用 CC Switch 的环境。

配置文件路径

若.claude目录不存在，可手动创建：

# macOS / Linux mkdir -p ~/.claude # Windows PowerShell New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.claude"

通用配置模板

将下列内容写入settings.json，替换为你的真实 Key 和网关地址：

{ "env": { "ANTHROPIC_BASE_URL": "https://你的-api-网关地址", "ANTHROPIC_AUTH_TOKEN": "sk-你的密钥", "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1", "CLAUDE_CODE_ATTRIBUTION_HEADER": "0" } }

示例（第三方平台，仅供参考）：部分教程（如 CSDN 国内使用指南）使用 TransAI 平台，Base URL 为https://transitai.chat。你的平台请以官方说明为准，不要照搬。

字段说明

Base URL 陷阱

不同平台对 Base URL 要求不同：

• 有的填根路径：https://api.example.com
• 有的要加/v1：https://api.example.com/v1

以你使用的 Provider 文档为准。填错常见现象：404、接口路径错误、连接失败。

验证配置

1. 保存settings.json，确认 JSON 格式正确（注意逗号、引号）

2. 关闭已打开的 Claude Code 会话，重新打开终端

3. 运行：

   mkdir claude-code-test cd claude-code-test claude

4. 输入：

   请用一句话回复：Claude Code 已经可以正常工作。

成功标志：收到正常回复。

安全提示：不要把真实 API Key 提交到 Git、发到群聊或截图公开。泄露后立即在平台后台删除并重建 Key。

7. 多种使用方式

本章目标：了解 Claude Code 在不同界面下的入口，按习惯选择终端或编辑器。

7.1 终端交互（最完整）

cd /path/to/your-project claude

在提示符下直接输入自然语言，或以/开头输入命令（见 第 9 章）。

7.2 一次性命令

claude "列出当前目录下的 Markdown 文件，并说明各自主题" claude -p "只输出项目使用的框架名称，一行即可"

适合脚本、CI 或快速查询。-p/--print用于非交互输出（具体选项以claude --help为准）。

7.3 VS Code 插件

安装：

1. 打开 VS Code，Ctrl + Shift + X打开扩展市场
2. 搜索Claude Code，安装 Anthropic 官方扩展
3. 安装后可在侧边栏或命令面板（Ctrl + Shift + P）中找到 Claude Code 入口

配置（第三方 API 时）：

在设置 → 扩展 → Claude Code（或命令面板搜索 Claude Code 设置）中填写：

成功标志：在 VS Code 中打开项目文件夹，发送「请用一句话确认已连接」，收到正常回复。

重要：VS Code 插件配置独立于终端~/.claude/settings.json。若终端能用、插件不能用，请分别检查插件内的 Key、Base URL、Model。使用 CC Switch 时，确认当前 Provider 已生效后再测插件。

7.4 IDE 集成与 Desktop

• 在 Claude Code 会话中输入/ide，查看当前 IDE 连接状态
• 已订阅且系统为 macOS/Windows 时，可用/desktop在 Claude Code Desktop 应用中继续当前会话

7.5 远程与会话迁移

8. 终端入门

本章目标：在真实项目中安全、高效地使用 Claude Code。

在项目目录中启动

Claude Code 依赖当前工作目录的上下文。请cd到项目根目录再运行：

cd my-project claude

若需额外只读目录，会话内可用/add-dir <路径>添加（配置发现仍以主项目.claude为准）。

新手推荐测试流程

不要第一次在大型生产项目上直接改代码。

第一步：空目录冒烟测试

mkdir claude-smoke-test && cd claude-smoke-test claude

帮我创建一个简单的 index.html，包含标题、输入框和按钮。

第二步：真实项目 — 先分析，后修改

cd my-real-project claude

先不要修改任何代码。请分析当前项目结构，并告诉我主要技术栈和入口文件在哪里。

确认分析准确后，再逐步授权修改：

请说明你将如何优化登录页表单布局，先给方案，不要改文件。

方案可以，请开始修改，改完后告诉我改了哪些文件。

常用 CLI 参数

会话内换模型可用/model；CLI 与斜杠命令等价关系以/help为准。

权限提示（Allow / Deny）

首次让 Claude 读文件、跑命令、改代码时，终端会询问是否允许。这是正常的安全机制：

• Allow：允许本次或按规则记住
• Deny：拒绝该操作

可在会话内用/permissions管理 allow/ask/deny 规则；项目级规则写在.claude/settings.json。

警示：在未经审核的生产仓库上，不要一次性 Allow 所有危险命令。大改动前先用/plan或「只分析不改文件」确认方案。

9. 终端技巧与斜杠命令

本章目标：掌握/命令菜单与 Skill，提升日常效率。

核心概念

命令必须出现在消息开头。/code-review 只看 src/中，/code-review后的文字会作为参数传入。

按场景常用命令

输入/help可查看当前安装版本的完整列表；更新后先/release-notes再/help。

Skill 与/的关系

• bundled Skill 示例：/code-review、/batch、/debug、/loop等，用法与自定义 Skill 相同
• 输入/skills列出所有 Skill；按t按 token 排序，Space可隐藏不在菜单中显示的 Skill
• 新增或修改~/.claude/skills/或.claude/skills/后，运行/reload-skills无需重启Claude Code

快捷键（因终端而异）

在 VS Code、Cursor 内置终端中，建议运行一次/terminal-setup以绑定 Shift+Enter。

工作流示例

新项目第一天：

/init /memory /mcp

大功能开发：

/plan 实现用户导出 CSV 功能

提交前：

/diff /code-review --fix

对话太长：

/compact 保留与认证模块相关的讨论

10. 项目级配置

本章目标：让 Claude 长期「理解」你的项目规则与权限。

CLAUDE.md

项目根目录下的项目说明书。Claude 在新会话中会读取，用于约定：

• 技术栈与目录结构
• 编码规范、测试命令
• 禁止事项（如不要改哪些目录）

生成起点：在项目根运行/init，会创建 starterCLAUDE.md，再用/memory细化。

用户级 vs 项目级配置

项目级 permissions 示例（仅示意）：

{ "permissions": { "allow": ["Read(src/**)", "Edit(src/**)"], "deny": ["Edit(.env*)"] } }

具体 schema 以官方 Settings 文档为准。

.claude 目录结构（常见）

my-project/ ├── CLAUDE.md └── .claude/ ├── settings.json └── skills/ └── my-team-skill/ └── SKILL.md

11. Skills 自定义

本章目标：创建可复用的/my-skill工作流。

什么是 Skill？

Skill 是一个文件夹 +SKILL.md文件，内含告诉 Claude如何完成某类任务的说明。与内置/code-review类似，你可以：

• 手动输入/my-skill调用
• 让 Claude 在相关场景下自动加载（除非设置了disable-model-invocation: true）

官方说明：Extend Claude with skills - Claude Code Docs

存放位置

文件夹名建议小写 + 连字符，如release-checklist。

最小示例

创建~/.claude/skills/hello-skill/SKILL.md：

--- name: hello-skill description: 用中文打个招呼并列出当前 git 分支 --- 当用户调用此 Skill 时： 1. 用中文简短问候 2. 运行 git branch --show-current 并告知当前分支 3. 不要修改任何文件

在 Claude Code 中：

/reload-skills /hello-skill

常用 frontmatter

排错 checklist

Skill 未出现在/菜单时：

1. 路径是否在skills/下且文件名为SKILL.md
2. 文件夹名是否与/命令名一致（小写、连字符）
3. 是否运行了/reload-skills
4. 运行/context查看是否有 Skill 被排除（描述过长等）

12. 常见问题 FAQ

本章目标：按现象快速定位认证、配置与使用问题。

以下每题结构：现象 → 原因 → 操作清单 → 仍不行时

401 Unauthorized

现象：请求失败，提示未授权。

原因：API Key 错误、不完整、含空格、已删除，或写入了错误配置项。

操作清单：

1. 在 CC Switch 或~/.claude/settings.json中确认ANTHROPIC_AUTH_TOKEN（或插件中的 API Key）
2. 重新从平台后台完整复制Key，粘贴后检查首尾无空格
3. 保存配置，关闭 Claude Code，重开终端再试
4. 若 Key 曾泄露，在平台删除并新建

仍不行：运行/doctor和/debug 401 问题，检查是否同时存在官方/login与 env Token 冲突。

404 或接口路径错误

现象：连接失败、404、path not found。

原因：ANTHROPIC_BASE_URL填错（多/少/v1、协议错误或域名拼写错误）。

操作清单：

1. 对照 Provider 文档确认 Base URL 格式
2. CC Switch 或 settings.json 中修正后切换/保存 Provider
3. 新开终端测试一句话回复

仍不行：用 curl 或平台提供的测试工具验证 Key + URL 是否在本机可达。

model not found

现象：提示找不到模型。

原因：模型 ID 与平台不一致；账号无该模型权限。

操作清单：

1. 登录 API 平台，从模型列表复制完整 ID（不要猜claude-sonnet简写）
2. 在 CC Switch Provider 或 VS Code 插件 Model 字段中粘贴
3. 确认账户余额与模型权限

配置不生效

现象：改了 settings.json 但行为不变。

原因：路径错误、JSON 语法错误、未重启、或被 CC Switch 覆盖。

操作清单：

1. 确认路径：~/.claude/settings.json（Windows 见 第 6 章）
2. 用 JSON 校验器检查逗号、引号
3. 关闭所有claude会话，重开终端
4. 若使用 CC Switch，在应用中确认当前 Provider并避免与手改文件冲突

终端能用，VS Code 插件不能用

现象：终端claude正常，插件无响应或报错。

原因：插件使用独立配置，未读取终端 settings.json。

操作清单：

1. VS Code 设置中单独填写 API Key、Base URL、Model
2. 保存后重载窗口（Developer: Reload Window）
3. 在插件中发送一句话测试

CC Switch 切换 Provider 无效

现象：已切换 Provider，Claude Code 仍连旧服务。

操作清单：

1. 确认 CC Switch 中该 Provider 为当前生效
2. 新开终端运行claude（Claude Code 多数情况支持热切换）
3. 检查共享配置是否写入成功

找不到某个斜杠命令

现象：文档里有/xxx，本机/help没有。

原因：Claude Code 版本过旧；或该命令仅特定计划/平台可用。

操作清单：

npm update -g @anthropic-ai/claude-code

会话内：/release-notes→/help

请求很慢或超时

现象：简单问题也等待很久。

原因：大型仓库上下文过多、网络延迟、模型繁忙。

操作清单：

1. 先用小目录冒烟测试，排除配置问题
2. 会话内/compact压缩历史
3. 用/context查看上下文占用
4. 复杂任务改用/plan分步执行

余额不足

现象：平台返回额度不足。

操作清单：登录 API 平台查看余额与调用记录；新手先用小任务验证，避免一上来分析超大 monorepo。

13. 从入门到精通学习路径

本章目标：按阶段系统提升，避免一次啃完所有高级功能。

Level 1 — 入门（第 1 天）

• [ ] 安装 Claude Code，claude --version与/doctor通过
• [ ] 完成一种认证方式（/login或 CC Switch / settings.json）
• [ ] 空目录生成简单 HTML，/clear开始新会话
• [ ] 阅读 第 8 章「先分析后修改」流程

Level 2 — 日常（第 1 周）

• [ ] 在真实仓库中只分析、不改代码，验证技术栈判断正确
• [ ] 大改动前使用/plan
• [ ] 提交前/diff+/code-review
• [ ] 配置项目CLAUDE.md（/init+/memory）

Level 3 — 进阶（第 2～4 周）

• [ ] CC Switch 配置 2 个以上 Provider 并熟练切换
• [ ] 编写 1 个个人 Skill（如发布检查清单），/reload-skills验证
• [ ] 在项目.claude/settings.json中设置 permissions
• [ ] 尝试/mcp连接一个 MCP 服务器

Level 4 — 精通

• [ ]/batch或 subagent 并行处理大范围重构
• [ ] 团队共享.claude/skills/与 CLAUDE.md 规范
• [ ] 配置 Hooks 自动化（如保存后 lint）
• [ ]/insights回顾使用习惯并优化工作流

14. 参考链接