不少朋友问我Claude Code到底怎么安装网上教程一搜一大堆但大部分要么只贴命令不讲原理要么一上来就让你配一堆环境变量看到一半就被劝退了。这篇教程的目标很明确用最直白的方式把安装这条路走通同时把每一步背后的逻辑讲清楚让你装完之后不仅会用还知道出了问题时该往哪个方向排查。内容覆盖macOS、Linux和Windows通过WSL以官方推荐的npm路线为主安装脚本路线为辅适合第一次接触Claude Code的开发者、运维朋友以及所有想在终端里体验AI结对编程的人。1. Claude Code安装教程装之前先搞清楚这几件事1.1 Claude Code是什么为什么值得在终端里试简单说Claude Code是一个运行在终端里的AI编程助手。它不是一个像ChatGPT那样打开网页聊天的工具而是直接嵌入你的命令行环境能读取你项目里的文件、理解代码结构、直接帮你改代码、跑命令、查日志甚至提交Git操作。你平时怎么用终端它就怎么工作。这带来的实际好处是你不需要把代码复制粘贴到网页里来回切换上下文它在你的项目目录里直接工作天然知道你在做什么。比如你接到一个陌生仓库可以直接让它先读一遍README和核心模块用几分钟快速建立全局认知遇到一段看不懂的函数直接针对那个文件提问写测试、改bug、重构逻辑都可以用对话推进。它适合谁我觉得主要是这几类人日常写脚本或维护项目的后端开发者经常要处理日志和命令的运维人员以及喜欢折腾工具的爱好者。有一点需要提前说清楚它不太适合完全没有编程基础的人因为你要能判断它给出的代码和命令是否合理而不是盲目接受结果。1.2 运行环境与账户要求安装前的一分钟自检在动手安装之前花一分钟确认环境能省掉后面一大半的坑。Claude Code虽然不算娇贵但对基础环境有明确要求。首先是操作系统。macOS和主流Linux发行版基本都能直接跑。Windows用户要注意了虽然Windows本身可以运行npm包但Claude Code依赖了不少类Unix环境的行为在Windows原生的CMD或PowerShell里体验很差。官方建议走WSLWindows Subsystem for Linux我们在后面的安装路线里会单独展开你只要记住“Windows 先搞WSL”这个大方向就对了。其次是Node.js环境。如果你用的是npm安装路线要求Node.js版本在18及以上。这个版本要求不算激进很多项目现在都跑在18或20上但你如果机器上的Node非常老安装时就会直接报engines相关的错误一眼就能认出来。然后是账户。Claude Code需要你有一个可用的Claude账号或者一个有效的API Key。这个在后面初始化登录那一步会用到我建议你提前准备好在浏览器里能正常登录账号避免装到一半卡在授权环节。最后是网络。安装过程需要从npm官方仓库拉取包首次运行时还需要访问官方的认证页面完成授权所以你的网络环境必须能正常连通官方站点。如果下载缓慢或者认证页面加载不出来优先检查网络连通性这是最基础的排查思路。2. 三条安装路线按你的环境选一条就行2.1 推荐路线npm全局安装一分钟搞定如果你已经有Node.js 18环境npm全局安装是最省事的路。先检查版本在终端里执行node -v如果输出类似v20.11.0这样的版本号说明Node环境没问题。如果没有Node先去Node官方站点下载LTS版本装上装完再回来。这里是唯一需要提前准备的大件。确认Node存在后直接执行安装命令npm install -g anthropic-ai/claude-code这个命令会把Claude Code安装到npm的全局目录macOS和Linux下通常在/usr/local/lib/node_modules或者nvm管理的Node版本目录里。Windows的WSL环境同样用这条命令逻辑一致。安装过程一般需要几十秒到一两分钟取决于你的网络速度。看到类似added 1 package或者changed 1 package的输出就说明装好了。接着验证版本claude --version能打印出版本号说明安装成功CLI已经被正确放进了PATH。如果此时提示command not found多半是npm全局bin目录不在PATH里这个问题我们在第五部分专门说。注意如果你的npm全局安装经常报EACCES权限错误不要用sudo npm install硬刚这会把全局目录搞得很乱。更合理的做法是用nvm这类版本管理器来装Node让npm全局目录落在你用户目录下彻底绕开权限问题。2.2 没有Node环境的替代方案官方安装脚本有些场景下你不想装Node比如机器上只是临时用一下工具嫌Node太占空间。Claude Code官方也提供了安装脚本路线本质上是一个自包含的安装器会下载CLI并放到你的用户目录下。具体命令以Claude Code官方文档“Install”章节为准。为什么我这里不贴一条死命令因为脚本地址偶尔会随版本调整背一个过时的URL意义不大打开官方文档拿最新命令是更稳妥的做法。安装完成后CLI会落在类似~/.local/bin的目录。如果执行claude --version提示找不到命令检查一下这个目录有没有加入PATHexport PATH$HOME/.local/bin:$PATH想永久生效的话把这行加到~/.bashrc或~/.zshrc里然后重新加载配置source ~/.bashrc这条路适合不想碰Node的人但有一点要心里有数脚本安装通常没有自动更新机制后续升级要么重新执行脚本要么关注官方给出的更新方式。npm路线更新时用npm update -g anthropic-ai/claude-code一行就搞定更符合常规习惯。2.3 Windows平台怎么装先配好WSL再继续Windows上最省心的路线不是直接在PowerShell里跑npm命令而是先安装WSL在WSL的Linux终端里完成所有操作。原因很简单Claude Code的很多行为依赖类Unix环境包括文件路径处理、权限模型、以及大量CLI工具链的调用这些在原生Windows环境里会频繁踩坑而在WSL里一切都会自然很多。具体步骤也不复杂。WSL的安装自己就能搞定在管理员权限的PowerShell里执行wsl --install重启后按提示创建一个Linux用户默认发行版通常是Ubuntu完成之后你就拥有了一个完整的Linux子系统。然后打开Ubuntu终端先更新包索引sudo apt update sudo apt upgrade -y接着安装Node.js 18。这里推荐用nvm来装避免sudo权限问题curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20装完Node后直接走2.1小节的npm全局安装命令即可。安装完成后你可以把常用的工作目录放到WSL的文件系统里比如/home/你的用户名/projects这样Claude Code读取文件、执行命令时体验最顺畅。提示在WSL里跑Claude Code时如果你用的是Windows Terminal它的WSL配置会自动处理好大部分显示问题。如果出现字符显示混乱或颜色异常通常需要设置export TERMxterm-256color这部分在第五部分排查表格里有说明。2.4 装完以后建议立刻做的验证安装完成后不要急着关终端花两分钟做一次系统性的验证确保不是“装了但残了”的状态。先看版本号能否正常输出然后尝试进入交互界面claude --version claude第二条命令会进入Claude Code的交互式终端界面。这一步如果能够正常启动说明核心安装没有问题。如果启动时提示缺这个缺那个接下来就能带着具体的报错信息去排查比自己盲猜高效得多。验证时还有一个容易忽略的细节确保你当前所在的目录不是一个空的临时目录。可以新建一个测试项目目录再启动这样后续做初始化配置时也顺手。如果你是从仓库里某个深层子目录启动的也没关系Claude Code会结合当前目录和Git仓库根目录来确定项目范围。3. 初始化登录与必要配置装完不等于能用3.1 第一次执行 claude 会经历什么安装完成后第一次在项目目录里执行claude你会看到终端弹出交互界面接着进入登录引导流程。这个过程实际发生的事情是CLI需要建立你的身份凭据确认你在使用哪个账号、以及该账号是否被允许调用后端服务。正常情况下终端会显示一个授权链接同时给你一个一次性授权码。你在浏览器里打开链接登录你的Claude账号然后输入授权码完成授权。授权成功后终端界面会刷新并出现欢迎信息这时工具才真正开始工作。这个流程本质上和很多CLI工具的OAuth授权类似比如你在终端里登录某个云服务商的CLI也是这个套路。理解了这一点遇到问题时思路就清晰了前端终端负责生成授权码浏览器负责登录认证两边都要正常才能走通。3.2 订阅账号与API Key两条路怎么选Claude Code支持两种账号对接方式理解它们的差异能帮你少走弯路。第一种是Claude账号授权也就是刚才说的浏览器登录方式。适合已经订阅了Claude Pro或Max的用户。走这条路工具的用量会计入你订阅套餐的额度体系不需要再额外管理密钥只管登录授权即可对大多数人来说是最省心的。第二种是API Key方式。你在API控制台创建一个密钥然后通过环境变量传给Claude Code。使用前先导出export ANTHROPIC_API_KEY你的密钥然后在同一个终端会话里再执行claude工具就会读取这个环境变量完成身份认证。这种方式适合需要独立核算用量、或者想把调用接入到自动化流程里的场景。两种方式的选择不算复杂有订阅就先用第一种简单直接如果要精细控制调用预算就走API Key。唯一需要警惕的是API Key是敏感凭证不要把它写进任何会被提交到Git仓库的文件里也不要随意分享给别人。3.3 把项目级配置文件提前放好Claude Code允许你在项目根目录创建一个配置文件名叫.claude/settings.json。这个文件的作用是定义这个项目的权限边界比如允许它读哪些文件、能不能执行Shell命令、能跑哪些命令。我刚上手时的建议是把配置文件和权限管理当成安装的一部分来做不要偷懒跳过。一个稳妥的项目级配置大致长这样{ permissions: { allow: [Read, Edit], deny: [Bash(npm publish*), Bash(git push*)] } }这个配置的意思是默认允许读文件和编辑文件但禁止执行发布和推送相关的危险命令。实际使用中你一定会根据项目需要调整权限比如某个项目确实需要它帮你跑测试命令那就把对应命令加入allow列表。还有一个对协作很有用的文件叫CLAUDE.md放在项目根目录。这个文件相当于给AI看的项目说明你可以在里面写清楚项目结构、编码规范、常用命令。Claude Code启动后会优先读取它相当于给AI做了一次“项目入职培训”。注意无论用哪种方式配置都不要把密钥、密码写在配置文件里。settings.json是明文文件一旦提交到仓库就等于泄漏了凭据。敏感信息请走环境变量或系统密钥管理工具。4. 实战走一遍让Claude Code接管一个小任务4.1 准备一个最小可用的实验仓库理论说再多都不如自己跑一遍。我建议你用一个小项目来试水不要一上来就拿生产仓库练手否则AI一旦执行了错误命令排查成本很亏。我自己的做法是拿一个模拟图像处理Demo练手名字叫模拟项目X结构很简单my-image-demo/ ├── main.py ├── utils.py ├── requirements.txt └── README.mdmain.py里放一个简单的灰度转换函数类似这样# main.py def to_grayscale(pixels): return [(r * 0.299 g * 0.587 b * 0.114) for r, g, b in pixels]utils.py里放一个读取像素数据的辅助函数。这个仓库足够小Claude Code几秒钟就能读完整个项目非常适合第一次上手观察它的工作方式。4.2 用对话把一次代码调整跑通在项目目录下启动Claude Codecd my-image-demo claude进入交互界面后我的第一条消息通常是这样的读取main.py和utils.py告诉我这两个文件的职责分工以及你认为最值得优化的一点是什么。注意这个问题刻意设计成“阅读总结建议”而不是一上来就让它改代码。这样你可以先观察它有没有正确理解项目回复内容是不是贴合你的代码结构。等确认它理解了再进入真正的修改请求。接下来我继续追问把to_grayscale函数改成支持线程安全的版本要在并发调用时不会出现共享状态问题并补一个简单的单元测试。Claude Code收到指令后会先读取目标文件然后列出修改方案接着直接对文件实施编辑。在这个过程中你能在终端里看到它调用工具、读取文件、写入文件的过程整个行为链非常透明。你不需要无条件接受每一步看到不合理的地方可以立刻打断纠正。这个实验的价值在于它能帮你建立对工具行为模式的判断力。读代码、改代码、跑测试命令它都能做但你作为负责人需要像带实习生一样先交代清楚边界再逐步下放权限。4.3 这些内置指令一上来就该记住Claude Code的交互界面里有一批内置指令都是斜杠开头熟练使用能明显提升效率。我挑几个最常用的说。/init是我强烈建议你第一次进入项目时先用的命令。它会让Claude Code分析当前项目结构并自动生成一个CLAUDE.md文件。这个文件能帮AI在后续会话中快速理解上下文相当于给你的项目建了一份给AI看的档案。/help是快速查找功能的入口拿不准某个斜杠指令时直接调用它。/clear用来清空当前会话上下文当对话内容太长、思路变乱时用它重置一下会比继续硬聊效果好得多。/status可以查看当前会话的状态信息包括模型上下文用量、当前项目路径等排查问题时很实用。退出交互界面只需要在终端里执行exit或者按两次CtrlC这个简单到很多人反而会忘记。5. 常见问题排查与避坑速查5.1 安装阶段三个高频报错第一类报错是command not found: claude。安装明明成功了但命令找不到多半是npm全局bin目录不在PATH里。先定位npm全局目录npm prefix -g输出目录下的bin子目录就是CLI放的地方把它加进PATH即可。如果用的是nvm检查一下当前Node版本是不是你安装时的那个版本有时候切了版本会导致全局包“消失”。第二类报错是安装过程中的EACCES权限错误。这是npm试图往系统目录写文件时权限不足导致的。前面说过不要用sudo硬解而是用nvm重新安装Node让全局包落在用户目录下一劳永逸。第三类是和Node版本相关的engines错误。Claude Code会校验Node版本如果报错信息里明确写了需要大于等于18那就老老实实升级Node。升级后顺手重新执行一次node -v确认版本再安装。5.2 运行、授权与环境变量问题进入运行阶段后最常见的卡点是登录授权页面打不开或授权失败。处理思路是这样的先确认网络能连通官方认证页面再用无痕模式打开授权链接排除浏览器插件干扰。如果授权码过期了回到终端重新执行claude生成一次新的即可。如果你是使用API Key方式登录启动时提示认证失败或者“permission denied”先检查环境变量有没有真的导出echo $ANTHROPIC_API_KEY如果输出为空说明环境变量没有生效回到3.2小节重新导出。还要注意环境变量只在当前终端会话里有效你新开一个终端窗口就要重新导出除非你把它写入了~/.bashrc或~/.zshrc。WSL环境的显示问题也值得单独提一下。如果你在Windows Terminal里发现Claude Code的界面出现了乱码、颜色异常或排版错乱通常是因为TERM环境变量配置不对。执行export TERMxterm-256color然后重新运行claude绝大多数显示问题都能解决。如果想永久生效同样把这行加到~/.bashrc里。5.3 避坑小清单与我的使用习惯最后整理一个速查表格把上面这些经验浓缩在一起方便你遇到问题时一眼定位症状可能原因建议处理claude命令找不到npm全局bin目录不在PATH执行npm prefix -g定位目录后加入PATH安装报EACCESnpm无权限写入全局目录用nvm安装Node避免sudo安装全局包安装报engines错误Node版本低于18升级Node到LTS版本后重装登录页面打不开网络连通性、浏览器插件干扰检查网络、换无痕窗口重新授权认证失败或permission denied环境变量未生效或密钥无效用echo $ANTHROPIC_API_KEY确认重新导出WSL界面显示乱码TERM环境变量不正确设置TERMxterm-256color后重启对话上下文越来越乱会话过长没有清理用/clear开始新对话重述任务目标还有一个很容易被忽视的细节Claude Code在修改文件时通常会在终端里展示即将执行的变更。我自己的习惯是每一条变更都确认过再继续尤其是它请求执行Shell命令时先看命令内容再决定是否允许。权限配置里我倾向于默认收紧只放行当前任务真正需要的命令宁可多问一次也不要稀里糊涂放行全局权限。在实际使用中我还发现一个小技巧如果你有一个比较大的改造任务不要一次性把十几个文件的需求全塞给它而是拆成几个子任务每个子任务用一个对话推进。这样上下文更清晰它犯错的概率明显降低出问题也更容易定位。等你对它的行为模式足够熟悉了再逐步放手让它承担更大的任务。
