企业官网建设流程全解析

如果你最近逛技术社区，肯定见过一个词频繁刷屏：claude code。无论你是写业务代码的、折腾 AI 工具的、还是想用自然语言批量处理文件的人，这个工具几乎成了"终端里的 AI 程序员"代名词。它不需要你开 IDE，不需要复制粘贴代码到网页对话框，而是在你项目的根目录里直接和你对话，读代码、改文件、跑命令、调 bug，一条龙干完。今天这篇"不完全使用指南"，我基于自己的实际体验，把从安装到配置、从接第三方模型到写自定义技能的全过程拆开讲一遍，尽量让你看完就能上手。

先说清楚这篇指南的定位：它不是官方文档的翻译，而是一个普通开发者踩过一堆坑之后的实操记录。我会从最简单的安装说起，接着讲怎么让它真正干活，再深入讲怎么接入 DeepSeek 这类模型、怎么用 Skills 定制自己的流程，最后整理一份高频报错的排查清单。无论你是 Windows、Ubuntu 还是 macOS 用户，都能在里边找到对应的操作路径。

1. 这个工具到底解决了什么问题

1.1 终端里的"自动编程代理"是什么意思

要理解 claude code 的价值，先得把它和常见的 AI 编程工具区别开。之前很多人用的 Copilot、CodeWhisperer，核心是"补全"：你在编辑器里写代码，它帮你续写下一行。后来有了 Cursor，可以框选代码然后说"帮我把这个函数改成异步"，它给你改。但 claude code 的工作方式完全不同——它是一个跑在终端里的 Agent（代理），能理解整个项目的结构，能读多个文件，能主动执行命令，然后基于命令的输出去做下一步判断。

我举个具体例子。假设你现在有个老项目，想把所有接口的错误处理从console.log改成统一的日志上报。如果人工改，你得先找出所有接口文件，逐个改，还要小心漏掉。如果用 claude code，你只需要在终端里说一句："把 src/api 目录下所有接口的错误处理改成调用 utils/logger 里的 reportError，并且把原来 console.log 的内容作为 message 参数传进去。"它会自己去翻文件、修改代码、跑测试验证，如果遇到不确定的地方，还会停下来问你。这种"理解上下文"到"动手执行"再到"自动验证"的闭环，才是它真正的核心能力。

1.2 它能做的不只是写代码

虽然名字叫 code，但它实际能干的事远不止写代码。我身边有人用它整理 CSV 数据，有人让它批量重命名文件，有人让它分析日志里的异常，还有人直接把它当项目文档生成器用。原因在于 claude code 终端环境下有文件读写和执行命令的权限，只要是在这个项目目录内能做的事，它都能尝试。

比如我见过一个最离谱的用法：有人拿 claude code 给自己做了一个"PPT 大纲生成器"，输入一个主题，它自动生成章节结构、拟好每页的标题和要点，然后输出成 Markdown 文件，再配合其他工具转成 PPT。虽然每一步做得不算深入，但胜在一条龙，省掉了大量重复劳动。所以，不要把它只当成程序员的专属工具，它更像一个"长在终端里的全能助手"，只要有命令行操作基础就能用。

1.3 适合哪些人用

先说结论：写代码的人最受益，但不是只有程序员能用。

如果你是程序员，claude code 能帮你做三类事最顺手：第一类是理解陌生项目，刚接手一个仓库时让它梳理目录结构、核心模块关系、关键接口调用链，比人肉翻代码快一个量级；第二类是写枯燥的样板代码，比如写单元测试、补注释、生成类型定义，这些活儿它做得又快又整齐；第三类是排查 bug，把报错信息直接丢给它，让它沿着调用栈往上查，通常它能给出比搜索引擎更贴合你项目的答案。

如果你不是程序员，但工作中经常碰命令行——比如运维、数据分析、自动化脚本编写——claude code 依然值得一用。你可以让它写一个批量处理文件的 Python 脚本，然后你在终端里运行，报错了把错误发回去让它改，来回几轮之后，一个能用的工具就出来了。本质上，它把一个"助手的思考能力"和"终端的执行能力"合并了，你只需要会表达需求就行。

2. 从零开始：安装环境的三个前置条件

2.1 Node.js 版本不是越新越好，但有底线

安装 claude code 之前，先检查你有没有装 Node.js，因为它的 CLI 版本是用 npm 分发的。官方要求 Node.js 18 及以上版本，低于 18 用不了。我用的是 20 的 LTS 版本，跑了很久都没出问题。这里要提醒一句：虽然 Node 20 是合理选择，但如果你机器上装的是 Node 18，也别急着升级，很多老项目对 Node 版本有要求，升级可能连带引出一堆兼容性问题。只要版本号大于等于 18，就先凑合用，遇到再升级。

怎么检查版本？打开终端，输入node -v，如果能输出版本号，就说明已经装了。如果提示找不到命令，需要先去 Node.js 官网下载安装包，或者用包管理器安装。macOS 用户如果装了 Homebrew，一条brew install node就能搞定；Ubuntu 用户建议用 nvm 装，避免 sudo 权限的坑；Windows 用户直接下载安装包最省事。

2.2 登录账号和订阅那些事

装完 CLI 之后，第一次运行claude会提示你登录。它支持用 Claude 账号登录，登录之后才能和 Anthropic 的模型对话。这里有个新手最容易迷惑的点：claude code 本身是免费的，但你实际调用 Claude 模型，要么有 Claude 的订阅（Pro 或 Max），要么有 API 额度并要消耗 token 费用。

如果不想折腾订阅，完全可以用我后面第 4 章讲的方案：在配置文件里把模型换成 DeepSeek、智谱或者其他兼容模型。这也是国内大量用户在用 claude code 的方式——把它当成一个"前端壳"，后端接不同的模型 API，既绕开了订阅成本，又能体验这套 Agent 流程。这个思路我会在配置部分详细介绍，先记住一点：登录不是死路，模型可以换。

2.3 三条安装路线：CLI、桌面版、VSCode 插件

claude code 官方提供了三种使用形态，我建议你按自己的使用习惯选：

• CLI 版本：npm install -g @anthropic-ai/claude-code全局安装，然后在任意项目目录里运行claude就能启动。优点是轻量、灵活，在任何终端里都能用；缺点是全命令行操作，对不熟悉终端的人门槛略高。

• 桌面版：官方后来推出了 Claude Code Desktop（桌面应用），提供图形界面，支持直接打开文件夹、在聊天框里发指令，还能看到运行日志和文件变更记录。对不太习惯纯命令行的人友好很多，我认识的很多非程序员用户都是从桌面版入门的。

• VSCode 插件：在 VSCode 扩展市场搜 "Claude Code"，装好之后可以绑定当前打开的项目，在编辑器面板里直接对话，查看代码变更也更直观。因为日常开发就在 VSCode 里，插件可以省掉切换终端的麻烦。

三条路线共用同一套配置和登录状态，也就是说你可以在 VSCode 插件里接入好模型，再去桌面版打开同一个项目，配置是互通的。它们之间的详细对比，我建议刚上手的人先装 CLI 版本，因为命令行版本最容易理解"这个工具到底在干嘛"；如果实在无从下手，就装桌面版，图形界面上手成本最低。

3. 核心操作：五分钟让 claude code 开始干活

3.1 在你的项目里启动第一次对话

安装完成并登录后，找一个你自己的项目文件夹，在终端里进入这个目录，然后输入：

claude

如果项目较大，它可能会先问你要不要跳过某些目录，比如node_modules、.git、dist这类无关紧要的地方。我建议你允许它自动生成一个虚拟文件系统索引，方便它后续快速查找文件，但如果项目动辄几十万文件，建议手动排除掉依赖目录，否则每次初始化都会卡半天。

启动后你会看到一个交互式输入框。这时候就可以直接提需求了。我第一个建议的需求是："简单介绍一下这个项目的功能和整体结构。"它会搜索文件、阅读关键配置，然后给你一个结构清晰的梳理。这个操作看似简单，实际上是测试它有没有正确读取项目的关键一步。如果连这个都答不好，多半是模型配置或文件权限有问题，趁早排查。

3.2 掌握斜杠命令，效率提升一个档次

claude code 的交互界面里，以/开头输命令可以快速完成很多操作。我把自己常用的整理成一张表：

日常使用中最容易忽略的是/clear。很多人和 AI 对话时会遇到一种情况：前面聊了 20 轮，后面让它做什么它都答非所问。这不是模型变笨了，而是上下文窗口被无关内容塞满，优先级被冲淡。这时候不要继续硬聊，直接/clear开新会话，把必要的背景重新说一遍，效果会好很多。

3.3 用 CLAUDE.md 给项目设定"操作规范"

每启动一个项目的 claude code，它都会自动读取项目根目录下的CLAUDE.md文件（如果存在的话）。这个文件用 Markdown 格式写，内容相当于你给 AI 的"项目交接文档"，让它了解这个项目的特殊约定和偏好。

我自己所有的项目都会维护这个文件，至少写三块内容：一是项目简介，说明这是一个什么系统、技术栈是什么；二是代码规范，比如"接口返回格式统一为 { code, message, data }""类型定义放 src/types 下"；三是禁忌事项，比如"不要修改迁移文件""公共组件改动前先问确认"。

举个实际例子，一个前端项目里写：

# 项目约定 - 组件使用 TypeScript + React，函数组件写法 - 样式使用 Tailwind，禁止引入其他 CSS 文件 - API 请求统一走 src/api/index.ts 封装 - 新增功能必须同步补充 README 文档 - 不要修改 src/entry.tsx 的挂载逻辑

这样，你每次启动 claude code，它不需要你重复交代这些背景，直接按照规则执行。这比在对话里每次说明要可靠得多。还有一个小技巧：CLAUDE.md支持引用其他文件，比如在文件里写@docs/architecture.md，它会自动把这个文件内容也作为上下文。如果你的项目文档较多，强烈建议用这种方式组织，避免 CLAUDE.md 自身膨胀得不可维护。

4. 进阶玩法：接入 DeepSeek 等第三方模型

4.1 为什么要换模型，以及换模型的思路

官方 claude code 默认用的是 Anthropic 的 Claude 模型，效果确实好，但对于个人开发者来说，订阅费用和网络门槛是绕不开的问题。我认识的所有国内开发者，几乎都在琢磨同一个问题：能不能让 claude code 接上别的模型？答案是可以，而且比想象中简单。由于 claude code 的架构支持通过环境变量指定模型接口，我们可以让它走 OpenAI 兼容协议，接上 DeepSeek、智谱 GLM 这些服务。这样一来，你依然用 claude code 的操作界面和 Agent 工作流，但底层的模型换成了成本低得多的国产方案。

当然要提前说清楚：换模型之后，体验不会和官方模型完全一致。不同的模型在指令跟随、代码理解、长上下文处理上各有差异。DeepSeek 在代码方面表现不错，日常写业务代码完全能打；智谱的 GLM 系列胜在稳定；如果你很在意效果，也可以再对比一下其他兼容模型。我的建议是别指望 100% 平替，而是把它当作一个"体验 Agent 编程流程的低成本入口"，如果以后预算允许，再切回官方模型也不迟。

4.2 修改 settings.json，核心配置项一次讲清

接入第三方模型的核心是配置文件。claude code 的配置路径在不同系统上略有差异，但逻辑一样：

• Windows：C:\Users\你的用户名\.claude\settings.json
• macOS / Linux：~/.claude/settings.json

如果这个文件不存在，自己新建一个就行。在 JSON 文件里，你需要设置env字段，写入模型接口的地址和密钥。以接入 DeepSeek 为例，网上流传最广的一份配置长这样：

{ "env": { "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic", "ANTHROPIC_AUTH_TOKEN": "你的DeepSeek密钥", "ANTHROPIC_MODEL": "deepseek-chat", "ANTHROPIC_SMALL_FAST_MODEL": "deepseek-chat" } }

这里有一个非常关键的坑：ANTHROPIC_BASE_URL必须以/anthropic结尾，因为 DeepSeek 提供了专门的 Anthropic 兼容接口，路径写错或者漏掉，会直接报连接错误。ANTHROPIC_AUTH_TOKEN填你在 DeepSeek 开放平台申请的 API Key，不用加 "Bearer " 前缀。ANTHROPIC_MODEL指定主模型，ANTHROPIC_SMALL_FAST_MODEL指定快速小模型，用于一些消息摘要等轻量任务，通常填同一个就行。

改完保存文件，重启终端里的 claude code，然后直接发一句"你好，介绍一下你自己"，如果它能正常回答，说明模型接通了。有些版本的 claude code 还会有模型更新提示，忽略即可，不影响使用。

4.3 多模型切换怎么办，试试 CC Switch

如果你不止接一个模型，比如既接了 DeepSeek 又接了智谱，不想每次都手动改配置文件，可以用一个开源小工具：CC Switch（cc-switch）。它本质上是一个图形化的配置管理器，让你在多个模型配置之间一键切换，不用碰命令行。

CC Switch 的使用逻辑很简单：先在软件里添加多个"供应商配置"，每个配置填上名称、API 地址、密钥、模型名，然后保存。之后想用哪个模型，点一下对应的配置，它会自动改写 claude code 的 settings.json，然后你重启 claude code 就能生效。等于把容易写错的 JSON 配置变成了点按钮。

我在多项目场景下特别喜欢这个工具。比如 A 项目用 DeepSeek 控制成本，B 项目用官方 Claude 追求效果，来回切换也就几秒钟的事。但要注意：切换模型后一定要重启 claude code 再继续，否则会话还保持着旧模型的连接。另外，CC Switch 本身不负责登录，它只是管配置，所以 Claude 账号登录和模型切换是两码事，别搞混。

4.4 兼容性问题的排查思路

接入第三方模型时，最容易踩的坑是版本不匹配。网上大量出现类似报错：某个模型名在 claude code 里不被识别（比如 "deepseek-v4-pro is not a model this version of claude code recognizes"）。这类问题的根因，不是模型供应商的问题，而是 claude code 的中继层对模型名做了校验，新出的模型不在它内置的模型列表里。

碰到这种报错怎么处理？我的排查顺序供你参考：第一步，确认ANTHROPIC_MODEL填的是不是官方支持的模型名，比如 DeepSeek 在 Anthropic 兼容接口里一般用deepseek-chat，别用带版本号后缀的别名；第二步，检查ANTHROPIC_BASE_URL有没有写错，不带/anthropic的地址可能在对话时没有模型名校验，但实际请求会失败；第三步，升级 claude code 到最新版，因为新版会同步更新模型支持列表。整体来说，配置层面 90% 的问题都能用这三步定位。

5. 让 claude code 学会你的私有流程：Skills 玩法

5.1 Skills 到底是什么，和 CLAUDE.md 有什么区别

当基础配置稳定后，就该聊聊让 claude code 真正"好用"的东西：Skills（技能）。理解 Skills 有个最简单的类比：CLAUDE.md 约定的是"你在这个项目里做事要遵守什么规矩"，Skills 则是"你能一招调用的一套完整工作流程"。规矩是静态的，流程是动态的。

具体来说，Skill 是一组文件，放在某个目录下。它告诉 claude code："当你需要使用这个技能时，应该按以下步骤操作，可以调用我提供的脚本或模板。"这样一来，你的很多重复性工作就可以沉淀成固定流程，让 AI 一键执行。

5.2 一个完整的 Skill 长什么样

Skills 的存放位置有一定讲究。官方规范是在项目根目录建一个.claude/skills文件夹，下面每一个子文件夹就是一个 Skill。每个 Skill 文件夹里至少有一个SKILL.md文件，用来描述这个技能是干什么的、什么时候用、怎么做。如果有配套的资源，还可以放脚本文件、模板文件等。

举个例子，如果你想给 claude code 加一个"生成提交信息"的技能，目录结构可以是这样：

.claude/skills/generate-commit/ ├── SKILL.md └── scripts/ └── suggest_commit.py

SKILL.md的内容大致长这样：

--- name: generate-commit description: 根据当前的 git diff 生成符合规范的 commit message --- ## 使用场景 在用户说"生成 commit message"或"提交代码"时使用。 ## 执行步骤 1. 运行 `git diff --stat` 查看变更范围 2. 运行 `git diff` 查看具体变更内容 3. 根据变更类型，用 conventional commits 规范生成 commit message 4. 将生成结果展示给用户，由用户确认后执行 `git commit`

注意description字段写得越清楚越好，因为 claude code 会扫描所有 Skills 的描述来决定何时调用某个技能。如果描述模糊，很可能需要你手动提醒它"用一下那个技能"。

5.3 实操案例：做一个检查需求的清单型 Skill

Skills 不只是代码工具。我最常用的一个 Skill 是"PR 自检"。每次写完代码要提 Pull Request 前，我会用自然语言说"帮我做一个提交前的检查"，它会按照 SKILL.md 里的流程逐项检查：是否有调试日志、是否有未使用的变量、是否有注释掉的死代码、测试文件是否更新、文档是否同步。这个流程以前完全靠人肉执行，现在变成了一次对话。

写这个 Skill 的 SKILL.md 也很简单，就是列一个 checklist：

--- name: pr-checklist description: 在用户准备提交 pull request 前，按照项目规范逐项检查代码质量 --- 1. 运行 `git diff HEAD` 获取当前全部改动的内容 2. 检查是否有 console.log/debugger 等调试残留 3. 检查是否有 TODO 标识未被处理 4. 检查新增文件是否有对应的单元测试 5. 检查是否更新了 README 或 API 文档 6. 汇总检查结果，逐条列出问题和修改建议

这个 Skill 我每天都在用。它的价值不在于逻辑有多复杂，而在于它把"标准操作流程"固化了。很多团队辛辛苦苦制定代码规范，但人总有忘的时候，Skill 不会忘。

5.4 在哪声明 Skills，以及多项目共享的技巧

Skills 默认只对当前项目生效，因为它是放在.claude/skills下的。如果你想所有项目都能用某个 Skill，可以把 Skill 放在全局目录里，比如在用户主目录下的~/.claude/skills。这样每次启动 claude code，它都能识别到这些全局技能，不用在每个项目里重复复制。

另外，我习惯在每个项目的CLAUDE.md里写一句类似"如果需要生成 commit message，使用 generate-commit 技能；提交 PR 前使用 pr-checklist 技能"的话。这样等于给 AI 一个更明确的触发条件，它能更快地判断何时该调技能，而不是等你手动指出。如果项目里多个技能容易混淆，这个做法尤其有效。

6. 踩坑实录：我从报错里攒下来的排查清单

6.1 一启动就报 529 错误，怎么处理

我用 claude code 过程中遇到最多的错误就是 529。这个错误码很直白地告诉你：服务器过载，当前请求量太大，模型服务端暂时处理不过来。对新用户来说，529 特别容易出现在刚配置好模型的第一次对话时，很多人以为是配置出了问题，急得不得了，其实不是。

处理方式很简单：等几秒到几分钟再试。如果频繁出现，可能和当前接的模型服务商在某个时段的负载有关，可以换个时段再用，或者切换备用的模型。如果是官方 Claude 服务频繁 529，基本就是官方全局负载高的表现，大家都会遇到，别慌。这个错误我以前会直接归因于"我配置错了"，白白折腾半天，后来才发现很多时候就是服务端的临时问题。

6.2 模型名不识别、配置不生效，问题出在哪

另一个高频报错是模型名无法识别。网上有很多截图，典型文案类似 "xxx is not a model this version of claude code recognizes"。这个报错我前面提过模型列表校验的问题，这里再补充两个排查点。

第一，检查模型名的大小写和连字符。DeepSeek 的官方模型名往往就是deepseek-chat这种格式，如果你从某篇文章复制了带版本号的名字，比如deepseek-v4-pro，大概率会撞上模型列表校验的坑。第二，配置文件保存后必须重启 claude code，环境变量的读取发生在启动时，光保存不重启不生效。如果你是在 VSCode 插件里改的配置，重启插件或重开窗口也算重启。还会遇到一种隐蔽情况：配置文件里有多个env块，后写的覆盖了先写的，导致你以为改了却没生效。这种时候把 JSON 格式化一下再看，或者干脆删掉多余的环境变量块。

6.3 输出乱码：编码问题的根源和解决

在 Windows 上使用 claude code 时，中文输出乱码是常见问题。根源基本都出在终端编码上。Windows 默认的 GBK 编码和 claude code 默认输出的 UTF-8 之间没对齐，中文就变成了一堆问号或者乱码。

解决办法有两种：一种是在启动前先执行：

chcp 65001

把当前终端代码页切到 UTF-8；另一种是在系统设置里把"使用 Unicode UTF-8 提供全球语言支持"的选项打开，这个选项在 Windows 的区域设置里，勾选后重启系统，基本能根除乱码问题。VSCode 的终端则通常默认 UTF-8，乱码概率低很多。Linux 和 macOS 用户遇到乱码的概率很小，如果出现了，检查终端 locale 设置即可。

6.4 卸载不干净，重装老是报错

很多人在初次配置失败后，选择把 claude code 卸载重装。但如果你只执行npm uninstall -g @anthropic-ai/claude-code，会发现重新安装后旧配置还在，有时甚至启动报错。因为这些命令只删了全局 npm 包，没有清理用户目录下的.claude文件夹。

如果你确实想干净卸载，我建议按这个顺序来：第一步，执行 npm 卸载命令；第二步，删除用户主目录下的.claude目录（注意提前备份settings.json和CLAUDE.md，避免重要配置丢失）；第三步，如果使用过桌面版，在系统设置里卸载桌面应用，并清掉对应的 AppData 或 Library 目录里的缓存。这样清理完之后重新安装，基本就是一个全新的状态，不会再被旧配置干扰。我见过不少"配不上、卸不掉、反复折腾"的情况，最后都是因为.claude目录没有清掉。

6.5 电脑风扇狂转、还发出各种声音提示

如果你用 claude code 时发现电脑风扇突然全速运转，或者运行过程中有提示音，这两种情况都正常到不值得慌张。风扇狂转一般发生在它执行大量文件读取或运行测试时，特别是大型项目，CPU 或磁盘 I/O 飙升是合理现象。但如果你在空闲状态下风扇依然飙高，那大概率是某个会话还挂着后台任务，可以通过/status看看有没有正在执行的命令，或者直接重启 claude code。

至于声音提示，claude code 在某些操作完成或出错时会触发系统提示音，这个可以在设置里关掉。如果你不喜欢"叮叮咚咚"的提示，在设置里开启静音模式，或者直接关闭终端声音。如果你在远程服务器上使用，声音提示通常不生效，那不是 bug，是服务器没接音频设备。

6.6 在 Windows 上装成快捷方式，还有个实用小习惯

最后分享一个 Windows 用户的便利性技巧。因为 claude code 是命令行工具，每次都要打开终端、输入claude，对没有快捷方式就难受的人来说有点繁琐。你可以创建一个桌面快捷方式，目标设为：

cmd /k claude

双击就能直接进入 claude code 界面，省去输入命令的步骤。如果你有固定的工作目录，可以把启动目录也改成项目文件夹，这样打开就是项目环境。我个人的习惯是在系统 PATH 里配了claude，然后用 Windows Terminal 固定一个 profile，启动即进入工作目录并自动运行claude，体验几乎等同于打开一个桌面应用。

7. 一些实际操作中沉淀下来的建议

用 claude code 大半年，我最深的体会是：这个工具的上限不在模型，而在你怎么用它。把 CLAUDE.md 写好、把常见流程固化成语义清晰的 Skills、在遇到报错时按系统性思路排查——这几件事做好之后，它的稳定性和效率会连跳几个台阶。反过来，如果只是随便装好然后裸用，遇到报错就认为是工具不行，那你大概率会错过这个其实很好用的东西。

最后提一个小技巧：如果你刚开始接触 claude code，不需要一上来就追求多模型切换、自定义 Skills 这些进阶操作。先在真实项目里连续用一周，至少完成两到三件小任务，比如"帮我写一个接口层的单元测试""帮我梳理这个模块的依赖关系""把这个函数的类型声明补全"。等你对它的工作方式产生了手感，再回头研究配置和技能，你会发现一切都顺理成章。工具就是这么个工具，重点是你要真的拿它去干一件具体的事。