企业官网建设流程全解析

最近一两个月，群里讨论频率最高的几个词里，Claude Code肯定排得上号。作为一个常年泡在命令行里的开发者，我一开始对"AI 编程助手"这件事是有点怀疑的——毕竟补全工具用了这么久，大家都有"看起来能补，实际不敢让它上手改核心逻辑"的默契。直到我把 Claude Code 装进自己维护的几个项目，跑通第一轮修改，才发现终端型智能体和 IDE 里的自动补全根本不是一个物种。这篇文章就从安装讲起，一直讲到你把第一行改动真正落进 git 提交，中间覆盖 VSCode 集成、DeepSeek 接入、常见报错、成本与缓存这几个新手最容易卡住的地方。我尽量把每一步写成可以直接照做的操作，不绕弯子。

1. Claude Code 是什么：一个住在终端里的 AI 程序员，而不是 IDE 插件

1.1 它和 Copilot 这类补全工具的本质区别

Claude Code 是 Anthropic 推出的一款终端智能体（agent）工具。它不是你 IDE 侧边栏里那个"帮你补下一行"的小窗，而是一个跑在终端里的完整"程序员助手"。

两者的差别用一句话概括：补全工具负责"写下一行"，Claude Code 负责"把整个任务闭环"。它会自己读文件、理解项目结构、生成修改方案、调用命令行执行测试、改完还要检查结果，不行就重来。比如你让它"把登录超时从 30 秒改成 60 秒，并把相关配置也同步掉"，它做的不是找到一处代码改掉，而是会去搜哪里定义了超时、哪里读取了配置、有没有对应的测试需要更新，然后逐步把整个链路改完。

这个"逐步执行 + 边看结果边调整"的循环，是它和普通补全工具最核心的分水岭。因为技术上的实现方式，Claude Code 跟编辑器是解耦的：它只依赖一个终端和 Node.js 环境。你用 VSCode、IDEA、Vim 还是裸终端，对它来说没有区别。这也解释了为什么网上搜"Claude Code 配置"的结果里有大量教你怎么在 VSCode 里调用它——因为它天然跑在集成终端里。

1.2 谁适合用、谁不适合用

从我的实际使用看，Claude Code 最适合的人群是：本来就用命令行和 git 工作的开发者。无论你写 JavaScript、Python、Java 还是做嵌入式，只要项目能在本地命令行里构建，它就能发挥作用。

不太适合的人有两类。一类是完全没有编程基础的小白，因为它没有图形界面，交互靠对话，犯错后需要你懂得看 diff、看日志、知道 git 怎么回滚，这些对没摸过命令行的人很不友好。另一类是只希望"点个按钮就有结果"的纯需求用户，那更适合等可视化产品，而不是 CLI 工具。

顺便提一句，网上有人问"Claude Code 能不能搞 STM32 项目"——能用，但有前提：你的编译链、烧录工具等必须先能在终端命令行跑通。Claude Code 本质上是"会打字、会读代码、会执行命令"的助手，它不会替你解决芯片厂商 IDE 的 GUI 操作问题。

1.3 它的核心三件套：命令、会话、配置文件

理解 Claude Code，把它拆成三样东西就够了。

第一件是claude命令。安装之后，在任意项目目录里输入claude就会启动一个新的会话。

第二件是会话（session）。你每次和它的完整对话、它执行过的命令、改过的文件，都属于一个会话。会话可以通过--continue或--resume <会话ID>找回来。这个机制既是它的优势（可以接着干），也是成本炸弹的来源，后面第 6 章细讲。

第三件是配置。全局配置在~/.claude/目录下，项目配置在项目根目录的.claude/settings.json里。模型的选型、API Key、权限规则、行为偏好都是在这些文件里定义的。

2. 安装前准备：Node.js、npm 与两种启动形态

2.1 第一步永远是检查 Node.js

Claude Code 是 npm 包，所以你的机器上必须要有 Node.js。官方要求 Node 18 及以上，但我建议直接用Node 20 或 22 的 LTS 版本，原因后面讲 Windows 报错时会提到——新版本的 Node 在底层网络实现上更省心。

先打开终端检查：

node -v npm -v

如果你看到类似v20.18.0这样的输出，说明 Node 没问题。如果提示找不到命令，就去 Node 官网下载 LTS 安装包，装完记得重开终端让 PATH 生效。Windows 用户也可以用 winget：winget install OpenJS.NodeJS.LTS。

这里特别提醒：装完之后一定要把终端完全关掉再重开。我第一次就是装完直接在旧终端里跑，结果node命令还是提示找不到，折腾了半天。

2.2 用 npm 全局安装 Claude Code

Node 环境就绪后，安装其实就一条命令：

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

安装完成后验证一下：

claude --version claude --help

能输出版本号，就说明装好了。Linus（Linux 版）和 macOS 也是一样的命令，只是 Windows 上要求你用的是 cmd、PowerShell 或 VSCode 集成终端，而不是 WSL 里的 Linux 子系统——如果你要在 WSL 里用，那就在 WSL 里重新装一遍 Node 和 Claude Code。

注意@anthropic-ai/claude-code这个包名很容易输错，少个@anthropic-ai前缀就完全不是同一个东西了。npm 上确实存在一堆名字类似的第三方包，有的只是包装壳，有的可能夹带私货，所以务必认准官方全名。

2.3 网络不稳定时的安装姿势

有人在群里问"Claude Code 下载不下来怎么办"。先分清两件事：下载慢/超时，和根本连不上。

如果只是 npm 官方源访问慢，最直接的办法是切换 npm 的公共镜像源，比如国内常用的 npmmirror。这是常规的加速手段，并非绕开任何网络限制，镜像源本身只是把 npm 官方包缓存了一份供人下载：

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

改完再执行安装命令，一般速度会明显提升。装完之后建议确认一下当前源，避免后续其他包也被迫走镜像：

npm config get registry

如果有人跟你说要装"Claude Code 桌面版"、给你一个来路不明的安装包，我的建议是：谨慎。官方主形态就是 CLI 这个 npm 包，桌面壳只是把终端套了个窗体，核心功能并不取决于它。与其下载来路不明的壳子，不如老老实实用终端跑claude，安全得多。

2.4 Windows 上容易踩的安装细节

Windows 上装完后如果claude命令找不到，九成是 PATH 没刷新。npm 全局包的目录通常在%APPDATA%\npm，你可以手动加进系统 PATH，或者干脆重开终端。

另外建议在 VSCode 里把默认终端配置成 PowerShell 或 cmd，方便后面集成。如果你用的终端是旧版的 Windows Terminal，也建议更新一下，某些奇怪的编码和按键问题会少很多。

3. 认证与基础配置：API Key、settings.json 与 DeepSeek 接入

3.1 两种认证方式怎么选

第一次运行claude，它会要求你登录。你有两条路：

• Claude 订阅账号登录（Pro/Max 用户）：它会打开浏览器让你授权，授权完成后终端就能直接用。这种方式适合本来就订阅了官方服务的人，流量按套餐算，不会按 token 额外扣费。
• API Key 方式：设置环境变量ANTHROPIC_API_KEY，指向你在 Anthropic 控制台申请的sk-ant-...密钥。这种方式按 token 计费，适合要精准控制成本、或接了第三方兼容接口的情况。

设置 API Key 时，Windows 用户建议用：

setx ANTHROPIC_API_KEY "sk-ant-xxx"

macOS/Linux 用户写进~/.zshrc或~/.bashrc：

export ANTHROPIC_API_KEY="sk-ant-xxx"

提示：密钥一旦泄露等于钱包被别人拿着，别写进项目里，更别提交到 git 仓库。如果怀疑泄露，去控制台吊销重办。

3.2 最小可用配置：settings.json 里到底能放什么

配置文件是你和 Claude Code 之间最常打交道的部分。全局的放在~/.claude/settings.json，项目级别的放在项目根目录的.claude/settings.json，后者的优先级更高。

一个最小但完整的示例长这样：

{ "model": "sonnet", "env": { "ANTHROPIC_API_KEY": "sk-ant-xxx" }, "permissions": { "allow": [ "Read(*)", "Bash(npm test:*)" ], "deny": [ "Bash(git push:*)" ] } }

解释几个关键字段：

• model：默认模型。可选 sonnet / opus / haiku，也可以写具体的模型 ID。
• env：你要注入会话的环境变量。API Key 放在这里，比每次手动 export 省事，也比写死在系统环境变量里更可控。注意别提交这个文件。
• permissions：权限白名单和黑名单。Claude Code 默认执行命令、改文件都要向你申请确认，配置好 allow 规则后，匹配的命令可以免确认直接跑，deny 里的命令则一律拒绝。

项目级 settings.json 的存在意味着你可以针对不同仓库差异化配置：一个 Java 项目允许Bash(mvn test:*)，一个前端项目允许Bash(npm test:*)，互不干扰。

3.3 把 DeepSeek 接到 Claude Code：兼容接口的配置方式

很多人在搜"Claude Code 接入 DeepSeek"，因为 DeepSeek 的 API 成本低、稳定，而且提供了 Anthropic 兼容接口。我实测下来，配置思路很简单：Claude Code 允许通过环境变量覆盖 API 地址和认证信息。

用环境变量配置的话：

export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic" export ANTHROPIC_AUTH_TOKEN="你的DeepSeek API Key" export ANTHROPIC_MODEL="deepseek-chat"

也可以写进 settings.json 的 env 字段：

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

注意：这时不要再设置ANTHROPIC_API_KEY，改用它兼容的ANTHROPIC_AUTH_TOKEN。模型名填 DeepSeek 自己的deepseek-chat或deepseek-reasoner。

这种"自定义 BASE_URL"的配置方式，其实也是其他第三方模型厂商接入 Claude Code 的通用做法。只要对方提供 Anthropic 兼容接口，原理都一样。顺带说一句：网上有人讨论"本地部署 Claude Code"，本质也是把ANTHROPIC_BASE_URL指向本地模型服务，区别只是模型能力、上下文长度和工具调用稳定性能不能撑起智能体的循环。

3.4 模型怎么选：别一上来就用最贵的

Claude Code 官方模型分三档：haiku（快、便宜，适合简单任务）、sonnet（默认，均衡）、opus（最强，贵，适合困难重构和复杂排错）。

我的选择习惯是：改配置、补注释、跑脚本这类"体力活"用 haiku；日常代码修改用 sonnet；只有遇到复杂的架构调整、跨多个文件的逻辑梳理时才切 opus。切换方法很简单——启动时加参数：

claude --model haiku

或者在会话里输入/model按提示切换。很多人全程用 opus 跑简单任务，结果账单一月下来直接懵了，这种浪费是不必要的。

4. 在 VSCode 里跑起来：终端集成、常用命令与第一轮对话

4.1 为什么我建议入门先别装插件

VSCode 里现在确实有 Claude Code 相关的官方插件，JetBrains 系也有对应插件。但我的建议是：入门阶段请先在集成终端里用纯 CLI 跑通一个任务。

原因有两个。第一，插件本质还是调用同一个 CLI，如果 CLI 本身不熟，插件只是多了一层让你困惑的 GUI。第二，Claude Code 的核心交互（权限确认、diff 查看、命令审批）都是为终端交互设计的，你先习惯终端里的操作逻辑，再套插件会顺畅得多。

在 VSCode 里打开项目，按Ctrl + `调出集成终端，确认当前目录是你的项目根目录，然后直接输入：

claude

就这一步，你已经在 VSCode 里用上 Claude Code 了。用不着改什么特殊配置，CLI 会自动继承当前终端的工作目录和 Git 上下文。

4.2 第一次启动：登录、/init 与项目记忆

第一次启动会走登录流程。登录成功后，我强烈建议你做的第一件事是输入：

/init

这个命令会扫描当前项目的语言、构建工具、目录结构，然后生成一份CLAUDE.md文件，里面写了这个项目怎么构建、怎么测试、代码在哪个目录、有什么约定。

千万不要小看这份文件。它相当于给 Claude Code 的"入职培训手册"，每次会话开始它都会默认读一遍。项目级的 CLAUDE.md 放在项目根目录，个人通用的可以放在~/.claude/CLAUDE.md，适合放你惯用的代码风格、commit 格式等个人偏好。

4.3 用一个真实小任务走完整个流程

假设你的项目里有一个配置文件，登录超时时间写死成了 3000 毫秒，你现在想改成 6000。直接对 Claude Code 说：

把登录超时时间从 3000 改到 6000，记得检查有没有测试用例引用了旧值，如果有就一并更新。

它会先搜索代码，定位超时配置定义的位置，可能是config.ts里的LOGIN_TIMEOUT = 3000，也可能在某个常量文件里。然后它会向你展示要改哪些文件、改成什么，请求你的确认。你按y或回车同意后，它真的动手改文件。

改完之后，你自己在终端里git diff看改动是否符合预期，再跑一遍相关测试确认没搞坏东西。确认没问题，再git add、git commit，第一次代码修改就完成了。

这个小流程看着平平无奇，但请记住一套黄金守则：让 AI 改之前，先确保项目的 git 工作区是干净的。如果当前有一堆你没提交的改动，AI 改完之后你根本分不清哪些是它改的、哪些是你之前的。习惯是每次动手前先git status看一眼，必要时开个新分支再干活。

4.4 权限、编辑模式与安全找回手段

Claude Code 提权干活时分几种模式，我平时用最多的是这三个：

• 默认模式：每步操作都问你，最安全，适合初学阶段。
• plan 模式：只分析不改代码，适合让它在动手前列计划。启动时用claude --mode plan。
• acceptEdits / bypassPermissions 模式：自动接受文件编辑或全部操作，适合非常信任的任务。慎用。

万一它改出问题了，最快的找回方式是 git：

git checkout -- .

这句话会丢弃当前分支所有未提交的改动，回到上一次提交的状态。平时我固定在一个干净的临时分支上让 Claude Code 干活，它改完我看着满意就 merge，不满意就直接删分支重来，几乎零风险。

5. 高频报错排查：context length、Windows 网络层错误与其他坑

5.1 “API error: 400 ... maximum context length is 10485”到底在说什么

这是接第三方模型时最常见的报错之一。报错字面意思是：当前模型允许的上下文长度上限是 10485 个 token，但这次请求需要的 token 量超过了它。

为什么请求会那么大？因为 Claude Code 在每一轮都会把系统指令、CLAUDE.md 内容、工具定义、历史对话全部打包发给模型。对话越长，每次请求的 token 越多。当模型本身上下文窗口很小时，比如某些模型的上下文上限只有 8K/16K，几乎聊不了几句就撞上限。

我的排查顺序是这样的：

1. 先看当前模型是什么。如果是 DeepSeek，确认用的模型名是不是deepseek-chat这类长上下文型号。
2. 如果模型没问题，那就是对话太长了。输入/compact压缩上下文，或者干脆开新会话。
3. 检查 CLAUDE.md 是不是塞了太多东西。我见过有人把整个项目的技术文档粘进去，几万字一读就爆。

这个报错的本质不一定是 bug，而是"项目复杂度 + 对话长度 + 模型窗口"三者不匹配。选对模型、控制对话长度，问题基本能消除。

5.2 Windows 上 “internetopenurl() failed. 0x800” 的根因与修复

这个报错在 Windows 上相当经典。报错出现在 CLI 执行需要联网的请求时，比如登录、拉取远程数据。根因出在 Node.js 的 fetch 实现上——Windows 版 Node 默认通过系统的 WinHTTP 发网络请求，它会读取系统代理设置，如果你的机器在公司内网、配了 PAC 代理脚本，或者装了 SSL 检测类安全软件，请求就可能被系统网络栈直接掐断，然后报出internetopenurl() failed。

修复方法我按推荐程度排：

1. 升级 Node 到新 LTS，然后设置NODE_USE_OPENSSL=1。这个环境变量会让 Node 的 fetch 改用 OpenSSL 实现，绕开 WinHTTP 那套系统代理逻辑：

set NODE_USE_OPENSSL=1

设置完重新打开终端，再跑claude。

2. 检查系统代理设置。如果你用的是系统自动代理（PAC），多半是它影响了 Node 的网络栈。在公司网络下，可以申请在安全策略里放行相关域名。
3. 实在排查不出来，试试换一个网络环境确认是不是本机的问题。

警告：网上有人让你直接设NODE_TLS_REJECT_UNAUTHORIZED=0跳过证书校验，千万别这样干。那等于把 HTTPS 的安全校验全关了，中间人攻击风险极大，尤其是要传输 API Key 的工具。

5.3 其他几个我见过的高频问题

• claude命令找不到：PATH 问题，重开终端，或者手动把 npm 全局 bin 目录加进去。
• npm 安装一直卡住：按第 2.3 节切换 npm 镜像源。
• 权限申请弹个没完：在 settings.json 里加permissions.allow白名单，把明确安全的命令（如Bash(npm test:*)）放行，别直接开 bypassPermissions。
• 改了代码但它不运行测试：很多项目测试命令复杂，它没有十足把握不会乱跑。你可以在请求里明确说"改完请执行npm test"，或者在 CLAUDE.md 里把测试命令写清楚。

6. 成本与缓存：长会话为什么贵，prompt caching 怎么用

6.1 先算一笔账：token 是怎么被"重复"收费的

很多人第一次被账单吓到，是因为没理解智能体的计费逻辑。普通对话你问一句它答一句，token 是一次性的。Claude Code 不一样——每一轮工具调用都会把当前全部上下文重新发送一次。

举个例子。你的项目文件加 CLAUDE.md 和系统指令大概 50K token，模型每执行一步操作（读一个文件、跑一条命令、改一段代码）都要带上这 50K 的"背景"。如果它完成一个任务需要执行 40 次操作，那光背景就消耗了 50K × 40 = 2M 的输入 token。会话开了几个小时，对话历史越来越长，从 50K 涨到 200K，那每个后续步骤的费用就变成 200K × N 次，自然越来越贵。

这还不是最坑的。如果你把一个会话放着不动几个小时再回来继续，冷落的这段时间里，本来生效的缓存已经过期了，下一次请求得重新算一遍全部上下文，费用立刻跳上一个台阶。"为什么一个会话等待几个小时之后耗费会大涨"，根因就在这：缓存过期 + 上下文已膨胀。

6.2 prompt caching 的读取规则：到底缓存了什么

缓存机制的核心逻辑是：模型提供商会把"会话开头那段不会变化的内容"缓存起来，下次请求如果前半段内容一致，就直接读缓存，这部分 token 的单价会便宜很多。

以 Anthropic 的官方实现为例，缓存的基本规则是：

• 缓存对象：系统指令、CLAUDE.md、历史对话里靠前且未修改的部分。一旦对话内容发生变化，从变化点往后的缓存全部失效。
• 缓存时长：默认缓存只在 5 分钟左右内有效，超过就清掉。开启ENABLE_PROMPT_CACHING_1H=1后可以延长到 1 小时。
• 成本结构：写缓存比正常输入贵（多约 25%），但读缓存比正常输入便宜非常多（价格可能低一个数量级）。

也就是说，缓存不是绝对的省钱。如果对话上下文每分钟都在剧烈变化，缓存频繁重建，你反而多付了缓存写入的溢价。它最划算的场景是"上下文稳定 + 大量重复请求"。

6.3 ENABLE_PROMPT_CACHING_1H=1 到底有没有用

这是一个被问了无数次的问题。我的回答是：有用，但有前提。

如果你的工作流是"一次性喝完一个会话，不中断"，那默认 5 分钟缓存基本够用，开不开 1 小时缓存差别不大。如果你经常聊到一半去开会、去 review 代码，隔半小时一小时再回来继续，那开启 1 小时缓存非常值，它避免了回来第一波请求重新算全部上下文的巨贵费用。

开启方法：

export ENABLE_PROMPT_CACHING_1H=1

或者写死在 settings.json 的环境变量里。

注意：如果你接的是 DeepSeek 这类第三方兼容接口，缓存行为完全由对方平台决定，很多第三方根本不缓存，这时候这个配置无效，别指望它省钱了。

6.4 控费实操清单

总结一份我自己的控费习惯，照着做能省不少：

• 按任务开会话。一个任务一个会话，做完就/clear或开新会话，别让无关内容堆积。
• 上下文大了立刻/compact。压缩后上下文变小，后续每步的成本都会下降。
• CLAUDE.md 保持精简。只写构建命令、测试命令、关键目录和硬性约定，不要把文档全文塞进去。
• 简单任务用 haiku。改个常量、写个脚本，完全没必要让 opus 上。
• 别长时间挂机。会话放着超过 5 分钟缓存就快过期了，确定要继续就别停太久。
• 细化权限，避免它执行一堆不必要的探索命令，比如把整个目录ls一遍又一遍。

7. 大型代码库实战与干净卸载：CLAUDE.md、.claudeignore、Skills 与卸载步骤

7.1 大仓库三板斧：CLAUDE.md、.claudeignore、精准 @引用

第一次把 Claude Code 丢到一个几十万行代码的大型仓库里，它的表现往往会让你失望，不是因为模型不行，而是因为信息过载。它会把所有文件都当成上下文候选，探索来探索去，看着热闹但效率很低。我的三板斧是：

第一，CLAUDE.md 画地图。明确告诉它：核心代码在src/，不要在vendor/、build/里浪费时间，构建命令是什么，测试怎么跑。这能省掉大量无效探索的 token。

第二，.claudeignore 划禁区。这个文件的作用类似.gitignore，告诉 Claude Code 哪些目录不读。举例：

build/ dist/ *.min.js docs/generated/

它默认就尊重.gitignore，但大型仓库里有些被 git 跟踪的杂目录，比如接口生成的客户端代码，也建议加进来。

第三，用 @ 精准引用。在对话里用@src/core/auth.ts这样的语法指定重点文件，它会优先读这些文件，比"你自个儿找去"高效得多。而且尽量一次只给它一个明确的小任务，别试图让它"一次性理解整个系统然后重构一遍"——那不是智能体的强项，是事故现场。

7.2 嵌入式与 Java 项目能不能用

回到前面提到过的 STM32 场景。我的观点是：能用，但不是开箱即用。嵌入式项目能否用 Claude Code 发挥价值，不取决于它，而取决于你的命令行工具链是否完整。make、cmake、arm-none-eabi-gcc这些能在终端跑了，它才能帮你改代码、执行编译、根据编译报错修复问题。

Java 项目的体验类似，只要mvn test或gradlew test能跑，它就能在改完代码后自动运行测试验证结果。所以我的建议是：在接给 Claude Code 之前，先把项目的命令行构建脚本整干净，这本身就是给项目长期健康做投资。

7.3 Skills 是什么，怎么手动装 GitHub 上的 skills

Skills 是 Claude Code 后来引入的一种能力扩展方式，相当于给智能体预装"某个场景的操作手册"。一个 skill 就是一个目录，里面有一份SKILL.md，用自然语言描述这个技能适用的场景、操作步骤、注意事项。

官方维护了anthropics/skills仓库，社区里也有很多第三方的。手动安装的方法是把它 clone 到指定目录：

git clone https://github.com/anthropics/skills.git ~/.claude/skills

或者只把其中某个 skill 目录复制到~/.claude/skills/<技能名>/。项目里也能用，放在项目根目录的.claude/skills/下。装好后在会话里输入/skills可以看到当前已加载的技能列表。

提示：社区 Skills 等于一段会被智能体执行的指令文本，来源不明的 skill 有可能诱导模型做危险操作。装之前看清楚 SKILL.md 内容，跟装软件前看权限申请是一个道理。

7.4 卸载与清理

如果你用了一段时间决定不常用了，卸载非常干净，核心一步是：

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

这会把命令行程序本身卸掉。接着考虑要不要清理配置文件：~/.claude/目录里存了你的配置、日志、认证信息。如果你确定不再用，可以整个删掉；如果要保留设置只删认证，建议先执行claude --logout清理登录态，再删对应的 credentials 文件。Windows 上记得检查%USERPROFILE%\.claude同名目录。

最后再分享一个我自己的体会：Claude Code 这类工具，用好的关键在于"先小人后君子"——权限、分支、配置文件规则，全都先行收紧，等信任积累了再慢慢放开。我见过太多人装完就全权委托，一个会话让它放手改整个模块，结果代码是能跑，但代码风格、边界处理、安全隐患全都跑了样。把它当实习生带，先让它在小任务上证明自己，再逐步扩大授权范围，这才是既快又稳的玩法。