1. 从一次失败的 winget 安装说起那天下午我在一台刚装好的 Windows 11 机器上敲下第一条命令准备把 Claude Code 装起来。按照官方文档的指引我输入了winget install anthropic.claudecode结果终端直接甩回来一句winget : 无法将“winget”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。这个报错其实很典型。它不是说 winget 坏了而是说当前这个 PowerShell 会话里根本找不到 winget 这个命令。很多人第一反应是去重装系统或者去网上找什么“winget 离线安装版本”但真正的原因往往简单得多——要么是 App Installer 没装要么是环境变量 PATH 里没有把 WindowsApps 目录加进去。我先说结论Claude Code 在 Windows 上的安装本质上就是两条路。一条是走 winget一条是走 npm。两条路各有各的坑而且坑的位置完全不一样。winget 的坑集中在“命令找不到”和“源连不上”npm 的坑集中在“脚本被禁止运行”和“镜像源配置”。这篇文章我会把这两条路都走一遍把每个报错背后的真实原因拆开讲清楚顺便把 settings.json 配置、VSCode 集成、卸载清理这些周边问题一并说透。如果你现在正卡在某个报错上建议先别急着搜“claude code 下载”先看完下面这张对照表大概率能直接定位到你的问题属于哪一类。报错关键词真实原因解决方向winget 无法识别App Installer 缺失或 PATH 未包含 WindowsApps安装 App Installer 或改用 npmnpm.ps1 禁止运行脚本PowerShell 执行策略限制修改 ExecutionPolicynpm 不是内部或外部命令Node.js 未安装或 PATH 未配置重装 Node.js 并勾选 PATHnode-domexception deprecated依赖包本身的废弃警告可忽略不影响功能源连接超时默认源网络不通换国内镜像源这张表是我踩完所有坑之后回头整理的基本上覆盖了 90% 的安装失败场景。下面我按实际排查顺序一个一个展开。2. winget 这条路为什么你的终端不认识它2.1 winget 到底是什么它为什么可能不存在winget 的全称是 Windows Package Manager它是微软随 Windows 10 1809 之后逐步推广的一个命令行包管理工具。你可以把它理解成 Windows 上的“应用商店命令行版”。它的好处是不用你去官网下载安装包、双击、下一步下一步直接一条命令就能把软件拉下来装好。但问题在于winget 并不是 Windows 的“内置组件”它实际上是通过一个叫App Installer的商店应用分发的。也就是说如果你的系统里没有装 App Installer或者装了一个很老的版本那么 winget 命令就不存在。这就是为什么很多人会去搜“缺少 winget”或者“winget 离线安装版本”——因为他们确实需要先把 App Installer 补上。判断方法很简单在 PowerShell 里敲Get-AppxPackage -Name Microsoft.DesktopAppInstaller如果没有任何输出说明 App Installer 没装。如果有输出但版本号很低也建议更新。正常情况下Windows 11 的较新版本会预装但一些精简版系统、企业定制镜像、或者手动优化过的系统经常会把这个组件删掉。2.2 补装 App Installer 的正确姿势补装 App Installer 最稳妥的方式是去微软官方渠道获取。注意我这里说的是“官方渠道”不是随便找个第三方站点下载一个 exe。因为 App Installer 本身是一个 msixbundle 包来源不可靠的话装上去可能带来其他问题。装好之后必须重开一个新的 PowerShell 窗口。这一点非常关键。因为 PATH 环境变量是在会话启动时读取的你在旧窗口里装完旧窗口的 PATH 不会自动刷新。很多人装完 App Installer 之后发现 winget 还是不能用就是因为没重开终端。重开之后验证winget --version能打印出版本号就说明 winget 可用了。如果还是不行那就检查一下 PATH 里有没有这个路径%LOCALAPPDATA%\Microsoft\WindowsApps这个目录是 Windows 存放“应用执行别名”的地方winget 的可执行文件就在这里。如果 PATH 里没有它手动加进去然后重开终端。2.3 源的问题为什么 winget install 会卡住或报错winget 能用之后下一个坑就是源。winget 默认使用的是微软的社区源在国内网络环境下有时候会出现连接慢、超时、甚至直接失败的情况。这时候你会看到类似“无法连接到源”或者一直卡在“正在搜索”的提示。解决办法是换源。winget 支持添加自定义源国内有一些高校和企业维护的镜像源可以用。比如中科大就有维护 winget 的镜像。添加方式大致是winget source remove winget winget source add winget https://mirrors.ustc.edu.cn/winget-source不过这里要提醒一句换源之前先确认这个源是否还在维护。镜像源这种东西维护状态是会变的有的源可能某段时间就停止同步了。如果换了源之后搜索不到包那就把源换回默认的或者换另一个可用的镜像。提示winget 换源之后建议先执行winget source update刷新一下索引再执行安装命令。否则可能搜到的还是旧索引里的包信息。2.4 winget 安装 Claude Code 的实际体验当 winget 和源都正常之后安装命令本身其实很简单winget install anthropic.claudecode但这里有个细节包名的大小写和拼写必须完全正确。winget 的包标识符是大小写不敏感的但拼错一个字母就会提示找不到包。如果你不确定包名可以先搜winget search claude搜索结果里会列出所有匹配的包确认一下发布者和包 ID 再装。装完之后Claude Code 的可执行文件通常会被放到一个由 winget 管理的目录里。你可以用where.exe claude来确认它到底装到哪了。如果where.exe找不到那说明安装目录没有进 PATH需要手动加。我个人对 winget 这条路的评价是适合系统比较干净、网络条件较好的情况。它的优点是安装过程自动化卸载也干净winget uninstall一条命令搞定。缺点是它对系统环境的依赖比较强App Installer 缺失、PATH 异常、源不通任何一个环节出问题都会卡住。如果你在这条路上折腾了超过二十分钟还没搞定我的建议是直接切到 npm 路线不要在 winget 上死磕。3. npm 这条路脚本执行策略是第一道坎3.1 为什么 npm 命令会“无法加载文件”从 winget 切到 npm 之后很多人遇到的第一个报错是这个npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1因为在此系统上禁止运行脚本。这个报错的信息量其实很大。它告诉你两件事第一npm 确实装了而且路径在C:\Program Files\nodejs\下面第二PowerShell 拒绝执行.ps1脚本文件。根本原因是PowerShell 的执行策略ExecutionPolicy。Windows 客户端系统默认的执行策略通常是Restricted意思是“不允许运行任何脚本文件”。这是出于安全考虑的设计但它会误伤 npm 这种通过.ps1包装器来调用的工具。查看当前策略Get-ExecutionPolicy如果返回Restricted那就是它了。解决办法是把当前用户的执行策略改成RemoteSignedSet-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSignedRemoteSigned的含义是本地写的脚本可以直接跑从网络下载的脚本需要有签名才能跑。对于开发用途来说这个级别是够用且相对安全的。不要图省事直接设成Unrestricted那个限制太松了。改完之后同样需要重开终端然后再试 npm 命令。3.2 npm 不是内部或外部命令Node.js 装完后的 PATH 陷阱另一个高频报错是npm 不是内部或外部命令也不是可运行的程序或批处理文件。或者 PowerShell 版本npm : 无法将“npm”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。这两个说的是同一件事系统找不到 npm 这个命令。原因通常是 Node.js 装了但安装时没有把 Node.js 的目录加入 PATH。Node.js 的 Windows 安装包在安装过程中有一个选项叫 “Add to PATH”默认是勾选的。但如果你用的是解压版zip 版或者安装时手动取消了这个勾选那 PATH 里就不会有 Node.js 的路径。手动配置 PATH 的步骤找到 Node.js 的安装目录通常是C:\Program Files\nodejs\或D:\Program Files\nodejs\。打开“系统属性” - “环境变量”。在“用户变量”或“系统变量”的 Path 里新增一条指向该目录的记录。确定保存重开终端。验证node -v npm -v两个都能打印出版本号才算真正配好。注意如果你同时装了多个版本的 Node.js或者之前装过又卸载过PATH 里可能残留了旧路径。这种情况下where.exe node会列出多条记录需要把失效的那条删掉否则可能调用到错误的版本。3.3 镜像源让 npm 安装不再超时PATH 和脚本策略都搞定之后npm 安装 Claude Code 的命令是npm install -g anthropic-ai/claude-code但如果你直接用默认源在国内网络下大概率会卡住或者超时。这时候需要换国内镜像源。常用的有淘宝源现在叫 npmmirrornpm config set registry https://registry.npmmirror.com设置完之后可以用npm config get registry确认一下。不过这里有个经验之谈镜像源并不是万能的。有些包在镜像源上同步不及时或者某些 scoped 包比如anthropic-ai/开头的在镜像上可能没有。如果你换了镜像源之后提示 404那就临时切回官方源再试npm install -g anthropic-ai/claude-code --registryhttps://registry.npmjs.org这种“镜像源 官方源兜底”的组合是我在实际操作中最常用的策略。平时用镜像源加速遇到找不到的包就单次指定官方源。3.4 那个 node-domexception 废弃警告要不要管安装过程中你大概率会看到这样一条警告npm warn deprecated node-domexception1.0.0: use your platforms native domexception instead这条警告的意思是node-domexception这个包已经废弃了建议使用平台原生的 DOMException。它是某个上游依赖引入的不是你直接安装的包。结论可以忽略。这条警告不影响 Claude Code 的安装和运行。npm 的 deprecated 警告只是提示不是错误。除非安装过程因此中断否则不需要专门去处理它。我见过有人为了消除这条警告去手动改依赖树结果把整个 node_modules 搞坏了得不偿失。4. 装完之后claude doctor 和 settings.json 配置4.1 用 claude doctor 做一次完整体检安装完成后第一件事不是急着用而是先跑一遍自检claude doctor这个命令会检查你的安装状态、配置、依赖、权限等。它会告诉你哪些东西是正常的哪些东西有问题。我强烈建议每个人装完之后都跑一次因为它能提前暴露很多隐藏问题比如配置文件格式错误、权限不足、依赖缺失等。如果claude doctor本身都跑不起来那说明安装环节还有问题需要回到上一步排查。如果它能跑起来但报了某些项异常那就按它给出的提示逐项处理。4.2 settings.json 到底该放哪、写什么Claude Code 的配置核心是settings.json。这个文件的位置很关键放错了地方就不会生效。常见的位置有用户级配置通常在用户主目录下的相关配置目录里。项目级配置在项目根目录下的配置目录里。用户级配置对所有项目生效项目级配置只对当前项目生效。如果你想让某个配置只在一个项目里起作用就放项目级如果是全局偏好就放用户级。一个典型的 settings.json 结构大致包含权限控制、模型选择、工具开关等字段。这里我不贴具体字段值因为版本迭代较快字段名可能变化。最可靠的做法是跑claude doctor它会告诉你当前配置文件的路径和格式要求。提示settings.json 是严格的 JSON 格式不能有注释不能有尾随逗号。一个多余的逗号就会导致整个配置文件解析失败。改完之后建议用 JSON 校验工具过一遍。4.3 权限配置别一上来就全放开Claude Code 在执行某些操作时需要权限确认。settings.json 里可以配置哪些操作自动允许、哪些需要手动确认。我的建议是初期不要把所有权限都设成自动允许。先保持默认的确认机制用一段时间观察它实际会执行哪些操作再根据你的信任程度逐步放开。一上来就全放开万一它在某个项目里执行了你不期望的命令后悔都来不及。权限配置的粒度通常可以按工具类型、按路径、按命令模式来划分。具体字段参考官方文档和claude doctor的输出。5. VSCode 集成与日常使用中的几个细节5.1 在 VSCode 里用 Claude CodeClaude Code 可以在 VSCode 的集成终端里直接使用这是最省事的方式。打开 VSCode调出终端直接敲claude就能进入交互界面。如果你想要更深的集成比如在编辑器内直接调用那就需要装对应的扩展或者配置任务。但说实话集成终端的方式已经够用了而且出问题的时候排查起来最简单——因为终端里的报错信息是完整的你能直接看到。VSCode 里有一个容易忽略的点集成终端默认使用的 shell 可能和你在外部用的不一样。比如你外部用的是 PowerShell 7但 VSCode 集成终端可能默认用的是 Windows PowerShell 5.1。这两个版本的执行策略是分开管理的。如果你在外部终端改好了执行策略但在 VSCode 里还是报“禁止运行脚本”那就需要在 VSCode 的终端里再改一次或者把 VSCode 的默认终端改成你配置好的那个 shell。5.2 卸载与清理别留下垃圾卸载 Claude Code 分两种情况如果是 npm 装的npm uninstall -g anthropic-ai/claude-code如果是 winget 装的winget uninstall anthropic.claudecode卸载之后配置文件和缓存目录通常不会自动删除。如果你打算彻底清理需要手动找到这些目录删掉。具体位置可以用claude doctor在卸载前查一下记下来再卸。另外npm 全局安装的包有时候会在全局 node_modules 里留下一些残留可以用npm ls -g --depth0看一下全局装了哪些包确认没有残留。5.3 几个我踩过的坑和对应技巧坑一在公司网络环境下 winget 源不通。公司网络通常有代理或者防火墙限制winget 的默认源可能连不上。这种情况下 npm 路线往往更靠谱因为 npm 可以灵活指定镜像源。坑二Node.js 版本太老。Claude Code 对 Node.js 版本有最低要求。如果node -v显示的是很老的版本比如 14.x建议先升级到 LTS 版本。升级 Node.js 最干净的方式是用版本管理工具而不是直接覆盖安装。坑三PATH 里有多个 node。前面提过where.exe node如果列出多条说明有冲突。把不需要的那条从 PATH 里删掉只保留一个。坑四settings.json 改坏了导致 claude 起不来。如果改完配置之后 claude 直接报错先把 settings.json 备份一下然后恢复成默认内容再逐项加回去定位是哪一项出的问题。坑五npm 全局安装权限不足。在 Windows 上npm 全局安装有时候会因为权限问题失败。解决办法是以管理员身份运行终端或者把 npm 的全局目录改到用户目录下npm config set prefix C:\Users\你的用户名\npm-global然后把C:\Users\你的用户名\npm-global加到 PATH 里。这样就不需要管理员权限了。6. 关于安装路线选择的个人建议走完这两条路之后我的整体感受是Windows 上装 Claude Codenpm 路线的可控性更强winget 路线的自动化程度更高但依赖系统环境。如果你对命令行比较熟我建议直接走 npm。因为 npm 的每一步你都能看到、能控制出了问题也容易定位。winget 虽然一条命令就完事但它把很多细节藏起来了一旦出错排查起来反而更麻烦。如果你是完全的新手系统又是比较标准的 Windows 11那可以先用 winget 试一次。成功了就省事失败了就切 npm不要在一个方向上耗太久。还有一个经常被忽略的点安装之前先确认你的网络环境。很多安装失败其实不是工具的问题而是网络的问题。镜像源、代理设置、防火墙这些都会影响安装。先把网络这一层理清楚后面的步骤会顺很多。最后说一个我自己的习惯每次在新机器上装开发工具我都会先建一个“环境检查清单”把 node、npm、git、winget 这些基础工具的版本和路径都确认一遍再开始装具体的东西。这个习惯帮我省了很多“以为是工具的问题、其实是环境的问题”的时间。装 Claude Code 也是一样先把地基打牢上面的东西才稳。