很多朋友第一次听说Claude Code都把它当成一个普通的聊天插件装上就能用。我刚开始也这么想结果装完之后一运行各种报错接踵而至什么“Node.js版本不支持”、“认证失败”、“目录权限拒绝”一折腾就是一下午。所以这次我干脆把从零开始装Claude Code的完整过程包括环境准备、安装方式、配置细节、坑点排查一次性整理成这篇教程希望能让你少走点弯路。Claude Code本质上是Anthropic官方推出的命令行编程助手它能直接跑在终端里读取你的项目代码、帮你改bug、写测试、做重构甚至跨文件分析整个代码库。它适合三类人一是刚接触AI编程但不想折腾IDE插件的新手二是重度依赖命令行、喜欢用Vim或Neovim的开发者三是需要在服务器或远程环境里写代码、没有图形界面的场景。这篇教程主要面向Windows、macOS和主流Linux系统内容从检查依赖环境开始一路到完成身份认证、跑通第一次对话都覆盖到了。1. 装之前必须先搞明白的三件事1.1 Claude Code依赖什么环境很多教程上来就让你跑一条npm命令装完发现用不了回头骂工具垃圾。实际上Claude Code的运行依赖两个核心前提Node.js运行环境和有效的Anthropic账号凭证。前者是工具的运行底座后者决定了你能不能调通API。Node.js这块Claude Code官方要求Node.js 18以上的版本。这里有一个很多人没注意到的点版本不是越新越好。有些Node.js 22以上的版本在部分系统上有兼容性问题如果你用公司配的电脑或者系统环境比较老建议装Node.js 20 LTS版本。LTS的意思是Long Term Support官方会持续维护稳定性有保障这也是我装过十几台机器之后得出的稳妥选择。账号凭证这块Claude Code目前主要有两种使用路径一种是订阅制账号直接登录使用另一种是用API Key走按量付费。你需要在Anthropic官网注册并完成相关配置才能拿到有效的身份凭证。这里特别提醒一句如果你之前用过其他AI工具习惯性地想去找什么“免费破解版”的配置源千万别这么做。代码助手要读取你的项目代码一旦用了来路不明的第三方代理轻则数据泄露重则整个代码仓库被拖走。1.2 你需要准备哪些基础工具除了Node.js本身我建议顺手把Git也装上。虽然Claude Code不强制要求Git但实际使用中它的很多功能——比如查看代码变更历史、生成commit信息、对比分支差异——都依赖Git环境。如果你之前看过那些“git安装及配置教程”顺手一起装了就行没有的话也不要紧我后面会说怎么快速搞定。Windows用户还要注意一个事Claude Code是纯命令行工具它默认跑在PowerShell或Windows Terminal里。但实际体验下来Windows Terminal比老版的PowerShell控制台好用得多支持多标签页、自定义主题、中文字体渲染也更清晰。如果你用的是Win10或Win11微软商店里直接搜Windows Terminal就能装免费。1.3 为什么推荐在项目目录里安装而非全局安装关于安装位置我见过很多教程直接让你npm install -g全局安装简单省事。但我个人强烈建议在具体的项目目录里安装Claude Code。原因有两个。第一Claude Code会读取当前目录下的文件作为上下文如果你在项目A的运行目录里启动它它默认操作的就是项目A的代码不会误伤其他项目。第二不同项目可能需要不同版本的Claude Code全局装一个固定版本升级或者回退都得动全局环境风险比较大。当然全局安装也有它的好处——任何目录下都能直接敲claude命令启动。我的做法是全局也装一份作为基础版本每个项目里再按需装一份精确锁定版本这样两端都能兼顾。不用担心后面看不懂这一块我在第3节实操里会详细拆解。2. 环境准备Node.js和Git的安装细节2.1 Node.js安装版本怎么选这一节是给纯新手看的。如果你电脑里已经装过Node.js可以跳过安装部分直接在终端里跑一下node -v确认版本号大于18就满足条件。没装过的朋友去Node.js官网下载页面找到“LTS”标签下的版本下载对应你系统的安装包。Windows用户下.msi格式的macOS用户下.pkg格式的双击安装一路Next就行。这里有一个安装配置的小细节Windows安装时一定要勾选“Add to PATH”这个选项默认是勾上的但有些精简版安装包会让用户自己勾选。如果漏掉了这个后面在终端里敲node命令会显示“node不是内部或外部命令”。特别是那些之前照着“pycharm安装教程”配过Python环境的同学对这个应该不陌生——环境变量这种坑几乎每个语言环境都会遇到一次。怎么验证装好了打开终端分别输入node -v npm -v如果能看到类似v20.11.0和10.2.4这样的输出说明Node.js和它的包管理器npm都就位了。2.2 Git安装和环境变量配置Git的下载地址是git-scm.com同样选择对应系统的安装包。Windows用户一路Next时有两处要注意第一处是“Adjusting your PATH environment”这一步选中间那个“Git from the command line and also from 3rd-party software”第二处是行结束符转换那里建议选“Checkout as-is, commit as-is”避免后续代码在Windows和Linux之间切换时出现换行符问题。装完之后在终端里跑一下git --version能输出版本号就说明装好了。如果你后续要用Claude Code的提交信息生成功能还需要先配置一下Git的用户名和邮箱git config --global user.name 你的名字 git config --global user.email 你的邮箱这一步不配的话Claude Code在帮你生成commit记录时会报错因为它找不到提交者信息。2.3 终端环境的选择建议macOS用户直接用自带的Terminal就行或者用iTerm2体验更好。Linux用户用系统自带的终端模拟器就好。Windows用户我再次推荐Windows Terminal。主要是Claude Code的界面里会大量用到颜色高亮和Unicode符号老版控制台对这两者的支持都很差看起来是一片乱码。Windows Terminal装完之后可以在设置里把默认配置文件改成PowerShell然后把字体调成“Cascadia Code”或者“Fira Code”渲染代码效果会舒服很多。另外如果你在中国大陆的网络环境下使用一些外部服务的连接可能不稳定这会在第5节排错部分具体说这里先有个心理预期。3. Claude Code安装步骤全拆解3.1 准备一个干净的测试目录我建议你新建一个目录来验证安装和跑通整个流程不要把Claude Code直接装到你正在开发的正式项目里。因为第一次使用肯定会有好奇阶段可能会让它批量改代码如果放在正式项目里一旦操作不当可能会造成一些不必要的改动。mkdir claude-playground cd claude-playground这个目录既是安装目录也是后续测试用的工作目录装完直接在里面跑不用来回切换上下文。3.2 npm安装命令与安装方式对比在测试目录里执行安装命令npm install anthropic-ai/claude-code注意这里我特意省略了-g参数也就是前面说的“项目内安装”。装完之后你会在当前目录下看到一个node_modules文件夹和一份package.json文件。启动方式是npx claudenpx是npm自带的一个命令它会先在当前目录的node_modules里找有没有claude这个命令找到了就用找不到再去全局环境找。这样即使你全局也装了它也会优先用项目内的版本。如果你之前已经全局安装过或者想在任何目录下都能直接启动那么用npm install -g anthropic-ai/claude-code安装后终端里直接敲claude就能进入交互界面。全局安装的好处是方便坏处是升级时得重新装一遍而且不同项目无法锁定各自的版本。这里给个对比表方便你按自己的场景选安装方式命令适用场景启动方式项目内安装npm install anthropic-ai/claude-code正式项目版本隔离npx claude全局安装npm install -g anthropic-ai/claude-code多目录快速使用尝鲜测试claude依赖包体积不小npm装起来可能需要几分钟如果卡在某个阶段长时间不动多半是网络问题。在国内环境可以考虑临时切换npm镜像源比如用npm config set registry https://registry.npmmirror.com装完再切换回来。这个方法在很多“vue安装及环境配置”、“maven环境配置”之类的教程里都有提到属于国内开发者的常规操作。但需要强调的是这只影响npm包下载速度不影响Claude Code后续的联网认证和调用那个环节仍需要稳定的网络连接。3.3 安装过程中的常见异常安装过程中最常见的报错有两类。一类是权限错误。在macOS或Linux上如果你用全局安装有时会遇到EACCES: permission denied之类的提示。这是因为npm默认的全局安装目录需要root权限。一个比较正规的解决办法是给npm配置用户级目录而不是直接sudo npm install。具体做法是npm config set prefix ~/.npm-global然后把这个目录加入PATH环境变量再重新安装。如果你用sudo npm install -g强行安装当时能用但后面升级、卸载都会遇到各种权限残留很麻烦。另一类是npm ERR! code EBADENGINE意思是当前Node.js版本不满足要求。解决方式很简单去装一个符合版本要求的Node.js LTS版本不需要去改什么配置文件。3.4 验证安装是否成功安装完成后在终端里执行npx claude --version如果看到类似0.2.x这样的版本号输出说明核心程序已经装好了。这个验证步骤别跳过因为下一节的身份认证还需要基于这个命令来触发版本号能正常输出说明Node环境、npm包、命令注册都没问题。4. 配置与身份认证让Claude Code跑起来4.1 首次启动与登录流程在测试目录里执行npx claude第一次启动时CLI工具会检查有没有已存在的登录凭证。没有的话它会进入交互流程引导你完成身份验证。通常在终端里会看到一个链接你需要用它来登录你的账号并在网页上确认授权完成之后终端会自动识别到凭证。这一套流程走完之后你不需要手动配置什么API Key环境变量Claude Code会把凭证存在你系统用户目录下的一个配置文件夹里之后启动会自动读取。4.2 配置解读CLAUDE.md文件如何使用登录成功进入交互界面后随手发一条消息试试比如“介绍一下当前目录的结构”。这时候Claude Code会读取当前目录的文件列表然后基于你的指令生成回答整个过程在终端里是流式的输出过程很像你在网页端和AI对话。如果你想让它长期记住一些“规则”就要用到CLAUDE.md文件。这个文件放在项目根目录下作用是给Claude Code定义当前项目的背景和约定。举个例子如果你在CLAUDE.md里写# 项目规范 - 代码风格使用TypeScript严格模式 - 测试框架使用Vitest - 提交规范遵循Conventional Commits提交信息必须包含对应的issue编号那么之后每次在这个目录里使用Claude Code它都会自动读取这个文件把里面的约定作为理解项目、生成代码、提建议时的默认依据。这一点是Claude Code比网页端对话工具更贴近“编程助手”定位的核心原因——它有一定的项目记忆能力而不是每次对话都从零开始。4.3 常见配置项和自定义选项除了CLAUDE.md之外Claude Code还有一些运行时配置项在配置文件中可以进行调整。其中比较常用的有模型选择、输出风格和权限控制。你可以在配置里指定某个模型作为首选模型也可以设置是否允许Claude Code自动执行修改文件的命令例如自动写入文件、自动运行测试还可以让它使用特定风格的输出比如简洁模式或详细模式。刚开始接触时建议开启“询问确认”模式也就是每次它想改文件或执行命令之前都会先问你要不要执行这样你可以看到它每一步的动作不容易出现它一口气批量改了一堆文件的情况。4.4 国内网络环境下的使用调整这是个绕不开的话题。Claude Code的推理服务需要持续和官方API保持通信如果网络环境不稳定可能会出现发送消息后长时间无响应或者中途输出中断、报连接超时。这些问题的根因在于你对官方服务的访问可用性不是Claude Code本身出了问题也不是你安装姿势不对。这一块我没办法做太具体的建议因为不同网络环境下可用的方案不一样。一个比较通用的排查思路是先确认你自己能否正常访问Anthropic的相关页面或API如果能说明网络没问题那问题大概率出在本地配置上如果不能就需要先解决网络可达性的问题再回头排查工具配置。另外用代理工具的朋友要注意Claude Code走的是Node.js的网络请求它的行为会受到系统代理或终端代理环境变量HTTP_PROXY、HTTPS_PROXY的影响如果代理不稳定也可能导致请求被中断。5. 手把手演示从启动到第一次跑通对话5.1 在测试目录里做一个简单项目为了验证安装是否真正可用我们在测试目录里写一个最简单的Python脚本然后让Claude Code来“接管”。mkdir demo-project cd demo-project创建两个文件。第一个是main.pydef add(a, b): return a b def subtract(a, b): return a - b if __name__ __main__: print(add(10, 5)) print(subtract(10, 5))第二个是test_main.pyfrom main import add, subtract def test_add(): assert add(3, 2) 5 def test_subtract(): assert subtract(5, 3) 2这个项目非常简单但足够用来测试Claude Code能不能正确理解上下文、执行命令、修改文件。5.2 让Claude Code理解项目并执行任务在demo-project目录下启动Claude Codenpx claude进入交互界面后输入main.py 请帮我分析一下这个文件它的功能是什么有没有可以改进的地方main.py是Claude Code的引用语法相当于明确告诉它“重点关注这个文件”它会把这个文件的内容作为上下文处理。很快它会给出分析指出这个模块做的是基本的四则运算然后可能会建议补充类型注解、增加异常处理、优化命名等。接着让它做实际的改动请给add和subtract函数加上类型注解并增加一个multiply函数同时在if __name__ __main__里测试一下新函数。如果Claude Code被配置为自动执行写入操作它会直接修改main.py文件改完后在对话里说明改了什么。整个过程都会在终端里显示出来你能清楚看到它调用了哪些工具、改动了哪些行。5.3 让它跑测试查看执行结果改完之后你可以让Claude Code直接跑测试请运行一下测试文件看看有没有报错。Claude Code会在终端里执行类似python -m pytest这样的命令然后把测试结果的摘要返回给你。如果测试挂了它还会分析失败原因并给出修改建议你可以继续让它修复整个迭代都在同一个对话里完成。这一套流程能走通说明你的安装和配置已经完全没有问题了。6. 实战中高频踩坑与排查技巧6.1 安装报错排查速查表我把安装和首次使用阶段最常见的报错整理成一个速查表方便你对照解决。报错信息含义解决方案node: not found或node 不是内部或外部命令Node.js 未安装或未加入 PATH重新安装 Node.js勾选 Add to PATH重开终端EBADENGINENode.js 版本过低安装 Node.js 18 以上版本推荐 20 LTSEACCES: permission deniednpm 全局目录无权限配置 npm 用户级前缀目录不要用 sudo 硬装npm ERR! code ETIMEDOUT网络超时切换 npm 镜像源后重试或检查自身网络状态Authentication failed登录凭证无效或已过期重新执行登录流程确认账号正常The user rejected your request在网页端拒绝了授权重新发起授权请求点击允许TypeError: fetch failed网络请求失败通常和代理有关检查系统代理、终端代理环境变量是否稳定每一行都是我实际踩过或者陪朋友排查过的尤其是fetch failed这个问题排查起来最折腾因为它不一定是代码问题而是网络链路问题。6.2 网络连接类问题的通用排查顺序如果你遇到发送消息后长时间没有回应或者回复到一半中断先不要急着卸载重装按下面这个顺序排查一检查你的机器能不能正常访问Anthropic官网和API。如果浏览器都无法打开说明网络链路本身有问题需要先解决底层访问问题。二检查系统代理或终端代理环境变量。在终端里执行echo $HTTP_PROXY echo $HTTPS_PROXY如果有输出说明终端请求走了代理代理不稳定的话即使你网页端正常Claude Code也会异常。三尝试把代理环境变量清空再试看看是不是代理导致的。四如果代理关了仍然不行再考虑是不是Node.js环境本身有异常可以用npx claude --debug启动调试模式观察日志输出。这套顺序基本能覆盖九成以上的连接问题。核心思想是先把“网络层”和“工具层”分开大部分诡异问题最后都指向网络层不是工具本身。6.3 一个容易被忽略的坑目录权限Claude Code在读取和写入文件时用的是启动它的那个用户的权限。如果你在某个目录下启动它而这个目录属于root或其他用户那么你会发现它读文件可以但写入文件时报EACCES错误。这个问题的排查方式很简单在终端执行ls -ld查看当前目录的属主如果不是你的用户名用sudo chown -R 用户名:用户组 目录路径改一下属主。特别是那些从服务器上拉下来的项目目录、或者用sudo创建过的目录最容易出现这个问题。还有一个更隐蔽的变种仓库根目录下面某些子目录是软链接symlink权限指向另一个位置。这种情况下Claude Code可能会提示“operation not permitted”但直接看目录属主也看不出问题排查时可以用ls -l看看有没有-符号有的话就顺着链接路径检查目标目录权限。6.4 在VS Code或其他IDE里使用Claude Code很多朋友问能不能在VS Code里用Claude Code因为平时写代码都在IDE里。很明确地说可以而且体验不错。做法有两种。一种是在VS Code的终端里直接跑claude或npx claude。VS Code的终端集成度很高能自动识别当前打开的工作区目录Claude Code会把这个工作区目录作为项目根目录读取文件范围刚好对齐不用手动切目录。另一种是装相关的扩展插件在编辑器侧边栏里直接唤起Claude Code面板这个方式更接近AI编程助手的交互体验不过不同扩展的实现质量差别比较大选的时候看看下载量和最近更新时间。不管用哪种方式都建议先在终端里跑通一遍基础的安装和认证再进IDE不然在IDE里报错会很难判断是哪一层的问题。7. 安装完成后的进阶操作与效率技巧7.1 给它“立规矩”自定义CLAUDE.md模板刚才说到的CLAUDE.md实际用起来非常灵活它不只可以约定代码风格还能约束Claude Code的行为边界。比如你不希望它在没有确认的情况下安装任何新的依赖包就在CLAUDE.md里写# 操作约束 - 未经用户明确同意禁止执行任何包安装命令 - 修改文件前先在对话中说明改动计划 - 提交代码前必须运行完整的测试套件这样一来Claude Code在这些项目里的行为就是“可控”的不是那种一上来就大改一通的感觉。我常用的做法是给不同类型的项目准备不同的CLAUDE.md模板前端项目、后端项目、数据脚本项目各一份新项目开始时直接复制过去再根据项目类型微调。7.2 配合其他工具链使用Claude Code还有一个很实用的用法就是可以和其他命令行工具联动。比如你在调试一个功能先用Claude Code定位到问题文件然后再用你自己惯用的调试工具、测试工具来做细粒度操作。热词里出现了“claude code cc switch ollama”这里解释一下cc switch是一个用来快速切换Claude Code配置比如切换不同模型端点或账号体系的社区工具ollama是本地运行开源模型的工具。这套组合的思路本质上是让Claude Code变成一个“前端入口”后端既可以接Anthropic官方服务也可以接本地模型或第三方兼容接口。它的优点是可以离线使用一部分能力、成本可控缺点是本地模型的能力比起官方模型版本还是有明显差距。我自己只在做代码量很小的脚本类任务时会切到本地模型正经写项目代码时还是用官方服务更稳。7.3 升级和降级的正确方式Claude Code更新迭代很快隔几周就会有一个新版本。升级方式很简单重跑一遍安装命令就行npm install -g anthropic-ai/claude-codelatest如果新版用着不顺手想降级到某个旧版本这样操作npm install -g anthropic-ai/claude-code0.2.1把版本号换成你想要的版本即可。不过升级前建议先看一下项目目录下的package.json里锁定的版本以及CLAUDE.md里是否有关键行为的依赖避免升级后行为变化影响工作流。这也是我为什么不建议在正式项目里用全局版本的原因——如果全局自动升级了项目里的行为也跟着变了容易出意外。8. 最后说点实在的经验从开始装Claude Code到现在我在不同系统上装过很多次踩坑最多的其实不是安装环节而是后面用起来之后的“环境问题”和“使用习惯问题”。安装环节本身并不复杂无非就是Node.js版本够不够、npm安装有没有被网络卡住、身份认证是不是顺利。真正决定成败的是两件事一是你自身有没有稳定的网络访问官方服务的能力这决定了你之后每次使用是否顺畅二是你有没有养成给Claude Code“立规矩”的习惯也就是用好CLAUDE.md文件让它在一个明确的边界内工作而不是放养式对话。再分享一个小细节Claude Code的输出是直接在你的终端里流式显示的如果你的终端字体设置偏小、配色方案偏暗长代码输出时看起来会特别费劲。建议把终端字号调到14号以上配色方案换成带较高对比度的主题这个投入特别小但日常使用体验的提升非常明显。这套流程走完你已经具备了日常使用Claude Code的基础能力。至于后面怎么把它和你的具体工作流结合起来——比如做成提交代码的自动检查器、作为数据库脚本的生成器、甚至配合cc switch在不同模型服务之间切换——那都是在这个基础上自然生长出来的东西了用到的时候再一步步探索就好。