企业官网建设流程全解析

如果你最近逛 GitHub，应该会注意到越来越多仓库根目录出现了一个叫CLAUDE.md的文件，commit message 里也频繁出现 "Generated with Claude Code"。我第一次看见时以为是什么新规约，直到自己把 Claude Code 装进终端、跑通一次登录，才意识到这东西的价值根本不是替人写几句代码，而是把一个仓库交给你手下一个会读文件、改代码、执行命令的终端代理。这篇文章我会从安装、登录到卸载，把整条链路里我自己踩过的坑和验证过的方案都写出来，给正在搜 claude code 安装、准备第一次上手的你一条不用再折腾的路线。内容按"先理解它是什么、再准备环境、然后真正动手装、登录、最后知道怎么干净卸载"的顺序展开，Windows、macOS、Linux 和 VS Code 的场景都会覆盖到。

1. 先搞清楚 Claude Code 到底是干嘛的：一个会改文件的终端代理

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

很多人第一次听说 Claude Code，第一反应是"这不就是终端里的 AI 聊天工具吗"。这个理解不算错，但会严重低估它的能力，也会让你在后续使用时摆不正心态。

网页版 Claude 的交互模式是"你提问，它回答"，回答内容停留在网页，你要自己复制代码、粘贴到文件里、跑测试，再看结果。而 Claude Code 的交互模式是"你下任务，它进仓库干活"——它会扫描当前目录的文件结构，阅读相关的源码，直接修改文件内容，执行终端命令，然后运行测试给你看结果。它不是聊天窗口，它是一个住在你电脑里的代理，操作对象就是你的工作区。

我印象最深的一次是让我写一个简单的数据迁移脚本。网页版我会先让它生成代码，然后自己建文件、粘代码、装依赖、跑起来调试接口。用 Claude Code 的时候，我只需要告诉它要把哪个表的数据迁移到新结构，它会自己去看数据库配置、读旧的迁移文件、写新脚本、执行迁移命令，然后告诉你哪里失败了、为什么失败。状态是它自己推进的，我更像一个监工。

这也解释了为什么大家都在找"claude code 安装"而不是继续用网页版——因为工具形态完全不同。

1.2 哪些项目和工作流最该装它，哪些情况先别装

根据我一段时间的实际体感，Claude Code 最适合的场景有这几类：

• 中大型存量项目：你接手一个别人写的仓库，代码结构不熟，用它做全局搜索、梳理模块关系、给旧代码补注释和测试，效率远高于自己一行行读。
• 测试和重构：它特别擅长"找出所有调用过某个函数的地方"，然后批量修改并逐个验证。
• 脚手架和一次性脚本：搭 CI 配置、写构建脚本、生成目录模板，这类任务目标清晰，试错成本低。
• 文档同步：当代码变化后，让仓库里的 README、接口文档跟着更新，这种事情人工做很烦，但它做得很稳当。

反过来，如果你只是偶尔写一个小练习，或者工作内容以纯文字写作为主，那暂时不需要安装 Claude Code，网页版对话可能更直接。另外，如果你对终端命令完全不熟悉，连cd都还处在需要查资料的程度，我也建议先把基本命令跑顺了再上手，否则它执行命令时你根本不知道发生了什么。

2. 装之前把环境理顺：Node.js 版本和安装方式的选择

2.1 Node.js 版本这个最大的隐形门槛

搜索"安装 claude code"时，大多数人踩的第一个坑不在安装命令本身，而在环境。Claude Code 是一个基于 Node.js 的命令行工具，核心包是通过 npm 分发的，所以本机必须有可用的 Node.js 运行时。官方要求 Node.js 18 及以上，但我实际操作下来，强烈建议直接上 Node.js 20 LTS 或 22 LTS，别再用 18 了——18 已经过了维护期，一些上游依赖的兼容性已经在松动，没必要在起跑线上给自己埋雷。

检查环境只需要两条命令：

node -v npm -v

如果系统提示command not found，说明 Node 没装。macOS 用户我建议用 nvm 而不是直接去官网下载 pkg，原因后面卸载部分会说：nvm 安装的 Node 能让你避免大部分EACCES: permission denied权限问题，也让日后的全局卸载干净得多。Linux 用户同理，用 nvm 或者系统包管理器都行，但注意系统包管理器自带的 Node 版本往往偏旧，装完还是先node -v确认一下。

Windows 用户稍麻烦一点：如果打算用 PowerShell 原生环境，装 Node 的时候记得选"Add to PATH"，否则后面npm命令会找不到。如果你用的是 WSL，那就在 WSL 里面按 Linux 的方式装，两边是独立的。

2.2 npm 全局安装与官方原生脚本的取舍

确认 Node 可用之后，摆在面前的就是安装方式选择。目前最主流的有两条路：

我个人的建议是：如果你日常写前端、写过 React/Vue，或者跑过任何 npm 项目，直接选 npm 全局安装。因为npm对你来说不陌生，而且卸载时一条命令就能移除入口文件，后续处理非常清晰。如果你基本没碰过 Node，或者这台机器上不想装一堆开发工具，那用官方原生安装脚本更合适，它会处理好运行时依赖。

另外，网上还有人会建议用 Homebrew 装，我没有把这条作为主推方案，因为 brew 公式有时更新不及时，而且卸载时容易留下缓存。后面卸载部分我会单独提它怎么处理。

这里还要给新手提个醒：官方原生脚本的本质是"把一段脚本从网上下载下来，然后交给 bash 执行"。这是个很高效的安装方式，但安全习惯上我建议你先下载下来看一眼，再决定是否执行：

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

看一眼脚本内容不是不信任官方，而是让你对"这台机器上即将执行什么"心里有数。这也是一个终端使用者该有的基本素养。

3. 动手装：macOS、Linux、Windows、VS Code 四套路径

3.1 macOS 与 Linux：npm 路线与脚本路线

确认 Node 版本 ≥ 18 之后，npm 安装其实只有一行：

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

等一下，先别急着加sudo。我见过太多人在这一步踩坑：直接用sudo npm install -g装完，之后每次执行claude或者想更新插件时，都会遇到权限错乱的问题。原因是 npm 的全局目录被写在了需要 root 权限的系统目录下，后续 npm 自己的自检都觉得别扭。

我推荐的顺序是这样：先不要sudo，直接执行

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

如果报EACCES权限错误，不要顺手加 sudo，正确做法是修一下 npm 的全局目录归属，或者干脆用 nvm 重装 Node。nvm 装的 Node，npm 全局包默认放在用户目录下，永远不会出现这类权限问题。这一步多花五分钟，后面一年都省心。

装完验证：

claude --version

能打出版本号就说明装上了。如果提示找不到命令，检查 npm 全局 bin 目录是否在 PATH 里：

npm prefix -g

然后把这个路径加到.zshrc或.bashrc的 PATH 中，再重新开一个终端。

官方原生脚本路线更省事，一条命令搞定：

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

脚本会自己检测系统架构、合适的运行时，然后把 Claude Code 放到对应位置。我个人在主力开发机上用的是 npm 方式，在另一台"不想污染环境"的服务器上用了脚本方式，两边都跑得很顺。

3.2 Windows：PowerShell 原生装法 vs WSL

Windows 用户现在是幸福的，官方提供了 PowerShell 安装脚本：

irm https://claude.ai/install.ps1 | iex

这条命令需要你在 PowerShell 里执行，执行完同样用claude --version验证。如果你之前用 npm 路线，也可以直接在 PowerShell 里npm install -g @anthropic-ai/claude-code。

但我要说句实在话：Claude Code 在 Windows 上体验最好的方案是装 WSL（Windows Subsystem for Linux），然后在 WSL 的 Linux 环境里使用。原因不复杂：这个工具的本质是一个"终端里的编码代理"，它经常要执行 shell 命令、调用 git 钩子、处理 Unix 风格的路径，纯 Windows 的 PowerShell 环境在遇到某些脚本工具链时，会出现各种各样奇奇怪怪的兼容问题。比如它执行一个 shell 脚本，PowerShell 里可能直接失败，而 WSL 环境就和 macOS/Linux 完全一致，少受很多罪。

WSL 下的安装流程也不复杂：

1. 先检查 WSL 状态：wsl --status，没有就wsl --install。
2. 进入 WSL 的 Ubuntu 发行版，用 nvm 装 Node 20 LTS。
3. 然后执行npm install -g @anthropic-ai/claude-code。
4. 直接在 WSL 终端里运行claude。

登录和授权这一步在 WSL 里和在 Linux 里完全一样，不会因为 Windows 宿主而产生额外问题。如果你已经装了 VS Code，配合 WSL 插件使用体验还会更好。

3.3 把它接进 VS Code：扩展安装与登录弹窗联动

很多人搜索"claude code for vs code"和"vscode 配置 claude code"，其实是希望在编辑器里直接使用它，而不是完全脱离 IDE 在纯终端里操作。这个需求很合理，因为看 diff、看文件树还是在编辑器里舒服。

在 VS Code 扩展市场搜索 "Claude Code"，找到 Anthropic 官方发布的那个，点安装即可。安装完成后，活动栏会出现一个 Claude Code 的图标，点开就是一个侧边面板，可以直接在编辑器里和 Claude Code 对话，它会像终端模式一样读取当前工作区、修改文件、把改动以 diff 形式展示出来。这个过程和我个人体验下来，比反复切终端稍微顺滑一点，尤其适合一边看代码一边下指令的场景。

这里有个很容易让人困惑的点：VS Code 扩展的登录状态和终端 CLI 是共享的。也就是说，你在终端里claude登录过一次，扩展面板里刷新后通常就是已登录状态，不需要二次输入。反过来，如果你在扩展面板里先登录了，终端里重新打开也是同一个会话。很多"登录弹窗一直跳"的问题，往往是因为两边状态不一致，后面第 4 部分会详细说排查方法。

3.4 安装后的验证与升级杂项

装完之后，除了claude --version，我还习惯跑一下内置的诊断命令：

claude doctor

它会检查环境变量、配置文件、Node 版本等是否正常，并给出提示。第一次跑如果全部通过，那安装环节基本就算焊死了。

升级方面，npm 方式用：

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

原生方式或者想省事的，直接执行claude update。Claude Code 的版本迭代相当频繁，我几乎每周都能看到新版本，所以建议养成"每次开工前顺手claude update"的习惯，让代理工作在更新的模型能力上跑。

4. 登录这件事：OAuth 授权流程、API Key 场景与常见报错定位

4.1 套餐账号走浏览器授权的标准流程

安装完成之后，在任意目录运行：

claude

第一次运行时，它会进入欢迎界面，给你几个选项，最常选的是"Authorize Claude Code"或类似字样的登录入口。选择之后，CLI 会唤起你的默认浏览器，打开一个授权页面。你在页面上登录自己的 Claude 账号，点授权，然后再回到终端，就会发现已经变成了登录状态，界面上会显示账号信息。

这套流程的本质是 OAuth 授权——不是你把自己的密码告诉 CLI，而是你在浏览器里确认"我允许这个终端工具使用我的账号"。所以整个过程中最忌讳的就是在终端里手动输入密码，任何要求你把账号密码明文交给命令行的做法都不正常。

Claude 套餐订阅用户（Pro 或 Max）登录之后，可以直接使用 Claude Code，不需要额外按 token 付费，但套餐内会有一部分"每周用量额度"，额度用完就得等下个周期。CLI 里通常能直接看到剩余额度，如果你经常跑大任务，建议时不时留意一下，别等到任务跑一半告诉你配额耗尽。

4.2 什么时候该用 API Key

如果你没有 Claude 订阅，而是用开发者 API 的方式按量计费，那登录方式就不走浏览器 OAuth，而是走 API Key。

我见过的两种常见做法：

1. 在claude的欢迎界面选择"使用 API Key"相关入口，然后把 key 粘贴进去。
2. 在环境变量里设置：

export ANTHROPIC_API_KEY=sk-ant-xxxxxxxx

设置环境变量的方式适合服务器或无人值守场景。但要注意：环境变量一设置，CLI 会优先走 API Key 通道，不再问你 OAuth 登录。如果你两边都想保留，建议在同一个终端里通过临时导出（比如只在当前会话 export）来控制，别写死到.zshrc里；写进去的话，哪天想切回 OAuth 登录反而莫名其妙。

API Key 方式的计费逻辑是按 token 走，模型能力更强的代价是价格也更高。所以我个人建议：如果没有很特殊的自动化需求，套餐订阅加 OAuth 登录体验更好，因为出问题的概率更小，也没有"key 泄露到代码仓库"的风险。

4.3 无浏览器的远程服务器登录方式

登录最让远程用户头疼的场景是：服务器上没有浏览器，怎么完成浏览器授权？

你不需要在服务器上装浏览器。实际流程是，在服务器上运行claude，输出授权相关提示时，CLI 会给出一个链接和一段授权码。你把这串内容复制到本地有浏览器的电脑上，打开链接、登录 Claude 账号、输入授权码，确认授权。授权完成后服务器端的终端会自动变成登录状态。

如果你日常就是 SSH 到服务器干活，这套设备码流程应该是熟悉的。遇到"复制了链接但打不开"的情况，最可能是链接过期或者你复制的时候少了字符，重新跑一次claude让它重新生成就行。不推荐在服务器上通过任何非常规手段强行跳转网络，授权流程本身已经够用了，问题多半出在网络策略，而不是工具本身。

4.4 登录失败可能绕不开的几个坑

我整理了一下自己在各类机器上遇到的登录报错，按出现频率排个序：

1. "Login failed: url fetch response failed" 这一类回调失败。原因是 CLI 在浏览器完成授权后，会往本机回调端口发一个请求，如果本机防火墙限制了 localhost 回环请求，或者企业内网环境对出站域名有白名单管控，回调请求就会被掐断。排查路径是：先看系统防火墙有没有拦截本地回环流量，再看企业网络是否要求把回调域名和端口加入放行名单。注意不是让你去改什么系统网络配置来"绕"问题，而是确认它是否被合法放行。

2. 授权页能打开，但一直转圈或跳回登录页。这种情况九成是浏览器里还残留着旧会话或 Cookie 状态异常。换个无痕窗口重新打开授权链接，多半就好了。

3. 登录明明是成功的，但终端告诉我们没有权限。这种情况常见于企业或团队账号，当前账号没有获得 Claude Code 的启用权限。需要找管理员在管理后台把这个功能打开，个人账号一般不会遇到。

4. 扩展面板点了登录，弹窗一闪而过。VS Code 扩展的登录弹窗本质是打开回调连接，如果扩展里提示连接被拒，先确认 CLI 是否正常安装、Node 运行时是否可用、扩展版本是否太旧。多数情况下重启一次 VS Code 的扩展宿主进程就能解决。

5. 明明已经登录，第二天又要求登录。这通常不是真的被登出，而是本地凭据文件出了问题。Claude Code 会把登录凭据存在~/.claude/.credentials.json，如果这个文件被权限修改或内容损坏，CLI 会认为自己没登录。在删除前，最好先做备份，确认路径无误再操作。

还有一个通用建议：遇到登录问题，先跑claude doctor，它会直接帮你检查配置和凭据状态，很多时候能直接指出是哪一步出了问题。

5. 卸载的三层清理：入口、配置目录、编辑器扩展

5.1 npm 卸载的完整验证链路

很多人以为卸载就是删除软件，然后觉得"删完了"，但在 Claude Code 这种工具上，卸载要分三层：命令入口、数据目录、编辑器扩展。一层不清理，都有可能留下痕迹，甚至残留配置影响之后重新安装。

先说 npm 方式安装的卸载。一行命令：

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

执行完之后，不要急着关终端，要验证是不是真的卸载干净了：

which claude

如果提示command not found，说明命令入口已经移除。如果还能找到路径，说明 npm 全局目录里可能有同名残留，用这招找到它：

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

有的话再执行一次npm uninstall -g @anthropic-ai/claude-code。这一步虽然机械，但确实是很多人忽略的检查项——我这里碰到过一次因为 nvm 版本切换导致 npm 全局目录漂移的残留情况，新版本 Node 对应一套全局目录，旧版本又一套，结果卸载了"当前版本"的命令，旧版本里的入口还挂着。

5.2 ~/.claude 目录里到底藏了什么

真正让"卸载"这个词变复杂的是~/.claude目录。npm 只删命令入口，但这个目录里存着所有会话历史、项目状态、登录凭据和个性化配置。它长这样：

ls -la ~/.claude

你会看到类似projects/、settings.json、.credentials.json、todos/、shell-snapshots/这样的内容。其中：

• projects/存的是各个项目的历史会话记录。
• .credentials.json里存的是 OAuth 登录凭据。
• settings.json存的是你的个性化配置。
• todos/和shell-snapshots/是任务状态和终端快照，用来支持会话恢复。

如果你确认要彻底卸载，不想保留任何历史记录，那么删掉这个目录：

rm -rf ~/.claude

注意这条命令是不可逆的，所有会话记录都会没。如果你只是暂时停用、以后可能会回来继续用，那我建议先不要删，把它改个名备份到别处，比如mv ~/.claude ~/.claude.backup，将来想恢复还能原样挪回来。

删完之后再确认一次：

ls -la ~/.claude

返回No such file or directory就是真的清干净了。

5.3 VS Code 扩展、Windows 残留与 Homebrew 包怎么清

VS Code 扩展的卸载很简单，在扩展面板找到 Claude Code 图标，点卸载按钮即可。喜欢命令行操作的可以这样：

code --list-extensions | grep -i claude

找到具体的扩展 ID 后执行：

code --uninstall-extension 这里填扩展ID

需要提醒的是，扩展卸载后，它在settings.json里写入的配置项不一定自动删除，如果你对配置洁癖比较重，去检查一下用户设置，把包含 claude 的配置段删掉。

Windows 用户要注意的是%USERPROFILE%\.claude这个目录，位置和内容与 Linux/macOS 的~/.claude一致，是同一个概念。如果你用 PowerShell 原生安装器装的，npm 卸载之外还要检查%APPDATA%\npm\node_modules\@anthropic-ai\claude-code是否还有残留。如果想要彻底清理，确认没有运行中的claude进程后，手动删除这些目录。另外 VS Code 扩展的缓存目录落在%USERPROFILE%\.vscode\extensions下，卸载扩展后如果有残留文件夹，也可以手动清掉。

Homebrew 的情况也顺带说一句：如果你当初是brew install装的，先看看是公式还是 cask：

brew list | grep -i claude brew list --cask | grep -i claude

确认包名后brew uninstall对应包，然后brew autoremove清理无用的依赖。brew 的缓存目录/Library/Caches/Homebrew或者~/Library/Caches/Homebrew下如果还有相关下载缓存，属于可选清理项，不影响使用，但强迫症可以顺手删掉。

归根结底，卸载 Claude Code 的原则是"入口靠包管理器，数据靠手动清目录"。

6. 安装登录一路走完，给你几条能少折腾的实在建议

6.1 新手最容易在这里放弃

以我见过的大量"装完就放弃"案例来看，第一个坎通常是权限问题。npm install -g报EACCES，然后有人直接sudo npm install -g，装完一时爽，后面每次执行都心惊胆战。解决办法在前面说过了，就是别让 npm 全局目录落在 root 手里，用 nvm 修一下，一劳永逸。

第二个坎是把 Claude Code 当成网页聊天框来用。网页版你不会让它随便执行命令，但终端版它真的会跑命令。于是很多人第一次看到它执行rm -rf 某个临时目录或者批量改文件时，吓得直接强退。这不是工具出 bug，而是它的工作方式就是如此。正确做法是：第一次运行完授权后，先不要直接甩一个大任务，用一个临时测试目录放两个假文件，让它做点小事，比如"把这两个文件合并成一个"，亲眼观察它怎么读文件、怎么改文件、怎么执行命令。等你有底之后再上真实项目。

第三个坎是不管上下文。默认情况下，Claude Code 会在会话里积累上下文，对话越长，它越容易被早期的大量信息"带偏"。新手经常遇到"任务越做越糊涂"的情况，其实是上下文中掺杂了太多陈旧状态。遇到这种情况，在对话里输入/clear清空会话，让它忘记之前所有内容，重新开始。这不是退步，反而是高效的工作方式——每次用完就清，保持每次任务都从干净上下文开始。

6.2 我从一开始就该建立的三个习惯

第一个习惯，在项目里尽早写好CLAUDE.md。这个文件是 Claude Code 的项目级记忆文件，告诉它这个项目的构建命令是什么、代码风格是什么、哪些目录不能动、测试怎么跑。没有这个文件，它每次都要靠猜和大量试探来理解项目；有了它，你的指令可以省一半。我自己建新仓库时第一件事不是写 README，而是先写一份简短的 CLAUDE.md。

第二个习惯，开工之前先确认工作区干净，时刻盯着 git diff。终端代理修改代码的速度比你肉眼读代码快得多，所以你要在它每次动手之间检查改动。我的做法是让它改完一个文件就先停下来，我git diff看一遍，确认没问题再让它进行下一步。如果你放任它一口气改二十个文件，出了问题回头定位的成本会高到你想哭。

第三个习惯，善用只读模式做规划。不要一上来就让 Claude Code 直接改代码，先让它只读地分析代码库，输出一份修改计划，你确认计划之后再允许它动手。这个"先计划后执行"的节奏不仅能减少误操作，还能帮你真正理解它准备怎么做。实际跑下来，你会发现它自己梳理出来的方案往往比你的第一直觉更完整，因为你可能只关注了单个文件，它却把关联调用全部找出来了。

最后分享一个小技巧：如果你准备换电脑或者长时间不用，别只卸了命令入口就完事，把~/.claude打包带走，新机器上装好 Claude Code 之后直接解压回去，你的历史会话和项目级状态都能接着用。这个我在从旧笔记本迁移到新机器时验证过，真的能省下不少重新磨合的时间。整个安装、登录、卸载流程并不复杂，复杂的是理解它作为一个终端代理的工作方式。搞清楚了这一点，后续所有功能对你来说都只是水到渠成的事情。