企业官网建设流程全解析

1. Claude Code 到底是什么，配置之前先搞清楚这几点

Claude Code 是 Anthropic 官方推出的终端型 AI 编程代理，本质是一个跑在命令行里的 AI 工程师：它能直接读写你项目仓库里的文件、在终端执行命令、查看报错、运行测试，然后根据结果不断自我修正。换句话说，它不是一个"聊天机器人"，而是一个真正能动手干活的 AI Agent。

很多人第一次运行 Claude Code 的时候会觉得"就这？"——原因很简单，默认配置下它只是一个什么都能干但什么都不精的通用助手。真正让它值钱的，是那套嵌套的配置体系：记忆文件、权限规则、子代理、技能扩展、MCP 工具。把这套东西配好，它才真的像一个能上手的工程团队成员；配不好，它就是一把没装保险的电锯，帮你改代码的同时也会帮你把仓库搅得天翻地覆。

这篇指南我会按照自己实际踩坑验证过的路径来写，覆盖从环境准备、安装登录、核心配置、编辑器集成，到 Skills 扩展、工作流搭建和常见故障排查的完整链路。适合刚接触 Claude Code 的新手，也适合想在团队里统一配置、把 AI 编程这件事管起来的技术负责人。看完之后你至少能回答三个问题：该怎么装、该怎么配、配完怎么用才不会翻车。

2. Claude Code 安装与环境准备：从零到能跑起来的完整流程

2.1 先检查 Node.js 环境，这一步别偷懒

Claude Code 是 npm 包，所以第一步是保证 Node.js 环境到位。我建议 Node.js 版本至少在 18 以上，太老的版本装完之后会报各种奇奇怪怪的错，比如SyntaxError或者模块加载失败，排查起来非常浪费时间。检查方式很简单：

node -v npm -v

如果机器上没装或者版本太低，直接去 Node.js 官网下 LTS 版本安装就行。装完之后一定确认 npm 全局安装目录在 PATH 里，否则后面claude命令会提示"command not found"。

这里有个非常典型的坑：很多开发者的 macOS/Linux 是用 nvm 装的 Node，全局包的路径是~/.nvm/versions/node/vxx.x.x/bin。如果你新开一个终端窗口，shell 没有自动加载 nvm，就会遇到"明明npm list -g能看到 claude-code，执行claude却提示找不到命令"的诡异情况。解决办法是检查 shell 配置文件（.bashrc/.zshrc）里有没有 nvm 的初始化脚本，没有就补上，然后source一下。

2.2 Git 环境与仓库状态

Claude Code 在项目里干活时大量依赖 git：查看 diff、理解提交历史、回滚错误改动、生成 commit 信息。所以目标目录必须是一个已经初始化的 git 仓库，机器上也必须装好 git 并且配置了用户名和邮箱。如果没配置，它会连 commit 都提交不上去，那个报错信息又藏在日志深处，非常容易被忽略。

git config --global user.name "Your Name" git config --global user.email "you@example.com"

顺便提醒一句：如果你准备让它在仓库里自由发挥，先确认当前分支干净（git status没有大量未提交的改动），或者先手动 commit 一次。否则它改到一半你想回退，会发现工作区和它改动的文件混在一起，分不清哪些是它的、哪些是你自己的。

2.3 安装 Claude Code 本体

环境就绪之后，安装本体只需要一行命令：

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

装完先验证版本：

claude --version

能输出版本号说明装好了。claude命令本身启动交互式终端界面，claude --help可以查看全部子命令。日常用得比较多的几个是：

• claude：进入交互模式
• claude -p "任务描述"：一次性执行，用于脚本和自动化
• claude --resume：恢复上一次会话
• claude --continue：接着最近的会话继续聊
• claude --output-format json：以 JSON 格式输出，方便程序解析

2.4 登录与认证的三种方式

Claude Code 需要认证之后才能调用模型接口。实战中我常用三种方式，按场景选：

1. Claude 账号 OAuth 登录。首次运行claude，终端会输出一个授权链接，在浏览器里打开并登录账号授权即可。这种方式最简单，适合个人电脑。
2. ANTHROPIC_API_KEY环境变量。适合服务器、Docker 容器、CI/CD 或者不想走浏览器授权流程的场景。设置方式：

   export ANTHROPIC_API_KEY="你的key" claude

3. ANTHROPIC_AUTH_TOKEN环境变量。适合团队统一管理密钥的场景。比如你不想把个人 API Key 散给每个成员，而是由后端统一签发 token，各成员只填 token 就能访问统一账户额度。

这三种方式在同一台机器上同时存在时，优先级可能会影响你最终用的是哪个账户。我的习惯是：个人电脑用 OAuth，服务器和 CI 一律用环境变量传 key，绝不写死在配置文件里——因为settings.json可能会被同步到版本库，key 一旦提交上去就相当于裸奔了。

3. Claude Code 核心配置拆解：CLAUDE.md、settings.json 与权限体系

3.1 CLAUDE.md 记忆体系：让 AI 记住规则，而不是每次重新教

这是整个配置体系里最值得花时间的部分。Claude Code 在每次会话中会读取一组记忆文件，其中最重要的是CLAUDE.md。它分为三个层级：

• 用户级：~/.claude/CLAUDE.md，全局生效。适合写个人偏好，比如"我是 Rust 开发者""默认不要动 package-lock.json""回答精炼，不要长篇大论"。
• 项目级：项目根目录的CLAUDE.md，跟着代码一起提交，团队共享。适合写项目架构说明、技术栈、目录结构、常用命令、编码规范。
• 项目本地级：CLAUDE.local.md，不提交到版本库。适合写只有你本人需要的上下文，比如本机数据库连接方式、临时调试脚本的位置。

我在项目级 CLAUDE.md 里通常会写这些内容：

• 项目一句话简介和技术栈
• 目录结构说明：哪个目录放什么，哪些目录不要碰
• 构建、测试、Lint 的准确命令，最好带参数
• 编码规范：命名习惯、格式化工具、禁止事项
• 常见坑位：比如"改 A 模块必须同步更新 B 文档""这个目录下的代码是自动生成的，不要改"

写的时候有一条铁律：只写事实和规范，不要写"你应该""请务必"这类没有信息量的废话。CLAUDE.md 是给模型读的上下文，信息密度越高越好。另外文件不要太长，控制在 200 行以内，否则模型读起来会"累"，反而抓不住重点。

初始化阶段可以直接在交互界面里运行/init，Claude Code 会分析当前仓库并自动生成一份 CLAUDE.md 草稿。但我建议把它当草稿看，里面的内容往往偏泛，你得自己补上那些真正的"团队隐性知识"。

3.2 settings.json 参数详解：全局、项目、局部三层覆盖

Claude Code 的配置有两个来源：一是在交互界面里用/config命令修改，二是直接编辑 settings.json 文件。配置文件的层级有三个：

• 用户级：~/.claude/settings.json
• 项目级：项目根目录.claude/settings.json，会提交到版本库
• 项目局部：.claude/settings.local.json，仅本地生效

优先级是 local 高于项目级、项目级高于用户级，也就是说越靠近当前项目、越私人的配置，越能覆盖全局的默认值。

我自己常用的一份项目级 settings.json 长这样：

{ "model": "claude-sonnet-4-20250514", "permissions": { "defaultMode": "acceptEdits", "allow": [ "Bash(git status)", "Bash(git diff)", "Read(CLAUDE.md)" ], "deny": [ "Bash(rm -rf *)" ] }, "env": { "MY_SERVICE_URL": "http://localhost:8080" }, "includeCoAuthoredBy": true }

几个关键字段说明：

• model：指定默认模型。不同模型在速度、推理能力、上下文长度上差别很大，建议把简单任务和复杂任务分开用不同模型。
• permissions：权限规则，下面专门讲。
• env：给 Claude Code 的运行环境注入自定义环境变量。适合告诉它测试环境的地址、外部服务的端口，不需要写进系统环境变量。
• includeCoAuthoredBy：如果为 true，它生成的 commit 信息会自动带上Co-authored-by署名，方便团队追溯哪些提交是 AI 写的。

注意一点：每次改完 settings.json 之后，需要重开会话或者运行/config刷新，否则不生效。我见过不少朋友改了权限规则之后发现没变，其实是还在旧会话里没刷新的缘故。

3.3 权限管理：放权与收权的平衡

Claude Code 默认对部分危险操作会弹确认框，比如执行 bash 命令、写入文件、修改删除文件。这个机制是保护你仓库的最后一道闸门，但每次弹框也确实烦人。权限体系支持按工具名和参数模式做精细控制。

我常用的权限配置方式：

# 全局允许所有 git 状态查询 claude config set -g allowedTools "Bash(git status)" # 允许执行特定前缀的 npm 脚本 claude config set -g allowedTools "Bash(npm run test:*)" # 允许读取特定文件 claude config set -g allowedTools "Read(CLAUDE.md)"

权限规则的匹配是支持通配符的，这意味着你可以只放开一小簇命令，而不是全盘放行。我的建议是"先收后放"：刚开始使用所有默认受限配置，等摸清它的行为模式之后，再把那些高频且安全的操作逐个加进白名单。

千万注意，不要图省事直接给Bash(*)全放行。AI 在执行rm -rf的时候可不会先征求你意见，它只会忠实执行你交给它的任务链条，而任务链条里某个看似无害的中间步骤，完全有可能把整个目录清空。我在测试环境里亲眼看过它把 node_modules 之外的目录一并删掉，亏得是测试仓库，不然心态直接崩了。

4. VS Code 集成与桌面端：把 Claude Code 塞进日常开发环境

4.1 在 VS Code 里跑 Claude Code，体验能提升一个档次

很多开发者习惯图形界面，离开 IDE 就没有安全感。好消息是 Claude Code 可以直接在 VS Code 的集成终端里跑起来，这样你就同时拥有了 IDE 的文件浏览、代码高亮、断点调试，以及 AI Agent 的自动执行能力。

具体做法有三种，按推荐的优先级排：

1. 安装官方 VS Code 扩展。扩展装好后，在侧边栏或命令面板里可以直接启动 Claude Code 会话面板，它会自动识别当前打开的工作区，还能直接在代码文件里看到它的修改建议和 diff。这种方式体验最好，因为 AI 改动的痕迹可以直接对照。
2. 在 VS Code 内置终端里手动运行claude。适合那些不想装任何扩展、又需要和编辑器同屏协同的场景。打开终端面板，cd 到项目根目录，运行claude就能开聊。注意窗口尺寸不要太窄，终端太窄的话它的排版会很难看。
3. 用 VS Code 的多终端并行。这个是我日常最常用的模式：一个终端窗口跑 Claude Code 让它写功能，另一个终端窗口跑测试命令人工盯结果，第三个窗口跑git status观察它到底动了哪些文件。

第一项扩展如果还没适配你的 VS Code 版本，装完之后可能需要重启一次窗口。另外要提醒的是：扩展面板里的会话和终端里的会话是独立的，两边不会自动同步对话历史，所以你起一个会话之后最好固定在一个入口里继续，别一会儿面板一会儿终端来回切。

4.2 桌面端与多窗口并行：一个人的 AI 团队怎么开

Claude Code 提供了桌面端的形态，本质上是一个可以同时打开多个会话窗口的图形化入口。这时候"构建你的 AI 工程团队"这句话才真正落地：你可以开三个窗口，A 窗口负责前端页面，B 窗口负责后端接口，C 窗口负责写测试用例。每个人工窗口互不干扰，只要你机器的资源扛得住。

用多窗口并行有个大前提：不同窗口承担的职责必须有明确的、不重叠的任务边界。如果你让两个窗口同时改同一个模块，它们互相不知道对方动了什么，最终结果就是文件冲突、逻辑重复、互相覆盖，你收拾残局的时间比让它们干活的时间还长。

我的建议是一个窗口管一个垂直领域，并且通过下面的角色定义文件把各自的行为约束清楚。这样它们才能像真正的团队一样分工协作，而不是一群各说各话的"野生实习生"。

5. Skills 与 MCP 扩展：给 AI 工程团队配专业装备

5.1 Skills 机制：让 Claude Code 掌握你的"独门绝技"

Skills 是 Claude Code 提供的能力扩展机制，本质上是让模型在特定场景下自动加载一组预置的指令和流程。你可以把它想象成给 AI 写"岗位说明书"：当它遇到某类任务时，会先去读对应的说明，再按说明里的步骤和方法执行，而不是凭通用经验自由发挥。

Skills 的目录结构是这样的：

.claude/ skills/ frontend-review/ SKILL.md checklist.md

其中SKILL.md是这个技能的核心定义文件，文件头部是 YAML frontmatter，用来声明技能的名称和用途；正文部分用自然语言描述这个技能的适用场景、执行步骤、注意事项和输出格式。

我自己写过一个"前端代码审查"技能，里面会要求 Claude Code：先定位改动文件、再检查类型定义、然后核对样式是否有硬编码、最后给出三档严重级别的结论列表。配完之后，我只需要说"用 frontend-review 审查一下我刚才改的页面"，它就会自动按这套流程输出结构化审查结果，比让它自由发挥稳定得多。

Skills 的价值在于沉淀：团队里那些资深工程师脑子里"看到这类问题应该怎么查"的隐性知识，可以被固化成可重复执行的指令，让 AI 也能按专家的思路干活。

5.2 MCP 接入外部工具

MCP（Model Context Protocol）是让 Claude Code 接入外部数据源和工具的统一协议。比如你可以通过 MCP 服务器让它直接查数据库、调内部 API、搜索项目文档、读写 GitHub Issue，而不是靠你手动把信息贴进对话里。

添加一个 MCP 服务器的命令格式：

claude mcp add my-db -- env DATABASE_URL=xxx npx my-db-mcp-server

也可以通过项目根目录的.mcp.json文件统一声明，这个文件的好处是可以提交到版本库，团队所有人拿到代码之后，Claude Code 会自动发现并加载同一组 MCP 配置。

.mcp.json的结构大概是：

{ "mcpServers": { "github": { "command": "npx", "args": ["@modelcontextprotocol/server-github"], "env": { "GITHUB_PERSONAL_TOKEN": "xxx" } } } }

配置好了之后，用claude mcp list可以查看当前已经加载的 MCP 服务器。我在实际项目中接入最多的是 GitHub 类和数据库类 MCP，接入之后 Claude Code 能自己去看 Issue、拉分支、查数据，但这些都属于"高危能力"，建议在权限配置里单独收紧，不要让它在无人值守场景下随意调用外部系统。

6. 用 Claude Code 搭工作流：角色定义、自动化钩子与无人值守

6.1 用 agent 定义文件拆分角色

在"构建 AI 工程团队"这个目标下，最核心的一步是给不同的 AI 实例定义不同角色。Claude Code 支持通过子代理定义文件来约束一个会话的行为边界。

子代理定义文件放在.claude/agents/目录下，每个.md文件代表一个角色。文件头部同样是 YAML frontmatter，声明名称、描述、可用工具、使用的模型；正文写这个角色的详细行为规范。

举个例子，我项目里有三个常用角色：

--- name: backend-engineer description: 负责后端接口和数据库相关任务 tools: Read, Write, Edit, Bash model: claude-sonnet-4-20250514 --- 你是后端工程师。接到任务时先看 CLAUDE.md 了解项目结构，再定位相关模块。 写代码时必须补充单元测试，数据库改动必须附带迁移脚本。

文件名（不含扩展名）就是角色的名字。在交互会话里用/agents可以查看和管理当前仓库可用的角色。给 AI 明确角色定义之后，输出的质量稳定性会明显提升，因为它们不再是"什么都会一点的通用助理"，而是"有明确职责边界的团队成员"。

6.2 Hooks：在关键节点插入你的控制逻辑

Hooks 是 Claude Code 设置项里的自动化钩子，可以在特定事件发生时触发外部脚本。支持的事件包括工具执行前、工具执行后、会话结束等场景。

举个例子，我想强制要求每次 Claude Code 执行 Bash 命令之前都先记录一条日志到文件：

{ "hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "echo \"运行命令: $(cat -)\" >> ~/.claude/cmd.log" } ] } ] } }

Hooks 的价值在于把 AI 的行为纳入你的既有流程：比如提交之前自动跑一遍 linter、改动文件之后自动更新某个文档索引、或者把 AI 的操作记录下来供审计。这比事后翻聊天记录靠谱得多。

6.3 无人值守与 CI/CD 集成

Claude Code 支持一次性执行模式，适合无人值守场景。命令格式：

claude -p "修复 tests/login.test.ts 里失败的用例，跑通测试后提交代码"

结合--output-format json可以拿到结构化的执行结果，方便后续脚本判断是否成功。

在 CI 流水线里，我见过比较稳的用法是：把 Claude Code 作为"自动修 bug 机器人"跑在固定 job 里，当测试失败时自动拉取失败日志，交给它分析并生成修复 PR。这种方式能节省大量排查时间，但前提是配置好权限、密钥和超时时间，并且限定它只能操作特定分支和特定目录，绝不放开对主分支的直接写权限。

无人值守和交互模式有一个显著差异：没有人盯着，AI 更容易跑偏。所以我的经验是：无人值守任务的描述必须极其具体，包含明确的验收标准，比如"必须通过npm test"或"不得修改 src/payment 目录"。任务描述越模糊，它自由发挥的空间越大，出事的概率也越大。

7. Claude Code 配置实战排坑：安装、登录、权限、卸载全记录

7.1 安装失败与命令行找不到的问题

安装阶段最常见的两个问题：第一，npm 全局安装权限不足，报EACCES错误。解决方案是不要用 sudo 硬装，而是把 npm 的全局目录改到用户目录下，或者用 nvm 管理 Node 版本，避免权限问题。

第二，明明装了却提示command not found。这个大概率是 npm 全局 bin 目录不在 PATH 里。验证一下：

npm prefix -g

如果这个目录确实不在你的 PATH 中，把它加到.bashrc或.zshrc里即可。如果你用的是 Windows PowerShell，则要在系统环境变量的 Path 里手动添加 npm 全局目录。

7.2 登录认证失败

认证失败通常表现为启动之后一直提示未经授权。排查顺序：

1. 确认环境变量是否被正确读取：运行echo $ANTHROPIC_API_KEY，看是否有值。
2. 确认是否有其他认证方式冲突：比如同时存在 OAuth 登录态和 API Key 环境变量，可能导致请求凭证不一致。
3. 确认密钥是否有权限访问你请求的模型。配上之后刷新会话再试。

/status命令可以查看当前会话的连接状态、模型信息和认证主体，这是排查认证问题最直接的入口。

7.3 权限被拒与"卡在确认框"

很多新手配置完权限之后发现 AI 还是频繁弹确认，或者直接被拒绝执行。排查思路：

• 检查权限规则是否写到了正确的配置文件层级。比如你在用户级配置的规则，可能被项目级配置覆盖了。
• 确认规则语法是否正确。权限匹配支持通配符，但不同工具的参数匹配格式不一样，写错了就直接被拒。
• 看看是否触发了deny规则。deny 的优先级高于 allow，某些被你写进黑名单的命令，即使 allow 里有也白搭。

建议在交互会话里运行/permissions，它会列出当前生效的完整规则集和匹配情况，比对着三个文件猜来猜去高效得多。

7.4 卸载与配置重置

如果你想彻底卸载 Claude Code 并清理全部配置：

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

然后手动删除配置文件：

rm -rf ~/.claude

切换到一个不想要 AI 残留的仓库目录，检查并删除项目下的.claude目录和仓库根目录的CLAUDE.md（如果不想保留）。注意项目级.claude/settings.json和CLAUDE.md是会被提交到版本库的，团队项目里要不要删，先问一声队友。

如果只是想重置行为、不想卸载，可以直接删掉~/.claude/settings.json或项目级.claude/settings.json，Claude Code 会恢复到默认配置，不需要重装。

7.5 常见问题速查表

8. 配置完善之后，我最后想说的一点体会

这套配置体系我用了几个月，最大的感受是：Claude Code 的能力上限，取决于你愿意花多少心思给它立规矩。它就像一块完全空白的主板，默认能跑，但跑成什么样全看你怎么接线。CLAUDE.md 是给它输指令集，settings.json 是给它画赛道，权限规则是给赛道装护栏，Skills 和 MCP 是往主板上插功能卡，Hooks 是接上你现有的流水线。

很多人配置到一半就放弃了，因为他们期待的是一个"开箱即用、无所不能"的黑盒，而实际上 Claude Code 更像一个需要磨合的新同事。你必须清楚告诉它项目背景、边界和验收标准，它才能在你放心的范围内发挥实力。花一个下午把记忆文件、权限规则和几个常用技能配好，之后每天省下来的时间远远不止一个下午。

最后再给一个小建议：每次 Claude Code 升级之后，记得看一下官方更新日志和claude --help的输出。这个工具迭代速度极快，配置字段和命令参数经常会有变化，这篇指南里提到的字段也可能在后续版本里改名。把配置当成代码来维护——版本化、可复查、有注释，你的"AI 工程团队"才会越用越顺手。