Claude Code 完整安装指南：从环境准备到登录卸载避坑

如果你最近逛 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 可用之后摆在面前的就是安装方式选择。目前最主流的有两条路对比项npm 全局安装官方原生安装脚本适用平台macOS / Linux / WindowsmacOS / Linux / Windows前置要求需自己装 Node 18脚本会检查并处理运行时更新方式npm update 或 claude updateclaude update卸载方式npm uninstall手动清目录适合谁本来就在 Node 工具链里的开发者不想折腾 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 与 Linuxnpm 路线与脚本路线确认 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 装的 Nodenpm 全局包默认放在用户目录下永远不会出现这类权限问题。这一步多花五分钟后面一年都省心。装完验证claude --version能打出版本号就说明装上了。如果提示找不到命令检查 npm 全局 bin 目录是否在 PATH 里npm prefix -g然后把这个路径加到.zshrc或.bashrc的 PATH 中再重新开一个终端。官方原生脚本路线更省事一条命令搞定curl -fsSL https://claude.ai/install.sh | bash脚本会自己检测系统架构、合适的运行时然后把 Claude Code 放到对应位置。我个人在主力开发机上用的是 npm 方式在另一台不想污染环境的服务器上用了脚本方式两边都跑得很顺。3.2 WindowsPowerShell 原生装法 vs WSLWindows 用户现在是幸福的官方提供了 PowerShell 安装脚本irm https://claude.ai/install.ps1 | iex这条命令需要你在 PowerShell 里执行执行完同样用claude --version验证。如果你之前用 npm 路线也可以直接在 PowerShell 里npm install -g anthropic-ai/claude-code。但我要说句实在话Claude Code 在 Windows 上体验最好的方案是装 WSLWindows Subsystem for Linux然后在 WSL 的 Linux 环境里使用。原因不复杂这个工具的本质是一个终端里的编码代理它经常要执行 shell 命令、调用 git 钩子、处理 Unix 风格的路径纯 Windows 的 PowerShell 环境在遇到某些脚本工具链时会出现各种各样奇奇怪怪的兼容问题。比如它执行一个 shell 脚本PowerShell 里可能直接失败而 WSL 环境就和 macOS/Linux 完全一致少受很多罪。WSL 下的安装流程也不复杂先检查 WSL 状态wsl --status没有就wsl --install。进入 WSL 的 Ubuntu 发行版用 nvm 装 Node 20 LTS。然后执行npm install -g anthropic-ai/claude-code。直接在 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。我见过的两种常见做法在claude的欢迎界面选择使用 API Key相关入口然后把 key 粘贴进去。在环境变量里设置export ANTHROPIC_API_KEYsk-ant-xxxxxxxx设置环境变量的方式适合服务器或无人值守场景。但要注意环境变量一设置CLI 会优先走 API Key 通道不再问你 OAuth 登录。如果你两边都想保留建议在同一个终端里通过临时导出比如只在当前会话 export来控制别写死到.zshrc里写进去的话哪天想切回 OAuth 登录反而莫名其妙。API Key 方式的计费逻辑是按 token 走模型能力更强的代价是价格也更高。所以我个人建议如果没有很特殊的自动化需求套餐订阅加 OAuth 登录体验更好因为出问题的概率更小也没有key 泄露到代码仓库的风险。4.3 无浏览器的远程服务器登录方式登录最让远程用户头疼的场景是服务器上没有浏览器怎么完成浏览器授权你不需要在服务器上装浏览器。实际流程是在服务器上运行claude输出授权相关提示时CLI 会给出一个链接和一段授权码。你把这串内容复制到本地有浏览器的电脑上打开链接、登录 Claude 账号、输入授权码确认授权。授权完成后服务器端的终端会自动变成登录状态。如果你日常就是 SSH 到服务器干活这套设备码流程应该是熟悉的。遇到复制了链接但打不开的情况最可能是链接过期或者你复制的时候少了字符重新跑一次claude让它重新生成就行。不推荐在服务器上通过任何非常规手段强行跳转网络授权流程本身已经够用了问题多半出在网络策略而不是工具本身。4.4 登录失败可能绕不开的几个坑我整理了一下自己在各类机器上遇到的登录报错按出现频率排个序Login failed: url fetch response failed 这一类回调失败。原因是 CLI 在浏览器完成授权后会往本机回调端口发一个请求如果本机防火墙限制了 localhost 回环请求或者企业内网环境对出站域名有白名单管控回调请求就会被掐断。排查路径是先看系统防火墙有没有拦截本地回环流量再看企业网络是否要求把回调域名和端口加入放行名单。注意不是让你去改什么系统网络配置来绕问题而是确认它是否被合法放行。授权页能打开但一直转圈或跳回登录页。这种情况九成是浏览器里还残留着旧会话或 Cookie 状态异常。换个无痕窗口重新打开授权链接多半就好了。登录明明是成功的但终端告诉我们没有权限。这种情况常见于企业或团队账号当前账号没有获得 Claude Code 的启用权限。需要找管理员在管理后台把这个功能打开个人账号一般不会遇到。扩展面板点了登录弹窗一闪而过。VS Code 扩展的登录弹窗本质是打开回调连接如果扩展里提示连接被拒先确认 CLI 是否正常安装、Node 运行时是否可用、扩展版本是否太旧。多数情况下重启一次 VS Code 的扩展宿主进程就能解决。明明已经登录第二天又要求登录。这通常不是真的被登出而是本地凭据文件出了问题。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装的先看看是公式还是 caskbrew 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 之后直接解压回去你的历史会话和项目级状态都能接着用。这个我在从旧笔记本迁移到新机器时验证过真的能省下不少重新磨合的时间。整个安装、登录、卸载流程并不复杂复杂的是理解它作为一个终端代理的工作方式。搞清楚了这一点后续所有功能对你来说都只是水到渠成的事情。