最近总有人问我同一个问题Windows 上到底怎么把 Claude Code 装起来。说句实话Claude Code 本身的安装过程并不复杂真正麻烦的是它依赖的一整条 Windows 工具链——PowerShell 执行策略、Git 安装路径、PATH 环境变量、WSL 子系统任何一环出了问题终端就会甩给你一串莫名其妙的报错然后你就开始怀疑人生。我最近刚好把整套流程在几台 Windows 机器上重新走了一遍从全新系统到老环境升级踩了一堆坑也把能遇到的典型报错都排查了一遍。这篇指南就是按实际踩坑顺序写出来的面向 Windows 10/11 用户从零开始涵盖 PowerShell、Git、PATH、WSL 四个核心环节后面还附了一份常见问题排查清单。如果你是那种照着文档装了三遍还是不行的人这篇应该能帮你少走不少弯路。前提是你本机网络能正常访问 Anthropic 官方服务否则后面对话和登录都会出问题。下面正式开始。1. 安装前的整体思路与方案选择1.1 为什么 Windows 下安装比 macOS/Linux 更容易翻车Claude Code 本质是一个跑在终端里的命令行工具官方生态一直更偏向 macOS 和 Linux。Windows 用户之所以经常卡住并不是工具本身多难装而是 Windows 的默认环境对脚本执行不友好PowerShell 默认禁止运行脚本、系统级和用户级 PATH 分离、老式控制台对 UTF-8 支持稀烂、Git 安装时的路径选项还经常选错。再加上很多人是在公司电脑上安装组策略和杀毒软件还会插一脚各种问题堆在一起看起来就像是 Claude Code 装不上其实是环境没准备好。搞清楚这一点很重要。后面所有步骤本质上都是在把 Windows 环境调整到适合命令行工具运行的状态Claude Code 反而是最省事的那一步。1.2 两条路线原生 Windows 和 WSL 怎么选安装 Claude Code 有两条主流路线先别急着动手花一分钟想清楚自己该走哪条。第一条是原生 Windows 路线直接在 PowerShell 里安装脚本和配置文件都落在 Windows 用户目录下。优点是没有虚拟机层路径直观VS Code 集成简单磁盘开销小缺点是有些 Linux 风格的工具链姿势在 Windows 上会别扭比如某些原生模块编译、依赖 Linux 命令行的脚本、以及 OAuth 登录时的弹窗兼容性。第二条是 WSLWindows Subsystem for Linux路线在 WSL 里装一个 Ubuntu再把 Claude Code 装到 Ubuntu 里面。优点是环境最接近官方推荐状态npm 生态、Python 工具链、shell 脚本全部都顺缺点是 WSL 虚拟磁盘会占几个 GB 空间首次启动稍慢文件读写跨系统时容易踩权限坑。我自己的建议是这样的如果你只是写业务代码、做日常开发原生 Windows 路线足够用装完即用不用折腾子系统如果你会跑 Linux 下的部署脚本、需要和 Docker/GPU 环境联动、或者做事喜欢一次到位直接上 WSL 路线。1.3 环境自查清单开始安装之前先把下面这张表过一遍。这一步能筛掉一半以上的安装失败。检查项要求说明系统版本Windows 10 版本号 19041 或更高Windows 11 全系老版本不支持新版 Terminal 和 WSL2管理员权限日常使用普通用户但能拿到管理员权限安装环节可能用到运行 Claude Code 不需要管理员网络状况能正常访问 Anthropic 官方服务这是登录和 API 调用的前提磁盘空间原生路线预留 3GBWSL 路线预留 15GBWSL 虚拟磁盘会动态增长终端工具Windows Terminal 优先老控制台对 UTF-8 和颜色支持太差自查没问题就可以往下走了。注意全程尽量不要用以管理员身份运行的终端来做日常操作这个习惯会直接影响后面一个高频报错我放到第 6 章详细讲。2. PowerShell 环境准备执行策略、乱码与脚本设置2.1 先装一个 Windows TerminalPowerShell 本身是个好东西但老式 conhost 窗口对现代化命令行工具的支持实在不敢恭维。我在所有 Windows 机器上都会优先安装 Windows Terminal界面好看还在其次关键是它原生支持 UTF-8、字体渲染正确、多标签管理也方便。安装很简单在 PowerShell 里执行winget install --id Microsoft.WindowsTerminal -e --source winget提示winget 是 Windows 自带的包管理器如果提示找不到 winget请先把系统更新到 Windows 10 19041 或更高版本。装好后以后所有操作都在 Windows Terminal 里进行别再点开始菜单那个蓝色 PowerShell 图标了。2.2 执行策略限制与解除很多人在安装时遇到的第一堵墙是这个报错无法加载文件 C:\Users\xxx\...因为在此系统上禁止运行脚本原因很简单PowerShell 的默认执行策略是 Restricted它不允许运行任何 .ps1 脚本。而 Claude Code 的安装脚本、以及后来的 npm 全局安装脚本都需要 PowerShell 能执行本地脚本。这个策略是保护机制不建议直接改成 Unrestricted用 RemoteSigned 就够了——它允许运行本地脚本但从网络下载的脚本必须带签名。在 PowerShell 里执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser这里的关键参数是-Scope CurrentUser只对当前用户生效不需要动系统全局策略也不需要管理员权限。执行完可以验证一下Get-ExecutionPolicy看到RemoteSigned就说明通过了。这一步是整个安装链条的起点很多后续报错追根溯源都是因为这一步没做。2.3 中文乱码问题PowerShell 中文乱码是个老生常谈的问题几乎每个人都会遇到。乱码的根源不是 Claude Code而是控制台默认代码页和程序输出编码不一致。Windows 下的旧终端默认代码页是 GBK936而 Claude Code 输出是 UTF-8中间不一致就会显示成锟斤拷。在 Windows Terminal 里最直接的做法是在打开终端时先切换代码页chcp 65001再把当前会话的编码设置为 UTF-8[Console]::OutputEncoding [System.Text.Encoding]::UTF8 $OutputEncoding [System.Text.Encoding]::UTF8注意以上命令只对当前终端会话生效。如果你不想每次打开终端都敲一遍请继续看 2.4 节把设置固化到 PowerShell profile 里。另外一个容易被忽略的点是终端字体。Windows Terminal 默认字体对中文支持没问题但如果用到特殊的符号和图标比如 Claude Code 状态栏的彩色圆点建议把字体换成Nerd Font或者更纱黑体。在 Windows Terminal 的设置界面里配置文件 - 外观 - 字体选一个支持 Unicode 的等宽字体即可。2.4 把命令固化到 PowerShell profile每次都手动敲 chcp 65001 太蠢了。PowerShell 有个 profile 文件相当于 bash 的 .bashrc每次启动时自动加载。用下面命令找到它$PROFILE通常路径是C:\Users\你的用户名\Documents\PowerShell\Microsoft.PowerShell_profile.ps1。如果文件不存在先创建目录再新建文件New-Item -ItemType Directory -Force -Path (Split-Path $PROFILE) New-Item -ItemType File -Path $PROFILE -Force然后用记事本或 VS Code 编辑这个文件写入$OutputEncoding [System.Text.Encoding]::UTF8 [Console]::OutputEncoding [System.Text.Encoding]::UTF8 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser -Force chcp 65001 $null保存后重开一个终端之前的乱码问题就一劳永逸地解决了。这里提醒一句profile 文件里不要随便粘贴不明来源的脚本它每次启动都会执行安全影响面很大。3. Git 安装与本地仓库配置3.1 下载与安装 GitClaude Code 虽然不强制要求用 Git但你的实际开发场景里几乎一定会用仓库而且 Claude Code 读取项目上下文、diff 能力都依赖 Git。Git 的安装本身不难难点集中在 PATH 选项和后续的 SSH 配置。在 PowerShell 里直接执行winget install --id Git.Git -e --source winget也可以去官网 git-scm.com 下载安装包两者本质一样。安装过程中有几个关键选项很多人在这里就埋下了隐患第一是Adjusting your PATH environment务必选择第三项Git from the command line and also from 3rd-party software。如果选了第一项Use Git from Git Bash only那 Git 命令就不会进入 PATH安装完在 PowerShell 里敲git --version会提示命令不存在。第二是Checkout line endings团队项目建议选择Checkout as-is, commit as-is避免自动换行转换导致整个文件被判定为变更。如果你参与的项目是多人 Windows 协作选Checkout Windows-stylecommit Unix-style也可以但这个选项尽量保持一致否则 diff 会很难看。第三是把默认编辑器改成 VS Code 或你习惯的编辑器如果不改Git 默认会打开 Vim对不熟悉 Vim 的人来说是一场灾难。3.2 安装后的 PATH 验证装完 Git重开终端敲git --version如果输出了git version 2.x.x表明安装成功。如果提示git 不是内部或外部命令基本可以断定是 PATH 没生效。这时候不要急着重装 Git先检查一下环境变量里有没有 Git 条目我放到第 4 章专门讲。提示安装完 Git 后一定要重开终端因为 PATH 环境变量的修改只在新的进程里生效。你看当前窗口发现找不到 git是正常的。3.3 SSH 密钥与免密配置Git 平台GitHub、GitLab 等的认证方式推荐 SSH 而不是 HTTPS 密码因为 SSH 密钥可以免密、也可以避免密码过期的问题。生成密钥在 PowerShell 里执行ssh-keygen -t ed25519 -C 你的邮箱一路回车即可。默认密钥会生成在C:\Users\你的用户名\.ssh\id_ed25519。然后启动 Windows 的 ssh-agent 服务并添加密钥Set-Service ssh-agent -StartupType Automatic Start-Service ssh-agent ssh-add $env:USERPROFILE\.ssh\id_ed25519把公钥内容添加到 GitHub 的 SSH keys 页面验证连接ssh -T gitgithub.com看到Hi 用户名! Youve successfully authenticated就说明 SSH 通了。这一步做完后续git clone、git push都不需要再输密码。常见 SSH 报错我也整理在后面的问题清单里比如Permission denied (publickey)大概率是公钥没添加对地方这点在第 6 章详细说。3.4 Git 全局配置Git 提交作者信息至少要配一波不然 commit 会带着一串unknowngit config --global user.name 你的名字 git config --global user.email 你的邮箱查看确认git config --global --list这里提醒一个 Windows 特有的坑如果 Windows 用户名是中文比如张三有些历史版本的 Git 和 npm 在解析用户目录路径时会出现编码问题。最稳妥的做法是把项目路径尽量放在纯英文目录下比如D:\workspace\project-a避免C:\Users\张三\...这种路径带来的玄学问题。你不需要改系统用户名只需要把代码目录放到全英文路径即可。4. PATH 环境变量原理、配置与验证4.1 PATH 到底是什么很多人装完软件发现命令找不到第一反应是重装其实问题八成出在 PATH 上。PATH 就是系统的一份命令查找目录清单你在终端里敲git系统会按照 PATH 里列出的目录顺序挨个去找有没有 git.exe。找到了就执行找不到就报不是内部或外部命令。类比一下PATH 就像是通信录里的快捷拨号你不会记住每个人的电话号码只需要记住一个简短的名字系统帮你按通信录去找到真正的号码。Windows 的 PATH 分成两层用户 PATH 和系统 PATH。用户 PATH 只对当前用户生效系统 PATH 对所有用户生效。平时不建议动系统 PATH除了要配置全局工具这种必要情况。Claude Code 的 npm 全局安装路径和 Git 都会写入用户 PATH所以你只需要关注用户那一层。4.2 编辑 PATH 的正确方式在 Windows 上编辑 PATH 有一个标准入口很多新手会犯的错误是直接在命令行里用set PATH...临时覆盖这个只是当前会话有效重启就没了。正确的做法是右键此电脑 - 属性 - 高级系统设置 - 环境变量或者更快的方式是按下Win R输入rundll32 sysdm.cpl,EditEnvironmentVariables直接弹出环境变量编辑窗口。在用户变量里找到 Path点击编辑新版 Windows 会显示一个多行列表每一项就是一个目录。点击新建填入要添加的路径保存即可。验证是否生效重开一个终端敲echo $env:Path确认新路径在输出里。4.3 常见 PATH 问题速查问题现象原因处理方式改完 PATH 不生效当前终端进程还持有旧的 PATH重开终端或注销重登同样的路径出现好几遍重复安装或手动重复添加清理重复条目保留一份带空格的路径变成两项忘记用引号或编辑器把分号拆开用环境变量编辑器操作不要手写某条路径失效但不影响别的路径对应的目录被删除找到并删除无效条目即可提示如果你发现自己安装 Global npm 包后claude命令找不到去查一下 npm 全局 bin 目录是否在 PATH 里。Windows 上 npm 全局目录一般是C:\Users\你的用户名\AppData\Roaming\npm。4.4 npm 与 Node.js 的 PATH 联动如果你的安装方式采用的是 npm 全局安装 Claude Codenpm install -g anthropic-ai/claude-code注意 npm 会把可执行文件放在一个固定的 bin 目录。安装 Node.js 时官方安装器通常会自动把这个目录加入 PATH但如果之前装过旧版 Node或者用了非官方安装包这步可能没做。安装完 Claude Code 后敲claude --version如果提示找不到命令就去环境变量里确认上面那个AppData\Roaming\npm路径存在。5. WSL 方案深度配置5.1 启用 WSL 并安装 Ubuntu如果你决定走 WSL 路线从启用到能用需要几步。新版 Windows 上启用 WSL 只需要一条命令wsl --install系统会默认安装 WSL2 并带上 Ubuntu 发行版。如果没带 Ubuntu可以显式指定wsl --install -d Ubuntu安装过程中会提示设置一个 Linux 用户名和密码这个用户名后续会有用别随便乱设然后忘了。装完重启电脑然后打开终端更新一下 WSL 内核这个步骤很多人会跳过结果后面各种报错wsl --update确认默认版本是 WSL2wsl --set-default-version 2进入 Ubuntuwsl看到$提示符就说明你已经在 Linux 环境里了。5.2 把 WSL 迁移到 D 盘WSL 的默认虚拟磁盘放在 C 盘用户目录下用久了能膨胀到几十 GB。C 盘紧张的人一定要在安装完、还没下载大量东西之前就迁移。迁移逻辑是先导出虚拟磁盘为 tar 包注销原有发行版再把 tar 包导入到指定目录。wsl --shutdown wsl --export Ubuntu D:\wsl\ubuntu.tar wsl --unregister Ubuntu wsl --import Ubuntu D:\wsl\ubuntu D:\wsl\ubuntu.tar --version 2提示wsl --unregister会删除原发行版的所有数据务必确认刚才的--export成功且 tar 文件存在。这步不能开玩笑。迁移完成后有个细节坑导入的发行版默认用户会变成 root你需要改回刚才设置的那个普通用户。方式是在 Ubuntu 里编辑/etc/wsl.conf[user] default你的用户名或者直接在 Windows 侧用发行版自带的配置命令ubuntu.exe config --default-user 你的用户名改完执行wsl --shutdown再重进确认whoami输出的是你想用的用户。5.3 在 WSL 里安装 Claude CodeWSL 里的安装步骤跟 Linux 版基本一致。先更新软件源安装 Node.js如果还没装sudo apt update sudo apt upgrade -y然后确认 Node.js 版本在 18 以上node -v npm -v如果 node 版本太低建议通过 NodeSource 或 nvm 装新版老版本 npm 随便装什么全局包都可能报错。在 Ubuntu 里安装 Claude Code最通用的方式仍是 npm 全局安装npm install -g anthropic-ai/claude-code之后运行claude首跑会触发登录流程按提示完成认证即可。如果在 WSL 里出现界面不显示、弹窗不弹出、彩色输出异常这类问题多半和 WSLg 有关。在/etc/wsl.conf里开启 systemd 可以改善很多集成问题[boot] systemdtrue然后执行wsl --shutdown再重进。systemd 开启后WSL 内的服务管理、桌面集成、后台进程都会更接近真实 Linux 的体验。6. 常见问题全排查从报错到解决6.1 禁止运行脚本的报错无法加载文件 ...因为在此系统上禁止运行脚本这是执行策略导致的解决办法就是第 2 章的Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser。注意如果你在组策略里被管理员锁死了执行策略当前用户改不了那就需要在管理员 PowerShell 里看下Get-ExecutionPolicy -List的输出来判断是哪个 Scope 在限制。6.2 Windows 守护进程报错高频error: start the windows daemon from a non-elevated terminal; shared clients这个报错我见得太多了本质是权限级别不匹配。Claude Code 在 Windows 上会启动一个守护进程用来支持多个终端共享会话。如果你用以管理员身份运行的终端启动了它守护进程运行在提升权限elevated状态而普通用户终端再尝试连接时就会报这个错。解决办法很简单关闭所有管理员终端使用普通用户身份打开 Windows Terminal再启动 Claude Code。如果是 VS Code 的集成终端确保 VS Code 本身不是以管理员身份运行的。我在排查时还发现有些人在 PowerShell 里执行了Start-Process ... -Verb RunAs之类的命令导致当前进程也被提升这个也要注意。提示日常开发完全不需要管理员权限。什么时候才需要管理员装系统级驱动、修改系统 PATH、操作 Windows 服务的时候。跑 Claude Code、写代码、Git 操作一律用普通用户终端。6.3 WSL 更新相关报错WSL needs updating这是在老版本 Windows 或者 WSL 内核版本过低时会出现的提示。处理方式wsl --update wsl --shutdown如果wsl --update也报错检查系统更新确保启用适用于 Linux 的 Windows 子系统和虚拟机平台两个功能。控制面板 - 启用或关闭 Windows 功能两个选项都勾上重启后一般就正常了。6.4 启动命令交互界面出现乱码终端里显示各种锟斤拷、方框、问号原因我们前面已经分析过核心是代码页问题。先执行chcp 65001再设置[Console]::OutputEncoding [System.Text.Encoding]::UTF8。如果是在 VS Code 集成终端里把 VS Code 的terminal.integrated.profiles.windows配置里的默认 profile 设置为 PowerShell并在设置中勾选Terminal Integrated Encoding: UTF-8或者直接换到 Windows Terminal 使用。6.5 PowerShell 被终止返回 System.Management.Automation.Utils 错误这个报错通常出现在开始菜单直接启动 PowerShell、一打开就闪退或被终止的情况。我遇到过几次触发场景大多是PowerShell 版本混乱、profile 脚本里有损坏的模块引用、或者 .NET 运行时注册表状态异常。排查思路不要乱按顺序来第一用另一个终端比如 cmd启动 PowerShell并跳过 profilepowershell -NoProfile如果能正常启动问题基本锁定在 profile 或模块自动加载上。先重命名 profile 文件排除比如把 Microsoft.PowerShell_profile.ps1 临时改成 .bak再重启终端测试。第二检查 PowerShell 版本$PSVersionTable正常输出至少是 5.1 或 7.x。如果版本异常用 winget 重装 PowerShellwinget install --id Microsoft.PowerShell -e第三如果以上都不行可能是 .NET Runtime 被第三方软件搞坏了。这种情况建议修复系统 .NET 组件或者把 PowerShell 升级到 7.x 系列新版 PowerShell 是独立安装的不依赖系统自带的 5.1。6.6 SSH 认证失败Permission denied (publickey)这几乎是 Git 平台认证最常见的报错。先确认公钥是否正确添加到了平台后台然后确认 ssh-agent 里有没有正确的私钥ssh-add -l没有输出说明私钥没加载重新执行Set-Service ssh-agent -StartupType Automatic Start-Service ssh-agent ssh-add $env:USERPROFILE\.ssh\id_ed25519注意如果公钥和私钥文件名不是默认的 id_ed25519比如你有多个密钥需要指定路径ssh-add 你的私钥路径。6.7 Claude Code 命令找不到claude : 无法将“claude”项识别为 cmdlet、函数、脚本文件或可运行程序的名称这个要分情况。如果是 npm 方式安装的去确认 npm 全局 bin 目录是否在 PATH 里路径是C:\Users\你的用户名\AppData\Roaming\npm。如果是通过官方工具安装的确认安装目录是否在 PATH 里。最直接的验证方式是打开终端输入where claudeWindows或which claudeWSL有输出就说明路径没问题没输出就是 PATH 缺失。6.8 高频问题速查表报错/现象根本原因解决入口无法加载文件禁止运行脚本执行策略受限Set-ExecutionPolicy RemoteSignedstart the windows daemon from a non-elevated terminal管理员终端启动守护进程换成普通用户终端WSL needs updatingWSL 内核过期wsl --update 后 wsl --shutdown中文全部是乱码代码页/编码不一致chcp 65001 UTF-8 输出Permission denied (publickey)SSH 密钥未加入 agent启动 ssh-agent 并 ssh-addclaude 命令找不到PATH 缺 npm/安装目录检查并补齐 PATHPowerShell 闪退/被终止profile 损坏或 .NET 异常-NoProfile 排查 重装Git 中文文件名乱码字符编码显示终端切 UTF-8Git config core.quotepath false7. VS Code 集成与日常使用技巧7.1 在 VS Code 里用上 Claude CodeVS Code 是 Claude Code 使用频率最高的前端之一。Windows 上集成有两条路径要么直接在 VS Code 的内置终端里跑claude要么用官方扩展做深度绑定。前者你只需要把默认终端设为 PowerShell 或 WSL Bash后者可以在扩展市场搜Claude Code安装后登录一次就能在编辑器面板里直接对话、选文件、看 diff体验比纯终端更顺手。如果走的是 WSL 环境VS Code 还有一招安装 Remote - WSL 扩展然后用命令面板执行WSL: Connect to WSLVS Code 就会连接进 WSL 环境这时候终端、扩展、文件系统全部切到 Ubuntu 侧。Claude Code 的 Linux 环境体验在 WSL 里是最接近官方预期值的。7.2 用 CLAUDE.md 管理项目上下文Claude Code 会读取一个叫CLAUDE.md的文件作为项目级记忆。你把它放在项目根目录里面写清楚项目的技术栈、目录结构、运行命令、注意事项Claude Code 在每一轮对话中都会参考这份上下文。这个文件用多了之后你会发现它的价值甚至比 prompt 还高相当于给 AI 建立了一份项目说明书。建议团队里把这份文件纳入版本管理跟 README 一样维护。7.3 版本升级与回滚Claude Code 更新频率不低。npm 方式安装的升级命令是npm update -g anthropic-ai/claude-code如果是 WSL 环境记得在 Ubuntu 里执行同样的命令而不是在 Windows PowerShell 里。验证版本claude --version如果升级后出现新问题可以先检查官方发布说明必要时回滚版本。npm 方式可以安装指定版本npm install -g anthropic-ai/claude-code版本号7.4 工作流小建议我在实际使用中有几个固定习惯。第一个是给 Claude Code 建一个独立的项目目录不让它在 C 盘用户目录里到处找工作文件所有实验项目都在D:\workspace下路径纯英文省去编码和权限的坑。第二个是不同项目用不同的 CLAUDE.md避免上下文互相污染。第三个是日常代码评审和 diff 生成都用 Claude Code 来跑它跟 Git 的配合在 Windows 下比很多 GUI 工具都流畅。最后再分享一个小技巧如果你卡在某个问题上先把claude --version、git --version、node -v三个命令的输出贴在报错信息前面一起排查。几乎所有环境类问题都能从这三个版本号里看出端倪这比反复重装工具高效得多。