企业官网建设流程全解析

1. 配置体系的设计逻辑：为什么偏偏是这三件套

我第一次接触 Claude Code 的时候，跟大多数人一样，先找安装教程，装完就急着让它写代码。跑通第一个 demo 之后，第二个念头才是“这玩意儿到底怎么调教”。这时候你会遇到一个绕不开的问题：同一个 Claude Code，为什么别人用起来像资深结对编程搭档，我用起来像刚入职还老忘事的实习生？答案几乎都在配置里。

Claude Code 的配置体系主要分成三块：settings.json、CLAUDE.md和memory。光看名字，很多人会以为settings.json是配置文件，CLAUDE.md是项目文档，memory是聊天记录，然后各配各的就完事了。实际上，这三者的分工完全不在一个维度上。

1.1 三者的分工：参数、规则与记忆

一句话概括就是：settings.json管“你能给 AI 什么”，CLAUDE.md管“你应该告诉 AI 什么”，memory管“AI 应该记住什么”。

具体拆开看：

• settings.json是行为和权限的开关。它决定 Claude Code 用什么模型、允不允许自己执行某类命令、要不要带环境变量、hook 怎么挂。这部分对应的是“工具层”配置，不依赖具体项目。
• CLAUDE.md是项目语义的载体。它告诉 Claude Code“这个项目是干什么的”“代码规范是什么”“构建命令怎么跑”“有哪些不能碰的目录”。这部分对应的是“项目层”配置，每个仓库应该有一份。
• memory是跨会话的长期记忆。它保存那些“你上次已经说过、这次不用再重复”的信息。比如你习惯用 pnpm 不用 npm，比如你上次告诉它“这个服务的部署脚本别动”，这些内容在下次新开会话时还能生效。

三者之间的关系，像一个公司的三层架构：settings.json是行政制度，规定谁能进哪个办公室、能用什么设备；CLAUDE.md是岗位说明书，说清楚这个项目该怎么干活；memory是工作笔记，记录你平时口头交代过的事情。缺了任何一层，AI 要么没法干活，要么不知道正确干法，要么反复问你同样的问题。

1.2 配置分层的核心优势：为什么不是一个万能文件

有人会问：为什么不搞一个巨大的配置文件，把所有东西都塞进去？答案很简单：配置的“上下文”不同，决定了它们必须分层。

settings.json如果塞进项目文档，那么换一个项目就要重写一遍；CLAUDE.md如果写进全局配置，那么这个 AI 在每一个项目里都会用同一套规则，遇到风格迥异的仓库就乱套；memory 如果全塞进CLAUDE.md，那文档会越来越长，最后超过上下文窗口，反而拖垮模型的理解能力。

我见过一个很典型的反面案例：有人把团队 coding style 巨细无遗地写进了全局的CLAUDE.md，然后所有项目共享。结果 A 项目用的是相对路径引入模块，B 项目强制绝对路径，AI 拿到全局规则后，在 B 项目里依然坚持 A 的写法。原因就是全局规则优先级覆盖了项目规则，这类冲突就是分层不清造成的。

所以这套三层设计，本质上是把“环境变量、项目规则、临时交代”这三个生命周期完全不同的信息分开管理。该全局的全局，该项目的项目，该记住的记住，该忘记的忘记，这才是配置体系的正确打开方式。

2. settings.json 实操：把全局行为捏在手心

聊完设计逻辑，先从最基础的settings.json讲起。这是 Claude Code 的全局配置入口，位置一般在用户目录下的.claude文件夹里，文件名就叫settings.json。如果你不知道它在哪里，直接在终端里运行claude之后，用/config命令就能看到当前生效的配置路径。

2.1 settings.json 都管些什么

先看一个比较典型的示例文件：

{ "model": "claude-sonnet-4-20250514", "forceLogin": false, "permissions": { "allow": [ "Bash(npm run dev)", "Bash(git status)", "Read(README.md)" ], "deny": [ "Write(credentials.json)", "Bash(rm -rf *)" ] }, "env": { "MY_CUSTOM_ENV": "some-value" }, "hooks": { "PostToolUse": [ { "matcher": "Read", "hooks": [ { "type": "command", "command": "echo '文件被读取了' >> /tmp/read_log.txt" } ] } ] } }

逐项看一下：

model指定默认模型。不是所有人都需要这一项，因为官方一般会自动选择最合适的模型。但如果你有明确偏好，比如某些任务希望用更快更便宜的模型来跑，这一项就很有用。有些版本还支持model用环境变量的方式去指定，方便做多环境切换。

permissions是大多数人最容易忽略、却最重要的一项。默认情况下，Claude Code 执行命令前会弹确认框。如果你信任它跑某些低频安全命令，可以放进allow列表里省掉确认环节；像删除操作、敏感文件读取这类危险动作，建议写进deny，从根上拦住。这里的规则支持 prefix 匹配、正则等多种写法，我在实际使用中最常用的是Bash(git ...)这种带命令前缀的写法，既放行了常见的 git 操作，又不至于把整个 Bash 都放开。

env是环境变量注入。做 AI 编程工具接入第三方模型的时候，经常会用到ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY这类变量，与其每次在终端里 export，不如写进settings.json，让 Claude Code 每次启动自动带好。

hooks是事件钩子。比如在 AI 读取某个文件、执行某条命令后，触发一段脚本做日志、通知或者格式检查。这个属于进阶玩法，普通人前期不一定要配，但知道有它，后面做自动化审计时会很顺手。

2.2 一个能直接抄的团队级配置

给一套我自己的配置逻辑供参考：

1. 先用/config打开配置文件，确认当前生效路径。
2. 把常见且安全的命令放进allow：git status、git diff、git log、npm run dev、npm test这类，避免频繁打断。
3. 把高风险命令全部deny：rm -rf、git push --force、直接写云服务器密钥文件等。
4. 在env里配置项目需要的环境变量。
5. 如果团队用统一模型，那model字段也建议锁死，避免有人用自己账号的模型导致结果不一致。

这套配置最大的价值是：减少 AI 干活时的确认打断，同时保证底线安全。我实测下来，配好permissions之后，AI 跑常规任务的顺畅度明显提升，基本不用坐在旁边一直点“允许”。

2.3 改配置容易踩的坑

最先要提的坑，就是热词里反复出现的报错：auto-update failed: no write permission to npm prefix。这个问题基本都出在 npm 全局目录权限不对上。Claude Code 默认倾向自动更新，但如果 npm 的全局目录被安装在系统保护区域，或者你用了 nvm 但权限配置不当，更新时就会卡住。

我的解决办法很直接：把 npm 的全局目录改到用户目录下，然后重新安装 Claude Code 并设置环境变量。

npm config set prefix ~/.npm-global export PATH=~/.npm-global/bin:$PATH npm install -g @anthropic-ai/claude-code

改完后再测试一次更新，如果还不行，检查一下当前用户对~/.npm-global是否有写权限。

另外要注意，settings 是分层的，常见的层级有全局层、项目层、本地层。项目目录下也可以放.claude/settings.json，它的优先级比全局高，适合做团队级项目规范覆盖。这个特性特别适合 monorepo 这种多团队协作场景，父目录配基础规则、子项目覆盖偏差规则。

3. CLAUDE.md：项目的“使用说明书”

如果说settings.json是让 AI 跑起来，那CLAUDE.md就是让 AI 跑对方向。它是整个配置体系里工作量最大、收益也最明显的一块。

3.1 为什么项目级配置最值得投入

CLAUDE.md解决的是语境缺失问题。把 AI 丢进一个陌生的代码仓库，它就像一个第一天入职的工程师：不知道项目结构、不知道构建命令、不知道代码风格、不知道哪些目录是生成产物不能碰。你可以在每次对话开头用自然语言把背景讲一遍，但会话一长、上下文一多，它就忘了。更现实的是，每个新会话都要重讲一遍，效率极低。

而CLAUDE.md是一份固化下来的项目说明，Claude Code 每次启动会话时会自动读取。这相当于把“入职培训手册”写成了文件，AI 每次开工前先读一遍，天然就带着项目语境。我在团队里推行的经验是：一个仓库至少有一份根目录的CLAUDE.md，里面写清楚“3 分钟上手”级别的关键信息。

3.2 自动载入机制与文档组织

这里要澄清一个常见误区：CLAUDE.md不只是放到根目录就有用，关键在于理解和利用它的自动载入范围。

Claude Code 在启动时会自动读取项目根目录、当前目录以及某些特定子目录下的CLAUDE.md。这意味着：

• 根目录的CLAUDE.md适合写全局规范：项目介绍、构建命令、目录结构、约定。
• 子目录的CLAUDE.md适合写局部说明：比如src/api/CLAUDE.md专门讲 API 层的规范，scripts/CLAUDE.md专门讲脚本使用方式。
• 用户目录下的~/.claude/CLAUDE.md则相当于个人偏好设置，适合作者的通用习惯，比如输出语言偏好、常用工具链偏好等。

这套层级跟 CSS 的优先级有点像：离当前目录越近的CLAUDE.md，优先级越高。所以我建议团队把通用规范放根目录，把局部规范放子目录，不要把所有内容堆到一个文件里。文件一长，AI 读起来会花更多 token，还会稀释重点。

3.3 一份合格的 CLAUDE.md 应该包含什么

直接给个结构模板：

# 项目名 ## 项目简介 - 一句话说清楚这个项目是干嘛的 ## 常用命令 - 开发: npm run dev - 测试: npm test - 构建: npm run build - 类型检查: npx tsc --noEmit ## 目录结构 - src/ 源码 - dist/ 构建产物，不要手动改 - scripts/ 辅助脚本 ## 代码规范 - 使用 TypeScript，禁止 any - 组件命名用 PascalCase - 业务逻辑写在 services/ 下，不要在组件里写 ## 重要约定 - 不要修改 database/migrations 下已发布的迁移文件 - 提交前必须跑 lint - 新功能默认走 feature branch + PR ## 常见问题 - 端口被占用怎么办：先 lsof -i :3000 找到进程再处理

写CLAUDE.md有个原则：只写“AI 不读会导致做错事”的内容。废话和常识不要写，比如“代码要清晰可读”这种，写了反而稀释重点。我见过有人把几十页架构文档整本塞进去，结果 AI 抓不住重点，连最基本的构建命令都要重新摸索。

另一个技巧是：遇到 AI 做错事，先问自己“它缺什么信息？”然后把缺失信息补进CLAUDE.md。比如某次它把构建产物提交到了 git，我就在文档里加了句“dist/ 是生成目录，禁止提交，构建命令是 npm run build”。之后再也没有犯过同类错误。这就是把CLAUDE.md当成一个不断迭代的“AI 防错手册”来维护。

3.4 命令行快速操作技巧

日常使用中，不一定每次都要手动编辑文件。Claude Code 内置的/init命令可以自动生成一份基础CLAUDE.md——它扫描项目结构、读取关键配置后，会生成初版文档。但注意，/init生成的版本通常比较粗糙，只能作为起点，还是要人工补充项目特有的约定和禁忌。

另外，对话过程中如果临时想补充规则，不用跳出会话去改文件，可以直接用/memory或让 AI 在对话里记住，之后再统一同步到CLAUDE.md。这样该更新的规则不会漏，最终维护在文档里也能沉淀下来。

4. memory：让 AI 记住该记住的

memory这个关键词，可能是三个配置里听起来最玄乎的。很多人以为 Claude Code 会像人一样自动记住所有历史对话，其实不是。这里的 memory 本质是一套可读写、可管理的持久化上下文，把它理解成 AI 的“备忘录”更准确。

4.1 memory 到底是啥

Claude Code 的 memory 主要由两部分构成：一是CLAUDE.md中的# Memory区块，二是/memory命令管理的临时记忆条目。前者是静态、持久的文件记忆；后者是动态、灵活的会话记录。日常使用中，“把某件事记住”通常是往 memory 里加一条，下次会话自动生效。

举个例子：你在一个项目里告诉它“部署窗口是每周二上午十点，其他时间不要执行发布命令”。如果这句话只写在当前会话里，下次新会话它就忘了。但如果把它写进项目的CLAUDE.md的 memory 区块，或者用/memory存下来，下次它会自动带着这个信息进入工作状态。

# Memory - 部署窗口固定为每周二 10:00-12:00，其他时间禁止执行发布命令 - 本项目使用 pnpm 而非 npm - 线上数据库凭据存放在 ~/.secrets/prod.env，不要读取其他位置 ## 2025-05-20 - 用户决定放弃旧的 `utils/legacy.js`，新代码禁止引用它

这里有个细节：memory 里加日期，是为了让 AI 知道哪些记忆是“临时的、可能过期的”。比如部署窗口这种可能变更的信息，加个日期后，过期后手动更新或删除就一目了然。

4.2 记忆的边界怎么划

用 memory 时最容易犯的错，是把它和CLAUDE.md搞重了。我自己的划分标准是：

• 永久事实：项目用什么包管理器、禁止修改哪类文件、团队规范，这些放CLAUDE.md正文。
• 近期临时决定：某次讨论后定下的方案、某次踩坑后得出的结论、某条还没固化到文档的约定，这些放 memory。
• 纯聊天记录：既不重要也不影响工作，直接不存。

这么说吧，CLAUDE.md是“公司章程”，memory 是“周例会纪要”。纪要攒多了，重要的要沉淀进章程，不重要的就删掉。很多用户一听说有 memory 功能，就疯狂往里面塞指令，到了最后记忆条目上百条，AI 反而被互相矛盾的旧记忆干扰。我的建议是：定期给 memory 做减法，每月花十分钟清一遍过期条目。

4.3 记忆的局限与坑

记忆不是万能的。它受上下文窗口限制，理论上单个会话内能携带的记忆量有上限，塞太多低价值信息，反而会挤占真正重要的项目上下文。

另一个我实际踩过的坑是：memory 和CLAUDE.md内容冲突时，AI 可能以临时记忆为准，导致行为不一致。比如CLAUDE.md写“提交前跑 lint”，但某次在 memory 里加了一句“这个项目 lint 很慢，跳过”，后面 AI 就一直跳过 lint，直到你发现提交记录里全是格式问题。所以修改 memory 时要检查它有没有跟既有规则冲突，如果冲突了，先改文档、再同步删掉临时记忆。

5. 常见报错与排查实录

配置体系讲完了，最后把热词里高频出现的报错和疑难场景汇总一下。这些都是新手最容易撞上的墙，我按排查顺序整理成速查表。

5.1 经典报错：auto-update failed / npm prefix 无权限

这个在 2.3 里已经说过原因和方案，这里补充一个排查顺序：

1. 先跑which claude看安装位置，然后npm config get prefix看 npm 全局目录。
2. 如果 prefix 指向系统目录比如/usr/local，按上文方法改到用户目录。
3. 如果已经改到用户目录还报错，检查目录所有者：ls -ld ~/.npm-global。
4. 在 nvm 环境下，也可以试试退出 nvm 后直接用系统 node 重新安装。

注意：不要用sudo npm install -g强行提权。这样虽然能装上，但后续每次更新都会遇到权限问题，而且会留下安全隐患。

5.2 WSL 下安装与模型接入的问题

很多开发者在 Windows 下用 WSL 跑 Claude Code。WSL 环境里最常见的坑是路径映射和 Node 环境混乱。我的建议是：在 WSL 内部完整安装一套 Node 工具链，不要在 Windows 侧装完再去 WSL 里调用，因为路径隔离容易出怪问题。

# 在 WSL 里安装 nvm 后 nvm install --lts npm install -g @anthropic-ai/claude-code claude --version

模型接入这块，被问得最多的是“Claude Code 能不能用别的模型”。答案是能，但要看具体版本的支持情况。通用做法是通过环境变量指定 API 的 base URL 和 key：

export ANTHROPIC_BASE_URL="https://your-endpoint.example.com" export ANTHROPIC_API_KEY="your-key" claude

这些变量也可以写进settings.json的env里，避免每次手动 export。接第三方兼容模型时，建议先确认它兼容 Anthropic API 协议，否则连上了也可能行为异常。另外，用非官方模型时，很多工具链特性（比如部分 hooks、permission 规则）可能不完全兼容，遇到问题记得优先怀疑模型层。

5.3 配置不生效的排查清单

配置写了不少，AI 好像没按我说的做，这是新手第二高频的困惑。大部分时候，问题出在以下四点：

一个值得记住的习惯是：改完配置后，重启 Claude Code 会话再验证。有些配置是在启动时加载的，不重启就跟没改一样。

5.4 排查思路：先分层、后看日志

如果真的遇到疑难杂症，别急着卸载重装。按“分层排查”思路走：先看是不是系统环境问题（Node 版本、npm 权限、网络连通性），再看是不是配置层问题（路径、优先级、语法），最后才怀疑程序本身。

遇到程序异常时，可以用claude --debug跑一个复现操作，查看日志输出，大部分问题都能从日志里找到线索。我也建议把claude升级到最新版，很多诡异的 bug 其实在新版本里早就修了。

结尾

配置这套东西，本质上是在给 AI 写使用说明书。你花半小时把settings.json、CLAUDE.md、memory三者搭建好，后期节省的是无数个重复解释、踩坑纠正的会话时间。

我个人在实操中的体会是：一开始不用追求“一步到位”。先搭一个最小可用的组合——settings.json配好权限和模型，CLAUDE.md写好命令和目录约定，memory 遇到问题再追加。用着用着，每次 AI 犯错都是在提示你“这里还缺一条规则”，补进去就是一次迭代。这才是配置体系真正发挥价值的方式。

最后送大家一个小技巧：每次你发现 AI 反复问同一个问题，或者反复犯同一个错误，技不如人，就该去更新配置了。把它当成一个信号，而不是抱怨的理由。用不了几轮，你的 Claude Code 就会从“能干活的工具”变成“懂你项目的搭档”。