企业官网建设流程全解析

Claude Code 是 Anthropic 出品的终端 AI 编程代理，核心价值不是“再给你一个聊天窗口”，而是让 AI 直接参与项目的读取、修改、命令执行和文档维护。它既能帮你把想法变成可运行代码，也能把现有代码整理成文档，正好对应标题里的“软件 + 文档”两条线。

这次我们直接拆一套完整的 Claude Code 使用流程：从环境准备、安装启动，到 VS Code 扩展、桌面版、CLI 配置，再到第三方模型接入（比如 DeepSeek）、Skills 功能、非交互调用和批量任务。最后把安装和运行阶段最容易翻车的几个坑列成排查清单，照着处理就行。

文章面向三类人：想把 Claude Code 当主力编程助手的开发者、需要自动生成和维护项目文档的技术写作者、以及想在 Claude Code 里接第三方模型或做批量调用的工程化玩家。

1. Claude Code 核心能力速览

从这张表能看出，Claude Code 的门槛主要在“环境配置”和“账号/模型接入”，不在显卡。这和本地跑大模型是完全两类玩法。

2. 适用场景与使用边界

Claude Code 适合谁？最典型的是日常在终端里干活的人。它和 IDE 插件不同，它天然工作在文件系统和命令行的上下文里，能自己读目录、改文件、跑测试，你只需要盯着它干活并随时审批。

适合场景：

• 快速写代码原型。比如写一个 Python 脚本、批量处理工具、数据清洗脚本。
• 理解陌生代码库。让它在仓库里检索，然后给你解释模块关系和调用链。
• 自动生成项目文档。基于代码生成 README、接口说明、变更记录。
• 规范化日常提交。根据 diff 生成 commit message。
• 终端里的自动化流程。用非交互模式批量处理一批文件。

不适合场景：

• 超大规模代码库的完全自主重构。这类操作 AI 很容易改出错，必须逐 diff 审查。
• 对隐私和合规要求极高的企业项目。代码会发送到第三方模型服务端，敏感信息要避免直接放进会话。
• 完全离线环境。Claude Code 本身不是本地模型，没有网络或没有可用 API 时无法工作。

使用边界必须明确：Claude Code 会读取你允许它读取的文件，会执行你在终端里批准的命令。使用前要核对项目是否有敏感凭据、密钥、客户数据；涉及受版权保护代码、人脸、声音、内部资料等场景时，需先取得授权。不要把生产数据库连接串、私有证书、未脱敏用户信息直接丢进对话。

3. 环境准备与前置条件

在安装 Claude Code 之前，先把环境检查一遍。这套流程在 Windows、macOS、Linux 上思路相同，只是终端命令略有区别。

3.1 检查 Node.js 和 npm

Claude Code 通过 npm 分发，所以 Node.js 是硬依赖。先确认终端里有没有：

node -v npm -v

如果显示node: not found，需要先安装 Node.js。Windows 上可以去官网下载 LTS 安装包；macOS 可以用 Homebrew：

brew install node

Ubuntu / Debian 可以通过 apt 安装，但要注意 apt 源里的 Node 版本可能偏旧，装完再确认一下版本。

3.2 准备终端工具

• Windows：建议用 PowerShell 或 Windows Terminal，避免在旧版 CMD 里折腾编码问题。
• macOS：系统自带 Terminal，也可以使用 iTerm2。
• Linux：常见发行版自带终端即可。

3.3 准备账号或 API 密钥

Claude Code 官方使用需要可用的 Anthropic 账号或 API 密钥。不同版本对登录方式要求不同，以官方文档为准。如果要用第三方模型，则需要准备对应的模型服务地址和 API Key，并确认它兼容 Anthropic Messages API 格式。

3.4 磁盘和网络

Claude Code 本身体积很小，但会生成一些配置和缓存。建议留出 1GB 以上空间。网络方面需要能正常访问对应 API 服务，如果在特殊网络环境里访问不稳定，解决网络连通性是前提，不在本文讨论范围内。

4. Claude Code 安装与启动

安装方式很直接，核心命令就是 npm 全局安装。

4.1 Windows 安装

在 PowerShell 或 CMD 中执行：

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

安装完成后，检查是否成功：

claude --version

常见的 Windows 问题是 PowerShell 执行策略限制。如果运行claude时报错提示 “无法加载文件 … because running scripts is disabled on this system”，需要放开当前用户的脚本执行权限：

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

然后重新打开终端，再执行claude --version。

4.2 macOS 安装

同样使用 npm：

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

如果提示权限不足，不要直接使用 sudo，推荐先修复 npm 全局目录权限，或者直接安装 nvm 后重装 Node.js。生产环境里用 sudo 装全局 npm 包容易留下后续升级权限问题。

4.3 Ubuntu / Debian 安装

Linux 上安装依赖 Node.js 环境。npm 全局包默认安装位置是/usr/lib/node_modules或/usr/local/lib/node_modules，需要让 PATH 包含对应目录。安装命令一致：

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

装完后如果找不到claude，先看 npm 的 prefix：

npm prefix -g

然后把prefix/bin加进 PATH。常见的 prefix 是/usr/local，对应的 bin 是/usr/local/bin。

4.4 首次启动与登录

在任意项目目录打开终端，执行：

claude

首次运行会进入认证流程。官方账号模式下，需要登录并完成设备授权；API Key 模式下，在提示位置粘贴密钥即可。认证完成后会生成本地配置，之后启动会直接进入交互界面。

看到欢迎语和提示输入框，说明安装启动成功。

5. 在 VS Code 中使用 Claude Code

VS Code 配置 Claude Code 是很多人关心的点。安装扩展后，操作路径从纯终端扩展为“编辑器内交互 + 文件上下文 + 终端命令执行”，对日常写代码更友好。

5.1 安装 VS Code 扩展

在 VS Code 扩展市场中搜索 “Claude Code for VS Code”，安装官方扩展。注意：扩展只是前端，底层仍然依赖 CLI 组件。

安装完成后重启 VS Code，在侧边栏或命令面板中找到 Claude Code 入口。

5.2 配置要点

扩展首次连接时，需要确认 CLI 是否可用。如果启动失败，多半是claude命令不在 VS Code 继承的 PATH 里，这种情况在 macOS 和 Linux 上尤其常见，因为 VS Code 不一定会加载 shell 配置文件。

解决办法是在 VS Code 的settings.json里显式指定 CLI 路径，例如：

{ "claude-code.path": "/usr/local/bin/claude" }

也可以先确认系统里which claude或where claude的路径，再填进去。

5.3 体验定位

VS Code 扩展适合边看代码边提问的场景。比如打开项目文件后，可以让 Claude Code 解释当前文件逻辑、直接生成修改 diff、运行测试并反馈结果。对纯 CLI 用户来说，这个扩展不是必需品，但能降低上手门槛。

6. 桌面版安装与使用说明

Claude Code 桌面版在部分版本和平台下提供。它的特点是带图形界面，适合不习惯纯终端的用户，但核心能力仍然依赖本地 CLI 组件。

安装方式：从官方渠道下载对应平台的安装包，或通过命令行安装器执行。不同平台、不同版本安装方式有差异，以官方发布说明为准。

使用中常见错误是启动时提示 “Claude app host ... binary not available. Check that the download ...”。这通常说明本地 CLI 组件缺失、安装不完整或者版本不匹配。排查思路：

• 检查是否已经用 npm 安装了@anthropic-ai/claude-code。
• 查看安装日志，确认下载过程是否中断。
• 卸载后重新安装 Claude Code，再重启桌面版。
• 如果桌面版和 CLI 版本不一致，优先更新 CLI 到最新版本。

桌面版适合把 Claude Code 当独立工具使用，批量操作和脚本集成还是更依赖 CLI。

7. 接入 DeepSeek 等第三方模型

从热搜词可以看出，很多人在折腾“Claude Code 接入 DeepSeek”“Claude Code + CC Switch + DeepSeek”。这里先说结论：Claude Code 能不能用第三方模型，取决于该模型厂商是否提供 Anthropic 兼容的 API 端点，或者有没有现成的中转工具。不是随便填一个模型名就能用。

7.1 为什么会出现 “model not recognized” 错误

很多用户遇到类似：

deepseek-v4-pro is not a model this version of claude code recognizes

这类报错第一层面是模型 ID 不被当前客户端识别。可能原因有三个：

• 模型名称写错。不同提供商的模型 ID 不同，例如同一个厂商可能有大模型、快速模型、推理模型，名称完全不同。
• 当前 Claude Code 版本不认识这个模型 ID。需要更新 Claude Code，或使用对应版本支持的模型名称。
• 当前 API 地址和模型 ID 不匹配。比如用 A 平台的地址，填了 B 平台的模型名。

解决方法不是硬改代码，而是先确认你用的模型服务商到底提供哪些模型 ID。

7.2 用 CC Switch 管理多模型配置

CC Switch 是社区常用配置管理工具，用来在 Claude Code 的不同 API 供应商配置之间快速切换，适合同时使用官方模型和第三方模型的人。

使用思路：

1. 安装并打开 CC Switch。
2. 添加多个配置：官方配置、DeepSeek 或其他第三方配置。
3. 每个配置填写 API 地址、API Key、模型名称。
4. 切换后重新启动 Claude Code。

这里的关键参数是 API 地址和模型名称，必须和供应商实际提供的一致。

7.3 手动配置第三方模型

如果你不想用图形工具，也可以直接通过环境变量或 Claude Code 配置来覆盖默认端点。通用模板：

export ANTHROPIC_BASE_URL="https://your-api-provider.example.com" export ANTHROPIC_API_KEY="your-api-key" export ANTHROPIC_MODEL="your-model-id"

注意：这是通用模板，具体变量名和值要以你使用的 Claude Code 版本以及模型供应商文档为准。Windows 下用 PowerShell 时，设置环境变量语法不同：

$env:ANTHROPIC_BASE_URL="https://your-api-provider.example.com" $env:ANTHROPIC_API_KEY="your-api-key" $env:ANTHROPIC_MODEL="your-model-id"

启动前可以先检查模型服务是否在线，再启动claude，避免把网络问题当成配置问题。

8. 软件实战：从 0 到 1 创建一个文件扫描工具

纸上谈兵没有意义。下面用 Claude Code 完成一个真实的小项目：写一个 Python 文件扫描工具，并生成对应文档。项目很小，但能完整走一遍“需求 - 编码 - 执行 - 验证 - 写文档”的链路。

8.1 创建项目并启动 Claude Code

在终端执行：

mkdir folder-scan cd folder-scan claude

8.2 输入需求

在 Claude Code 对话中输入：

请创建一个 Python CLI 工具 folder_scan.py，需求如下： 1. 接受一个目录路径作为参数。 2. 递归列出目录下所有文件，输出为树形结构。 3. 只使用 Python 3 标准库，不要安装第三方依赖。 4. 增加 -o 参数，可以把结果保存到指定文件。 5. 完成后运行 python folder_scan.py . -o output.txt 验证。 6. 如果验证通过，写一个 README.md，说明安装和用法。

8.3 观察执行过程

Claude Code 会读取当前目录、创建文件、执行命令。这里要盯住几个关键点：

• 它是否创建了folder_scan.py。
• 它执行验证命令前，是否请求你的确认。
• 它是否根据执行结果调整代码。
• 最后是否生成README.md。

如果中途失败，比如 Python 脚本报错，Claude Code 通常会根据终端输出重新修改并重试。你需要做的是审核 diff，而不是直接让它自行狂奔。

8.4 验证结果

退出 Claude Code 后，自己执行一次：

python folder_scan.py . -o output.txt

查看output.txt内容是否符合预期。再看一眼README.md是否包含安装、用法、参数说明。有问题就重新启动claude，让它补齐。

这类小项目能验证 Claude Code 的“软件能力”到底靠不靠谱。建议第一次使用者都从这种小工具开始，不要直接拿生产仓库测试。

9. 文档实战：用 Claude Code 维护项目文档

Claude Code 写文档的能力，其实比写代码更稳定。它擅长阅读文件、整理结构、生成规范化文本。常见用途：

• 给项目补 README。
• 生成 API 接口说明。
• 把散落在代码注释里的信息整理成正式文档。
• 对比代码状态和已有文档，找出过时内容。

9.1 自动生成 README

在项目根目录启动claude，输入：

阅读当前项目的代码结构，理解主要功能。请生成一份 README.md，要求： 1. 项目名称与简介。 2. 安装步骤。 3. 使用示例。 4. 目录结构说明。 5. 常见问题。 不要修改任何源代码。

生成后亲自检查一遍，重点看 README 里的命令和参数是否和代码真实实现一致。

9.2 用 CLAUDE.md 固定文档规范

Claude Code 支持项目级指令文件，常见的文件名是CLAUDE.md。把文档规范写进去，后续每次会话都会遵守。

示例：

# 项目规范 - 所有新增 API 必须在 docs/api.md 中补充说明。 - 文档注释使用中文，代码注释使用英文。 - README 更新时需同步修改 CHANGELOG.md。 - 不要在文档中写入密钥、内部地址、个人信息。

有了这个文件，Claude Code 在生成文档时就会带上约束，比每次对话重复强调效果好得多。

9.3 文档和代码同步校对

写完文档后，可以继续向 Claude Code 提问：

检查 docs/api.md 是否和当前代码一致，列出所有不一致的地方。

这个能力适合做发布前的技术文档审计。

10. Skills 入门：定义可复用技能

Claude Code 的 Skills 功能在热词里出现频率很高。简单理解，Skills 是给 Claude Code 预置的“技能包”，把一类任务的步骤、脚本、约束打包，在需要时按技能名调用。适合把团队内部固定流程沉淀下来。

10.1 典型应用场景

• 代码 review 技能：规定审查顺序、关注点、输出格式。
• 文档生成技能：预置模板、语气、目录结构。
• 测试执行技能：规定测试命令、失败处理方式、报告输出位置。
• 数据脱敏技能：规定哪些字段不能出现在输出里。

10.2 配置结构

Skills 通常由一个目录和一个说明文件组成，核心文件是SKILL.md。位置可以在用户全局配置目录，也可以在项目目录里，具体看版本支持。

SKILL.md示例：

# skill: generate-changelog ## 描述 根据 git log 生成 CHANGELOG.md，按 Conventional Commits 格式分类。 ## 步骤 1. 运行 git log --oneline -20。 2. 解析提交信息，按 feat/fix/docs/refactor/chore 分类。 3. 生成 CHANGELOG.md，保留最近 10 条变更。 4. 如果存在已有版本号，则追加到当前版本区块。 ## 约束 - 不要修改源代码。 - 不要生成空分类。

配置好后，在对话中直接说“使用 generate-changelog”，Claude Code 就会按步骤执行。不同版本对 Skills 的加载路径和触发方式可能不同，建议先查看当前版本的说明文档。

11. 非交互模式与批量任务

Claude Code 的 CLI 支持非交互模式，这是批量任务和自动化集成的基础。可以先看帮助：

claude --help

非交互模式的核心是-p或--print参数，直接传 prompt，输出结果到 stdout。通用示例：

claude -p "阅读 src/utils.py，用三句话概括它的功能"

11.1 批量生成文档

假设有一个项目列表文件projects.txt，每一行是一个项目路径。可以用脚本循环调用：

while read project; do cd "$project" claude -p "阅读当前项目，生成 README.md" > /dev/null done < projects.txt

注意：批量循环会消耗大量 token，也可能触发接口限流。建议在循环里加输出日志和停顿。

11.2 批量代码审查

对一批文件逐个生成审查意见，输出到独立文件：

for file in src/*.py; do claude -p "请审查 $file，指出潜在 bug 和改进建议" > "reports/$(basename $file).review.md" done

这种批量任务适合交付前的代码自检，但不要当作正式 review 的唯一依据。

11.3 失败重试与日志

批量任务必须考虑失败场景。最简单的做法是每个任务输出一个日志文件：

for file in src/*.py; do echo "Processing $file" claude -p "请审查 $file" > "reports/$(basename $file).md" || echo "$file failed" >> batch_errors.log sleep 2 done

通过||捕获失败，并在结束后查看batch_errors.log。

12. 资源占用与运行观察

Claude Code 是云端推理，本地不跑大模型，因此不占显存。主要资源开销在终端、Node.js 进程和网络请求。

观察点：

• 内存占用。执行大项目分析时 Node.js 进程内存可能会有明显上升，但正常使用一般不构成瓶颈。
• 网络请求。每次问答都会产生网络延迟，长文本响应需要更多时间。
• 终端输出量。批量任务建议把输出重定向到文件，避免终端被刷屏。
• token 消耗。大批量任务前先小范围测试，确认单次任务的 token 消耗量，再评估成本。

如果出现长时间无响应，先看网络是否正常，再看是否触发了限流。和本地推理不同，Claude Code 的响应速度更多由云端服务状态决定。

13. 常见问题与排查方法

14. 最佳实践与使用建议

第一，先用小成本项目做通全流程。不要一上来就让 Claude Code 重构整个仓库，先让它写一个 100 行的脚本并生成 README，建立信任后再扩大任务范围。

第二，配置好 CLAUDE.md。项目规范文件能显著提升输出稳定性。把禁止事项写清楚，比事后再纠正 10 次更省事。

第三，批量任务做好日志、重试和 token 成本控制。可以用一个最小任务先估算平均成本，再决定批量规模。

第四，涉及隐私和数据安全时，默认“不传”比“传了再说”安全。API 密钥、数据库连接串、个人信息、企业机密，都不应该出现在 prompt 里。

第五，发布或商用前的代码和文档，务必人工复核。Claude Code 生成的内容不能替代最终审核。

15. 总结与下一步

Claude Code 最值得尝试的点，是把 AI 从“聊天生成代码片段”推进到“直接参与项目文件与命令执行”。最先应该验证三个功能：CLI 安装启动、VS Code 扩展连接、CLAUDE.md 项目规范是否生效。

最容易踩的坑集中在两个环节：一是第三方模型配置时模型 ID 不匹配，二是批量任务没有控制频率导致限流。前者用官方模型 ID 核对机制解决，后者用日志和 sleep 解决。

后续可以继续扩展的方向：把常用流程沉淀成 Skills，在团队内统一编码和文档规范；用非交互模式对接 CI 流程，做提交信息生成、代码审查辅助、文档同步；在多个模型供应商之间用 CC Switch 配置快速切换。

Claude Code 不是替代开发者的工具，而是把你从重复性文件操作和文档维护里解放出来的终端助手。先把安装和第一个小项目跑通，后面就顺了。