1. 为什么一个命令行工具的安装能让人折腾一下午Claude Code 这个工具刚出来的时候我身边不少朋友都在群里问怎么装。按理说一个命令行工具无非就是下载、安装、配置三步走能有多难但实际情况是从 Windows 到 macOS从 winget 到 npm从 PowerShell 权限到环境变量每一步都可能卡住人。我自己前前后后在三台机器上装过踩的坑加起来能写满一页纸所以干脆把整个过程复盘一遍把那些官方文档里不会写的细节都摊开讲。先说清楚这个工具是什么。Claude Code 是 Anthropic 推出的一个终端里的编程助手你可以在命令行里直接跟它对话让它帮你读代码、改代码、跑命令。它不是一个带界面的客户端而是跑在终端里的所以对习惯图形界面的人来说第一步就会有点懵。它支持 Windows、macOS 和 Linux但不同系统上的安装方式差别挺大Windows 上尤其容易出问题。这篇文章适合谁看如果你是完全没碰过命令行的新手我会把每一步都拆开讲包括怎么打开终端、怎么复制粘贴命令、报错了怎么读。如果你是有经验的开发者但被 winget 或者 npm 的报错卡住了可以直接跳到对应的排查章节。我会把 Windows 和 macOS 两条线都覆盖到重点放在 Windows 上因为 Windows 的坑最多。核心关键词我先自然带一下Claude Code 的安装主要依赖 winget 和 npm 两条路径装完之后要用 claude doctor 做自检配置文件涉及 settings.json而 npm 在国内需要换镜像源才能顺畅。这些词后面都会反复出现你看到就知道对应的是哪个环节。我写这篇东西的原则很简单不堆砌官方文档里已有的内容只讲我实际踩过的坑和验证过的解法。每个步骤我都会说清楚为什么要这么做报错信息怎么读以及有没有更省事的替代方案。你照着做大概率能一次装好就算报错也能自己定位问题。2. 安装前的环境盘点与方案选型2.1 先搞清楚你的系统该走哪条路Claude Code 的安装方式不是随便选的它跟你的操作系统和已有环境强相关。我整理了一个对照表你先对号入座操作系统推荐安装方式前置依赖典型难点Windows 10/11winget 或 npmwinget 或 Node.jsPowerShell 执行策略、PATH 配置macOSnpm 或官方脚本Node.js权限、全局包路径LinuxnpmNode.js全局包权限、镜像源Windows 上我优先推荐 winget因为它是系统自带的包管理器装完自动处理 PATH省心。但问题是很多人的 Windows 是精简版或者老版本压根没有 winget这时候就得走 npm 这条路。macOS 和 Linux 基本就是 npm 一条路偶尔用官方脚本但 npm 更可控。这里有个判断标准你先在终端里敲winget --version如果能输出版本号说明 winget 可用走 winget 路线。如果提示无法将 winget 项识别为 cmdlet那就是没有 winget直接跳到 npm 方案。别在这上面纠结没有就是没有装 winget 本身又是另一个坑。2.2 winget 和 npm 到底选哪个这两个不是互斥的但新手容易搞混。winget 是 Windows 的包管理器类似手机上的应用商店一条命令就能装好软件并配置好环境。npm 是 Node.js 的包管理器本来是给 JavaScript 项目装依赖用的但很多命令行工具也通过 npm 分发。选 winget 的理由自动配 PATH不用管环境变量卸载也干净。选 npm 的理由跨平台一致macOS 和 Linux 上也是这套而且版本更新可能更快。我的建议是Windows 用户先试 winget失败了再转 npm。因为 winget 装完基本不用管配置而 npm 装完经常要手动处理 PATH 和权限。但如果你本来就在做前端开发机器上已经有 Node.js 和 npm那直接用 npm 更顺手不用额外装东西。注意不要两个方式都装一遍。winget 装的和 npm 装的可能装到不同目录导致命令冲突到时候claude命令指向哪个版本都说不清。选一个装到底。2.3 装之前必须确认的三件事在动手之前花两分钟确认这三件事能省掉后面一半的麻烦。第一确认你的终端是什么。Windows 上可能是 PowerShell、CMD 或者 Windows Terminal不同终端对命令的解析不一样。我强烈建议用 PowerShell因为 winget 和 npm 在 PowerShell 里表现最稳定。CMD 有时候会有编码问题Windows Terminal 本质上是套壳底层还是 PowerShell 或 CMD。第二确认网络能通。Claude Code 的安装包和依赖都要从境外服务器拉取国内网络直连经常超时。这不是让你去搞什么特殊手段而是老老实实换国内镜像源。npm 有淘宝镜像、中科大镜像winget 也有中科大源这些后面会详细讲。第三确认你有管理员权限。winget 安装软件需要管理员权限npm 全局安装在某些配置下也需要。如果你在公司电脑上可能权限被锁了这时候要么找 IT 开权限要么用免安装的绿色版本。3. Windows 下 winget 安装全流程与报错拆解3.1 winget 安装的标准步骤假设你的 Windows 有 winget安装 Claude Code 就一条命令winget install anthropic.claudecode敲下去之后winget 会去源里找这个包下载、安装、配置 PATH一气呵成。正常情况下你会看到进度条走完然后提示安装成功。装完之后关掉终端重新开一个敲claude --version能输出版本号就说明装好了。但现实往往没这么顺。我见过最多的报错是这一条winget : 无法将winget项识别为 cmdlet、函数、脚本文件或可运行程序的名称。这个报错的意思是系统里根本没有 winget 这个命令。原因通常是你的 Windows 版本太老或者装的是 LTSC 精简版微软把应用商店和 winget 一起砍掉了。这时候你有两个选择一是去装一个 winget 的离线安装包二是直接放弃 winget 走 npm。装 winget 离线包这件事本身又是个坑。你需要先装 Microsoft.VCLibs 依赖再装 DesktopAppInstaller顺序错了就报错。而且不同 Windows 版本对应的包还不一样。我的建议是如果你不是特别想折腾直接跳到 npm 方案省下来的时间够你装三遍 npm 了。3.2 winget 源太慢怎么办就算 winget 能用默认源在境外下载速度可能只有几十 KB一个几十兆的包能下十分钟。这时候换中科大源是最有效的办法。中科大镜像站维护了 winget 的完整镜像速度能跑满带宽。换源的命令是winget source remove winget winget source add winget https://mirrors.ustc.edu.cn/winget-source第一行是移除默认源第二行是添加中科大源。执行完之后再跑安装命令速度会有质的提升。如果你担心中科大源更新不及时也可以保留默认源只是把中科大源加进去作为备选但 winget 默认会按添加顺序选源所以还是移除默认源更干脆。提示换源之后如果报源无效或者无法访问先确认你的网络能打开中科大的网页。有些公司网络会拦截镜像站这种情况只能换其他镜像或者用手机热点。3.3 安装完命令找不到的排查winget 提示安装成功但敲claude提示不是内部或外部命令这是 PATH 没生效。winget 装的东西一般在%LOCALAPPDATA%\Microsoft\WinGet\Packages下面安装时应该自动加到用户 PATH 里但有时候需要重启终端甚至重启电脑才生效。先别急着重启按这个顺序排查关掉当前终端重新开一个。PATH 的变更对已打开的终端不生效。如果还不行敲echo $env:PATH看看输出里有没有 winget 的路径。没有的话手动去系统属性 - 环境变量里在用户变量的 Path 中加上%LOCALAPPDATA%\Microsoft\WinGet\Packages下对应的目录。加完再开新终端测试。这里有个细节winget 装的包目录名可能带版本号和哈希比如Anthropic.ClaudeCode_1.0.0_x64__abc123你要进到具体目录里找到可执行文件所在的文件夹把那个文件夹加到 PATH。别直接把 Packages 根目录加进去那样找不到。4. npm 安装路线从 Node.js 到镜像源配置4.1 Node.js 装完之后 npm 用不了走 npm 路线的前提是机器上有 Node.js。很多人去官网下了 Node.js 安装包一路下一步装完结果在终端敲npm -v报这个错npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1因为在此系统上禁止运行脚本。这个报错跟 npm 本身没关系是 PowerShell 的执行策略在拦。PowerShell 默认不允许运行脚本文件而 npm 在 PowerShell 里是通过一个 .ps1 脚本调用的所以被拦了。解决办法是改执行策略。以管理员身份打开 PowerShell敲Set-ExecutionPolicy RemoteSigned然后输入 Y 确认。RemoteSigned 的意思是本地脚本可以跑从网上下载的脚本需要签名。这个策略比 Unrestricted 安全又比默认的 Restricted 宽松是开发机的常规配置。改完之后再敲npm -v应该就能输出版本号了。如果还报错检查一下是不是在 CMD 里敲的CMD 不受 PowerShell 执行策略影响如果 CMD 里能用 PowerShell 里不能用那百分百是执行策略问题。4.2 npm 全局安装 Claude Codenpm 环境正常之后安装命令是npm install -g anthropic-ai/claude-code-g表示全局安装装完之后在任何目录都能用claude命令。但国内网络直连 npm 官方源大概率会卡在下载阶段或者报超时。这时候要换国内镜像源。换源命令npm config set registry https://registry.npmmirror.com这是淘宝的镜像源更新比较及时。中科大的源是https://npmreg.proxy.ustclug.org/也可以。换完之后用npm config get registry确认一下输出的是你设置的地址就对了。换完源再跑安装命令速度会快很多。但有时候还是会报一些 deprecated 警告比如npm warn deprecated node-domexception1.0.0: use your platforms native dome这个警告不用管它只是说某个依赖包过时了不影响安装。npm 的 deprecated 警告大部分都是噪音除非是 error 级别的报错否则可以忽略。4.3 全局安装后命令找不到的两种解法npm 全局安装的包可执行文件放在 npm 的全局 bin 目录里。这个目录默认可能不在 PATH 里导致装完了敲claude找不到。先查全局 bin 目录在哪npm config get prefixWindows 上一般输出C:\Users\你的用户名\AppData\Roaming\npmmacOS 和 Linux 上一般是/usr/local或者~/.npm-global。这个目录下的可执行文件就是全局命令。把这个目录加到 PATH 里。Windows 上在环境变量里加macOS 和 Linux 上在.bashrc或.zshrc里加export PATH$PATH:/usr/local/bin加完 source 一下配置文件或者重开终端。然后再敲claude --version测试。如果还不行可能是 npm 的 prefix 配置有问题。有些教程会让你改 prefix 到自定义目录改完之后 bin 目录也跟着变容易乱。我的建议是保持默认只把默认的 bin 目录加到 PATH别自己改 prefix。5. claude doctor 自检与 settings.json 配置5.1 装完先跑 claude doctor不管用哪种方式装的装完第一件事是跑自检命令claude doctor这个命令会检查你的安装是否完整、配置是否正确、网络是否通畅、认证是否有效。它会逐项输出检查结果哪一项有问题会明确标出来。我见过的问题包括Node.js 版本太低、配置文件缺失、认证 token 过期、网络连不上 API 端点。doctor 的输出里如果有红色的 fail就按它给的提示去修。如果是黄色的 warn一般不影响使用可以先放着。最有用的是它会告诉你配置文件在哪以及当前读的是哪个配置。5.2 settings.json 到底该放哪Claude Code 的配置放在一个叫settings.json的文件里。这个文件的位置在不同系统上不一样系统配置目录Windows%USERPROFILE%\.claude\settings.jsonmacOS~/.claude/settings.jsonLinux~/.claude/settings.json注意这个.claude目录是隐藏的Windows 上要在文件管理器里开启显示隐藏文件才能看到或者直接在终端里用命令进。settings.json 里可以配的东西包括API 密钥、默认模型、代理设置、权限规则、快捷键绑定等。新手最容易搞错的是把它当成项目配置文件。项目级的配置是放在项目根目录的.claude/settings.json用户级的配置是放在用户目录的.claude/settings.json。两个都存在时项目级覆盖用户级。注意settings.json 是严格的 JSON 格式多一个逗号、少一个引号都会导致解析失败。改完之后一定要跑claude doctor验证别等到用的时候才发现配置没生效。5.3 权限配置与常见安全设置Claude Code 默认会问你很多权限比如能不能读某个目录、能不能执行某个命令。这些权限规则也写在 settings.json 里。默认配置比较保守每次操作都问用起来很烦。你可以配置允许列表让常见的只读操作直接放行。一个典型的权限配置长这样{ permissions: { allow: [ Read, Glob, Grep ], deny: [ Bash(rm -rf *) ] } }allow 列表里的操作不会询问deny 列表里的操作直接拒绝。中间地带的操作还是会问。我的建议是先把 Read、Glob、Grep 这些只读操作放行写操作和命令执行保持询问等你用熟了再逐步放宽。千万别一上来就把 Bash 全部放行那样 Claude Code 可以执行任何命令包括删文件的命令。我见过有人图省事全放行结果让工具帮忙清理临时文件它跑了个 rm 把源码目录删了。虽然能恢复但那个下午是废了。6. 常见报错速查与避坑经验6.1 报错速查表我把装 Claude Code 过程中最常见的报错整理成了一张表遇到问题先来这里对报错信息根本原因解决办法winget 无法识别系统没有 winget装离线包或转 npmnpm.ps1 禁止运行脚本PowerShell 执行策略Set-ExecutionPolicy RemoteSignednpm 不是内部或外部命令Node.js 没装或 PATH 没配重装 Node.js 并勾选 Add to PATH安装超时网络连不上境外源换国内镜像源claude 命令找不到全局 bin 目录不在 PATH把 npm prefix 目录加到 PATHsettings.json 解析失败JSON 格式错误用 JSON 校验工具检查doctor 报认证失败API 密钥无效或过期重新配置密钥这张表覆盖了九成以上的问题。遇到没见过的报错先把报错信息完整复制下来去搜索引擎搜一般都能找到答案。别只看报错的第一行后面的堆栈信息往往才是关键。6.2 我踩过的三个印象最深的坑第一个坑是 winget 装完 PATH 没生效。我当时装完敲claude找不到以为装失败了又用 npm 装了一遍。结果两个版本冲突claude命令指向了旧版本怎么都更新不了。后来把两个都卸了只留 winget 版本重启终端才正常。教训是装完先重启终端别急着下结论。第二个坑是 npm 镜像源换了但没生效。我换了淘宝源但安装还是慢。查了半天发现是项目目录下有个.npmrc文件里面的 registry 配置覆盖了全局配置。npm 的配置是有优先级的项目级 用户级 全局级。项目目录下的.npmrc优先级最高如果你在某个项目里装全局包它会读项目的配置。解决办法是删掉项目里的.npmrc或者在里面也写上镜像源。第三个坑是 settings.json 的路径搞错了。我在 Windows 上把配置写到了C:\Users\Administrator\.claude\settings.json但实际登录的用户不是 Administrator而是另一个账户。结果配置一直不生效doctor 读的是另一个目录。Windows 上多用户切换很常见一定要确认当前登录用户是谁配置写到对应用户的目录下。6.3 卸载与重装的正确姿势装坏了想重装别直接覆盖安装先把旧的清干净。winget 装的卸载命令winget uninstall anthropic.claudecodenpm 装的卸载命令npm uninstall -g anthropic-ai/claude-code卸载完还要手动清理残留删掉.claude目录配置和缓存都在里面检查 PATH 里有没有残留的路径。如果之前改过环境变量把相关的条目删掉。重装之前把终端全部关掉最好重启一次电脑。因为 PATH 的变更和文件占用有时候要重启才能释放。我见过卸载完重装报文件被占用的就是因为旧进程还在后台跑着。提示重装之前把 settings.json 备份一下里面可能有你调了很久的配置。重装完直接拷回去省得重新配。7. 装完之后怎么用起来7.1 第一次启动的认证流程装好之后第一次敲claude它会引导你做认证。一般是让你登录账号或者输入 API 密钥。认证信息会存到.claude目录下的配置文件里之后就不用重复认证了。如果认证卡住先检查网络能不能通到 API 端点。doctor 命令会帮你测。认证失败最常见的原因是密钥复制的时候带了空格或者密钥本身没有对应权限。把密钥重新复制一遍注意别多复制了换行符。7.2 在 VS Code 里用 Claude Code很多人想在 VS Code 里直接用 Claude Code而不是切到终端。这个需求可以通过 VS Code 的集成终端实现在 VS Code 里打开终端面板直接敲claude就能用。因为 VS Code 的终端继承了你系统的环境只要系统里装好了VS Code 里就能用。如果 VS Code 终端里找不到命令检查 VS Code 的终端配置看它用的是哪个 shell。有时候 VS Code 默认用 CMD而你的 PATH 是在 PowerShell 里配的就会找不到。把 VS Code 的默认终端改成 PowerShell 就行。7.3 日常使用中的几个效率技巧用起来之后有几个技巧能明显提升效率。第一把常用的提示词存成文件用的时候直接引用不用每次手打。第二配置好权限允许列表减少确认弹窗。第三用claude doctor定期检查尤其是升级之后确保配置没被覆盖。还有一个容易被忽略的点Claude Code 会读取项目根目录的.claude配置你可以在不同项目里放不同的配置比如前端项目允许跑 npm 命令后端项目允许跑测试命令。这样切换项目的时候权限自动适配不用手动改。我在实际使用中的体会是安装环节的坑虽然多但都是可以绕过去的。真正影响体验的是配置和权限配好了用起来很顺配不好天天弹窗。花半小时把 settings.json 调明白后面能省几十个小时的确认时间。这个投入产出比怎么算都划算。