企业官网建设流程全解析

用过网页版AI编程助手的人，应该都体验过那种“复制代码到聊天框、再粘贴回编辑器”的循环：改一行、粘一次、报错了再回去问。Claude Code把这个过程整个砍掉了——它直接跑在终端里，能读你项目里的文件、按照你的要求改代码、自己执行命令看结果，然后继续修正，直到任务完成。这是“光子AI”系列教程的第一章，我打算用一整章的篇幅，把Claude Code入门前必须搞清楚的原理、安装、配置和第一次实操完整走一遍。

这套工具适合什么人？简单说，只要你的日常工作离不开命令行和代码编辑器，它就能实实在在减少重复劳动。不管你是写前端、后端、脚本，还是负责维护老项目，都可以从这一章开始。哪怕你之前只会在网页聊天框里用AI，只要愿意打开终端，照着下面的步骤走一遍，也能在半小时内跑起来。

我先把丑话说在前面：Claude Code不是那种“输入一句话就自动完成整个项目”的魔法，它更像一个上手很快、但需要你掌握节奏的实习生。你需要给它清晰的任务、帮它确认边界、替它做最终审查。这一章不讲花哨技巧，只把一个能用、稳定、安全的基础环境搭好。

1. 先把它放在合适的位置：Claude Code到底是个什么东西

很多人第一次打开Claude Code，会下意识把它当成“跑在终端里的ChatGPT”。这么理解不算错，但很容易让你在真正使用的时候踩坑。因为它和网页版AI助手的本质差别，不在于界面换成了黑底白字，而在于它拥有了操作计算机的能力。

1.1 它和网页版AI的本质区别

网页版AI的交互模型，本质上是“问答”：你把代码贴进去，它给你反馈，你再贴回去。这种模式下，AI永远看不到你的完整项目，只能靠你贴出来的片段猜上下文。你贴少了它理解不了，贴多了又受限于一次能输入的文本长度，于是大部分时间都浪费在“整理提问材料”上。

Claude Code换了一个思路：它不是一个聊天窗口，而是一个跑在你项目目录里的编程代理。启动之后，它能直接读取当前项目的目录结构，查看文件内容，执行命令，然后基于真实运行结果继续工作。你在终端里和它对话，它可以直接改文件、跑测试、看报错、再改，直到任务完成。

这个区别可以这样理解：网页版AI像一个坐在另一间办公室的顾问，你只能通过传真把材料发给他；而Claude Code像一个坐在你工位旁边的同事，你告诉他“把用户注册接口加个邮箱校验”，他自己会打开项目、找到对应文件、改完代码、跑一遍测试给你看。

当然，它的权限不是无限制的。第一次涉及修改文件或者执行命令时，它都会征求你的确认。你点头它才动手，这一点后面我会专门讲。

1.2 工作方式：一个简单的Agent循环

Claude Code的工作方式，可以拆成一个循环：观察、决策、行动、验证。

所谓观察，就是读取文件内容、查看目录结构、执行命令获取输出；所谓决策，是根据当前任务和观察结果，决定下一步要做什么；行动就是实际修改文件或运行命令；验证，则是通过执行测试、运行程序等方式确认修改是否生效。如果验证失败，它会回到观察阶段，重新看错误信息，再尝试另一个方案，直到你满意或者它明确承认搞不定。

这也是为什么它在改代码时，看起来比网页版AI“聪明”：因为它是基于你项目的真实报错来调整方案，而不是靠猜。你写了一个Python脚本，运行报错说“模块不存在”，它自己会去安装依赖，然后重新运行。这种“有反馈闭环”的交互方式，才是它能处理复杂任务的根本原因。

1.3 边界与限制：它不是什么都能做

我必须先泼一盆冷水。Claude Code虽然能读文件、能跑命令，但它不是你项目的万能救星。

第一，它没有真正的“常识”。它不知道你团队内部的命名规范，不知道某个模块为什么被废弃，不知道你老板说的“尽快”到底有多快。这些上下文如果你不说清楚，它就会按照最通用的方式写代码，结果可能不符合你的预期。

第二，它只会对自己能看到的东西负责。如果项目里有一堆历史遗留问题、混乱的目录结构、缺少文档的依赖项，它看到的是一团乱麻，做出的决策就会很保守，甚至会让局面更复杂。

第三，它不能替代你的判断。工具本身只会“照着理解执行”，它认为合理的方案，未必符合你项目的长期设计。尤其在涉及数据删除、大批量重构、生产环境变更时，你必须有意识地保持控制权。

所以，Claude Code适合处理“目标明确、能验证”的任务，比如写接口、修bug、补测试、批量重构、写脚本。它不适合处理“你自己都说不清楚想要什么”的任务。用得好不好，很大程度上取决于你描述任务的能力，以及你审查结果的能力。

2. 装好它，别在第一步翻车

安装Claude Code并不复杂，但我在看过不少新手现场翻车之后，还是决定把这一节单独拿出来，把容易出错的地方一次讲清楚。准备工作做足了，后面能省很多事。

2.1 检查你的电脑环境是否达标

Claude Code是跑在终端里的工具，所以你需要一个能用的终端环境。Windows用户建议提前装好Windows Terminal或者其它你习惯的终端模拟器，macOS用户用系统自带的终端就行，Linux就更不用说了。

更关键的前置条件是Node.js。Claude Code是构建在Node运行时上的工具，所以你得先确认电脑里装了Node.js。打开终端，执行下面这条命令：

node -v

如果屏幕上输出了一个版本号，比如v20.11.1，说明环境没问题。如果提示“node: command not found”，那就需要先去Node.js官网下载并安装一个长期支持版本。我建议至少使用18以上版本，太老的版本可能会在安装或运行过程中出现兼容性问题。

顺便说一下为什么它非得依赖Node.js：这主要是工具实现方案决定的，就像很多命令行工具选择用Python发布一样。你不必为此专门去学Node.js，只需要把环境装好就行。我见过有人误以为“用了Claude Code就必须会JavaScript”，其实完全不是一回事，你带的项目是Python、Java、Go还是其它语言，它都能处理。

2.2 安装命令与安装方式

环境检查通过后，安装本身只是一条命令的事。Claude Code是通过npm分发的，所以使用npm全局安装即可。不同操作系统上我习惯这样处理：

npm install -g claude-code

如果你所在的网络环境导致npm总是超时，可以先检查npm镜像源是否可用。这里有个小经验：安装失败时先区分是权限问题还是网络问题。如果你看到的是“EACCES”之类的权限报错，说明当前用户没有全局写权限，常见于Mac或Linux系统，解决办法是通过nvm管理Node环境，或者使用sudo前缀。如果你看到的是“ETIMEDOUT”或“network”相关报错，那基本就是网络问题，检查一下代理设置、镜像源，或者换个时间段重试。

装完之后，验证是否安装成功的命令也很直接：

claude --version

如果能看到版本号，恭喜你，安装这一步就算完成了。

2.3 登录与API Key：必须认真对待的环节

安装完成只是拿到了客户端壳子，要让Claude Code真正能调用AI能力，还需要完成认证。一般来说，Claude Code提供两种认证路径：一种是用账号体系走浏览器授权登录，一种是使用API密钥。

我自己更喜欢浏览器授权登录的方式，因为它比较省事。第一次运行claude命令时，终端会打印一个链接，你用浏览器打开、确认授权，然后回到终端，它就能识别你的身份了。整个流程类似你在新手机上登录各种在线服务，只是这次发生在终端和浏览器之间。

如果你所在的项目环境里没办法打开浏览器跳转，也可以走API密钥的方式。一般步骤是：拿到API密钥后，把它配置成环境变量，比如在你的shell配置文件中写入类似export CLAUDE_CODE_API_KEY="你的密钥"这样的内容。但这里有一条我反复强调的底线：绝对不要把密钥硬编码在代码仓库里，更不要随手贴到聊天软件里。密钥一旦泄露，别人就可以用你的额度，后果很尴尬。

另外，登录状态也不是一劳永逸的。官方有时会因为安全策略让登录过期，遇到提示“需要重新认证”时，不用慌，重新走一遍授权流程就行。别因为这个就怀疑是不是自己操作有问题。

2.4 第一次启动会看到什么

认证完成之后，在任意目录下输入claude，就会进入交互模式。你看到的界面是一个普通的命令行提示符，但你输入的自然语言会被当成任务描述。第一次启动时，它通常会显示一些欢迎信息和基本命令提示，告诉你可以用/help查看帮助、/quit退出会话。

我建议你第一次启动时不要急着干正事，先做两个测试。第一个测试，输入几个跟环境相关的简单问题，比如“当前这个目录里有什么文件”，看它能不能正确读取目录结构。第二个测试，随便让它写一个十行以内的小函数，比如“写一个Python函数，判断字符串是不是回文”，然后退出。

这两个测试能帮你确认三件事：安装是否成功、认证是否有效、基本对话是否通畅。如果这两步都能顺利跑通，就可以进入下一节，把Claude Code配置成适合你项目的形态。

3. 进入真实项目之前，先把“规矩”立好

安装只是开始。真正让Claude Code发挥价值的时刻，是把它放进一个真实项目里。但如果你不做任何准备工作，直接对着一个大仓库发号施令，很快就会遇到上下文混乱、权限失控、误改代码一堆问题。所以进入项目之前，先把“规矩”立好，很有必要。

3.1 在正确的目录里启动它

Claude Code的工作基准是“当前目录”。它读取文件、执行命令，都是基于它启动时所在的目录。这个特性决定了你启动它的位置很重要。

假设你现在有一个电商项目，结构大概是这样的：根目录下有前端代码、后端代码、数据库脚本、部署配置等等。如果你在根目录启动Claude Code，它看到的范围就是整个项目。有好有坏：好处是它能统筹全局，坏处是它的上下文很容易被无关文件占满，反应速度会变慢，决策也可能被干扰。

我的习惯是：按任务范围选择启动目录。如果你想改后端接口，就进入后端目录再启动；如果你想做全项目的依赖升级，才需要在根目录启动。另外，项目里的node_modules、dist、build这类生成目录，应该通过项目的.gitignore控制好。因为Claude Code在探索目录时通常也会受这些忽略规则影响，忽略规则写得好，它就能把注意力放在真正的源码上。

还有一点值得注意：不要在空目录里让它“创建一个完整项目”之后，又频繁移动到其它目录。Claude Code的会话上下文是累积的，同一个会话内频繁切换项目范围，容易让它产生错误关联。

3.2 权限控制是重中之重

我在前面提过，Claude Code改文件或执行命令前会征求确认。但这只是一个默认机制，具体到你的使用场景，权限控制策略必须自己定清楚。

Claude Code通常提供几种权限模式。一种是“每次都问我”，这是最安全但最啰嗦的，适合刚上手、或者处理高价值文件时使用；一种是“自动接受对特定文件或目录的修改”，适合你信任它维护的范围；还有一种是“完全自动执行”，我强烈不建议新手使用，尤其是在生产环境或重要分支上。

我见过的翻车案例里面，有相当一部分是用户为了省事，把权限调成了全程自动，结果Claude Code一段时间内跑了大量测试、改了多个文件，最后什么都没留下。你说它错了吗？它只是忠实地执行了你的指令而已。所以权限这关，宁严勿松。

对于关键文件，我还会额外做一层保护：比如把数据库迁移脚本、支付相关模块、生产配置这类文件，在权限配置里明确拒绝自动修改。这样即使任务描述里有歧义，它也不会轻易碰到不该碰的东西。

3.3 用CLAUDE.md建立项目记忆

Claude Code有一个项目记忆的机制：通过一个名为CLAUDE.md的文本文件，记录这个项目的背景信息、编码规范、命令约定等等。它启动时会自动读取这个文件，相当于你在一开始就给它做了一份入职培训。

这个文件里可以写什么？举个例子，如果你在维护一个Python后端项目，可以写清楚：“本项目的Python版本是3.11，依赖管理使用poetry，测试框架使用pytest，运行测试的命令是poetry run pytest tests/，代码风格遵循Black。”这样它执行任务时，就会优先使用这些约定，而不是随手乱猜。

我第一次意识到这个文件有用，是在一个老项目里。那个项目没有文档，依赖关系非常混乱，Claude Code一开始频繁给出错误的重构方案。后来我把项目架构、模块职责、构建命令写进CLAUDE.md之后，它的准确率立刻上升了一个档次。所以，如果你只愿意做一个配置文件，我建议就做这个。

3.4 把这几个内置命令用熟

Claude Code内置了一些斜杠命令，功能覆盖查看状态、清除会话、生成项目说明、退出等等。入门阶段不需要全记，常用这几个就够：

其中/clear我建议养成一个习惯：每次切换任务之前先清空一下会话，避免上一个任务的内容干扰下一个任务的理解。这就好比你和同事讨论完A需求之后，再讨论B需求时，肯定会主动切换话题，不会让上一个需求的细节一直占据桌面。

4. 第一次实操：让Claude Code动起来

基础环境和配置都说完了，这一节进入实战。我会用一个模拟的练手项目，完整走一遍“提需求—执行—审查—调整”的流程。建议你跟着操作，不要跳步。第一次的完整体验很重要，它能帮你建立对工具的直觉。

4.1 准备一个适合练手的小项目

在真实项目上做第一次实验风险太大，我建议你准备一个独立的、没有业务压力的小项目。这里我拿一个图像处理Demo举例：一个Python脚本，功能是把指定目录下的图片统一转换成JPEG格式，并压缩到指定大小，支持批量处理。

我先在项目目录里启动Claude Code：

cd ~/projects/image-demo claude

启动成功后，我先问了一句：帮我描述一下当前项目结构和主要功能。它快速浏览了目录，准确说出了脚本文件名、依赖文件和大致功能。这个步骤虽然简单，但很有价值——它证明Claude Code确实看到了项目内容，而不是在凭空猜测。

4.2 用自然语言布置一个清晰的任务

接下来，我给它布置了第一个任务。我试着完全按照新手的思维，输入了一段比较含糊的话：“把图片处理脚本优化一下，让它快一点。”它的反馈很典型：先询问我“快一点”具体指什么，是处理速度更快，还是生成的图片更小，还是代码结构更清晰。

这个瞬间其实很有启发。Claude Code和前几代的AI工具差别很大，它面对模糊指令时会主动追问，而不是硬着头皮乱写。这时候我进一步明确需求：现有的脚本串行处理图片，我想改成并行处理，利用多核CPU提升批量处理速度；同时图片压缩质量参数可以保持不变，但要让代码保持可读性。

这个清晰的指令直接决定后面一路顺畅。所以在这里分享一个写提示词的经验：把“任务目标、输入输出、约束条件、验收标准”这四要素说清楚。你可以在自然语言里直接写：“把当前图片批量处理改成使用线程池并行执行，保持输出目录结构不变，处理完成后在控制台打印每个文件的耗时，运行python process.py tests/input应该能在不影响输出质量的前提下明显变快。”

4.3 观察它的执行过程

任务布置下去之后，我没有立刻当甩手掌柜，而是盯着它的执行路径看了一遍。它先打开了脚本文件，理解当前的串行逻辑，然后生成一份修改计划，大致说明要改哪些函数、引入什么库、如何避免并发写入冲突。这些步骤清晰可见，也方便你在它动手之前喊停。

确认计划没问题之后，我允许它修改文件。它很聪明地保留了函数接口不变，只是将循环处理改成使用线程池，同时对输出文件的写入做了互斥保护。改完之后，它自己跑了python process.py tests/input验证结果。第一次运行时出现了一个问题：输出目录里的临时文件没有先清理，部分旧文件还在，导致看起来像是“没有变化”。于是它主动发现异常，重新清理目录后再跑一遍，直到输出符合预期。

这个过程我建议所有入门者都完整观察一遍，因为它能帮你建立对工具能力的信心，也让你看清楚它的思考步骤。万一它走偏了，你可以在第一步就打断并纠正。另外，注意观察它每一次修改文件之前是否征求确认——如果某一步它没有确认就直接动手，说明你的权限配置比预想的宽松，需要回去调整。

4.4 用git diff守住最后一道防线

任务看起来“执行成功”了，但我不建议直接收工。Claude Code毕竟是自动生成代码，代码风格、逻辑边界、甚至潜在的bug都需要你亲自审查。

我习惯的收尾动作是：让它停止任务后，先在终端里跑git diff，逐行查看这次改动，再决定是否提交。这一步不能省。我见过有人完全信任AI的输出，直接提交了一批改动，后来因为并发安全问题引发了线上小故障。不是因为Claude Code写得差，而是因为主人没有审核。

对于这个图像处理Demo，我会重点检查三个方面：并发控制是否正确、错误处理是否覆盖异常场景、是否引入了多余依赖。如果发现不理想的地方，你可以直接跟Claude Code说：“线程池的异常处理还不够完善，如果某个图片文件已损坏，希望跳过并记录日志，不要中断整个任务。”它会继续修改，直到你满意。

整个流程走下来，你会发现：一个原本需要自己读源码、查文档、手写并发控制的改动，现在变成了“提需求—审查—微调”的过程。省下的时间不是一点点，但前提是你要掌握审查权。

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

用Claude Code一段时间之后，你大概率会遇到几个高频问题。这里我把典型情况和解决思路整理成一份速查笔记，希望能帮你少走弯路。

5.1 安装或启动时报错

“claude: command not found”应该是出现频率最高的报错之一。原因一般有三种：npm全局安装路径不在系统的PATH环境变量里；安装过程中发生了权限错误；或者根本没有安装成功。

解决思路也简单：先重新执行node -v和npm -v确认基础环境，再检查npm config get prefix查看全局安装路径，确认该路径是否已加入PATH。如果你用的是nvm管理Node版本，还要确认当前shell加载了nvm环境。这类问题属于环境配置问题，跟Claude Code本身关系不大，耐心排查都能解决。

还有一类情况是安装完成后启动，提示缺少依赖或者版本不兼容。这种我一般是建议把Node.js升级到官方推荐的长期支持版本，然后把Claude Code重新安装一遍。另外，如果你之前装过早期测试版本，也要确保升级到了当前版本，避免新旧版本文件混杂。

5.2 认证失败或登录过期

认证相关的问题也很多。常见场景包括：第一次启动时浏览器授权流程一直不成功、一段时间后提示需要重新登录、API Key没有生效等等。

浏览器授权失败的时候，先确认终端里打印的链接能完整打开。如果链接很长，有些终端会自动截断，你可以手动复制完整链接到浏览器。如果授权流程卡住，可以退出会话重新运行一次，大部分情况下重试能解决问题。

API Key模式不生效，优先检查环境变量是否真的设置成功。可以在终端里打印一下环境变量的值确认没有特殊字符或空格，确认之后再重启Claude Code进程。

5.3 上下文太大或反应变慢

在大型项目里用Claude Code，最常见的体验问题是：它思考得越来越慢，而且偶尔会忘记前面看过的东西。这通常是因为项目文件太多、无关内容占满了上下文空间。

解决办法有两个。第一，善用忽略规则，确保依赖目录、构建产物、缓存文件不会反复出现在Claude Code的视野里。第二，把任务拆小，不要试图在同一个会话里让它同时完成“重构整个项目、写全部测试、更新所有文档”。拆成小任务，配合/clear清空历史，效果会好很多。

5.4 输出结果“看起来对了，实际有问题”

这是很多新手最难识别的问题。Claude Code写的代码能跑通，测试也过了，但性能很差、边界情况没处理、或者代码风格和项目完全不一致。这类问题不能靠工具本身解决，要靠你的审查习惯。

我的建议是：代码审查优先级永远高于效率。不要因为AI生成得很快，就理所当然地认为它是正确的。尤其是在处理并发、数据一致性、权限验证等敏感逻辑时，至少要看一遍核心改动，必要时让它补几个边界测试用例给你。它并不反感被追问，你让它解释某个复杂函数的设计原因，它通常会给出详细说明，这个过程也能帮你加深理解。

所以，如果你决定把Claude Code融入日常工作，我希望你能接受一个理念：它是你的协作者，不是你的替身。你负责带路、把关、兜底，它负责执行、探索、提速。这个平衡掌握好了，它会成为你习惯里很难丢掉的一个工具。