企业官网建设流程全解析

最近我把 Claude Code 从安装到接入日常开发工作流完整跑了一遍，过程中踩了不少坑，也把整个链路摸顺了。Claude Code 是 Anthropic 推出的命令行 AI 编程助手，直接跑在终端里，能读你的项目目录、改文件、执行命令、跑测试，和那种“只能聊天补代码”的 AI 工具完全是两种用法。这篇是系列文章的第一篇，目标很明确：从零开始安装、登录、跑通第一个任务，再顺手把 VS Code、本地模型、MCP 这些高频需求配好。适合刚听说 Claude Code 还没动手的人，也适合装到一半卡住、正犹豫要不要卸载的人。

1. 安装前必读：Claude Code能做什么，两种计费模式怎么选

1.1 一句话说清它是干什么的

其实它就是一个跑在终端里的命令行工具。打开终端，输入claude，它就进入交互模式，可以直接对话。但它和普通聊天工具不一样的是，它天然有工作区上下文：你在项目根目录启动它，它会自动读取项目结构、git 状态、文件内容。你给它一个任务，比如“这个接口超时了，帮我排查一下”，它可以自己去看代码、加日志、跑测试，一步步把问题定位并修复。整个过程非常像你雇了一个远程实习生，给了它权限，它替你干活。

很多第一次用的人会问：这不就是 Copilot 吗？不太一样。Copilot 更像“输入法”，在你写代码时提供补全；Claude Code 更像是“执行者”，它接收的是一个更大的任务，自己决定怎么读文件、怎么改、怎么验证。说直白点，它是一个能在你的终端里长期工作的 agent，而不是一个弹窗补全工具。

1.2 计费模式：订阅登录和 API，到底用哪个

安装前建议先想清楚用哪种账号，两种方式区别挺大。

第一种是 Claude 账号登录，也就是 Pro/Max 订阅用户在终端里执行claude login，用浏览器授权。这种方式额度按订阅套餐计算，比如 Pro 套餐有每周限额，高峰期会遇到类似“your limits are temporarily boosted. your weekly Claude Code limit is 50% high”的提示，意思是本周额度显示已经用了一半，高峰期可能需要等额度恢复再继续。

第二种是 Anthropic API Key，设置ANTHROPIC_API_KEY环境变量。这种方式按实际消耗 token 计费，多退少补，适合频繁使用、对响应速度有要求的人，缺点是要预充值、盯着账单。

这两种方式的选择直接影响后面的登录步骤和额度策略。如果只是偶尔用一下，订阅登录更划算；如果是重度使用，API 按量计费更可控。我自己的习惯是：日常探索和轻量任务用订阅额度，跑自动化脚本、批量任务时切 API Key，两边互不干扰。

1.3 环境的硬性要求

Claude Code 本质上是一个 Node.js 编写的命令行程序，所以环境要求其实很宽松，但有几个版本坑必须先确认。

• 操作系统：Windows 10/11、macOS、主流 Linux 发行版都可以。
• Node.js：官方要求 18.0.0 以上，实际体验下来建议用 20 LTS 或更高。版本太老不仅装不上，装上也容易在登录时报莫名其妙的问题。
• npm：跟着 Node 一起装的就行，建议 6.14 以上，实际上新一点的 npm 版本对依赖处理更稳健。
• 终端：Windows 下用 PowerShell 7 或 Windows Terminal 体验更好，老版本 cmd 对渲染和中文支持都不太行。

检查 Node 和 npm 版本：

node -v npm -v

如果提示找不到 node，先去装 Node 再继续；如果 node 版本低于 18，建议用 nvm 或直接装新版。这里特别提醒一句：不要在同一台机器上试图绕过低版本的限制，Claude Code 的依赖库对旧 Node 兼容性很差，省这一步会在后面花十倍时间排查。

2. 安装实操：从命令行到跑通第一个任务

2.1 两条官方安装路径

第一个是 npm 全局安装，一条命令：

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

注意包名有作用域：@anthropic-ai/claude-code。网上有些教程写claude-code或anthropic-claude-code，都可能是旧包或第三方包，认准这个作用域名最稳。安装过程如果网络不稳定，npm 容易卡在下载阶段，可以先临时切到国内镜像源再装：

npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

第二个是官方原生安装器，适合不想碰 npm 的人：

curl -fsSL https://claude.ai/install.sh | bash

macOS 和 Linux 上可以直接用这个脚本，Windows 用户还是走 npm 更省事，或者提前装好 WSL 后在 WSL 内安装。

2.2 验证安装是否成功

装完之后，先检查版本：

claude --version

如果能输出版本号，说明命令已经进入 PATH。如果提示“claude 不是内部或外部命令”（Windows）或“command not found”（macOS/Linux），多数情况是 npm 全局安装目录没被加入 PATH。Windows 上先看 npm 全局根目录：

npm config get prefix

把输出的目录加到系统环境变量 PATH 里，再重开终端。macOS/Linux 上如果用的是 nvm，npm 全局包往往放在~/.nvm/versions/node/xxx/bin下，确认这个路径在 PATH 里。

新版本 Claude Code 还提供了一个自检命令，可以顺手跑一下：

claude doctor

这个命令会检查 Node 版本、登录状态、环境变量是否正常，遇到问题它会直接告诉你哪里不对。第一次接触这个工具的人，建议在登录前先跑一遍，能省很多排查时间。

2.3 登录认证：两种账号，两条路径

安装完成后，第一次运行claude会提示登录。

订阅用户直接在终端里执行：

claude

第一次启动会跳出一个链接，浏览器打开后确认授权，回到终端就能使用。这里有个常见问题：浏览器打开了但终端一直转圈，或者提示 403。多数原因是 Node 版本过旧，或者终端网络状态不稳定，可以先升级 Node 再试。如果反复失败，把登录凭证缓存清掉再试：

rm -rf ~/.claude/.credentials.json

API 用户走环境变量路线，不需要交互式登录：

export ANTHROPIC_API_KEY=你的APIKey

Windows PowerShell 下写成：

$env:ANTHROPIC_API_KEY = "你的APIKey"

这种方式对脚本化、CICD 场景更友好，因为不涉及浏览器授权。

2.4 首次启动：跑一个最简单的任务

登录成功后，进入项目目录，直接运行：

claude

看到提示符后，先不要急着写复杂需求。建议先输入/status查看当前模型、账号类型和本轮上下文占用情况。然后可以这样问：

“先看一下这个项目的目录结构，告诉我每个文件大致是干什么的。”

Claude 会开始读项目，给出结构梳理。这个过程可以直观感受到它和普通聊天的区别——它读的是真实文件，不是猜。任务完成后输入/exit或直接 Ctrl+C 退出。

这里特别提醒：Claude Code 在第一次执行有副作用的操作时，比如修改文件、执行命令，会询问你是否允许，并给出具体命令。比如它要执行git commit，会列出完整命令等你确认。这个机制叫权限确认，新手期建议保持默认的询问模式，熟悉后再考虑放权。我见过不少人在第一次使用时直接选“一直允许”，结果它把整个项目的文件格式化了一遍，后悔都来不及。

3. 进阶实用配置：VS Code、本地模型与 MCP

3.1 VS Code 集成：不是插件，胜似插件

Claude Code 官方没有出传统意义的“插件”，但 VS Code 集成方式反而更简单：在 VS Code 里直接打开集成终端，cd 到项目目录，运行claude，它就能看到当前项目文件。配合 VS Code 自身的文件树、diff 视图，一边和 Claude 对话，一边看它的改动，体验非常顺。

如果希望更深入的联动，可以安装官方扩展“Claude Code for VS Code”或社区相关扩展，原理上基本是在编辑器里嵌入一个 Claude Code 面板。无论哪种方式，核心都是保持 Claude Code 在正确的工作目录运行。不要在 VS Code 的全局终端里启动，然后指望它读某个特定项目——它是按当前目录来决定上下文的，目录错了，读到的内容就全是错的。

3.2 用 Ollama 接入本地模型

这个话题最近特别热，因为很多人既想体验 Claude Code 这种 agent 工作流，又不想每轮都消耗云端 token。理论上，只要本地模型服务能兼容 Anthropic API 格式，Claude Code 就能通过环境变量对接，Ollama 是最常见的选择。

第一步，确保 Ollama 已经运行，拉一个代码能力不错的模型：

ollama pull qwen2.5-coder:7b

第二步，设置环境变量：

export ANTHROPIC_BASE_URL=http://localhost:11434 export ANTHROPIC_MODEL=qwen2.5-coder:7b

然后正常运行claude。注意一点：本地模型不能完全替代官方模型，尤其是工具调用能力和超长上下文理解上差距明显。我实测下来，本地模型更适合做代码片段生成、解释、单元测试编写，但让它自主重构多文件项目风险偏大。另外 Ollama 的接口默认不完全等于 Anthropic 格式，实际使用往往需要一个小型适配层，或者换成兼容 Anthropic API 的服务端，社区里也有现成工具，本质都是在协议层做转换。如果不想折腾，也可以直接用 cc switch 这类第三方工具一键管理模型和供应商之间的切换。

3.3 接入 DeepSeek 等兼容模型

除了本地模型，把 Claude Code 接到 DeepSeek 这种事也有人尝试。DeepSeek 官方提供了 Anthropic API 兼容端点，配置起来非常顺：

export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic export ANTHROPIC_AUTH_TOKEN=你的DeepSeekAPIKey export ANTHROPIC_MODEL=deepseek-chat

设置完后运行claude，如果模型识别正常，就能开始对话。这里有个很典型的坑：如果你写了一个当前版本的 Claude Code 不认识的模型名，终端会直接报错“xxx is not a model this version of Claude Code recognizes”，然后停止自动补全。解决办法就是保持ANTHROPIC_MODEL的值为该平台官方支持的模型名，不要随便填别名。

3.4 MCP：让 Claude Code 能读数据库和文件

MCP 全称 Model Context Protocol，是 Anthropic 推动的开放协议，作用简单说就是给 AI 加“外接设备”：让它能读数据库、访问文件系统、调用外部服务。Claude Code 对 MCP 支持得不错，通过claude mcp命令来管理。

比如给 Claude Code 接一个 SQLite 数据库：

claude mcp add my-db -- npx -y @modelcontextprotocol/server-sqlite ./test.db

添加完后可以在 Claude Code 里输入/mcp查看已连接的 server，确认状态是 connected。以后你在对话里说“查一下数据库里 orders 表的数据”，它会通过 MCP 去读，而不是靠猜。文件系统、PostgreSQL、GitHub 等都有官方或社区 server。需要说明的是，MCP server 本质是给 AI 打开了一个可执行远程操作的通道，生产环境里务必按最小权限原则配置，别图省事把所有库都暴露给它。

3.5 省 token 的几个实用技巧

最后说一个大家最关心的问题：怎么少烧 token。我实践下来最有效的有几条。

第一，限制输出长度，设置环境变量：

export CLAUDE_CODE_MAX_OUTPUT_TOKENS=4096

数值越小，单次回复越短，token 消耗自然少。第二，有意识地压缩上下文。完成一个阶段后，让它先汇总要点，再在汇总基础上继续；不要连续几小时把大量源码日志直接灌进同一轮对话里。第三，用命令切换模型。对话中输入/model可以切换模型，简单任务切到便宜或轻量模型，复杂重构再切回旗舰。第四，让 Claude 先给方案，再动手改代码。你可以明确说“先不要改文件，只告诉我计划”，这能省掉大量改完又回滚的无效 token 消耗。

4. 和 Codex 相比，Claude Code 的定位差异

这段时间总有朋友问我“选 Codex 还是 Claude Code”，这俩确实经常被放在一起比。Codex 是 OpenAI 推出的类似 agent 产品，两者目标用户几乎重合，但实际体验侧重点不一样。下面这张表是我自己用下来的感受整理，不一定绝对权威，但至少能帮你快速定位。

4.1 两者到底差在哪：一张表格看明白

从我自己的体验来说，Claude Code 在“读懂大仓库”这件事上做得更细，它读文件的方式更像一个真正在翻代码的人，会自己确认依赖关系、搜索关键定义；Codex 则和 OpenAI 的工具链贴合更紧，日常快速问答、写一次性脚本时响应风格更直接。

4.2 我的选型经验：按任务类型切换

选型建议很直接：如果你已经重度使用 Claude 模型，那 Claude Code 的上下文风格和模型能力是衔接最自然的；如果你团队本来就在用 GPT 系列，或者依赖 ChatGPT 的协作流程，那 Codex 会更顺手。工具没有绝对好坏，更多看你的项目类型和习惯。

我自己的做法是两者都装，按任务类型分别用：读大仓库、做多文件重构时用 Claude Code，日常快速问答、写脚本时用 Codex。终端里装两个 agent 并不冲突，反而能互补。不要把选型当成站队，工具最终是拿来干活的。

5. 常见问题与排查技巧实录

5.1 PowerShell 安装报错

Windows 下最常见的报错有两类。一类是“无法加载文件……因为在此系统上禁止运行脚本”，这不是 Claude Code 的问题，是 PowerShell 执行策略限制。解决：

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

然后再试。另一类是安装时卡住或报网络错误。这种先把 npm 缓存清掉，再换镜像源安装，基本都能解决：

npm cache clean --force npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

5.2 登录返回 403

登录时打开浏览器授权后，终端提示 403，是问得最多的问题。依我的经验，按下面顺序排查：先看 Node 版本是否满足要求；再看授权回调是否被本地安全软件或系统防火墙拦截；最后清理凭证缓存重新登录。如果以上都试过还不行，改用 API Key 方式，不依赖浏览器授权，稳定性高很多。

5.3 终端乱码

Windows 默认代码页是 GBK，Claude Code 输出中文时容易乱码。切到 UTF-8 再启动：

chcp 65001

另外建议把终端字体调成支持中文和符号的等宽字体，部分疑似乱码其实是字体缺字形，换个字体就好。macOS 和 Linux 上这类问题少很多，基本不需要处理。

5.4 对话历史到底存在哪、怎么恢复

Claude Code 默认会保存对话历史和会话记录，不需要手动开设置。历史文件一般存放在~/.claude/projects目录下，按项目维度存成 JSONL 格式。想恢复某个历史会话，启动后输入：

claude --resume

回车后会出现历史会话列表，选择就能继续。想直接接着上一次对话继续，用：

claude --continue

这个功能很实用，特别是长任务做到一半关了终端，下次还能接着聊，上下文不会断。

5.5 识别不了第三方模型

如果你手动设置了本地模型或第三方模型，却看到类似“xxx is not a model this version of Claude Code recognizes”的报错，说明模型名写得不对，或者当前版本的模型清单里没有这个模型。处理方式：先去对应平台查询官方支持的模型名，填完整准确的名称；如果是本地 Ollama 模型，确认ANTHROPIC_MODEL的值和ollama list里显示的名字完全一致。报这个错时通常不会自动补全，因为工具根本不知道你指的是哪一个模型。

另外提醒一句关于“桌面版”的说法：Claude Code 官方目前的主体形态是 CLI 和编辑器集成，并没有一个官方独立的“桌面版 App”。网上搜到的“Claude Code 桌面版”很多是第三方封装或同名工具，安装前先确认来源，尽量走官方渠道，避免装到来路不明的包。

最后说点我自己的使用体会。Claude Code 和传统 AI 补全工具最大的不同，是它把“AI 写代码”从单点操作变成了完整的工作流：它会读文件、执行命令、跑测试、根据结果反复调整。刚开始用的时候，我习惯什么都让它直接改，后来发现最好的方式是人定方向、它做执行：让它先读代码给我结论，我确认后再让它动手，效率和确定性都高很多。

这个系列后续我还会继续写具体场景的使用技巧，包括怎么用好 Skills、怎么调 MCP、怎么在团队里统一配置。这一篇先把安装和基础配置搞定，剩下的后面慢慢聊。