企业官网建设流程全解析

Claude Code 是 Anthropic 推出的终端 AI 编程助手，核心使用方式是命令行，但它能做的远不止“帮你在终端里回答问题”。它可以直接读取项目文件、分析代码结构、修改文件、执行命令，并且能感知 Git 状态和会话上下文，因此在写脚本、修 bug、重构代码、生成项目文档这些场景里，比在网页对话框里复制粘贴代码要高效得多。下面的内容会围绕 Claude Code 的安装、VS Code 集成、模型接入、Skill 配置和常见报错排查展开，目标是让读者从零开始，独立完成工具安装、接入第三方模型、配置自定义 Skill，并在遇到报错时能按照明确的排查链路定位问题。

实际使用中，很多开发者的卡点并不在“会不会输入提示词”，而在环境配置。比如claude命令装好后找不到，或者按网上的教程在项目里新建了settings.json，第三方模型还是接不进去。这些问题大部分不是 Claude Code 本身坏了，而是运行入口、配置文件位置和环境变量优先级没有理清。所以这里会先把运行机制讲清楚，再一步步给出可复现的配置过程。

1. 先理解 Claude Code 的工作方式，再动手安装

1.1 它解决什么问题

Claude Code 解决的核心问题是“AI 编程助手如何进入真实项目上下文”。网页端的 AI 工具一次只能看到你粘贴进去的代码片段，无法了解项目的目录结构、依赖关系、Git 变更和运行环境。Claude Code 直接运行在项目根目录，启动时会读取当前仓库内容，调用模型接口，并根据模型返回的指令执行文件修改或终端命令。它把“你复制代码、去对话框提问、再把结果贴回来”这个过程，变成了“你在终端里描述需求，它直接操作项目”。

这里要强调：它不是自动在后台乱跑的进程。模型每次需要执行工具操作，都会先产生一个计划，Claude Code 再在终端里展示出来。用户可以确认、修改或拒绝。这个交互模型很重要，因为这是它能够安全应用于真实项目的前提。

1.2 CLI、插件和桌面端的关系

从软件架构上看，Claude Code 的底层是一个命令行工具，官方以 npm 包方式发布。VS Code 插件和桌面版都是在 CLI 能力之上做的集成。VS Code 插件会让 CLI 运行在编辑器侧边栏或面板中，便于查看代码 diff 和文件树；桌面版则提供独立的图形界面。三者读写底层配置时不一定完全相同，尤其在使用社区配置工具时，常见的问题是把配置写到了其中一个入口的路径，而另一个入口启动时读不到。

因此在开始安装之前，先确认自己主要会从哪个入口使用。如果你想在 VS Code 里用，仍然建议先装好 CLI，因为插件需要调用本机的claude命令。如果你只用桌面版，也需要知道桌面版最终读取的还是同一套用户级配置目录~/.claude。

1.3 模型从哪里来

Claude Code 本身不生产模型能力。它把本地项目文件、命令输出和提示词一起发送给模型服务，模型返回结果，再由客户端执行。通常的模型来源有两种：Anthropic 官方服务，以及兼容 Anthropic Messages API 的第三方模型服务。许多团队没有官方 API 访问条件，会通过网关或兼容层接入其他模型供应商，比如 DeepSeek、国产模型服务或自建模型推理服务。接入时的核心要求是 API 协议兼容，不是随便填一个模型名称就能用。

如果模型服务只是提供了 OpenAI 风格的接口，而没有 Anthropic Messages API 兼容端点，就需要一个协议转换网关。直接把ANTHROPIC_BASE_URL指向一个不支持 Anthropic 协议的地址，Claude Code 会发出格式不匹配的请求，进而表现为连接失败或响应异常。

1.4 常见的误解

有一个很大的误解是“只要装好 Claude Code，官方模型随便用”。实际上，只有登录了有权限的账号，或者配置了有效的 API Key，请求才能被模型服务接受。另一个误解是“settings.json 写一次就能全局生效”，实际上配置有作用域，用户目录、项目目录和系统环境变量之间还有优先级关系。后面排查部分会专门处理这个问题。

还有一个常见误区是把“模型名”和“模型服务商”混为一谈。比如别人截图里写deepseek-v4-pro，你就直接抄到配置里。如果该名称不是当前服务端真正支持的模型 ID，就会得到来源不明的报错。正确做法是始终以服务商文档里的模型 ID 为准。

2. 安装 Claude Code：环境检查、安装命令与卸载

2.1 环境要求

在安装前先确认系统满足基本条件。Claude Code 官方提供了 macOS、Linux 和 Windows 支持，但 Windows 下有几种使用方式，直接在 PowerShell 中使用也可以，在 WSL 中使用更贴近大多数教程中的终端行为。Node.js 版本要求需要以官方文档为准，通常建议 18 或更高版本，太低会导致执行时报语法错误。

2.2 检查 Node.js 和 npm

打开终端，依次执行：

node -v npm -v

如果系统提示找不到命令，说明 Node.js 尚未安装或没有加入 PATH。macOS 上可以通过 Homebrew 安装，Windows 可以安装官方安装包，Linux 发行版可以用各自的包管理器或 nvm。安装完成后重新打开终端，确保 PATH 生效。

推荐使用 nvm 管理 Node.js 版本，因为 Claude Code 更新频繁，Node 版本升级和回退都比较方便。示例命令：

nvm install 20 nvm use 20

2.3 全局安装 CLI

确认 Node 环境正常后，全局安装 Claude Code：

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

-g表示全局安装，安装后的claude命令会被放到 npm 的全局 bin 目录。安装完成后执行：

claude --version

如果能看到版本号，说明 CLI 安装成功。如果提示command not found，执行npm config get prefix找到全局目录，然后把对应的bin目录加入 PATH。在 Windows PowerShell 中，如果执行claude时提示脚本无法运行，通常需要调整 PowerShell 执行策略，可以在管理员终端中执行：

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

执行后重试即可。这里调整的是当前用户的执行策略，目的是允许本机安装的 npm 全局脚本运行，不影响系统安全配置。

2.4 在项目目录中启动

安装好后，进入需要处理的项目目录，执行：

cd /path/to/your-project claude

首次运行会进入登录或身份认证流程。使用官方订阅账号可以直接登录；使用 API Key 时，可以通过设置环境变量或在配置文件中写入认证信息，不需要走网页登录。启动后 Claude Code 会扫描当前目录，如果项目很大，第一次生成上下文可能会稍慢。

2.5 安装 VS Code 插件

在 VS Code 扩展市场搜索“Claude Code for VS Code”，安装后重启编辑器。插件通常会自动查找本机claude命令。如果本机没有安装 CLI，或者 PATH 里找不到，插件会报could not locate the claude cli on path。所以无论你用不用 CLI，建议先完成 2.3 的全局安装。

2.6 卸载和清理

如果不需要使用，卸载命令是：

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

卸载之后，建议清理残留的配置和缓存目录。CLI 主要配置在~/.claude，项目目录下还可能出现.claude目录。如果这些目录里有自定义 Skill 或 settings.json，需要单独备份。删除这些目录后，再检查 shell 的 PATH 配置里是否还有指向旧claude路径的内容。这样才能做到“卸载干净”。

3. 桌面端、CLI 和 VS Code 插件怎么选

3.1 三个入口的差异

3.2 桌面版和 CLI 的配置差异

Claude Code 桌面版虽然提供 GUI，但核心能力仍然来自 CLI。桌面版启动时也会读取用户目录下的~/.claude配置，但项目路径的感知可能与 CLI 不一样。用户在桌面版里打开一个文件夹，该文件夹会被当作当前项目目录。因此，如果 CLI 方式下配置好了settings.json，但桌面版仍然无法接入模型，先检查桌面版打开的项目目录是否正确，再看桌面版是否有独立的认证状态。

社区常说的“桌面版免登录配置”，本质上不是绕过登录，而是通过 API Key 方式完成身份认证，让启动时不再进入网页登录流程。也就是在配置文件里写入环境变量，并在启动时选择 API Key 模式。这个过程与 CLI 的 API Key 配置是一致的。

3.3 选型建议

日常开发中，CLI 是最高效的方式。它可以在任意终端会话中启动，不需要打开编辑器，适合配合 tmux、远程开发等场景。如果你在做前端或重构，需要在编辑器中频繁查看文件，VS Code 插件更适合。如果你只希望有一个独立聊天窗口，不关心终端输出，桌面版可以满足。但要注意，多个入口同时连接同一个项目时，文件写入可能互相干扰，建议同一时间只使用一种方式。

4. 模型接入：API Key、环境变量与第三方模型

4.1 原生模型和第三方模型有什么区别

Claude Code 默认请求的是 Anthropic 官方 API。请求需要认证信息，并且模型名称必须被服务端支持。第三方模型服务要接入 Claude Code，通常需要满足两个条件之一：一是服务商实现了 Anthropic Messages API 兼容接口，二是存在一个协议转换网关，把 Claude Code 发来的请求改写成下游模型服务能识别的格式。

如果你只是把ANTHROPIC_MODEL改成某个第三方模型名称，但没有把ANTHROPIC_BASE_URL指向兼容服务，仍然会请求官方 API，自然报错。

4.2 设置 API 认证信息

最直接的方式是设置环境变量：

export ANTHROPIC_API_KEY="sk-xxxx" export ANTHROPIC_BASE_URL="https://your-gateway.example.com" export ANTHROPIC_MODEL="your-model-id"

在 PowerShell 中：

$env:ANTHROPIC_API_KEY="sk-xxxx" $env:ANTHROPIC_BASE_URL="https://your-gateway.example.com" $env:ANTHROPIC_MODEL="your-model-id"

设置后，在当前终端启动claude，它就会使用这些变量。注意环境变量是进程级别的，关闭终端后失效。不要把真实 Key 写进代码仓库，也不要在公开博客里贴自己的 Key。

4.3 使用 settings.json 持久化配置

如果希望每次启动都自动使用第三方模型，可以在用户级或项目级配置文件中写入环境变量。用户级配置路径是：

~/.claude/settings.json

示例：

{ "env": { "ANTHROPIC_BASE_URL": "https://your-gateway.example.com", "ANTHROPIC_API_KEY": "sk-xxxx", "ANTHROPIC_MODEL": "your-model-id" } }

项目级配置放在项目根目录的.claude/settings.json，只对该项目生效。建议 API Key 放在用户级配置文件，并用文件权限控制访问；项目级配置只放端点和模型名，避免 Key 被提交到 Git。

4.4 用 ccswitch 管理多套模型配置