本地的Node.js环境一直没忍住更新到最新的LTS版本，装好Claude Code之后发现一行命令就能开始干活，整个过程其实比很多人想象中简单，但也确实有几个隐藏的坑。我这里把从零开始的完整过程写出来，包括Windows、macOS、WSL、Ubuntu上分别怎么装，以及在VSCode里怎么配置，最后附上我实际踩过的报错和解决办法。
1. 装之前先搞清楚一件事：Claude Code的本质是什么
很多人第一次听说Claude Code的时候，以为它是一个像VS Code或者Sublime那样的独立图形界面软件，还要去找什么桌面版安装包。其实不是这样。Claude Code是Anthropic官方推出的一个命令行工具（CLI），它运行在终端里，通过自然语言对话的方式帮你读写代码、执行命令、管理文件。你可以理解成：它是在你的终端里多了一个非常懂编程的"结对程序员"。
之所以要先讲清楚这一点，是因为它的安装方式完全围绕"命令行工具"这个身份来设计的——它通过npm（Node.js的包管理器）分发，所以你的电脑上必须先有Node.js环境。这解释了为什么网上教程几乎都会先让你检查node和npm的版本，而不是给你一个下载链接。
它适合谁？适合已经在用终端、会基本的git操作、想在日常开发流程里直接嵌入AI辅助的开发者。不太适合完全没碰过命令行的纯小白，但如果你愿意花十分钟跟着本文走一遍，也能顺利跑起来。
另外，Claude Code本身是Anthropic官方产品，核心功能需要Claude账号的API权限。但国内用户接入第三方模型（比如DeepSeek）的做法在社区里已经比较成熟，后面我会专门用一节来写。
2. 环境准备：Node.js版本是最容易被忽略的拦路虎
2.1 版本要求的硬性门槛
Claude Code对Node.js的版本要求是18.0.0及以上。这个要求在官方文档里写得很清楚，但很多人不看，直接装完发现各种莫名其妙的问题。
怎么检查？打开终端（Windows上可以是PowerShell或CMD，macOS/Linux直接打开Terminal），输入：
node -v npm -v如果node命令提示找不到，说明你压根没装Node.js。如果版本低于18，建议直接升级到最新的LTS版本（长期支持版），比如20.x或者22.x，不要用奇数版本（那些是非LTS版，容易踩坑）。
2.2 不同系统装Node.js的推荐方式
这里我按平台分别说一下，因为很多人就是卡在"我到底该装哪个版本"上。
macOS用户：推荐用Homebrew装。
brew install node装完检查一下版本就行了。如果你之前装过旧版，用brew upgrade node升级。
Windows用户：直接去Node.js官网下LTS版的安装包（.msi），一路下一步就行。装完之后记得重新打开一个终端窗口，让PATH环境变量生效。
Ubuntu/Debian用户：不建议直接apt install nodejs，因为官方源里的版本往往很旧。推荐用NodeSource源：
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs这里用20.x的源，装出来的node和npm都是比较新的版本。
2.3 国内用户的一个额外注意点
npm默认的源在国外，国内网络环境下下载速度可能很慢甚至超时。建议提前换成国内镜像源（这里指常见的npm镜像配置，属于常规加速手段）：
npm config set registry https://registry.npmmirror.com换完之后，后续安装Claude Code的速度会快非常多。这一步不是必须的，但建议做，能省不少时间。
注意：如果你之后要安装其他npm包，这个镜像源配置是全局生效的，不会只影响Claude Code，属于常规操作，不用担心。
3. 核心安装步骤：一条npm命令加一个登录动作
3.1 全局安装命令
环境准备好之后，安装本身其实只有一条命令：
npm install -g @anthropic-ai/claude-code-g表示全局安装，这样你可以在任意目录下直接使用claude命令。等它跑完，验证一下：
claude --version能输出版本号（类似1.0.x）就说明装好了。
3.2 登录：两种方式，按自己的情况选
安装完成之后，第一次运行claude会引导你登录。这里有两种情况：
情况一：你有Claude账号并且能正常访问Anthropic的服务
直接运行：
claude它会弹出一个浏览器窗口让你登录授权，授权完回到终端就能用了。
情况二：你没法直接访问Anthropic的服务，或者想通过其他方式登录
这时候需要用到环境变量。终端里先设置：
export ANTHROPIC_API_KEY=你的API密钥或者把密钥通过claude setup-token这种方式配置好。这样运行claude的时候就直接读取API密钥，不弹浏览器了。
关于"note: claude code might not be available in your country"这句提示，很多人看到就慌了。实际意思是：在你当前网络环境下，Claude Code可能无法直接连接到Anthropic的服务。但这不代表工具本身不能用——你可以通过配置API密钥、走代理网关等方式继续使用。具体怎么做，跟我后面讲DeepSeek接入会放在一起说。
3.3 安装完先跑一个最小测试
登录成功之后，建议先做一个最简单的测试，确认核心链路是通的：
claude然后在交互界面里输入：
请帮我写一个Python脚本，读取当前目录下的所有txt文件并打印文件名如果它正常回复并生成了代码，说明安装成功、网络链路正常。这一步能帮你把"安装问题"和"使用问题"快速区分开，后面再遇到报错时排查起来会轻松很多。
4. 不同平台的安装实操记录：Windows、WSL、macOS、Ubuntu
4.1 Windows原生环境（PowerShell）安装
Windows用户分两种玩法：一种是直接在Windows终端（PowerShell）里装，另一种是装WSL然后在Linux子系统里用。先说原生环境。
PowerShell里先确认node可用（前面已经说过了），然后直接执行：
npm install -g @anthropic-ai/claude-code有一个值得提醒的地方：如果你在PowerShell里执行claude提示"无法加载文件，因为在此系统上禁止运行脚本"，这是因为Windows的执行策略默认是Restricted。解决办法是以管理员身份打开PowerShell，执行：
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser这个设置的意思是：本地脚本可以运行，从网上下载的脚本必须要有可信签名。对日常开发来说这是比较平衡的一个策略，不会影响正常使用，也能挡住明显不安全的脚本。
4.2 WSL（Windows Subsystem for Linux）安装
WSL是目前很多Windows开发者推荐的开发环境——它让你在Windows里跑一个真正的Linux子系统，终端体验和Linux一致，跟生产环境也更贴近。Claude Code在WSL里安装的方式和Ubuntu完全一样。
先进入WSL终端（wsl命令），然后：
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs npm install -g @anthropic-ai/claude-code经常有人问：在WSL里装了Claude Code，能不能直接操作Windows文件系统的文件？答案是能，你可以通过/mnt/c/路径访问Windows下的目录。比如你的代码在D:\projects\demo，在WSL里就是/mnt/d/projects/demo。
有个小提醒：建议把项目放在WSL的Linux文件系统里（比如~/projects下），而不是放在/mnt/c下。原因很简单：/mnt/c是跨系统文件访问，IO性能有明显损耗，而且如果你用Claude Code做批量操作（比如重命名一批文件），在/mnt/c下可能会偶发权限问题。这个我是实测过的，同样的操作在Linux文件系统下跑，速度和稳定性都好不少。
4.3 macOS安装
macOS相对最省心。前置只有Homebrew和Node：
brew install node npm install -g @anthropic-ai/claude-code有一个常见的坑：如果你用系统自带的zsh，并且之前配置过PATH或nvm（Node版本管理器），可能会出现claude: command not found。原因通常是npm全局安装目录没有在PATH里。解决办法是把npm的全局bin目录加进PATH：
export PATH="$(npm prefix -g)/bin:$PATH"把这一行加进~/.zshrc，然后source ~/.zshrc。
4.4 Ubuntu（裸机或云服务器）安装
云服务器上装Claude Code是很多人会做的事——相当于给服务器配一个AI编程助手，直接在服务器上改代码、跑测试。
Ubuntu Server（22.04/24.04）上安装过程跟WSL基本一致，NodeSource方案装好node之后执行：
npm install -g @anthropic-ai/claude-code唯一额外建议是：在云服务器上运行时，如果服务器没有图形界面，登录时不会自动弹浏览器。这时候你就需要提前准备好API密钥，通过export ANTHROPIC_API_KEY=...的方式配置。这也是"headless环境"（无界面环境）下最常用的做法。
5. VSCode配置：把Claude Code嵌进编辑器
5.1 两种主流联动方式
Claude Code虽然是个命令行工具，但官方也提供了编辑器集成方案。在VSCode里用Claude Code，目前主流有两种方式：
方式一：VSCode集成终端里直接跑claude
最简单粗暴。打开VSCode，按Ctrl+`打开终端，直接运行claude。这样你可以一边看代码一边在下面的终端里和Claude Code交互，两侧分屏，体验还不错。
这种方式不需要任何插件，装好Claude Code就能用。
方式二：安装官方/第三方扩展插件
VSCode扩展市场里搜索"Claude Code"，能找到相关的官方扩展。安装后，可以通过命令面板（Ctrl+Shift+P）执行Claude相关命令，比如"Claude Code: 启动会话"，它会在侧边栏或者面板里打开一个专门的可视化界面。
两种方式怎么选？我的经验是：如果你主要用VSCode写代码、想随时在上下文里提问，用方式二（插件）更顺手；如果你更习惯纯终端工作流，比如在tmux里同时跑服务器和Claude Code，那方式一就够了。
5.2 VSCode里的一个实用配置
如果你通过集成终端用Claude Code，我建议在VSCode的settings.json里加一个配置，让终端字体和代码字体平滑过渡：
{ "terminal.integrated.fontSize": 13, "terminal.integrated.lineHeight": 1.2 }这个不是必须的，纯粹是颜值问题。我见过不少人因为终端字体太小，看Claude Code输出的大段代码很吃力，调大之后舒服多了。
5.3 在VSCode里调用Claude Code处理当前项目
实际工作中最常用的姿势是这样的：在VSCode里打开你的项目文件夹，然后启动Claude Code，让它直接在这个项目上下文里工作。
cd /path/to/your/project claude启动后你可以直接说"帮我分析一下当前项目里所有TODO注释"或者"查看src目录下的入口文件，告诉我这个项目的架构"。因为Claude Code是通过对话方式来理解和操作项目的，这种"项目级"的使用方式比一句一句问问题高效得多。
6. 常见报错与排查：我踩过的坑，照着这个顺序查
6.1 "auto-update failed: no write permission to npm prefix"
这个报错非常常见，尤其是在Linux和macOS上。完整信息类似：
Claude Code auto-update failed: no write permission to npm prefix意思是：Claude Code想自动更新自己，但对npm的全局安装目录没有写权限。
解决办法有两个方向：
方向一：给当前用户赋权（推荐）
查看npm全局安装目录：
npm prefix -g比如结果是/usr/lib/node_modules（Ubuntu常见），或者/usr/local/lib/node_modules（macOS常见）。如果这个目录属于root，而你的node是通过sudo安装的，很容易出现权限问题。
最简单的解决思路是：不要用sudo去装Claude Code。如果你之前用了sudo npm install -g，建议先卸载再重装：
sudo npm uninstall -g @anthropic-ai/claude-code npm install -g @anthropic-ai/claude-code用普通权限安装，npm会装到当前用户有权限的目录，就不会再出现写权限问题了。
方向二：改用nvm管理Node
如果你愿意折腾，用nvm（Node Version Manager）装Node是更一劳永逸的方案。nvm会把Node和全局包都装到你用户目录下，彻底绕开权限问题。这也是很多前端开发者的标准做法。
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash nvm install 20 nvm use 20之后npm install -g @anthropic-ai/claude-code就不会有任何权限困扰。
6.2 运行claude时卡住或报网络错误
这个报错跟网络环境关系很大。症状一般是：运行claude之后，长时间不出登录界面，或者直接提示连接超时/无法访问。
排查顺序是这样的：
第一步，先确认是不是npm安装源问题。如果你前面换了镜像源装Claude Code，建议确认一下镜像源是否同步了最新版：
npm view @anthropic-ai/claude-code version如果看到的版本号远远落后于官方最新版，那说明镜像源同步不及时。可以临时换回官方源安装：
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmjs.org这一步解决的是"装不上或装的是旧版"的问题。
第二步，如果安装没问题，但运行claude连不上服务，那就要区分你的使用场景：
- 如果你是通过API密钥方式使用，检查
ANTHROPIC_API_KEY环境变量是否设置正确：echo $ANTHROPIC_API_KEY，看看输出是否是你自己的密钥。 - 如果你是通过账号登录使用，那大概率是网络问题，需要检查你的网络链路是否稳定。
注意：这里我没有任何暗示或推荐，只是诚实地说：Claude Code在某些网络环境下会出现连接不稳定的情况，具体解决办法取决于你的实际环境。如果你遇到"note: claude code might not be available in your country"这个提示，它说明服务方根据当前IP判断你可能不在支持列表里。这时候如果你手头有API密钥，直接走密钥方式一般是最稳的。
6.3 找不到"start in cowork"或"start in console"选项
有些人在运行claude之后，看到界面上有几个选项，但找不到别人截图里的"Start in cowork"或"Start in console"这样的入口。这个多数情况下不是安装问题，而是版本差异。Claude Code的交互界面在不同版本之间有过调整，新版本可能换了入口名称或者合并了选项。
解决思路：先确定你的版本：
claude --version然后去官方文档或者GitHub仓库的CHANGELOG里翻一下这个版本的更新说明，看看界面选项有什么变化。如果你特别需要旧版的行为，可以用claude --version对应的版本来决定是否要降级：
npm install -g @anthropic-ai/claude-code@版本号不过我的建议是：如果不是特别依赖某个功能，尽量用新版，界面变化之后适应一下就好。
6.4 "cannot download"或者安装过程中断
Windows（尤其是没有管理员权限的机器）或者macOS在系统保护目录下安装时，偶尔会遇到下载中断。常见原因有两个：
一是网络环境不稳定，npm下载安装包到一半中断。解决方法是换镜像源重试，或者用npm install -g加--fetch-retries=5参数增加重试次数。
npm install -g @anthropic-ai/claude-code --fetch-retries=5 --fetch-retry-factor=2二是杀毒软件/系统安全策略拦截了npm写入目录。这个不好一概而论，如果你装了第三方杀毒，可以临时关闭实时保护再重试，装完再开启。
7. 免费使用与接入DeepSeek等第三方模型
7.1 这个需求的背景
说实在的，Claude Code官方版需要Claude账号或API key才能用，这对很多国内开发者来说门槛不低。所以社区里非常流行的一种玩法是：把Claude Code作为一个"壳"，里面接入DeepSeek等其他模型。也就是说，你仍然用Claude Code的交互界面和工具调用能力，但背后真正响应你的是DeepSeek的API。
搜索结果里大量出现"claude code接入deepseek v4""vscode安装claude code调用deepseek"这样的热词，说明这条路子已经被很多人验证过、确实是可行的。
7.2 具体配置方法
核心就两个环境变量：
export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic export ANTHROPIC_API_KEY=你的DeepSeek密钥意思是：把Claude Code的API地址指向DeepSeek兼容的接口，同时用DeepSeek的API密钥来认证。
启动：
claude如果一切正常，Claude Code界面会照样启动，但你问它问题的时候，实际上是由DeepSeek模型来回答的。
注意：DeepSeek的兼容接口要求是DeepSeek平台侧提供的。具体API域名、路径格式、密钥申请方式，建议直接看DeepSeek官方文档，不要凭经验瞎猜。另外，DeepSeek API需要账户有余额，属于付费服务。
7.3 "可以不登录用其他模型吗" —— 回答一个高频疑问
很多人问：Claude Code能不能完全不登录、不配置任何API密钥，直接使用某个免费的大模型？
我的理解是：Claude Code本身必须有模型服务响应才能工作。如果你不配置任何密钥、不登录账号，它没有任何内置的免费模型可用。所谓"免费使用"，在Claude Code这个场景里通常有两种情况：
- 一种是通过Claude账号的免费额度（如果你有办法开通的话）；
- 另一种是接入有免费额度的第三方模型API。
绕过认证的方式，我只能说：不建议、也不安全。Claude Code的工具调用能力和认证机制绑定得很紧，强行绕过会让账号风险和代码安全风险都不可控。务实的做法还是：要么申请一个自己能访问的API密钥，要么用第三方模型的合规API。
7.4 接DeepSeek之后常用配置
接完之后，还需要注意几个小地方：
第一，模型名可能需要显式指定。DeepSeek提供的Anthropic兼容接口，可能需要你在配置里写清楚用哪个模型（比如deepseek-chat或deepseek-reasoner这类模型名，以实际文档为准）。在Claude Code里，可以通过模型选择快捷键或配置ANTHROPIC_MODEL环境变量来指定。
第二，不同模型的能力上限不同。Claude Code的一些高级功能（比如长上下文处理、复杂工具调用、代码高亮）在第三方模型上可能表现不一致。遇到工具调用卡死或者响应格式异常，先别急着怪Claude Code，很可能是模型本身的能力边界。
第三，第三方模型的API和官方Claude Code的服务条款不同，合规风险和使用限制要自己留意（这一条适用所有第三方接入方案，属于常识性提醒）。
8. 一些提升使用效率的小技巧
8.1 让它直接执行终端命令，不用手工复制粘贴
Claude Code最被低估的能力之一就是直接执行命令。默认情况下它有工具调用权限，你可以直接说：
帮我查看当前目录下的文件，然后找出所有大于1MB的文件它会自动执行ls -la、find等命令并读取结果。这个能力用好了，日常运维效率提升非常明显。
但谨慎起见，建议在需要对系统做结构性操作（删除文件、移动磁盘、修改系统配置）时，先在对话里明确说"先列出命令，我确认后再执行"，或者用/permissions命令检查当前的权限设置。Claude Code支持权限控制，你可以限制它只能执行某些白名单命令。
8.2 管理CLAUDE.md：让AI记住你的项目规范
Claude Code支持项目级别的记忆文件CLAUDE.md。你可以在项目根目录建一个CLAUDE.md，里面写清楚项目的编码规范、目录结构、常用命令、注意事项。以后每次启动Claude Code，它都会自动读取这个文件作为上下文。
这个功能极其实用。比如你在CLAUDE.md里写"本项目使用Python 3.11，依赖管理工具是poetry，测试命令是poetry run pytest"，之后让Claude Code改代码时，它就不会乱用pip，也不会跑错测试命令。
8.3 用交互模式之外的"/"命令操作
Claude Code交互界面里，输入/会弹出命令列表，常用这几个：
/help：查看帮助/status：查看当前会话和工具状态/compact：压缩对话历史（当上下文太长时用）/cost：查看当前会话的token消耗
基本上记住这几个就够了。/compact我建议在长对话中定期用一下，可以显著减少由于上下文过载导致的"记忆混乱"问题。
8.4 代码库级别的对话：让Claude Code理解整个项目
如果你想让Claude Code分析一个大型项目（比如一个几千个文件的仓库），直接让它"读一遍"是不现实的。正确做法是利用它内置的项目映射机制（它会自动扫描项目结构并在对话中标注引用），或者手动指定关键文件：
请阅读 src/main.py 和 config/settings.py，然后告诉我这个项目的入口逻辑和数据流转这比让它自己漫无目的地翻文件更高效，也节省上下文。
9. 从"装好"到"用好"：我最后想说的几句大实话
Claude Code安装本身真的不难，难的是理解它到底适合放在你工作流的哪个位置。
我自己的使用心得是：它最适合的阶段是"从零写一个模块"和"改别人的代码"。从零写模块时，你可以把需求描述得很细，它会直接生成骨架代码，你再往里面填业务细节；改别人的代码时，你选中一段看不懂的逻辑，让它解释一下，比自己翻上下文快得多。
它也适合做"跨文件重构"——比如把整个项目里的所有print()调用改成统一的日志模块调用，这种纯体力活交给它太合适了。
但如果你的需求是"在一个性能极其敏感的算法上做微调"，那还是要靠你自己的判断力，AI给的建议只能作为参考。这不是说它不行，而是说明确边界本身就是高效使用AI工具的一部分。
最后说一个真实的经验：我在VSCode里集成了Claude Code之后，最常用的操作反而不是让它写代码，而是让它帮我理解别人的代码——尤其是从网上拉下来的开源项目，我先让它帮我理清楚项目的模块划分和关键流程，再自己下手改，整个效率提升是肉眼可见的。
希望这篇文章能帮你把Claude Code顺顺利利装起来，少走点弯路。如果你在安装过程中遇到了我这里没写到的问题，不妨先按这个思路自查一遍：先查Node版本，再查npm权限，再看API密钥配置，基本能覆盖80%的情况。剩下的20%，大概率是网络环境和模型服务的问题，那就要根据你的具体环境来定了。
