主题
Claude Code 安装教程（Windows 10 / 11）
在 Windows 上从零安装 Claude Code CLI 的完整步骤，含国内网络环境下最容易卡住的代理配置。
Windows 10 与 Windows 11 的步骤基本一致，差异集中在终端和 winget 是否自带，文末单列。
先决定：原生 Windows 还是 WSL？
早期 Claude Code 只支持 WSL，所以流传着「WSL 效果最好」的说法。现在原生 Windows 已是官方支持，这条经验已经过期。
决定因素不是哪个更好，而是你的文件和工具链在哪一侧。
| 对比项 | 原生 Windows | WSL2 |
|---|---|---|
| 代理 | 直接读 Windows 环境变量，配一次 | WSL 默认够不到宿主机 127.0.0.1 上的代理，要额外放行 |
| 访问 Windows 文件 | 原生速度 | 走 /mnt/c 有明显性能损失 |
| 内存占用 | 无额外开销 | vmmem 默认可占用较大比例内存 |
| 开机可用性 | 直接可用 | 需要额外保活 |
| Shell 质量 | Git Bash（MSYS），有少量怪癖 | 真 Linux bash，干净 |
结论
- 写文档、改代码、连服务器、日常使用 → 用原生 Windows，本文即按这条路线。
- 要在本机跑 R、生信、Linux 专属工具链 → 用 WSL2，参见 WSL2 安装 Claude 进度。
一个真实踩过的坑
原生 Windows 的 Bash 工具走 Git Bash（MSYS），它不把 NUL 当空设备，而当成普通相对文件名。若某个配置里写了 > NUL，会在当前目录生成一个名为 NUL 的文件；它是 Windows 保留设备名，git 读不了会直接报 short read while indexing NUL，导致 git add 整体失败。统一写 /dev/null 即可，两侧客户端都认。
步骤一：安装三个依赖
以管理员身份打开 PowerShell：
powershell
winget install OpenJS.NodeJS.LTS # Node.js LTS（22.x）
winget install Git.Git # Git for Windows
winget install Microsoft.WindowsTerminal # 终端（Win11 已自带，可跳过）Git for Windows 不是可选项
Claude Code 在原生 Windows 上的 Bash 工具依赖 Git Bash（MSYS）提供的 POSIX 环境。不装 Git，Bash 工具直接不可用。
不需要单独安装 npm
npm 随 Node.js 一起发布，装完 Node 就有了，没有独立的安装命令。下一步的 npm install ... 是使用 npm，不是安装 npm。
装完关闭并重新打开终端（让 PATH 生效），然后验证：
powershell
node -v # 期望 v20 或更高
npm -v # 有输出即说明 npm 已随 Node 装好
git --version三条都有输出才继续。
步骤二：允许 PowerShell 运行脚本
别跳过这一步
Windows 10 / 11 客户端系统的默认执行策略是 Restricted，禁止运行任何 .ps1 脚本。
而 npm 在 Windows 上装了两个入口：npm.cmd（给 cmd.exe 用）和 npm.ps1（给 PowerShell 用）。你在 PowerShell 里敲 npm，调用的正是被拦住的那个，下一步会直接失败并报：
无法加载文件 ……\npm.ps1，因为在此系统上禁止运行脚本。
先改掉再往下走（不需要管理员权限，只影响当前用户）：
powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser确认提示输入 Y，然后关闭并重开终端，验证：
powershell
Get-ExecutionPolicy -List # CurrentUser 一行应显示 RemoteSigned
npm -v # 能出版本号即已放行为什么选 RemoteSigned
| 策略 | 效果 | 建议 |
|---|---|---|
Restricted | 禁止一切脚本（系统默认） | 太严，npm 用不了 |
RemoteSigned | 本地脚本可运行，从网上下载的必须带有效签名 | ✅ 推荐 |
Unrestricted / Bypass | 全部放行 | ❌ 不要用，网上抄来的脚本会无提示执行 |
-Scope CurrentUser 只改当前用户，不动系统全局，所以不需要管理员权限。
实在不想改策略
可以显式调用 cmd 版本 npm.cmd install -g @anthropic-ai/claude-code，或者改在 cmd.exe 里执行（cmd 不受执行策略约束）。但之后每次用 npm 都得记着加后缀，长期还是建议改设置。
步骤三：安装 Claude Code
powershell
npm install -g @anthropic-ai/claude-code验证：
powershell
claude --version步骤四：配置代理（国内环境的关键一步）
这一步是国内安装最常见的失败点，而且有个容易忽略的细节。
坑：不能填 SOCKS 端口
Claude Code 是 Node 应用，读取 HTTPS_PROXY / HTTP_PROXY 环境变量，但不支持 socks5:// 协议。
常见代理客户端会同时开两个本地端口：
| 类型 | 常见默认端口 | 能否用于此处 |
|---|---|---|
| SOCKS5 | 10808 | ❌ 不可用 |
| HTTP | 10809 | ✅ 用这个 |
请到你的代理客户端界面确认实际的 HTTP 入站端口，不同客户端和配置不一样。
先临时测试
powershell
$env:HTTPS_PROXY="http://127.0.0.1:10809"
$env:HTTP_PROXY="http://127.0.0.1:10809"
claude --version确认可用后再永久写入
用户级环境变量，不需要管理员权限：
powershell
[Environment]::SetEnvironmentVariable("HTTPS_PROXY","http://127.0.0.1:10809","User")
[Environment]::SetEnvironmentVariable("HTTP_PROXY","http://127.0.0.1:10809","User")写入后再关一次终端才会生效。
如果内网有不该走代理的地址
powershell
[Environment]::SetEnvironmentVariable("NO_PROXY","localhost,127.0.0.1,::1","User")步骤五：登录
powershell
claude首次运行会自动打开浏览器完成登录。凭据保存在 %USERPROFILE%\.claude\.credentials.json。
不要在机器之间拷贝凭据文件
换机时重新登录即可。拷贝 .credentials.json 既有安全风险，也容易出现状态不一致。
步骤六：验证
powershell
claude doctor会检查 Node 版本、Git 可用性、网络连通性、配置文件完整性等。全绿即安装完成。
Windows 10 与 11 的差异
| 项目 | Windows 10 | Windows 11 |
|---|---|---|
| winget | 1809 及以上通常自带；没有则从 Microsoft Store 装「应用安装程序」 | 自带 |
| Windows Terminal | 不自带，需手动安装 | 自带 |
| 默认终端 | conhost，中文和框线渲染较差，建议换 Windows Terminal | Windows Terminal |
| 其余步骤 | 完全相同 | 完全相同 |
Windows 10 上如果 winget 命令不存在，可以改用官方安装包：
- Node.js LTS：https://nodejs.org/
- Git for Windows：https://git-scm.com/download/win
- Windows Terminal：Microsoft Store 搜索安装
常用命令
powershell
claude # 启动交互会话
claude doctor # 环境体检
claude update # 更新到最新版
claude --version # 查看版本会话内常用斜杠命令：
| 命令 | 作用 |
|---|---|
/help | 查看全部命令 |
/login /logout | 账号切换 |
/config | 修改模型、主题等设置 |
/effort | 调整思考投入程度 |
/fast | 切换快速输出模式 |
/clear | 清空当前上下文 |
故障排查
npm 报「无法加载文件 npm.ps1，因为在此系统上禁止运行脚本」
说明步骤二跳过了或没生效。跟 npm 本身无关，是 PowerShell 执行策略拦的。
powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser改完必须关闭并重开终端才生效——这一点最容易被忽略。用 Get-ExecutionPolicy -List 确认 CurrentUser 那行已变为 RemoteSigned。原理与策略取舍见步骤二。
安装时 npm 报网络错误
代理没配好，或配成了 SOCKS 端口。回到步骤四，确认用的是 HTTP 端口。也可临时给 npm 单独设置：
powershell
npm config set proxy http://127.0.0.1:10809
npm config set https-proxy http://127.0.0.1:10809提示 claude 不是内部或外部命令
npm 全局目录不在 PATH 中。查看目录：
powershell
npm config get prefix把输出的路径加入用户 PATH，然后重开终端。
登录后仍报连接失败
- 确认代理客户端正在运行且已开启系统代理
- 确认
HTTPS_PROXY用的是 HTTP 端口而非 SOCKS 端口 - 确认环境变量写入后重开过终端
- 用
$env:HTTPS_PROXY打印当前值核对
Bash 工具报错找不到命令
Git for Windows 没装，或装了但没重开终端。用 git --version 确认。
中文显示为乱码
改用 Windows Terminal。若仍有问题，在终端里执行 chcp 65001 切到 UTF-8。
iex (irm ...) 报「无法将“#”项识别为 cmdlet」
托管的 .ps1 文件带了 UTF-8 BOM。走 iex 执行时，BOM 会被当成命令名的一部分，于是报这个错。
它不影响后续执行（脚本照样会跑完），但看着像失败，容易误判。
修法是把托管文件保存为「UTF-8 无 BOM」。中文不会因此乱码——只要服务端在 Content-Type 里带了 charset=utf-8，PowerShell 就能正确解码：
Content-Type: text/plain; charset=utf-8BOM 什么时候才需要
本地 .ps1 文件用 PowerShell 5.1 直接运行时，带 BOM 能避免中文乱码；而通过 HTTP 拉取执行时，编码由响应头决定，BOM 反而有害。同一个脚本，两种分发方式的要求相反。
irm 拉取脚本报「远程服务器返回错误: (308) 永久重定向」
URL 少写了 https://。不带协议时 PowerShell 按 http:// 发起请求，服务端强制 HTTPS 会回 308 Permanent Redirect——服务端行为是正确的。
问题在客户端：PowerShell 5.1 不支持 308。它底层的 .NET Framework HttpWebRequest 只自动跟随 301 / 302 / 307，遇到 308 直接抛错。PowerShell 7 则能正常跟随，所以同一条命令在 PS 7 上测不出这个问题。
powershell
# ❌ PS 5.1 上会报 308
iex (irm scripts.example.com/foo.ps1)
# ✅ 补全协议即可
iex (irm https://scripts.example.com/foo.ps1)用 $PSVersionTable.PSVersion 可以确认当前版本。养成始终写全 https:// 的习惯，在 PS 5.1 和 7 上都不会出问题。
换机迁移
全新安装开箱即用，不迁移任何东西也能正常使用。要把旧机器的密钥、凭据和记忆带过来，有两条路。
推荐：一键还原脚本
前提是旧机器已经按下文的打包方式做好了加密包，并放到了网盘。
powershell
cd <你想放项目的目录> # 加密包也下载到这里
iex (irm https://scripts.cong.in/restore.ps1)一路回车 + 输一次解密密码即可。脚本按七步走：
| 步骤 | 内容 |
|---|---|
| 1 | 检查 git / openssl / tar，Git 缺失会自动安装 |
| 2 | 按「当前目录 → 下载 → 桌面」顺序找 .tar.gz.enc，列出候选供选择 |
| 3 | 提示输密码 → 解密 → 解包（明文归档立即删除） |
| 4 | 询问项目目录（默认当前目录），自动推导记忆库目录名 |
| 5 | 四个落点自动就位：.ssh\、项目文件、memory\、settings.json（已存在会先备份） |
| 6 | 自动 icacls 收紧全部私钥；读 config 检查 ProxyCommand 所需程序 |
| 7 | 从 config 读出所有主机别名，逐个 ssh 测通 |
结束时自动清理临时解压目录。
脚本公开，数据不公开
脚本托管在无鉴权的公开地址上，因此它不包含任何密钥、IP、域名或账号，只是一段流程。真正敏感的加密包放在需要登录的网盘，密码由你自己保管。三者分开，缺任意一项都无法还原。
有三处位置改不了
.ssh\、memory\、settings.json 都必须位于用户目录下（OpenSSH 与 Claude Code 只认这些固定位置），脚本不会询问。可自选的只有「项目文件」放哪，记忆库的目录名会按它自动推导。
权限模式由 settings.json 决定，别忘了带上
每次执行命令都要手动确认，通常是因为没把 settings.json 带过来。记忆文件里记录的工作偏好只是让模型知道你的习惯，不等于系统层面的授权——真正放行的开关在 settings.json 的 permissions.defaultMode。
反过来说，如果新机器会带出门或接入公共网络，也可以借这个机会把它调严一些。
如果只想手动做，或者想了解每一步在干什么，看下面两节。
第一层：能连上服务器的最小集
如果新机器要接管原有的服务器运维工作，这几个文件是刚需，其中私钥丢了无法重建：
| 文件 | 原位置 | 说明 |
|---|---|---|
| SSH 私钥 | %USERPROFILE%\.ssh\ | ★ 唯一凭证。若服务器已关闭密码登录，丢失后只能从服务商控制台救 |
| 对应公钥 | %USERPROFILE%\.ssh\ | |
config | %USERPROFILE%\.ssh\ | 主机别名、端口、跳板/代理定义 |
| 凭据文件 | 你自己的项目目录 | 账号密码与云 API 密钥 |
CLAUDE.md | 项目根目录 | 项目级说明，通常含 SSH config 的文字备份 |
加起来往往只有十几 KB。
落位后必须收紧私钥权限
powershell
mkdir "$env:USERPROFILE\.ssh" -Force
# 把私钥等文件复制进去后：
icacls "$env:USERPROFILE\.ssh\<私钥文件名>" /inheritance:r /grant:r "$env:USERNAME:R"这一步不能跳过
Windows OpenSSH 会拒绝使用权限过宽的私钥，报 UNPROTECTED PRIVATE KEY FILE，表现为「密钥明明在却一直要密码」。
如果 config 里用了 ProxyCommand
需要连的主机若通过本地代理跳转，config 里通常长这样：
ProxyCommand "C:\Program Files (x86)\Nmap\ncat.exe" --proxy 127.0.0.1:10808 --proxy-type socks5 %h %p那么新机器上还必须：
- 安装 nmap（提供
ncat.exe）：winget install Insecure.Nmap - 确认安装路径与
config中写死的路径一致，不一致就改config - 代理客户端保持运行，且 SOCKS5 端口与配置里一致
直连的主机不受影响，所以排查时先测直连的那台，再测走代理的，能快速区分是密钥问题还是代理问题。
验证
powershell
ssh <直连别名> "hostname" # 先测这个，验证密钥本身没问题
ssh <代理别名> "hostname" # 再测这个，验证代理链路第二层：Claude Code 自身配置
配置目录在 %USERPROFILE%\.claude\：
建议迁移：
rules/—— 编码规范、工作流约定skills/—— 技能库commands/—— 自定义斜杠命令agents/—— 子代理定义hooks/—— 钩子脚本settings.json—— 模型与权限设置projects/<项目名>/memory/—— 记忆库
不要迁移：
.credentials.json—— 重新登录history.jsonl—— 会话历史cache/、paste-cache/、shell-snapshots/、file-history/—— 缓存，会自动重建sessions/、daemon/、jobs/—— 机器本地状态
记忆库目录名与项目路径绑定
projects/ 下的子目录名由项目绝对路径转换而来，例如 F:\project 对应 F--project。新机器上项目路径不同的话，记忆库不会被识别。 要么保持相同的项目路径，要么按新路径重命名：D:\project 对应 D--project，C:\work\proj 对应 C--work-proj。
不必一次性全搬
技能和规则装得越多，启动时的上下文开销越大。建议先裸装使用，用出习惯后再挑常用的几个搬过去。
怎么把这些安全地送到新机器
第一层的内容包含私钥和明文凭据，不要用聊天软件传，也不要放在无鉴权的公开地址（例如以 iex (irm ...) 方式对外提供的脚本站，那类地址设计上就是公开可拉取的）。
推荐做法是打包加密后再走网盘，密码与文件分开走：
powershell
# 1. 打包（用 Windows 自带的 tar，不要用 Git Bash 的 MSYS tar）
C:\Windows\System32\tar.exe czf pack.tar.gz -C <暂存目录> .
# 2. 加密（openssl 由 Git for Windows 提供）
openssl enc -aes-256-cbc -pbkdf2 -iter 600000 -salt -in pack.tar.gz -out pack.tar.gz.enc
# 3. 立刻删除未加密的中间文件
Remove-Item pack.tar.gz -Force新机器上解开：
powershell
openssl enc -d -aes-256-cbc -pbkdf2 -iter 600000 -in pack.tar.gz.enc -out pack.tar.gz
tar xzf pack.tar.gz上传之前，务必先自己解一次
加密包一旦成为唯一副本，密码错一个字符就永久打不开，而且要等到换机当天才会发现。所以打包完立刻做一次往返校验：
powershell
# 用同一个密码解回来，与原始文件逐字节比对
openssl enc -d -aes-256-cbc -pbkdf2 -iter 600000 -in pack.tar.gz.enc -out verify.tar.gz
fc /b pack.tar.gz verify.tar.gz比对通过再上传、再删除源文件。
用命令行生成密码时当心不可见字符
在 Git Bash 等环境里，openssl rand 之类的命令可能输出 CRLF 行尾。若只用 tr -d '\n' 清理，会留下一个不可见的回车符 \r，它进了加密密码却无法用键盘输入——结果就是密码看着完全正确，却永远提示 bad decrypt。
两个规避办法：
- 清理时把两种行尾都去掉：
tr -d '\r\n' - 或者干脆不经过 shell，用 Python 之类直接生成并写文件
顺带建议密码避开易混淆字符（I O 0 1 l）和 + / 这类符号，改用连字符分组，例如 XXXX-XXXX-XXXX-XXXX。换机时往往要手工敲入，这能显著降低出错率。
三个容易忽略的点
- 加密包走网盘，密码走另一条路（密码管理器 / 线下记录）。两者放同一处等于没加密。
- 新机器解压出来的明文副本，用完请删除，别留在下载目录或桌面。
- 解密依赖
openssl，而它由 Git for Windows 提供 —— 所以新机器要先完成本文步骤一，再解包。
为什么用 Windows 自带的 tar
若 PATH 中 Git Bash 的 MSYS tar 排在前面，它会把 C:\Users\... 里的冒号当成远程主机分隔符，报 Cannot connect to C: 并且打不出包。显式写 C:\Windows\System32\tar.exe 可以避开。
相关页面
- WSL2 安装 Claude 进度 —— 需要 Linux 工具链时的方案
- tmux 使用说明 —— 终端复用器速查