Claude Code本地部署实战：Windows与WSL环境搭建全指南-优快云博客

1. 先说清楚：Claude Code 不是“本地大模型”，而是本地运行的 AI 编程协作者

很多人看到“本地部署 Claude Code”这个标题，第一反应是：“终于能绕过网络、在自己电脑上跑 Claude 了？”——这是个根深蒂固的误解，必须立刻掰正。

Claude Code 不是一个可以在你笔记本上加载几十GB权重、离线推理的本地大语言模型。它本质上是一个 高度工程化的本地客户端（CLI + Desktop App） ，核心功能是：把你本地的代码项目、文件系统、终端环境，安全、结构化地“桥接”到 Anthropic 的云端 Claude 模型服务（目前主要通过 Claude Pro/Max/Team 等订阅账户接入），同时提供强大的本地工具调用能力（比如自动执行 shell 命令、读写文件、调用 git、运行测试等）。

你可以把它理解成一个“超级智能的本地代理”：它不生成答案，但它知道该向谁提问、该问什么、该把哪些上下文打包发过去、又该把返回的答案如何精准地作用于你的本地文件和终端。它的“本地性”体现在三件事上：

本地执行环境 ：所有命令都在你自己的 Windows/macOS/Linux 机器上运行，不上传源码到第三方服务器（除非你明确授权某项 MCP 工具）；
本地状态管理 ：会话历史、项目配置、工具白名单、MCP 服务器连接信息都存在你本机 ~/.claude/ 目录下；
本地工具链集成 ：能直接调用你系统里已有的 git 、 npm 、 python 、 curl 、甚至 VS Code 或 JetBrains 的 CLI 工具，形成闭环工作流。

这也是为什么官方文档反复强调“internet connection required”——没有网络，Claude Code 就像没插网线的路由器，再强的本地逻辑也发不出请求。而那些热搜词里反复出现的 wsl , node.js , npm , npm.ps1 报错，恰恰暴露了绝大多数人卡住的第一关： 不是模型没连上，而是这个本地代理的运行环境本身就没搭稳。

我去年帮团队落地 Claude Code 时，70% 的初期咨询都集中在“为什么 claude 命令打不出来”“为什么 WSL 里装好了却提示 command not found ”“为什么 npm 安装完双击桌面图标没反应”。这些问题和模型能力无关，纯粹是本地开发环境的“地基”没夯实。所以这篇内容不讲高阶提示词技巧，也不聊 MCP 插件开发，就死磕一件事： 让你的 claude 命令，在 Windows 或 WSL 里，稳稳当当地敲出来、跑起来、连上账号、开始干活。 后面所有炫酷功能，都建立在这个最朴素的前提之上。

2. 环境诊断：Windows 用户必做的三道“安检门”

在 Windows 上部署 Claude Code，最大的陷阱不是技术多难，而是系统默认策略和用户操作习惯之间的“静默冲突”。很多报错看似随机，实则有迹可循。我整理出三道必须亲手验证的“安检门”，跳过任何一道，后续安装大概率失败。

2.1 第一道门：PowerShell 执行策略 —— 解决 `npm.ps1 无法加载` 的根源

你一定见过这个经典报错：

npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1，因为在此系统上禁止运行脚本。
所在位置 行:1 字符: 1
+ npm -v
+ ~~~
    + CategoryInfo          : SecurityError: (:) []，PSSecurityException
    + FullyQualifiedErrorId : UnauthorizedAccess

这不是 Node.js 装错了，也不是 npm 损坏了，而是 Windows PowerShell 的 执行策略（Execution Policy） 在起作用。出于安全考虑，Windows 默认禁止运行本地脚本（ .ps1 文件），而 npm 的 Windows 版本正是用 PowerShell 脚本封装的。

正确解法不是“禁用安全策略”，而是精准放行：
打开 管理员权限的 PowerShell （右键开始菜单 → Windows PowerShell（管理员）），执行：

# 查看当前策略
Get-ExecutionPolicy -List

# 仅对当前用户放宽策略（最安全！不影响系统其他用户）
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

# 验证是否生效
Get-ExecutionPolicy -Scope CurrentUser
# 应输出：RemoteSigned

提示： RemoteSigned 是微软官方推荐的安全级别——它允许你运行本地编写的脚本（如 npm.ps1），但要求从互联网下载的脚本必须有可信签名。这比 Unrestricted 或 Bypass 安全得多，也比直接用 CMD 绕过问题更治本。

为什么不用 CMD？因为 CMD 无法执行 .ps1 ，但 npm 在 CMD 下会退化为调用 npm.cmd ，而 npm.cmd 本质是批处理文件，它内部又会尝试调用 PowerShell 脚本。最终结果就是：CMD 下 npm -v 可能显示版本，但 npm install -g @anthropic-ai/claude-code 会卡在某个环节无声失败。 PowerShell 是 npm 的原生主场，必须让它合法上岗。

2.2 第二道门：WSL 状态与发行版选择 —— 解决 `an error occurred while running a wsl command` 的实操路径

an error occurred while running a wsl command. please check your wsl configu 这个报错，90% 源于 WSL 本身没启动成功或配置异常。别急着重装，先做三步快速诊断：

第一步：确认 WSL 功能已启用且内核已安装 以管理员身份运行 PowerShell，执行：

# 检查 WSL 功能是否启用
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
# ⚠️ 这两行执行后必须重启电脑！否则后续所有操作无效

第二步：检查 WSL 内核版本 重启后，再次打开 PowerShell（非管理员），执行：

wsl --list --verbose
# 如果报错 "The term 'wsl' is not recognized"，说明 WSL 内核未安装，去官网下载：https://aka.ms/wsl2kernel
# 如果输出为空或只有 "NAME STATE VERSION"，说明没装发行版，需要手动安装