Claude Code 安装与卸载全指南：Node.js 环境配置、npm 全局包管理与常见问题排查

1. 为什么值得花时间搞清楚这套工具的安装与卸载Claude Code 是 Anthropic 推出的命令行 AI 编程助手它直接跑在终端里能读写你本地的代码文件、执行命令、理解整个项目结构。和网页版对话不同它更像一个坐在你旁边、能直接动手改代码的搭档。而它的安装方式走的是 npm 全局包这条路这就意味着 Node.js 环境、npm 配置、系统权限、Shell 脚本策略这些环节任何一个出问题都会让你卡在第一步。我见过太多人在这上面翻车有人npm install跑完以为装好了结果敲claude提示命令不存在有人在 PowerShell 里遇到那个经典的“无法加载文件 npm.ps1因为在此系统上禁止运行脚本”报错折腾一下午没解决还有人想卸载却发现残留一堆配置文件和缓存不知道哪些该删哪些不该删。这些问题本身都不复杂但如果没有一份把前因后果讲清楚的指南新手很容易在环境配置阶段就放弃。这篇文章面向所有想用 Claude Code 的人不管你是刚接触命令行的新手还是已经用过其他 npm 工具的开发者。我会把安装、登录、卸载三个环节拆开讲透每个步骤都解释为什么这么做遇到问题怎么排查。你跟着走一遍基本能一次搞定不用反复试错。2. 安装前的环境准备Node.js 与 npm 的正确姿势2.1 Node.js 版本选择与安装方式Claude Code 依赖 Node.js 运行环境官方要求 Node.js 18 或更高版本。我的建议是直接上 LTS长期支持版本目前是 20.x 或 22.x 系列。别去追最新的奇数版本那些是实验性的可能引入兼容问题。热词里有人提到 “node.js v24.21.0 is not yet released” 这种报错就是因为指定了一个根本不存在的版本号npm 找不到对应的包自然报错。安装 Node.js 有三条路我按推荐程度排一下官方安装包去 nodejs.org 下载 LTS 版本的安装程序Windows 是 .msimacOS 是 .pkg。这种方式最省心安装程序会自动配好环境变量和 npm。版本管理器macOS/Linux 上用 nvmWindows 上用 nvm-windows 或 fnm。好处是可以在多个 Node.js 版本之间切换项目之间不打架。如果你同时维护多个项目强烈建议走这条路。系统包管理器Ubuntu 上可以用aptmacOS 上用 Homebrew。但系统源里的 Node.js 版本往往偏旧可能不满足 Claude Code 的要求需要额外配置源才能装到 20 版本。装完之后验证一下打开终端敲node -v npm -v两条命令都能输出版本号说明环境没问题。如果node -v有输出但npm -v报错那多半是 npm 没跟着装上或者环境变量没配好。2.2 npm 镜像源配置国内用户的加速方案npm 默认的 registry 在国外国内直接拉包经常慢到怀疑人生甚至超时失败。换成国内镜像源能显著提速。目前常用的有淘宝源npmmirror和腾讯源。设置方式npm config set registry https://registry.npmmirror.com设置完可以用npm config get registry确认一下。想换回官方源就把地址改回https://registry.npmjs.org。注意有些公司内网有自己的私有 registry如果你在公司环境下操作先确认一下是否需要走内部源别盲目改成公共镜像导致拉不到内部包。另外如果你只是临时想用某个源装一次包可以用--registry参数指定不影响全局配置npm install -g anthropic-ai/claude-code --registry https://registry.npmmirror.com2.3 Windows 用户的 PowerShell 脚本策略问题这是 Windows 上最高频的坑。你在 PowerShell 里敲 npm 相关命令可能直接弹这个错npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1因为在此系统上禁止运行脚本原因不是 npm 坏了而是 Windows 的 PowerShell 默认执行策略Execution Policy限制了脚本运行。npm 在 PowerShell 里是通过一个 .ps1 脚本调用的策略不允许就跑不起来。解决办法有两种方案一修改执行策略推荐以管理员身份打开 PowerShell执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUserRemoteSigned的意思是本地脚本可以跑从网上下载的脚本需要签名。-Scope CurrentUser表示只对当前用户生效不影响系统其他用户比较安全。执行后会提示确认输入 Y 回车即可。方案二改用 CMD 或 Git Bash如果你不想动系统策略可以直接用 CMD命令提示符代替 PowerShellCMD 不受这个策略限制。或者装个 Git Bash在里面操作也没问题。实操心得改执行策略这件事很多人担心有安全风险。实际上RemoteSigned加上CurrentUser范围风险是可控的。真正危险的是Unrestricted全局放开那个不建议用。3. Claude Code 的安装实操从命令到验证3.1 全局安装命令与参数解读环境准备好之后安装本身就一条命令npm install -g anthropic-ai/claude-code拆解一下这条命令install是安装-g表示全局安装global装完之后在任何目录下都能调用claude命令。包名是anthropic-ai/claude-code这是官方发布的 npm 包。为什么不装成项目本地依赖因为 Claude Code 是一个工具型 CLI不是某个项目的库。全局装一次所有项目都能用没必要每个项目重复装。安装过程中你会看到 npm 在拉取依赖、解压、链接可执行文件。如果卡在某个环节不动大概率是网络问题检查一下镜像源配置。如果报权限错误EACCES 或 EPERM说明当前用户没有全局目录的写权限。3.2 权限报错的两种解决路径Linux 和 macOS 上全局安装默认会往/usr/local/lib/node_modules写东西普通用户没权限就会报 EACCES。有两种处理方式方式一改 npm 全局目录到用户目录mkdir -p ~/.npm-global npm config set prefix ~/.npm-global然后把~/.npm-global/bin加到 PATH 环境变量里。在~/.bashrc或~/.zshrc末尾加一行export PATH~/.npm-global/bin:$PATH重新加载配置文件source ~/.bashrc就生效了。这种方式不用 sudo更安全。方式二用 sudo 安装sudo npm install -g anthropic-ai/claude-code简单粗暴但有个隐患sudo 装的包属于 root 用户后续升级或卸载时可能又需要 sudo而且可能带来权限混乱。我个人更推荐方式一。Windows 上一般不会有这个问题因为全局目录在用户 AppData 下天然有写权限。如果真遇到权限问题检查一下是不是用了什么安全软件拦截了文件写入。3.3 安装后的验证与 PATH 排查装完之后敲claude --version能输出版本号就说明安装成功。如果提示command not found或claude 不是内部或外部命令那就是 PATH 没配好npm 的全局 bin 目录不在系统搜索路径里。排查步骤先查 npm 全局目录在哪npm config get prefix输出的路径下的binWindows 是根目录本身就是可执行文件所在位置。检查这个路径是否在 PATH 里。Linux/macOS 用echo $PATHWindows 用echo %PATH%。不在的话手动加进去。Windows 通过“系统属性 → 环境变量”图形界面添加Linux/macOS 改 shell 配置文件。注意Windows 上改完环境变量需要关掉当前终端重新开一个才生效因为环境变量是终端启动时读取的。4. 登录与初始化配置让工具真正跑起来4.1 首次启动的登录流程安装成功只是第一步Claude Code 需要登录账号才能用。在终端里进入你的项目目录敲claude首次运行会引导你完成登录。它会给出一个链接让你在浏览器里打开并授权。授权完成后终端会自动获取到凭证完成登录。登录凭证会保存在本地配置目录里macOS/Linux 通常在~/.claude或~/.config/claudeWindows 在%USERPROFILE%\.claude。这个目录里存了认证信息和一些偏好设置。如果你在无图形界面的服务器上操作没法打开浏览器Claude Code 通常也支持通过 API Key 的方式认证。具体方式是在启动时按提示选择对应的认证方式或者设置环境变量。这个细节官方文档会随版本更新建议以你安装的那个版本的提示为准。4.2 在 VS Code 中集成使用热词里有人搜 “claude code for vs code” 和 “vscode 配置 claude code”说明不少人想在编辑器里直接用。Claude Code 本身是终端工具但可以在 VS Code 的集成终端里运行体验很顺一边是代码一边是终端里的 AI 助手改完直接看到效果。配置方式很简单在 VS Code 里按Ctrl打开集成终端直接敲claude就行。如果想让它在特定项目目录启动先在 VS Code 里打开项目文件夹再开终端工作目录自然就是项目根目录。有些版本还提供了 VS Code 扩展能在侧边栏直接对话。装扩展的方式是在 VS Code 扩展市场搜 “Claude Code”找到官方发布的那个安装。装完可能需要配置一下 CLI 路径指向你全局安装的 claude 可执行文件。4.3 项目级配置与忽略文件Claude Code 在项目里工作时会读取项目文件作为上下文。有些文件你不想让它碰比如密钥文件、大型二进制文件、构建产物。可以在项目根目录建一个.claudeignore文件类似.gitignore的语法列出要排除的路径。另外你可以在项目里放一个CLAUDE.md文件写一些项目约定、代码规范、常用命令Claude Code 启动时会自动读取相当于给它一份项目说明书。这个文件对提升协作效率很有帮助建议每个项目都配一个。实操心得CLAUDE.md里写清楚项目的技术栈、目录结构、构建和测试命令能明显减少 AI 问东问西的情况。我一般还会写上“不要修改 xx 目录”“提交前必须跑 lint”这类约束。5. 卸载与清理干净移除不残留5.1 标准卸载命令卸载 Claude Code 本体就一条命令npm uninstall -g anthropic-ai/claude-codeuninstall是卸载-g对应安装时的全局标志包名要和安装时一致。执行完 npm 会移除包文件和对应的可执行链接。验证是否卸载干净再敲claude --version如果提示命令不存在说明本体已经移除。5.2 残留配置与缓存的清理npm 卸载只移除包本身不会动你的配置文件和缓存。这些残留包括配置目录~/.claude或~/.config/claudeWindows 在%USERPROFILE%\.claude里面有登录凭证、偏好设置、历史记录。npm 缓存npm cache里可能还留着这个包的 tarball。项目里的.claudeignore、CLAUDE.md等文件这些是你自己创建的卸载工具不会删。如果你想彻底清理把配置目录删掉rm -rf ~/.claudeWindows 上用文件资源管理器找到对应目录删除或者用 PowerShellRemove-Item -Recurse -Force $env:USERPROFILE\.claude清 npm 缓存可以用npm cache clean --force注意删配置目录会丢失登录状态和所有本地设置下次装回来要重新登录。如果你只是暂时不用想保留配置就别删这个目录。5.3 卸载全局包时的常见问题热词里有 “npm 卸载全局包” 这个搜索说明不少人在这上面遇到困惑。几个典型情况卸载时报 EACCES 权限错误和安装时一样全局目录权限问题。如果你当初是用 sudo 装的卸载也得 sudo。如果是改了 prefix 到用户目录的直接卸载即可。卸载后命令还在可能是 PATH 里有多个 claude 可执行文件比如你既用 npm 装过又手动下载过二进制。用which claudeLinux/macOS或where claudeWindows查一下所有匹配路径手动删掉多余的。想卸载 Node.js 本身如果你连 Node.js 都不想要了Windows 上通过“控制面板 → 程序和功能”卸载macOS 上用 Homebrew 装的用brew uninstall nodeLinux 上用包管理器卸载。但注意卸载 Node.js 会影响所有依赖它的工具确认没有其他项目在用再动手。6. 高频问题排查速查表6.1 安装阶段问题问题现象可能原因解决方法npm.ps1 无法加载禁止运行脚本PowerShell 执行策略限制改执行策略为 RemoteSigned或改用 CMDEACCES/EPERM权限错误全局目录无写权限改 npm prefix 到用户目录或用 sudo安装卡住不动网络问题拉包超时配置国内镜像源node.js vXX is not yet released指定了不存在的版本用 LTS 版本别指定未发布版本号claude命令找不到PATH 未包含 npm 全局 bin把全局 bin 目录加入 PATH6.2 登录与使用阶段问题问题现象可能原因解决方法登录链接打不开网络或浏览器问题复制链接到其他浏览器或用 API Key 方式登录后仍提示未认证凭证未正确保存检查配置目录权限重新登录VS Code 里找不到 claude集成终端工作目录不对在项目根目录打开终端再运行读取了不该读的文件未配置忽略规则建.claudeignore排除敏感文件6.3 卸载阶段问题问题现象可能原因解决方法卸载后命令仍可用存在多个安装副本用 which/where 查找并手动清理卸载报权限错误当初用 sudo 安装卸载也用 sudo配置残留占空间配置目录未清理手动删除~/.claude目录想彻底重装旧配置干扰卸载后删配置目录再重装7. 几个容易被忽略的实操细节7.1 版本升级的正确方式Claude Code 更新比较频繁想升级到最新版直接重新跑一遍安装命令就行npm install -g anthropic-ai/claude-codenpm 会检测到已安装拉取最新版本覆盖。也可以用npm update -g anthropic-ai/claude-code升级前建议看一眼当前版本claude --version升级后再看一次确认版本号变了。如果升级后出现异常可以回退到指定版本npm install -g anthropic-ai/claude-code1.0.xx把1.0.xx换成你要的版本号。查可用版本用npm view anthropic-ai/claude-code versions。7.2 多版本 Node.js 环境下的注意事项如果你用 nvm 管理多个 Node.js 版本要注意全局包是跟着 Node.js 版本走的。在 Node 18 下装的 Claude Code切到 Node 20 后可能就找不到了因为两个版本的全局目录是独立的。解决办法要么在每个用到的 Node.js 版本下都装一遍要么设置一个共享的全局目录。nvm 用户可以配置nvm的--reinstall-packages-from选项在切换版本时自动迁移全局包。实操心得我一般会固定一个 LTS 版本专门用来跑这类全局 CLI 工具其他版本只用于项目开发。这样避免全局包散落在多个版本里管理起来清爽。7.3 代理与网络环境的处理如果你在公司内网或需要走代理的环境下npm 拉包可能需要配置代理npm config set proxy http://your-proxy:port npm config set https-proxy http://your-proxy:port不需要时记得清掉npm config delete proxy npm config delete https-proxy代理配置不对会导致各种奇怪的连接错误排查网络问题时先确认代理设置是否符合当前环境。7.4 配置文件的位置与备份前面提过配置目录的位置这里再强调一下备份的重要性。如果你花时间调好了各种设置、写了不少项目级的CLAUDE.md换机器时这些不会自动同步。建议把配置目录里的关键文件排除凭证类敏感信息纳入你的 dotfiles 管理或者手动备份。项目级的CLAUDE.md和.claudeignore跟着项目走只要项目用 Git 管理自然就同步了。这也是我建议把这些文件放进版本控制的原因。8. 从安装到卸载的完整命令清单把全文涉及的命令汇总一下方便你复制使用。安装与验证node -v npm -v npm config set registry https://registry.npmmirror.com npm install -g anthropic-ai/claude-code claude --versionWindows PowerShell 策略调整Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser权限问题处理Linux/macOSmkdir -p ~/.npm-global npm config set prefix ~/.npm-global export PATH~/.npm-global/bin:$PATH升级与卸载npm update -g anthropic-ai/claude-code npm uninstall -g anthropic-ai/claude-code rm -rf ~/.claude npm cache clean --force这套流程我在 Windows、macOS、Ubuntu 三种环境下都跑过核心步骤一致差异主要在权限处理和 PATH 配置上。Windows 用户重点盯 PowerShell 策略和 PATHLinux/macOS 用户重点盯全局目录权限。把这两块搞定剩下的就是顺水推舟。最后分享一个我踩过的坑有次在 Ubuntu 上装完claude命令死活找不到查了半天发现是之前用 sudo 装过旧版本可执行文件在/usr/local/bin而新装的在用户目录PATH 里/usr/local/bin优先级更高一直调用的是旧的。用which -a claude才看到两个路径。所以遇到命令行为诡异的时候先确认你调用的到底是哪个副本这个排查思路能省不少时间。