企业官网建设流程全解析

简介：这份ClaudeCode实战指南代码包面向希望借助AI编程工具提升开发效率的开发者，从安装配置到高级功能均有覆盖。压缩包内共3个文件，包含inscode配置文件、HTML格式详细指南以及gitignore文件，整体仅5KB，轻便易得。已有840人学习下载。指南重点讲解了国内环境下的使用方案、智谱GLM4.5与Kimi K2模型接入、ClaudeCodeRouter扩展其他大模型，并深入介绍了子Agent系统、钩子系统、MCP Server配置、提示词技巧、三种工作模式切换与历史回退等进阶内容，同时涵盖多行输入、常用指令解释及自定义指令等基础操作，可帮助读者从入门到精通系统掌握ClaudeCode，有效提升日常编码效率，是学习AI辅助编程的实用参考资料。

1. ClaudeCode不是又一个套壳插件：真把AI拽进终端干活的命令行工具

作为一个在命令行里泡了十几年的工程师，我见过太多号称“AI编程”的工具：装在IDE里像个聊天框，写代码靠它、跑起来还是要自己抓瞎。ClaudeCode不一样——它是跑在终端里的原生AI编程代理，直接吃你的文件树、Git历史和终端输出，能自己读报错、改代码、跑测试，再回来告诉你改了什么。它不是网页版Claude的搬运工，而是一个把“上下文感知”做到极致的终端角色。适合谁？受够了IDE插件半吊子补全的人，手里攥着一堆老项目、想用AI快速梳理代码的人，以及想给团队搭一套可复用的AI工作流的人。这篇指南，就是围绕ClaudeCode的安装、配置、实战和排错整理的完整笔记。

2. 装对再用：安装、鉴权与模型接入的四个关键点

ClaudeCode看起来就是个npm包，但装完之后能不能跑顺，取决于你怎么装、用什么鉴权、接什么模型。这一章先把地基打牢。

2.1 两条安装路径与版本选择

最常见的做法是走npm全局安装：

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

这条命令把ClaudeCode装成全局可执行文件。npm install -g意味着它会写入npm的全局bin目录，claude --version用来第一时间确认装没装上。我一般装完顺手敲一下版本号，如果提示command not found，赶紧去查npm全局bin目录是否在PATH里。

如果不想污染全局环境，也可以用官网提供的安装脚本：

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

脚本方式本质也是下载可执行文件放到用户目录，好处是不依赖Node版本。这里要提醒一句：如果本机Node版本过旧，npm方式会出现依赖编译失败，脚本方式反而更省事。两条路选一条，别混着用，混装的后果是claude命令指向不确定，后患无穷。

2.2 鉴权方式：订阅登录与API Key两种走法

装完之后第一关是鉴权。ClaudeCode支持两种方式，适用场景完全不同。

订阅用户直接在终端执行claude，它会自动打开浏览器完成OAuth登录，登录后凭证存在~/.claude/.credentials.json里，之后每次调用SDK都自动带token。这种方式适合个人日常开发，最简单，但换机器就要重新登录。

另一种是走API Key，通过环境变量注入：

export ANTHROPIC_API_KEY="sk-ant-xxxxxxxx"

这种方式适合CI/CD流水线、服务器部署这类没有浏览器交互的场景。注意一个细节：环境变量设置之后，ClaudeCode会优先读环境变量，不会再去碰OAuth凭证。如果你之前登录过订阅账号，又设置了API Key，最终鉴权信息以API Key为准，别被日志里的"login as xxx"误导。

2.3 接入DeepSeek或其他兼容模型：改两个环境变量

ClaudeCode能跑不止一个模型。只要目标服务提供Anthropic兼容端点，改环境变量就能切过去，不需要重装。以DeepSeek为例：

export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic" export ANTHROPIC_MODEL="deepseek-chat" export ANTHROPIC_API_KEY="sk-your-deepseek-key"

这里三个变量缺一不可：ANTHROPIC_BASE_URL指向兼容端点的根地址；ANTHROPIC_MODEL指定模型名；ANTHROPIC_API_KEY填的是DeepSeek平台的key而不是Anthropic的。设置完成后跑一句claude -p "ping"，如果返回正常文本，说明链路通了。这套玩法在很多国内模型服务上都能复用，本质上ClaudeCode只认SDK协议，模型服务是谁它不关心。

2.4 验证安装是否可用的三个命令

装完别急着写代码，先跑一遍自检流程：

claude --version claude doctor claude -p "say ok"

claude doctor是内置诊断命令，会检查认证状态、配置文件和本地环境，有问题它会直接提示；-p是无交互模式，用来验证模型调用链路。三个命令全绿，才是真正把环境跑通了。我现在每次换机器，都强制走一遍这三条，能省掉八成环境问题。

3. 配置工作区：CLAUDE.md、MCP与权限边界

装好只是开始，让ClaudeCode听懂你的项目，需要三层配置：角色设定、外部工具接入、权限控制。这一章逐层拆。

3.1 CLAUDE.md：一句话说清项目规矩

ClaudeCode最核心的配置文件是CLAUDE.md，放在项目根目录。它相当于给AI的一份“入职手册”，每次对话开始时自动加载。我的做法是控制在一屏以内，只写四件事：

# 项目惯例 - 前后端分离，前端在 /web，后端在 /server - 后端框架为 FastAPI，Python 3.11 - 所有数据库操作必须走 SQLAlchemy 模型，禁止裸 SQL # 代码风格 - Python 代码用 black 格式化，行宽 120 - 提交信息格式：`type(scope): subject` # 禁止事项 - 不要修改 /migrations 下的文件 - 不要删除任何 test 文件 # 常用命令 - 测试：`pytest -q` - 启动：`uvicorn server.main:app --reload`

写这段文件的逻辑在于：AI默认不知道你的项目规矩，你给它什么边界，它就怎么干活。比如“禁止裸SQL”这条，能直接把AI往ORM上推，省得你每次review都纠正它。关键词是具体——写“代码风格统一”没意义，写“用black格式化、行宽120”才有效。

如果项目同时存在多个子目录，可以在子目录里再放一个CLAUDE.md，ClaudeCode会自动合并根目录和当前目录的规则，子目录优先。这个特性在大型monorepo里非常有用。

3.2 MCP配置：让ClaudeCode摸到外部系统

MCP是ClaudeCode接入外部工具的通道。装完自带一套文件系统能力，但真要操作GitHub、查数据库、读API文档，就得配MCP服务器。直接用命令添加：

claude mcp add filesystem -- npx @modelcontextprotocol/server-filesystem /var/www/my-project claude mcp list

这条命令注册了一个名为filesystem的MCP服务。add后面跟服务名和启动命令，npx是让它临时拉起Node包，最后一个参数是允许访问的目录。list确认注册结果。配完MCP，ClaudeCode就能调用filesystem工具做文件遍历，比默认能力更可控。

MCP配置存储在~/.claude.json里，想改就手动编辑，想删用claude mcp remove filesystem。有几个坑：MCP服务器地址必须是从ClaudeCode所在机器能访问的；本地文件类MCP务必把访问范围写小，我见过有人直接给根目录/，ClaudeCode全程裸奔。

3.3 权限控制：别让AI裸奔园子里乱跑

ClaudeCode默认会征求许可再执行命令，但修改文件等操作有时会放开。控制权限有两个手段：

claude --permission-mode plan claude --allowedTools "Read, Write, Bash, Edit"

--permission-mode plan让ClaudeCode只做分析和计划，不真正改动文件，适合代码评审场景；--allowedTools把可执行工具白名单限定死，不在列表内的工具直接拒绝。两种参数也可以组合，比如计划模式下仍允许读文件。

和权限配套的还有个重要概念：/permissions命令可以查看当前会话的所有权限设置，自定义规则写在~/.claude/settings.json里。我给团队搭环境时，会强制在settings.json里禁用WebFetch这类外联工具，避免AI乱抓第三方内容。

4. 实战工作流：从需求到提交的三种运行模式

配置就位，接下来就是真正用它干活。ClaudeCode支持三种运行模式，对应不同的开发节奏，我用实际场景逐个讲。

4.1 管道模式：一次性任务交给脚本链

处理“改个小东西”这类单次任务，用-p管道模式最合适：

echo "把 vue.config.js 里的 devServer.port 改成 8080" | claude -p "执行修改并告诉我改动内容"

管道模式的意思是：标准输入进来的文本作为任务描述，ClaudeCode跑完直接退出。优势是不开交互终端、不占会话，适合扔进脚本或Makefile里。-p后面那段是给ClaudeCode的指令，要求它做完修改还输出改动摘要，方便人工复核。

这种模式我常用于批量操作，比如Refactor前先跑一遍“找出所有已废弃的API调用”。它也有局限：上下文是独立的，不知道上次聊了什么。需要连续多轮任务时，就别用管道模式。

4.2 交互式会话：复杂开发的主力模式

Android UI相关的需求，我一般直接开交互式会话：

claude

进入会话后用自然语言描述需求，比如“在订单列表页加一个滑动手势，触发退款操作，参照 @OrderDetailPage.kt 里的样式”。ClaudeCode会自己读文件、改代码、跑构建。过程中我可以持续打断、追问、改方向，它保持整个上下文。

会话里几个高频斜杠命令：/context看当前加载了哪些文件，/compact压缩上下文，/clear清空重来。我习惯每20分钟敲一次/context——如果发现塞进太多无关文件，立刻用/compact瘦身，能有效防止它“忘事”。交互式会话适合需要多轮讨论的重构、新功能开发，也是日常使用占比最高的模式。

4.3 无人值守批处理：后台跑任务盯日志

还有一种场景是扔一个任务进去，人去做别的，跑完了回来看结果。比如：

claude -p "给 utils/date.py 补充类型注解，补齐缺失的 import，不修改逻辑" --output-format stream-json > claude_run.log 2>&1

这种组合的含义是：-p指定一次性任务；--output-format stream-json把输出改成流式JSON，便于后续解析；> claude_run.log 2>&1把标准输出和错误输出都重定向到日志文件。跑完查看日志里的result字段，就能看到改动文件列表和自述。

这个模式最适合代码迁移、注释补齐这类“工作量大但不需要讨论”的任务。注意点：任务描述必须给足约束条件，“不修改逻辑”这种边界词很重要。另外建议任务粒度拆小，一次只处理一个模块，别拿一个5000行的大目录试它，跑崩了日志会很长。

4.4 Git提交前的自检闭环

我习惯把ClaudeCode嵌进Git提交前的自检流程。具体做法是：

git diff --name-only | claude -p "根据变更文件生成提交信息，并指出可能的代码问题（不用修改）"

这条命令把git diff --name-only列出的变更文件列表喂给ClaudeCode，让它做代码评审并生成提交信息。它不会真正改动文件，只是输出建议，人工决定采纳与否。这一步等于代码被AI过了一遍，很多低级问题在提交前就被拦下来了。

5. ClaudeCode避坑手册：七个高频翻车场景

把ClaudeCode用熟的代价，是踩过不少坑。这一章直接写翻车记录，全程按“现象→原因→解决”走。

5.1 安装、鉴权与模型接入的三类问题

坑一：装完claude命令找不到现象：npm install没报错，但终端里敲claude提示command not found。 原因：npm全局bin目录不在当前用户的PATH里，Node装了但命令没暴露。 解决：先跑npm config get prefix拿到全局目录，比如/usr/local，再确认/usr/local/bin在PATH中；不在就写入shell配置。如果还不行，直接改用官网脚本方式安装，彻底绕过npm路径问题。

坑二：日志报401 Unauthorized现象：配置好API Key后，ClaudeCode启动即报401，或者跑到一半突然鉴权失败。 原因：大概率是环境变量只对当前终端有效，换了个终端窗口或重启后变量丢失；也可能是ANTHROPIC_API_KEY写成了别的key，跟登录账号冲突。 解决：把环境变量固定写入~/.zshrc或~/.bashrc，然后source一下再跑。写完了用env | grep ANTHROPIC确认变量已生效。如果同时登录了订阅账号，先退出登录，防止两套凭证互相打架。

坑三：接入DeepSeek后一直超时现象：claude -p "ping"要么长时间转圈，要么直接报连接超时。 原因：ANTHROPIC_BASE_URL写错了直接访问不存在的路径，或者模型名和平台不匹配；另外有些兼容端点的路径末尾带不带/anthropic有讲究。 解决：先确认BASE_URL以/anthropic结尾；再查平台文档确认模型名，填成deepseek-chat而不是deepseek-v2这类猜测名。最后用curl -v手动请求一遍兼容端点，看返回是不是200。

5.2 运行与上下文相关的四类问题

坑四：MCP服务器反复断连现象：MCP配置成功，但用着用着工具调不通，日志显示connection closed。 原因：npx首次拉起包需要时间，操作一快就超时；或者服务端目录在启动后才创建，文件工具找不到目标。 解决：手动先跑一次npx @modelcontextprotocol/server-filesystem /your/path，看有没有报错；确保目标目录在ClaudeCode启动前存在。再把MCP的启动超时参数调大，命令里加--timeout 30，给npx留足拉包时间。

坑五：ClaudeCode乱改文件现象：明明只让改一个文件，结果它顺手改了相邻的配置文件，甚至重排了导入顺序。 原因：权限白名单给得太宽，默认模式允许写文件时，它对“可写”的理解超过人的预期。 解决：立刻用--permission-mode plan降级，让它只出方案不动手；同时在CLAUDE.md里写下“只修改用户明确要求的文件，不得格式化无关代码”。涉及大规模重构时，先把整个目标目录用Git提交一次，多一个后悔药。

坑六：上下文越长越健忘现象：会话聊到三十分钟后，ClaudeCode开始答非所问，甚至忽略前面明确给的约束。 原因：长会话里的token被大量中间过程占满，它对早期指令的注意力衰减。 解决：不要一个会话干到底，阶段性成果出来就/clear开新会话；开新会话前把关键约束重新在CLAUDE.md里写清楚。另外常用/compact压缩历史，把早期对话浓缩成摘要，释放上下文空间。

坑七：卸载后残留旧配置现象：npm卸载后重装，老配置依然生效，改了设置不生效。 原因：~/.claude/目录和~/.claude.json不会随卸载删除，旧凭证、旧MCP配置全部残留。 解决：想彻底重来就手动清掉~/.claude和~/.claude.json再卸载：

npm uninstall -g @anthropic-ai/claude-code rm -rf ~/.claude ~/.claude.json

如果只是想保留MCP配置、重置登录态，就只删~/.claude/.credentials.json。

6. 让它更懂你的工程：上下文瘦身与自建命令两个进阶技巧

最后聊两个能明显提升使用体验的技巧，都是我日常反复在用的。

技巧一：会话瘦身组合拳。长项目里上下文膨胀是性能杀手。我现在的习惯是：每完成一个可验证的改动，就敲/compact做一次压缩；每到一个阶段里程碑，直接/clear开新会话，新会话里只保留CLAUDE.md和最近改动涉及的文件。如果发现ClaudeCode总在忘了“不要动test文件”这条规则，八成是上下文里无关内容太多，压缩一次就能救回来。/context这个命令我建议每分钟都可能用——它能让你看清模型眼睛里到底装了什么东西。

技巧二：自建斜杠命令。在~/.claude/commands/目录下新建一个Markdown文件，就自动注册成斜杠命令：

--- name: review description: 执行一次快速代码评审 --- 对当前工作区的未提交变更做代码评审，重点检查： 1. 是否有硬编码密钥或路径 2. 是否存在明显性能问题（循环里的查询等） 3. 错误处理是否完整 只输出问题清单和对应文件行号，不要修改代码。

保存为review.md后，任意会话里敲/review，ClaudeCode就会按这个模板执行评审。这套机制可以把团队规范沉淀成命令文件，新人上手直接就有了一套AI辅助质检流程。我就是在一次改坏别人代码的翻车之后，逐步建立起这条命令库的——从那以后，每次开始处理新需求前，我都强制先跑一遍/context确认状态，再决定开新会话还是续旧对话，整个过程已经成了肌肉记忆。希望这些从坑里爬出来的经验，能帮你少走一段弯路。

本文还有配套的精品资源，点击获取