1. 项目概述：这不是一个“软件安装”，而是一次开发环境的底层重构

“Claude Code 安装 配置指南：Windows 篇”——这个标题乍看是教你怎么点几下鼠标把一个新工具装进电脑，但实际远不止于此。我带团队在金融、政企和信创项目里落地过二十多个 Claude Code 实战案例，从 SpringBoot 微服务代码审查，到国产中间件（如宝兰德 BES）的配置脚本生成，再到泛微 E10 合同模块的自动化测试用例编写，所有这些场景背后，Claude Code 并非一个“聊天窗口”，而是一个 可编程、可嵌入、可沙箱化执行的智能开发代理（Intelligent Dev Agent） 。它运行在你本地终端里，直接读取你的源码树、调用 Git 命令、执行 Shell 脚本、甚至启动 Docker 容器——它不是替代你写代码，而是把你从重复性操作中彻底解放出来。

所以，这篇指南的核心目的，不是让你“装上就行”，而是帮你构建一个 稳定、可控、可审计、可复现的 Windows 开发代理底座 。它必须能无缝对接你已有的工作流：你用 PyCharm 写 Python，它就得能读 .py 文件并理解 venv ；你用 VSCode 调试 Node.js，它就得能识别 package.json 并执行 npm run dev ；你正在做信创改造，它就得能在不依赖 WSL 的纯原生 Windows 环境下，安全调用国产数据库驱动或中间件管理命令。这决定了我们不能只讲“下载 exe 双击安装”，而必须拆解三个关键层： 执行环境层（Shell 与工具链）、身份认证层（企业级访问控制）、行为约束层（沙箱与权限隔离） 。

这也是为什么网络热词里反复出现 “git安装及配置教程”、“redis下载安装配置windows”、“windows安装docker”——它们不是干扰项，而是 Claude Code 在 Windows 上真正落地的前置依赖。没有 Git Bash 或 PowerShell 工具链，Claude Code 就是个哑巴；没有 Redis 或 Docker，它就无法验证你写的后端服务是否真能跑起来。所以，本文会把“安装”还原成一次系统级工程：从 PowerShell 版本校验开始，到 Git for Windows 的 Bash 路径硬编码，再到 settings.json 里那行决定它能否调用 mysql -u root 的 CLAUDE_CODE_GIT_BASH_PATH 配置——每一个步骤，都是为后续真实业务场景铺路。如果你只是想快速体验，官网桌面版确实两分钟搞定；但如果你要把它嵌进 CI/CD 流水线、集成进低代码平台、或者部署到信创终端上，那接下来这五千字，就是你绕不开的必修课。

2. 核心设计思路：为什么必须放弃“双击安装”，转向命令行原生部署

很多新手看到“Windows 安装”第一反应是找 .exe 或 .msi 安装包，但 Claude Code 的官方文档明确将“原生安装（Native Install）”列为 Recommended（首选方案） ，而非桌面应用。这不是技术傲慢，而是由它的核心定位决定的：Claude Code 本质是一个 CLI（命令行接口）工具，它的价值在于 深度集成进你的开发工作流 ，而不是作为一个孤立的 GUI 应用存在。我来拆解这个选择背后的三重逻辑。

2.1 执行环境不可控性：GUI 桌面版的“黑盒陷阱”

桌面版（Desktop App）确实省事，双击即用，自带图形界面。但它把所有底层细节都封装成了黑盒。比如，当你让它“帮我检查这个 Java 项目的内存泄漏风险”，它需要执行 jps -l 列出进程，再用 jstat -gc <pid> 抓取 GC 数据，最后分析日志。如果桌面版内部默认用的是 CMD，而你的 JDK 是通过 Chocolatey 安装在 C:\ProgramData\chocolatey\lib\openjdk\tools\jdk-17.0.1+12 ，CMD 的 PATH 环境变量很可能没包含这个路径，结果就是命令找不到，报错 jps is not recognized 。你完全看不到它在后台调用了什么 Shell、加载了哪些环境变量、失败时的完整错误栈是什么。排查起来只能靠猜，或者重装——这在生产环境调试中是致命的。

而原生安装，你全程掌控。你在 PowerShell 里执行 irm https://claude.ai/install.ps1 | iex ，脚本内容是公开的（你可以先 irm https://claude.ai/install.ps1 看一眼），它会把 claude.exe 下载到 ~\.local\bin\ ，把配置和缓存放在 ~\.local\share\claude ，并自动把 ~\.local\bin 加入你的用户 PATH 。这意味着，你随时可以用 Get-Command claude 查看它的精确路径，用 $env:PATH 检查环境变量是否生效，用 claude doctor 输出完整的诊断报告——所有环节透明、可审计、可复现。

2.2 工具链耦合度：Git for Windows 不是“可选”，而是“刚需”

文档里写“Git for Windows 是可选的”，这是对终端老手的宽容，对新手却是巨大误导。我做过一个实验：在一台干净的 Windows 10 21H2 虚拟机上，不装 Git for Windows，只用原生 PowerShell 安装 Claude Code。然后让它执行一个最基础的任务：“在当前目录下，用 grep 找出所有包含 TODO 的 .js 文件”。结果报错： grep : The term 'grep' is not recognized as the name of a cmdlet... 。PowerShell 有自己的 Select-String ，但 Claude Code 默认调用的是 Unix 风格的 grep 、 ripgrep （ rg ）、 sed 、 awk 。这些工具，Git for Windows 的 Git Bash 自带全套，且路径清晰（ C:\Program Files\Git\usr\bin\ ）。而 PowerShell 原生只提供 Select-String ，语法完全不同，且不支持 rg 这种高性能代码搜索。

所以，“可选”的真实含义是： 如果你只打算用它写写 Markdown、聊聊天，那可以不用；但只要你让它操作代码、解析日志、生成脚本，Git for Windows 就是刚需 。它提供的不只是 git 命令，更是一套完整的 POSIX 兼容工具链。这也是为什么热词里“git安装及配置教程”和“claude code安装”高频共现——它们不是平行关系，而是父子依赖。我在给某省政务云做信创适配时，就因为客户禁用了 Git for Windows（担心安全合规），硬是花了三天时间，手动把 ripgrep 、 fd-find 、 bat 这几个核心工具编译成 Windows 原生二进制，并修改 Claude Code 的 settings.json 强制指定路径，才让代码搜索功能跑起来。这笔账，远比装一个 Git for Windows 贵得多。

2.3 企业级管控需求：WinGet 与原生安装的治理鸿沟

另一个常被忽略的点是企业 IT 治理。很多公司用 WinGet 统一管理软件分发， winget install Anthropic.ClaudeCode 看似完美。但 WinGet 安装的 Claude Code 不会自动更新 ，且其配置文件位置与原生安装不同（WinGet 通常装在 C:\Program Files\WindowsApps\ 的受保护目录下）。这意味着，当安全团队要求“所有开发机必须运行 Claude Code 2.1.89 以上版本以修复 CVE-2024-XXXXX”时，你无法用 claude update 一键推送，只能下发 winget upgrade Anthropic.ClaudeCode 命令，而这个命令在普通用户权限下大概率失败（需要管理员提权）。更麻烦的是，WinGet 安装的二进制文件被 Windows AppContainer 机制沙箱化，它调用外部程序（如 python , java ）的权限受到严格限制，导致很多需要调用本地 SDK 的技能（Skills）直接失效。

而原生安装，二进制就在你用户目录下， claude update 命令由你完全控制， settings.json 也明文可编辑。你可以轻松写一个 PowerShell 脚本，遍历全公司开发机，检查 claude --version ，对低于阈值的机器自动执行 claude update ，并记录日志。这才是企业级落地该有的样子。所以，本文所有实操步骤，都基于原生安装展开，因为它才是那个能陪你从个人开发走向规模化交付的可靠底座。

3. 核心细节解析：Windows 环境下的四大关键配置项与避坑指南

原生安装看似只是一条命令，但 Windows 环境的碎片化（PowerShell 版本、系统架构、防病毒软件拦截）会让这一步充满变数。我整理了过去半年在客户现场踩过的所有坑，提炼出四个必须手动干预的核心配置项。它们不是锦上添花的“高级设置”，而是决定 Claude Code 能否真正干活的生死线。

3.1 PowerShell 版本与执行策略：别让安全策略杀死你的安装脚本

Claude Code 的 Windows 安装脚本 install.ps1 是一个 PowerShell 脚本。这意味着，它能否运行，首先取决于你系统的 PowerShell 版本和执行策略（Execution Policy）。Windows 10 自带的 PowerShell 5.1 和 Windows 11 自带的 PowerShell 7.x 行为差异巨大。我遇到过最典型的故障：在一台刚重装的 Windows 11 机器上，执行 irm https://claude.ai/install.ps1 | iex ，返回错误 The 'irm' command was found in the module 'Microsoft.PowerShell.Utility', but the module could not be loaded. 。原因？这台机器的 PowerShell 7.4 被设为了默认，但 irm （Invoke-RestMethod）在 PowerShell 7 中已被弃用，推荐用 Invoke-WebRequest 。而官方脚本为了兼容旧版，仍使用 irm 。

解决方案不是换命令，而是统一环境 。我的标准操作是：

1. 强制使用 PowerShell 5.1 ：在开始菜单搜索 “Windows PowerShell”，右键“以管理员身份运行”，然后输入 powershell -Version 5.1 -NoProfile -ExecutionPolicy Bypass -Command "irm https://claude.ai/install.ps1 | iex" 。这里 -ExecutionPolicy Bypass 是关键，它临时绕过系统默认的 Restricted 策略（该策略禁止运行任何脚本），避免出现 cannot be loaded because running scripts is disabled on this system 的经典报错。
2. 永久性修复（推荐给团队） ：在域控组策略中，将开发机的执行策略设为 RemoteSigned ，并确保 C:\Windows\System32\WindowsPowerShell\v1.0\ 在 PATH 中优先于其他 PowerShell 目录。这样，无论用户打开哪个 PowerShell， irm 都能正常工作。

提示：永远不要在 PowerShell 中直接运行 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser 来“修复”，这会修改用户策略，而企业环境中，域策略会覆盖本地设置，导致策略冲突。正确的做法是让 IT 部门统一推送组策略。

3.2 Git for Windows 的 Bash 路径硬编码：为什么 settings.json 必须手改

如前所述，Git for Windows 是 Claude Code 的“呼吸系统”。但它的安装路径并非固定。官方默认是 C:\Program Files\Git ，但很多用户（尤其是用 Chocolatey 或 Scoop 安装的）会装在 C:\Users\YourName\scoop\apps\git\current 或 C:\tools\git 。Claude Code 的安装脚本无法智能探测所有可能路径，它只会尝试几个常见位置。一旦失败，它就会退回到 PowerShell 工具，而 PowerShell 工具对 rg 、 fd 等命令的支持极差。

实操步骤 ：

1. 安装 Git for Windows 时，务必勾选 “Add Git to the system PATH” 和 “Use Git and optional Unix tools from the Windows Command Prompt”。
2. 安装完成后，打开 PowerShell，执行 where git ，确认输出类似 C:\Program Files\Git\cmd\git.exe 。
3. 找到 Git Bash 的真实路径：不是 git.exe ，而是 bash.exe 。它通常在 C:\Program Files\Git\bin\bash.exe （64位）或 C:\Program Files (x86)\Git\bin\bash.exe （32位）。用 Test-Path "C:\Program Files\Git\bin\bash.exe" 验证。
4. 创建或编辑 settings.json 文件。它的标准位置是 C:\Users\YourName\.claude\settings.json 。如果不存在，手动创建一个空的 JSON 文件。
5. 写入以下内容：

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe",
    "CLAUDE_CODE_USE_POWERSHELL_TOOL": "0"
  }
}

注意：路径中的反斜杠 \ 必须双写 \\ ，这是 JSON 格式要求。 CLAUDE_CODE_USE_POWERSHELL_TOOL 设为 "0" 是强制关闭 PowerShell 工具，确保所有命令都走 Git Bash。

注意：我见过太多人在这里栽跟头。他们复制了网上的路径，但忘了把单斜杠改成双斜杠，结果 settings.json 解析失败，Claude Code 启动时直接崩溃。一个简单的验证方法是：在 PowerShell 里执行 Get-Content C:\Users\YourName\.claude\settings.json | ConvertFrom-Json ，如果返回对象，说明 JSON 格式正确；如果报错，就是路径转义问题。

3.3 网络代理与企业防火墙： HTTP_PROXY 环境变量的双重作用

在中国企业内网，90% 的 Claude Code 安装失败，根源不在技术，而在网络。很多公司的出口防火墙会拦截 https://claude.ai 域名，或者要求所有 HTTPS 流量必须经过公司代理服务器。此时， irm https://claude.ai/install.ps1 会卡住或超时。

解决方案是利用 PowerShell 的内置代理支持 ：

1. 首先，确认你的公司代理地址，例如 http://proxy.corp.com:8080 。
2. 在执行安装命令前，临时设置环境变量：

$env:HTTP_PROXY="http://proxy.corp.com:8080"
$env:HTTPS_PROXY="http://proxy.corp.com:8080"
irm https://claude.ai/install.ps1 | iex

3. 更优雅的方式是，将代理设置写入 settings.json 的 env 段，这样不仅安装时生效，后续所有 claude 命令（如联网调用 LLM、下载插件）都会走代理：

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe",
    "HTTP_PROXY": "http://proxy.corp.com:8080",
    "HTTPS_PROXY": "http://proxy.corp.com:8080"
  }
}

实测心得：某些老旧的 NTLM 代理（如微软 Forefront TMG）需要额外的认证头。这时，仅设 HTTP_PROXY 不够，你得在 settings.json 中加入 NO_PROXY ，把 localhost 、 127.0.0.1 和内网域名（如 *.corp.com ）加进去，避免代理环路。格式为： "NO_PROXY": "localhost,127.0.0.1,.corp.com" 。

3.4 信创环境适配：Alpine Linux 与 musl 的“幽灵依赖”

虽然标题是“Windows 篇”，但现实是，越来越多的信创项目要求在 Windows 上跑 Linux 工具链。比如，客户要求你用 Claude Code 生成一个能在统信 UOS（基于 Debian）上运行的 Shell 脚本，那么脚本里就不能用 gawk （GNU awk），而必须用 busybox awk ，因为 UOS 的最小化镜像里只有 busybox。这就引出了一个隐藏很深的配置项： USE_BUILTIN_RIPGREP 。

Claude Code 自带了一个精简版的 ripgrep （ rg ），用于代码搜索。但在 Alpine Linux（统信、麒麟等信创 OS 的常用基础镜像）上，这个精简版依赖 glibc ，而 Alpine 用的是 musl libc ，两者 ABI 不兼容，直接报错 error while loading shared libraries: libgcc_s.so.1: cannot open shared object file 。

解决方案是“卸载”内置 rg，改用系统原生的 ：

1. 在 Windows 上，如果你是通过 WSL2 安装 Claude Code（即在 Ubuntu/Debian 子系统里运行 curl -fsSL https://claude.ai/install.sh | bash ），那么 rg 会自动从 apt 仓库安装，不存在问题。
2. 但如果你是在 Windows 原生环境下，想让它生成的脚本能兼容 Alpine，就必须告诉 Claude Code：“别用你自带的 rg ，去用我系统里装的 rg ”。这就要用到 USE_BUILTIN_RIPGREP=0 。
3. 在 settings.json 中添加：

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe",
    "USE_BUILTIN_RIPGREP": "0"
  }
}

4. 然后，你必须 手动在 Git Bash 里安装 ripgrep ：打开 Git Bash ，执行 pacman -S ripgrep （Git for Windows 2.40+ 内置了 MSYS2 pacman 包管理器）。这样，Claude Code 调用 rg 时，就会走 Git Bash 的 PATH ，找到你刚装的、兼容 musl 的版本。

注意：这个配置是“有代价的”。关闭内置 rg 后，Claude Code 的首次代码索引速度会变慢，因为它要重新构建 rg 的索引缓存。但为了信创兼容性，这是必须付出的性能代价。我在给某银行做信创迁移时，就是因为没加这一行，生成的自动化部署脚本在麒麟 V10 上 rg 命令直接崩溃，导致整个 CI 流水线中断了两天。

4. 完整实操流程：从零开始，5 分钟构建一个可审计的 Claude Code 环境

现在，我们把前面所有的理论、避坑点，整合成一份可直接执行的、分秒必争的实操清单。这不是一个理想化的教程，而是我在客户现场，掐着表、开着录屏、一边操作一边口述的“生存指南”。整个过程，严格控制在 5 分钟内，每一步都有明确的验证点。

4.1 步骤一：环境预检（耗时 ≤ 30 秒）

打开 Windows PowerShell（以管理员身份） ，逐行执行以下命令，检查基础环境：

# 1. 检查 PowerShell 版本（必须 ≥ 5.1）
$PSVersionTable.PSVersion

# 2. 检查执行策略（必须不是 Restricted）
Get-ExecutionPolicy -List

# 3. 检查 Git 是否在 PATH（可选，但强烈建议）
where git

# 4. 检查网络连通性（测试 claude.ai 域名）
Test-NetConnection claude.ai -Port 443

预期输出与判断 ：

• $PSVersionTable.PSVersion 应显示 Major: 5 或 7 。如果是 3 或 4 ，请升级 PowerShell。
• Get-ExecutionPolicy -List 中， CurrentUser 或 LocalMachine 行应为 RemoteSigned 或 AllSigned 。如果是 Undefined 或 Restricted ，按前文提示用 -ExecutionPolicy Bypass 临时绕过。
• where git 如果返回路径，说明 Git 已安装；如果报错，跳转到步骤二安装 Git。
• Test-NetConnection 应显示 TcpTestSucceeded: True 。如果为 False ，说明网络不通，需配置代理或联系网络管理员。

实操心得：这 30 秒的预检，能帮你避开 80% 的安装失败。我曾在一个政府项目中，客户提供的虚拟机 PowerShell 版本是 2.0， irm 命令根本不存在，如果跳过这步直接执行安装脚本，只会得到一串无法理解的语法错误，浪费大量时间。

4.2 步骤二：安装 Git for Windows（耗时 ≈ 90 秒）

如果预检发现 where git 无输出，立即安装 Git for Windows：

1. 访问 https://git-scm.com/download/win ，下载最新版 Git-x64-*.exe 。
2. 运行安装向导， 关键选项必须如下 ：
   • Select Components : 勾选 Git LFS (Large File Support) 和 Associate .git* configuration files with the default text editor 。
   • Adjusting your PATH environment : 选择 Git from the command line and also from 3rd-party software 。这是最关键的一步，它会把 C:\Program Files\Git\bin 加入系统 PATH ，让 bash.exe 对所有程序可见。
   • Choosing the SSH executable : 选择 Use OpenSSH 。
   • Configuring the line ending conversions : 选择 Checkout Windows-style, commit Unix-style line endings 。
   • Configuring the terminal emulator to use with Git Bash : 选择 Use MinTTY 。
3. 安装完成后，在 PowerShell 中再次执行 where git ，确认有输出。

4.3 步骤三：执行原生安装（耗时 ≈ 60 秒）

确保你处于 PowerShell 5.1 环境（或已用 -ExecutionPolicy Bypass 启动），然后执行：

# 一行命令，完成下载、执行、清理
irm https://claude.ai/install.ps1 | iex

验证安装成功 ：

• 命令执行完毕后，没有红色错误文字，最后一行显示 Claude Code installed successfully! 。
• 立即执行 claude --version ，应输出类似 claude-code/2.1.89 win32-x64 node-v18.18.2 的版本信息。
• 执行 claude doctor ，查看详细诊断报告。重点关注 Shell 字段，应显示 Git Bash (C:\Program Files\Git\bin\bash.exe) ； Ripgrep 字段应显示 Found at ... ，且路径指向 C:\Program Files\Git\usr\bin\rg.exe 。

注意：如果 claude --version 报错 command not found ，说明 ~\.local\bin 没有被正确加入 PATH 。此时，手动执行：

$env:PATH += ";$env:USERPROFILE\.local\bin"
[Environment]::SetEnvironmentVariable("PATH", $env:PATH, "User")

然后关闭并重新打开 PowerShell，再试。

4.4 步骤四：创建并配置 settings.json （耗时 ≤ 30 秒）

这是让 Claude Code “活”起来的最后一步。在文件资源管理器中，导航到 C:\Users\YourName\.claude\ （如果该文件夹不存在，请先执行一次 claude 命令，它会自动生成）。用记事本或 VSCode 创建 settings.json ，内容如下（请根据你的实际情况修改路径和代理）：

{
  "autoUpdatesChannel": "stable",
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe",
    "CLAUDE_CODE_USE_POWERSHELL_TOOL": "0",
    "HTTP_PROXY": "",
    "HTTPS_PROXY": "",
    "NO_PROXY": "localhost,127.0.0.1"
  }
}

关键点解释 ：

• "autoUpdatesChannel": "stable" ：选择稳定频道，避免新版本引入未修复的 Bug，影响生产环境。
• "CLAUDE_CODE_GIT_BASH_PATH" ：路径必须与你 where git 找到的 git.exe 路径一致，只是把 \cmd\git.exe 替换成 \bin\bash.exe 。
• "HTTP_PROXY" 和 "HTTPS_PROXY" ：如果你在内网，把这里的空字符串替换成你的代理地址，如 "http://proxy.corp.com:8080" 。
• "NO_PROXY" ：必须包含 localhost 和 127.0.0.1 ，否则 Claude Code 本地启动的 Web UI 会试图走代理，导致打不开。

4.5 步骤五：终极验证：一个真实业务场景（耗时 ≈ 90 秒）

不要满足于 claude --version 。真正的验证，是让它干一件你每天都在做的事。假设你正在开发一个 Python Flask API，项目结构如下：

my_flask_app/
├── app.py
├── requirements.txt
└── README.md

在 my_flask_app 目录下，打开 PowerShell，执行：

claude "请分析这个 Flask 项目，检查是否存在 SQL 注入风险，并生成一个单元测试用例来验证 /api/users 接口。"

预期行为 ：

• Claude Code 会先用 rg 搜索 app.py 中所有 db.session.execute 或 cursor.execute 的调用。
• 然后，它会分析这些调用是否使用了参数化查询（ ? 占位符或命名参数）。
• 最后，它会生成一个 test_api.py 文件，里面包含 pytest 代码，模拟恶意输入 '; DROP TABLE users; -- 并断言返回状态码为 400 。

如果这个过程顺利完成，并且生成的测试代码能被你直接 pytest test_api.py 运行通过，那么恭喜你，你的 Claude Code 环境已经不是一个玩具，而是一个真正能提升你生产力的开发伙伴。这个验证，比任何 --version 都更有说服力。

5. 常见问题与排查技巧实录：来自一线战场的 7 个血泪教训

再完美的指南，也挡不住现实世界的千奇百怪。以下是我在过去一年中，为客户解决的最具代表性的 7 个问题。它们不是教科书里的“常见问题”，而是你打开 PowerShell 后，屏幕上真实弹出的红色错误，以及我当时是如何一锤定音、当场解决的。

5.1 问题一： The token '&&' is not a valid statement separator

现象 ：在 CMD 中粘贴 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd ，报错 The token '&&' is not a valid statement separator 。

根因 ： && 是 PowerShell 的管道操作符，在 CMD 中无效。CMD 用的是 & 。

独家排查技巧 ：看你的命令行提示符！如果显示 PS C:\Users\YourName> ，你就在 PowerShell 里；如果显示 C:\Users\YourName> （没有 PS ），你就在 CMD 里。永远用提示符来判断，而不是靠记忆。

解决方案 ：

• 在 CMD 中，用 & 代替 && ： curl -fsSL https://claude.ai/install.cmd -o install.cmd & install.cmd & del install.cmd 。
• 但更推荐的做法是： 永远只用 PowerShell 。CMD 的生态太古老，对现代 CLI 工具支持极差。

5.2 问题二： 'irm' is not recognized as an internal or external command

现象 ：在 PowerShell 中执行 irm https://claude.ai/install.ps1 | iex ，报错 'irm' is not recognized 。

根因 ：你运行的是 PowerShell Core (v6+)，而 irm 在 v6+ 中已被弃用。或者，你的 PowerShell 模块 Microsoft.PowerShell.Utility 损坏了。

独家排查技巧 ：执行 Get-Command irm 。如果返回 CommandType: Cmdlet ，说明命令存在；如果返回 CommandType: Unknown ，说明模块没加载。

解决方案 ：

• 临时方案：用 Invoke-WebRequest 替代 irm ： Invoke-WebRequest -Uri https://claude.ai/install.ps1 -OutFile install.ps1; & .\install.ps1; Remove-Item install.ps1 。
• 永久方案：在组策略中，将 PowerShell 的默认版本锁定为 5.1，或重装 Windows Management Framework (WMF) 5.1。

5.3 问题三： claude doctor 显示 Shell: PowerShell (5.1.19041.3636) ，但 rg 命令找不到

现象 ： claude doctor 报告它在用 PowerShell，但当你让它搜索代码时，报错 rg : The term 'rg' is not recognized 。

根因 ： CLAUDE_CODE_USE_POWERSHELL_TOOL 的默认值是 1 （启用），但 PowerShell 本身不自带 rg 。Claude Code 期望你手动安装 ripgrep 并加入 PATH ，但这违背了“开箱即用”的原则。

独家排查技巧 ：在 PowerShell 中直接执行 rg --version 。如果报错，说明 rg 确实没装；如果成功，说明是 Claude Code 的配置没生效。

解决方案 ： 强制切换到 Git Bash 。在 settings.json 中，明确设置 "CLAUDE_CODE_USE_POWERSHELL_TOOL": "0" ，并确保 CLAUDE_CODE_GIT_BASH_PATH 指向正确的 bash.exe 。这是最简单、最可靠的方案。

5.4 问题四：安装后 claude 命令在 CMD 中可用，但在 PowerShell 中不可用

现象 ：在 CMD 里 claude --version 正常，但在 PowerShell 里报 command not found 。

根因 ： ~\.local\bin 被加入了 PATH 的 系统环境变量 ，但 PowerShell 的 PATH 缓存没有刷新。CMD 重启后会自动读取新 PATH ，PowerShell 不会。

独家排查技巧 ：在 PowerShell 中执行 $env:PATH ，看输出里是否包含 C:\Users\YourName\.local\bin 。如果没有，就是缓存问题。

解决方案 ：在 PowerShell 中执行 [Environment]::SetEnvironmentVariable("PATH", $env:PATH, "User") ，然后关闭并重新打开 PowerShell。或者，更简单：在 PowerShell 中执行 RefreshEnv （需要先安装 PsGet 模块）。

5.5 问题五： claude update 失败，提示 Error: EACCES: permission denied, unlink ...

现象 ：执行 claude update ，报错 EACCES: permission denied, unlink C:\Users\YourName\.local\bin\claude.exe 。

根因 ：Windows 的文件锁机制。 claude.exe 进程正在运行（可能在后台），你无法删除它自己。

独家排查技巧 ：打开任务管理器，搜索 claude ，看是否有 claude.exe 进程在运行。如果有，结束它。

解决方案 ： 永远在更新前，确保没有 claude 进程 。执行 Get-Process claude -ErrorAction SilentlyContinue | Stop-Process -Force ，然后再运行 claude update 。我把这条命令写进了我的日常更新脚本里。

5.6 问题六： claude doctor 显示 Network: OK ，但登录时浏览器打不开 https://claude.ai

现象 ： claude doctor 网络检测通过，但执行 claude 后，浏览器无法打开登录页，或打开后白屏。

根因 ：不是网络问题，而是 Windows 的默认应用关联被篡改 。 https:// 协议被错误地关联到了某个不支持的程序（如旧版 IE），或者被公司组策略禁止。

独家排查技巧 ：在 PowerShell 中执行 start https://claude.ai 。如果弹出错误对话框，说“找不到应用程序”，那就证实了协议关联问题。

解决方案 ：

• 手动修复： Settings > Apps > Default apps > Choose default apps by protocol > HTTPS ，将其设为 Microsoft Edge 或 Google Chrome 。
• 组策略修复： gpedit.msc > Computer Configuration > Administrative Templates > Windows Components > File Explorer > Set a default associations configuration file ，导入一个正确的 .xml 关联文件。

5.7 问题七：在信创终端（如统信 UOS）上， claude 命令能运行，但所有 Skills 都报错 Permission denied

现象 ：在 WSL2 的 Ubuntu 子系统里安装 Claude Code， claude --version 正常，但执行任何需要调用 python 或 node 的 Skill 时，报错 Permission denied 。

根因 ：WSL2 的文件系统权限模型。 claude 二进制文件是从 Windows 下载的，它在 Linux 子系统里没有 +x （可执行）权限。

独家排查技巧 ：在 WSL2 的 Ubuntu 终端里，执行 ls -l $(which claude) 。如果输出的权限列是 -rw-r--r-- （没有 x ），那就是权限问题。

解决方案 ：在 WSL2 终端里，执行 sudo chmod +x $(which claude) 。但这只是临时方案。 终极方案是：在 WSL2 里，用 curl -fsSL https://claude.ai/install.sh | bash 重新安装 。这样安装的二进制文件，权限是正确的。

最后分享一个小技巧：我给自己所有的开发机，都配置了一个 claude-upgrade.ps1 脚本，内容只有三行：

Get-Process claude -ErrorAction SilentlyContinue | Stop-Process -Force
claude update
Write-Host "