最近在 Windows 上折腾 Claude Code相信不少人和我一样被 “Claude’s workspace requires the virtual machine platform on Windows. Enable…” 这段提示卡住了好一阵子。我一开始也以为是 Claude Code 安装包的问题重装了好几遍结果错误依旧后来才搞清楚是 Windows 系统底层的虚拟机平台没打开。这篇文章就把我完整的排查和解决过程记录下来从报错原因、底层原理到具体操作、VSCode 集成配置一次性说清楚给同样被卡住的朋友一份可以直接照做的方案。1. 认识 Claude Code 与底层工作区环境1.1 Claude Code 是什么解决什么问题Claude Code 是 Anthropic 官方推出的终端编程助手它不是一个简单的聊天窗口而是能直接运行在命令行里、读取你项目目录、修改文件、执行测试命令的 Agent 型工具。你可以把它理解为团队里多了一个随叫随到的高级程序员你跟它说“帮我分析一下这个仓库的代码结构”它会真的在终端里遍历文件、输出分析报告你说“给这段函数补上单元测试”它不只是给你贴代码而是直接把测试文件写到项目目录里。这种交互模式和传统“复制粘贴型”AI 工具有本质区别。但在实际使用中Claude Code 的 Windows 版依赖一个特殊的运行环境——Claude’s Workspace——它本质上是构建在 Windows 虚拟机平台Virtual Machine Platform之上的隔离沙箱。这个沙箱负责托管 Claude Code 运行所需的轻量级 Linux 子系统让 CLI 工具链在 Windows 上运行时拥有和 Linux 一致的兼容性。很多 Windows 用户在安装后第一次运行 claude 命令时终端可能报错提示 “Claude’s workspace requires the virtual machine platform on Windows. Enable the Windows Hypervisor Platform and Virtual Machine Platform features.” 或者在 VSCode 里启动 Claude Code 扩展时直接弹出 “failed to start Claude’s workspace” 的报错弹窗。这两类提示其实都是同一个根源系统没有完整开启虚拟化相关功能。1.2 为什么 Windows 上必须开虚拟机平台Windows 上的 Claude Code 工作区不是用 WSL 传统发行版实现的而是依赖 Windows Hypervisor PlatformWHP和 Virtual Machine PlatformVMP这两个系统功能来创建轻量级虚拟机。打个比方Claude 的 workspace 相当于在 Windows 里搭建了一个隔离的“运行舱”舱内跑了 Linux 内核模块而这些功能必须由宿主机也就是你的 Windows 系统提供虚拟化底层能力。如果这两个系统功能没启用或者 BIOS 层面的虚拟化被关闭那 workspace 就起不来自然就会出现上面那两类报错。更关键的是很多教程只告诉你要装 WSL2却没告诉你 Claude Code 需要的是比单纯 WSL2 更底层的虚拟机平台。如果你之前只是装了 WSL2 但没有打开“虚拟机平台”功能Claude Code 启动时依然检测不到虚拟化能力照样报错。这也是为什么很多人明明 WSL 好好的一跑 Claude Code 就翻车。2. 排查报错根源从现象到系统底层2.1 从报错文案反推系统状态当你在终端里输入claude然后看到类似下面的信息时先别急着卸载重装Claudes workspace requires the virtual machine platform on Windows. Enable the Virtual Machine Platform and Windows Hypervisor Platform features and try again.或者你在 VSCode 的 Claude Code 插件面板里看到Failed to start Claudes workspace这两种提示其实已经说得很明白系统缺少两个关键功能。但很多人不理解的是明明 Windows 11 默认已经开启了 Hyper-V 相关能力为什么还提示缺失这是因为 Windows 系统为了兼顾性能默认并不会完整开启所有虚拟化功能尤其是“虚拟机平台”和“Windows 虚拟机监控程序平台”这两个。它们属于“可选功能”需要手动开启。2.2 检查 CPU 虚拟化是否真的开启还有一个容易忽略的点即使系统功能全部打开如果 CPU 的虚拟化在 BIOS 中被关闭一切等于白搭。检查方法很简单按Ctrl Shift Esc打开任务管理器切到“性能”选项卡点左下角的“CPU”看右下角“虚拟化”一栏。显示“已启用”就正常显示“已禁用”或“未开启”就需要进入 BIOS通常开机按 Del、F2 或 F10找到类似 Intel Virtualization Technology 或 SVM Mode 的选项并打开。我试过一台较早的 i5 笔记本Windows 11 下功能都开了但 BIOS 里 VT-x 被误关了Claude Code 一样报 workspace 无法启动。这一点很多网上教程没有提到属于最容易忽略的坑。如果你在系统日志里看到Hyper-V相关错误八成和这一步有关。2.3 快速判定当前虚拟化状态除了任务管理器你还可以用命令行快速判断。以管理员身份打开 PowerShell运行systeminfo在输出中找“Hyper-V 要求”这一段。如果看到Hyper-V 要求: 已检测到虚拟机监控程序。将不显示 Hyper-V 所需的功能。说明虚拟化已经可用。如果看到类似“固件中已启用虚拟化: 是”说明 BIOS 层面 OK如果“固件中已启用虚拟化: 否”就按上面说的去 BIOS 打开。还有另一种常见情况系统显示“虚拟机监控程序未运行”但固件虚拟化是启用的那大概率就是 Windows 可选功能没开齐正好对上我们接下来的操作步骤。3. 完整修复步骤从功能开启到 Claude 正常跑起来3.1 开启 Windows 虚拟机平台与 hypervisor 平台我先说结论Claude Code 在 Windows 上成功运行至少需要四个系统组件协同工作Virtual Machine Platform虚拟机平台Windows Hypervisor PlatformWindows 虚拟机监控程序平台Windows Subsystem for Linux可选但强烈建议装虚拟机监控程序Hyper-V 底层具体开启路径有两种我分别说。方法一图形界面开启按Win R输入optionalfeatures回车打开“Windows 功能”窗口。依次勾选“虚拟机平台”“Windows 虚拟机监控程序平台”“适用于 Linux 的 Windows 子系统”如果你想顺带使用 WSL“虚拟机监控程序平台”有些系统版本显示为“Hyper-V”注意如果你平时不用 Hyper-V 管理工具不要勾选“Hyper-V”完整项只勾上面这几个轻量级功能即可。完整 Hyper-V 会接管整个系统的虚拟化层有时候和第三方虚拟机软件如 VirtualBox、VMware冲突反而会带来别的麻烦。点击“确定”系统会提示重启保存好手头的工作再重启。方法二命令行一键开启推荐省事以管理员身份打开 PowerShell逐条执行以下命令dism /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart dism /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism /online /enable-feature /featurename:HypervisorPlatform /all /norestart如果第三条提示找不到功能名可以换成dism /online /enable-feature /featurename:Windows-Hypervisor-Platform /all /norestart全部执行完后重启电脑。3.2 验证功能是否真正生效重启后别急着跑 Claude Code先用命令行验证一下功能是否真的打开了。在 PowerShell 里执行Get-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform看输出里的State是否为Enabled。同理检查HypervisorPlatform。两个都显示 Enabled 之后再继续下一步省得又白折腾一轮。另外如果你之前从来没有安装过 WSL2 内核建议顺手更新一下。虽然 Claude Code 自带 workspace 不强制依赖用户手动装的 WSL 发行版但底层还是需要 WSL2 的内核模块支持。打开管理员 PowerShell 执行wsl --update看到“已安装最新版本的 Linux 内核”之类的提示就说明 OK。如果这条命令报错也可以去微软官方文档下载 WSL2 内核更新包手动安装。我遇到过一次 Windows 10 老版本下wsl --update不受支持的情况手动下载安装包解决。3.3 安装 Claude Code CLInpm 与 native 安装对比系统虚拟化问题解决后Claude Code 本身的安装就顺畅多了。目前主流安装方式有两种我分别说下适用场景。方式一npm 全局安装最通用推荐新手先确保 Node.js 环境存在建议 18 以上版本然后以管理员身份运行npm install -g anthropic-ai/claude-code安装完成后直接在任意终端输入claude如果配置正确终端会进入交互式对话界面。这种方式的好处是升级方便npm update -g anthropic-ai/claude-code方式二PowerShell 原生安装不需要 Node.jsClaude Code 也提供了独立安装脚本运行下面的命令irm https://claude.ai/install.ps1 | iex或者用 curlcurl -fsSL https://claude.ai/install.sh | bash这个方式的优势是不依赖 Node.js 环境适合不想装一堆开发运行时的用户。但注意国内直连 claude.ai 的速度可能不稳定如果下载很慢可以稍后重试或考虑配置代理环境变量这里不做展开。3.4 验证 Claude Code 是否能识别 workspace安装好后先在一个空目录里运行claude看它能否正常进入对话。如果一切正常你可以输入个简单指令测试比如/status或者直接让它打印一句自我介绍。如果 workspace 还是有问题大概率是系统功能没重启生效或者杀毒软件拦截了虚拟化进程需要去 Windows 安全中心检查“内核隔离”和“基于虚拟化的安全”设置。我遇到过一位朋友的电脑系统功能全开了但 Windows Defender 的内核隔离功能挡了虚拟机平台导致 Claude Code 一直 failed to start workspace关掉内核隔离的“内存完整性”选项后就好了。4. VSCode 集成配置实操4.1 安装 Claude Code 扩展并绑定 CLI大多数人不会只用纯命令行在 VSCode 里跑 Claude Code 是刚需。VSCode 里使用 Claude Code 有两种主流方式一是通过官方扩展市场搜索“Claude Code”安装插件注意别装错仿冒扩展认准 Anthropic 官方的二是在 VSCode 的终端面板里直接运行claude命令。前者体验更丝滑后者更像传统终端流。官方扩展安装后在侧边栏会出现 Claude Code 面板首次使用会让你选择或登录 API 账号。登录成功后扩展会调用系统安装的 Claude Code CLI如果你前面已经 npm 装好扩展一般能自动检测到。检测不到时需要在 VSCode 设置里手动指定 claude 可执行文件的路径。Windows 下 npm 全局包的路径一般在C:\Users\你的用户名\AppData\Roaming\npm\claude.cmd在 VSCode 设置里搜索 claude找到相关配置项填上这个完整路径即可。4.2 解决 VSCode 内常见报错VSCode 里几个典型问题我按频率排个序failed to start Claude’s workspace这个在前面已经解了核心就是虚拟化功能和内核。还有一个小概率是 VSCode 本身权限不足建议用管理员身份运行 VSCode。终端中文乱码Claude Code 输出中文时偶尔会乱码这是因为 Windows 终端默认代码页和 UTF-8 冲突。在 VSCode 设置里搜索terminal.integrated.defaultProfile.windows把默认终端改成Command Prompt然后在设置 JSON 里加terminal.integrated.env.windows: { PYTHONIOENCODING: utf-8, LANG: zh_CN.UTF-8 }扩展加载后空白多半是 API 代理配置问题或网络问题。Claude Code 支持通过环境变量走代理比如set HTTPS_PROXYhttp://127.0.0.1:7890设置后重启 VSCode 再看。4.3 VSCode 和命令行模式怎么选我用下来最大的感受是VSCode 扩展适合边看代码边对话的场景。选中文案时会直接高亮引用代码片段点一下就能定位到文件位置省去来回翻终端的麻烦。而纯终端模式更适合快速小改动比如让 Claude 给某个函数加注释、分析一段报错信息不需要打开整个编辑器。如果你两个都在用一定注意别同时跑两个会话操作同一个目录下的文件——除非你想体验“两方同时改文件互相覆盖”的刺激。我在一次重构中就因为终端和 VSCode 各开了一个会话改同一个文件最后 git diff 出来一堆无意义的冲突白白浪费了半小时。5. 实战案例从零到 Claude Code 正常运行的完整记录5.1 一台“干净” Windows 11 机器的完整配置流程为了让你有更直观的参照我拿一台刚装好 Windows 11 23H2、什么都没配置过的电脑完整走一遍流程。第一步检查 BIOS 虚拟化开机进 BIOS确认虚拟化开启进系统后任务管理器里显示“虚拟化: 已启用”。第二步以管理员身份打开 PowerShell依次执行dism /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart dism /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism /online /enable-feature /featurename:HypervisorPlatform /all /norestart wsl --update重启电脑。第三步安装 Node.js 和 Claude Code我直接装 Node 20 LTS然后npm install -g anthropic-ai/claude-code claude --version此时如果没有报错说明 CLI 装好了。第四步运行 claude 测试在任意空文件夹里输入claude首次运行会提示 workspace 初始化等十几秒进入对话界面就算成功。整个过程大概十五分钟最容易卡住的就是第二步后忘了重启导致第四步一直报 workspace 错误。你如果遇到类似情况回头第一步里逐个确认功能状态就对了。5.2 遇到 persistent 错误的完整排查清单我将所有可能踩的坑整理成一张速查表便于你逐个排查。症状可能原因解决办法virtual machine platform相关提示系统功能未开启或未生效开启后重启验证 State 为 Enabledfailed to start Claudes workspace虚拟化被安全软件拦截或 BIOS 关闭检查 BIOS、检查内核隔离设置终端执行claude提示不是内部命令npm 全局路径未加入 PATH手动添加 npm 路径到系统环境变量网络请求超时或无法连接网络直连不稳定配置 HTTPS_PROXY 环境变量VSCode 扩展找不到 CLI扩展未识别 npm 路径在 VSCode 设置中指定 claude.cmd 完整路径中文对话乱码代码页不匹配设置 UTF-8 环境变量这张表看起来简单但每一条都是我实际遇到或者帮别人排查过的。尤其第六个“中文乱码”我一开始还以为是 Claude Code 没优化好最后发现只是 Windows 终端编码问题调完设置后一切正常。5.3 几个高级用法和参数配置Claude Code 装好跑通之后有几个配置值得分享一下能明显提升体验。输出流模式运行claude --output-format stream-json可以让输出变成流式 JSON 格式适合做自动化脚本对接。比如我想把 Claude 的回答接进内部通知机器人就用的这个参数。指定模型在对话中可以用--model参数临时切模型或者直接在配置文件里设置默认模型。Claude Code 支持 Claude Opus 和 Claude Sonnet 等不同能力档位的模型简单任务用 Sonnet 更快复杂架构重构用 Opus 更稳妥。代码权限设置在工作区根目录创建一个.claude/settings.json文件可以控制 Claude 能做什么、不能做什么。比如{ permissions: { allow: [Bash(*),Read(*),Edit(*)], deny: [Read(/etc/*)] } }这样 Claude 可以执行命令、修改文件但不能读 /etc 下的敏感配置。有点类似给它上了一把“权限锁”。如果你做团队协作还可以在项目里维护一个CLAUDE.md文件里面写清楚项目的代码规范、目录结构、常用命令Claude Code 会自动读取这个文件来适配当前项目的开发风格。我用下来感觉这个文件的作用好比给新来的人发了一份老员工整理好的项目手册Claude 的理解准确率和代码风格贴近程度能提升一个台阶。6. 常见报错全收录与独家避坑心得6.1 failed to start workspace 深度排查这是目前我见过最多人提问的报错。如果你按照前面的步骤做了之后问题依旧请不要灰心大概率是下面三种情况之一第一种安装完功能后没有“彻底”重启。注意这里说的彻底重启是关机再开机不是“重启”这个选项。在某些 Windows 版本中“重启”确实可以应用功能更改但个别驱动的虚拟化模块在“快速启动”机制下没能重新加载所以如果你开了 Windows 快速启动最好先彻底关机再开机。第二种第三方优化软件把虚拟化功能禁用了。比如某些“系统优化工具”会默认关闭 Hypervisor 相关的服务来“提升性能”。检查一下服务和驱动在运行窗口输入services.msc找HV Host Service确保状态是“正在运行”启动类型是“手动”。第三种Windows 沙盒或 内核隔离与应用冲突。我之前帮朋友排查时发现某个安全软件为了加强防护把虚拟化相关的权限全锁了。解决办法是去 Windows 安全中心的“设备安全性”里点击“内核隔离详细信息”关闭“内存完整性”再重启。不要怕平时用它带来的性能损失几乎感觉不到但兼容性能大幅提升。6.2 其他高频问题及处理记录问题一claude 命令找不到。如果你用 npm 安装后新开一个终端提示“claude 不是内部或外部命令”说明 npm 全局路径没在系统 PATH 里。手动把C:\Users\你的用户名\AppData\Roaming\npm加到 PATH再重开终端。问题二安装时卡在某个百分比。多半是网络问题。你可以先设置代理环境变量再安装注意仅设置安装期间的代理装完可以取消。问题三Claude Code 的回答速度很慢。有可能是模型负载高导致排队。这种情况大概率不是你电脑的问题你可以稍等几分钟再试或者切到速度更快的 Sonnet 模型。6.3 经验之谈避坑与性能优化技巧最后分享几个在多次实践中沉淀下来的经验。第一建议在 Windows 功能里勾选“虚拟机平台”和“Windows 虚拟机监控程序平台”时一并把“Linux 子系统”那个选项也勾上。即使你暂时不用 WSL后面用起来可以省一次重启。同时wsl --update这个操作强烈建议做一次能让底层内核和 Claude workspace 的兼容性更好。第二如果你电脑配置一般建议在 Claude Code 配置里限制并发命令的执行数量防止它同时跑多个测试导致电脑卡死。在settings.json里添加{ maxConcurrentRequests: 2 }第三Windows 上有些安全软件会扫描 CLI 工具每次运行时的临时文件导致性能下降严重。如果条件允许把 Claude Code 的缓存目录加入白名单。具体路径可以通过命令查看claude -debug调试模式下会输出缓存目录把那个目录加进杀软排除名单你会发现启动速度快不少。第四善用/memory命令管理上下文。Claude Code 会长期记住你告诉它的约定但如果你改了工作目录或团队规范记得更新记忆内容。我在实际使用中发现Claude Code 在 Windows 上最大的门槛其实不在 Claude 本身而在于微软这层虚拟化矩阵的配置琐碎。只要把 VirtualMachinePlatform 和 HypervisorPlatform 这两个坑填平后续安装和集成基本一路绿灯。希望这份记录能帮你少走两步弯路。如果你还碰到别的幺蛾子欢迎在评论区把报错信息贴出来我看到能帮的一定帮。
最近在 Windows 上折腾 Claude Code相信不少人和我一样被 “Claude’s workspace requires the virtual machine platform on Windows. Enable…” 这段提示卡住了好一阵子。我一开始也以为是 Claude Code 安装包的问题重装了好几遍结果错误依旧后来才搞清楚是 Windows 系统底层的虚拟机平台没打开。这篇文章就把我完整的排查和解决过程记录下来从报错原因、底层原理到具体操作、VSCode 集成配置一次性说清楚给同样被卡住的朋友一份可以直接照做的方案。1. 认识 Claude Code 与底层工作区环境1.1 Claude Code 是什么解决什么问题Claude Code 是 Anthropic 官方推出的终端编程助手它不是一个简单的聊天窗口而是能直接运行在命令行里、读取你项目目录、修改文件、执行测试命令的 Agent 型工具。你可以把它理解为团队里多了一个随叫随到的高级程序员你跟它说“帮我分析一下这个仓库的代码结构”它会真的在终端里遍历文件、输出分析报告你说“给这段函数补上单元测试”它不只是给你贴代码而是直接把测试文件写到项目目录里。这种交互模式和传统“复制粘贴型”AI 工具有本质区别。但在实际使用中Claude Code 的 Windows 版依赖一个特殊的运行环境——Claude’s Workspace——它本质上是构建在 Windows 虚拟机平台Virtual Machine Platform之上的隔离沙箱。这个沙箱负责托管 Claude Code 运行所需的轻量级 Linux 子系统让 CLI 工具链在 Windows 上运行时拥有和 Linux 一致的兼容性。很多 Windows 用户在安装后第一次运行 claude 命令时终端可能报错提示 “Claude’s workspace requires the virtual machine platform on Windows. Enable the Windows Hypervisor Platform and Virtual Machine Platform features.” 或者在 VSCode 里启动 Claude Code 扩展时直接弹出 “failed to start Claude’s workspace” 的报错弹窗。这两类提示其实都是同一个根源系统没有完整开启虚拟化相关功能。1.2 为什么 Windows 上必须开虚拟机平台Windows 上的 Claude Code 工作区不是用 WSL 传统发行版实现的而是依赖 Windows Hypervisor PlatformWHP和 Virtual Machine PlatformVMP这两个系统功能来创建轻量级虚拟机。打个比方Claude 的 workspace 相当于在 Windows 里搭建了一个隔离的“运行舱”舱内跑了 Linux 内核模块而这些功能必须由宿主机也就是你的 Windows 系统提供虚拟化底层能力。如果这两个系统功能没启用或者 BIOS 层面的虚拟化被关闭那 workspace 就起不来自然就会出现上面那两类报错。更关键的是很多教程只告诉你要装 WSL2却没告诉你 Claude Code 需要的是比单纯 WSL2 更底层的虚拟机平台。如果你之前只是装了 WSL2 但没有打开“虚拟机平台”功能Claude Code 启动时依然检测不到虚拟化能力照样报错。这也是为什么很多人明明 WSL 好好的一跑 Claude Code 就翻车。2. 排查报错根源从现象到系统底层2.1 从报错文案反推系统状态当你在终端里输入claude然后看到类似下面的信息时先别急着卸载重装Claudes workspace requires the virtual machine platform on Windows. Enable the Virtual Machine Platform and Windows Hypervisor Platform features and try again.或者你在 VSCode 的 Claude Code 插件面板里看到Failed to start Claudes workspace这两种提示其实已经说得很明白系统缺少两个关键功能。但很多人不理解的是明明 Windows 11 默认已经开启了 Hyper-V 相关能力为什么还提示缺失这是因为 Windows 系统为了兼顾性能默认并不会完整开启所有虚拟化功能尤其是“虚拟机平台”和“Windows 虚拟机监控程序平台”这两个。它们属于“可选功能”需要手动开启。2.2 检查 CPU 虚拟化是否真的开启还有一个容易忽略的点即使系统功能全部打开如果 CPU 的虚拟化在 BIOS 中被关闭一切等于白搭。检查方法很简单按Ctrl Shift Esc打开任务管理器切到“性能”选项卡点左下角的“CPU”看右下角“虚拟化”一栏。显示“已启用”就正常显示“已禁用”或“未开启”就需要进入 BIOS通常开机按 Del、F2 或 F10找到类似 Intel Virtualization Technology 或 SVM Mode 的选项并打开。我试过一台较早的 i5 笔记本Windows 11 下功能都开了但 BIOS 里 VT-x 被误关了Claude Code 一样报 workspace 无法启动。这一点很多网上教程没有提到属于最容易忽略的坑。如果你在系统日志里看到Hyper-V相关错误八成和这一步有关。2.3 快速判定当前虚拟化状态除了任务管理器你还可以用命令行快速判断。以管理员身份打开 PowerShell运行systeminfo在输出中找“Hyper-V 要求”这一段。如果看到Hyper-V 要求: 已检测到虚拟机监控程序。将不显示 Hyper-V 所需的功能。说明虚拟化已经可用。如果看到类似“固件中已启用虚拟化: 是”说明 BIOS 层面 OK如果“固件中已启用虚拟化: 否”就按上面说的去 BIOS 打开。还有另一种常见情况系统显示“虚拟机监控程序未运行”但固件虚拟化是启用的那大概率就是 Windows 可选功能没开齐正好对上我们接下来的操作步骤。3. 完整修复步骤从功能开启到 Claude 正常跑起来3.1 开启 Windows 虚拟机平台与 hypervisor 平台我先说结论Claude Code 在 Windows 上成功运行至少需要四个系统组件协同工作Virtual Machine Platform虚拟机平台Windows Hypervisor PlatformWindows 虚拟机监控程序平台Windows Subsystem for Linux可选但强烈建议装虚拟机监控程序Hyper-V 底层具体开启路径有两种我分别说。方法一图形界面开启按Win R输入optionalfeatures回车打开“Windows 功能”窗口。依次勾选“虚拟机平台”“Windows 虚拟机监控程序平台”“适用于 Linux 的 Windows 子系统”如果你想顺带使用 WSL“虚拟机监控程序平台”有些系统版本显示为“Hyper-V”注意如果你平时不用 Hyper-V 管理工具不要勾选“Hyper-V”完整项只勾上面这几个轻量级功能即可。完整 Hyper-V 会接管整个系统的虚拟化层有时候和第三方虚拟机软件如 VirtualBox、VMware冲突反而会带来别的麻烦。点击“确定”系统会提示重启保存好手头的工作再重启。方法二命令行一键开启推荐省事以管理员身份打开 PowerShell逐条执行以下命令dism /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart dism /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism /online /enable-feature /featurename:HypervisorPlatform /all /norestart如果第三条提示找不到功能名可以换成dism /online /enable-feature /featurename:Windows-Hypervisor-Platform /all /norestart全部执行完后重启电脑。3.2 验证功能是否真正生效重启后别急着跑 Claude Code先用命令行验证一下功能是否真的打开了。在 PowerShell 里执行Get-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform看输出里的State是否为Enabled。同理检查HypervisorPlatform。两个都显示 Enabled 之后再继续下一步省得又白折腾一轮。另外如果你之前从来没有安装过 WSL2 内核建议顺手更新一下。虽然 Claude Code 自带 workspace 不强制依赖用户手动装的 WSL 发行版但底层还是需要 WSL2 的内核模块支持。打开管理员 PowerShell 执行wsl --update看到“已安装最新版本的 Linux 内核”之类的提示就说明 OK。如果这条命令报错也可以去微软官方文档下载 WSL2 内核更新包手动安装。我遇到过一次 Windows 10 老版本下wsl --update不受支持的情况手动下载安装包解决。3.3 安装 Claude Code CLInpm 与 native 安装对比系统虚拟化问题解决后Claude Code 本身的安装就顺畅多了。目前主流安装方式有两种我分别说下适用场景。方式一npm 全局安装最通用推荐新手先确保 Node.js 环境存在建议 18 以上版本然后以管理员身份运行npm install -g anthropic-ai/claude-code安装完成后直接在任意终端输入claude如果配置正确终端会进入交互式对话界面。这种方式的好处是升级方便npm update -g anthropic-ai/claude-code方式二PowerShell 原生安装不需要 Node.jsClaude Code 也提供了独立安装脚本运行下面的命令irm https://claude.ai/install.ps1 | iex或者用 curlcurl -fsSL https://claude.ai/install.sh | bash这个方式的优势是不依赖 Node.js 环境适合不想装一堆开发运行时的用户。但注意国内直连 claude.ai 的速度可能不稳定如果下载很慢可以稍后重试或考虑配置代理环境变量这里不做展开。3.4 验证 Claude Code 是否能识别 workspace安装好后先在一个空目录里运行claude看它能否正常进入对话。如果一切正常你可以输入个简单指令测试比如/status或者直接让它打印一句自我介绍。如果 workspace 还是有问题大概率是系统功能没重启生效或者杀毒软件拦截了虚拟化进程需要去 Windows 安全中心检查“内核隔离”和“基于虚拟化的安全”设置。我遇到过一位朋友的电脑系统功能全开了但 Windows Defender 的内核隔离功能挡了虚拟机平台导致 Claude Code 一直 failed to start workspace关掉内核隔离的“内存完整性”选项后就好了。4. VSCode 集成配置实操4.1 安装 Claude Code 扩展并绑定 CLI大多数人不会只用纯命令行在 VSCode 里跑 Claude Code 是刚需。VSCode 里使用 Claude Code 有两种主流方式一是通过官方扩展市场搜索“Claude Code”安装插件注意别装错仿冒扩展认准 Anthropic 官方的二是在 VSCode 的终端面板里直接运行claude命令。前者体验更丝滑后者更像传统终端流。官方扩展安装后在侧边栏会出现 Claude Code 面板首次使用会让你选择或登录 API 账号。登录成功后扩展会调用系统安装的 Claude Code CLI如果你前面已经 npm 装好扩展一般能自动检测到。检测不到时需要在 VSCode 设置里手动指定 claude 可执行文件的路径。Windows 下 npm 全局包的路径一般在C:\Users\你的用户名\AppData\Roaming\npm\claude.cmd在 VSCode 设置里搜索 claude找到相关配置项填上这个完整路径即可。4.2 解决 VSCode 内常见报错VSCode 里几个典型问题我按频率排个序failed to start Claude’s workspace这个在前面已经解了核心就是虚拟化功能和内核。还有一个小概率是 VSCode 本身权限不足建议用管理员身份运行 VSCode。终端中文乱码Claude Code 输出中文时偶尔会乱码这是因为 Windows 终端默认代码页和 UTF-8 冲突。在 VSCode 设置里搜索terminal.integrated.defaultProfile.windows把默认终端改成Command Prompt然后在设置 JSON 里加terminal.integrated.env.windows: { PYTHONIOENCODING: utf-8, LANG: zh_CN.UTF-8 }扩展加载后空白多半是 API 代理配置问题或网络问题。Claude Code 支持通过环境变量走代理比如set HTTPS_PROXYhttp://127.0.0.1:7890设置后重启 VSCode 再看。4.3 VSCode 和命令行模式怎么选我用下来最大的感受是VSCode 扩展适合边看代码边对话的场景。选中文案时会直接高亮引用代码片段点一下就能定位到文件位置省去来回翻终端的麻烦。而纯终端模式更适合快速小改动比如让 Claude 给某个函数加注释、分析一段报错信息不需要打开整个编辑器。如果你两个都在用一定注意别同时跑两个会话操作同一个目录下的文件——除非你想体验“两方同时改文件互相覆盖”的刺激。我在一次重构中就因为终端和 VSCode 各开了一个会话改同一个文件最后 git diff 出来一堆无意义的冲突白白浪费了半小时。5. 实战案例从零到 Claude Code 正常运行的完整记录5.1 一台“干净” Windows 11 机器的完整配置流程为了让你有更直观的参照我拿一台刚装好 Windows 11 23H2、什么都没配置过的电脑完整走一遍流程。第一步检查 BIOS 虚拟化开机进 BIOS确认虚拟化开启进系统后任务管理器里显示“虚拟化: 已启用”。第二步以管理员身份打开 PowerShell依次执行dism /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart dism /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism /online /enable-feature /featurename:HypervisorPlatform /all /norestart wsl --update重启电脑。第三步安装 Node.js 和 Claude Code我直接装 Node 20 LTS然后npm install -g anthropic-ai/claude-code claude --version此时如果没有报错说明 CLI 装好了。第四步运行 claude 测试在任意空文件夹里输入claude首次运行会提示 workspace 初始化等十几秒进入对话界面就算成功。整个过程大概十五分钟最容易卡住的就是第二步后忘了重启导致第四步一直报 workspace 错误。你如果遇到类似情况回头第一步里逐个确认功能状态就对了。5.2 遇到 persistent 错误的完整排查清单我将所有可能踩的坑整理成一张速查表便于你逐个排查。症状可能原因解决办法virtual machine platform相关提示系统功能未开启或未生效开启后重启验证 State 为 Enabledfailed to start Claudes workspace虚拟化被安全软件拦截或 BIOS 关闭检查 BIOS、检查内核隔离设置终端执行claude提示不是内部命令npm 全局路径未加入 PATH手动添加 npm 路径到系统环境变量网络请求超时或无法连接网络直连不稳定配置 HTTPS_PROXY 环境变量VSCode 扩展找不到 CLI扩展未识别 npm 路径在 VSCode 设置中指定 claude.cmd 完整路径中文对话乱码代码页不匹配设置 UTF-8 环境变量这张表看起来简单但每一条都是我实际遇到或者帮别人排查过的。尤其第六个“中文乱码”我一开始还以为是 Claude Code 没优化好最后发现只是 Windows 终端编码问题调完设置后一切正常。5.3 几个高级用法和参数配置Claude Code 装好跑通之后有几个配置值得分享一下能明显提升体验。输出流模式运行claude --output-format stream-json可以让输出变成流式 JSON 格式适合做自动化脚本对接。比如我想把 Claude 的回答接进内部通知机器人就用的这个参数。指定模型在对话中可以用--model参数临时切模型或者直接在配置文件里设置默认模型。Claude Code 支持 Claude Opus 和 Claude Sonnet 等不同能力档位的模型简单任务用 Sonnet 更快复杂架构重构用 Opus 更稳妥。代码权限设置在工作区根目录创建一个.claude/settings.json文件可以控制 Claude 能做什么、不能做什么。比如{ permissions: { allow: [Bash(*),Read(*),Edit(*)], deny: [Read(/etc/*)] } }这样 Claude 可以执行命令、修改文件但不能读 /etc 下的敏感配置。有点类似给它上了一把“权限锁”。如果你做团队协作还可以在项目里维护一个CLAUDE.md文件里面写清楚项目的代码规范、目录结构、常用命令Claude Code 会自动读取这个文件来适配当前项目的开发风格。我用下来感觉这个文件的作用好比给新来的人发了一份老员工整理好的项目手册Claude 的理解准确率和代码风格贴近程度能提升一个台阶。6. 常见报错全收录与独家避坑心得6.1 failed to start workspace 深度排查这是目前我见过最多人提问的报错。如果你按照前面的步骤做了之后问题依旧请不要灰心大概率是下面三种情况之一第一种安装完功能后没有“彻底”重启。注意这里说的彻底重启是关机再开机不是“重启”这个选项。在某些 Windows 版本中“重启”确实可以应用功能更改但个别驱动的虚拟化模块在“快速启动”机制下没能重新加载所以如果你开了 Windows 快速启动最好先彻底关机再开机。第二种第三方优化软件把虚拟化功能禁用了。比如某些“系统优化工具”会默认关闭 Hypervisor 相关的服务来“提升性能”。检查一下服务和驱动在运行窗口输入services.msc找HV Host Service确保状态是“正在运行”启动类型是“手动”。第三种Windows 沙盒或 内核隔离与应用冲突。我之前帮朋友排查时发现某个安全软件为了加强防护把虚拟化相关的权限全锁了。解决办法是去 Windows 安全中心的“设备安全性”里点击“内核隔离详细信息”关闭“内存完整性”再重启。不要怕平时用它带来的性能损失几乎感觉不到但兼容性能大幅提升。6.2 其他高频问题及处理记录问题一claude 命令找不到。如果你用 npm 安装后新开一个终端提示“claude 不是内部或外部命令”说明 npm 全局路径没在系统 PATH 里。手动把C:\Users\你的用户名\AppData\Roaming\npm加到 PATH再重开终端。问题二安装时卡在某个百分比。多半是网络问题。你可以先设置代理环境变量再安装注意仅设置安装期间的代理装完可以取消。问题三Claude Code 的回答速度很慢。有可能是模型负载高导致排队。这种情况大概率不是你电脑的问题你可以稍等几分钟再试或者切到速度更快的 Sonnet 模型。6.3 经验之谈避坑与性能优化技巧最后分享几个在多次实践中沉淀下来的经验。第一建议在 Windows 功能里勾选“虚拟机平台”和“Windows 虚拟机监控程序平台”时一并把“Linux 子系统”那个选项也勾上。即使你暂时不用 WSL后面用起来可以省一次重启。同时wsl --update这个操作强烈建议做一次能让底层内核和 Claude workspace 的兼容性更好。第二如果你电脑配置一般建议在 Claude Code 配置里限制并发命令的执行数量防止它同时跑多个测试导致电脑卡死。在settings.json里添加{ maxConcurrentRequests: 2 }第三Windows 上有些安全软件会扫描 CLI 工具每次运行时的临时文件导致性能下降严重。如果条件允许把 Claude Code 的缓存目录加入白名单。具体路径可以通过命令查看claude -debug调试模式下会输出缓存目录把那个目录加进杀软排除名单你会发现启动速度快不少。第四善用/memory命令管理上下文。Claude Code 会长期记住你告诉它的约定但如果你改了工作目录或团队规范记得更新记忆内容。我在实际使用中发现Claude Code 在 Windows 上最大的门槛其实不在 Claude 本身而在于微软这层虚拟化矩阵的配置琐碎。只要把 VirtualMachinePlatform 和 HypervisorPlatform 这两个坑填平后续安装和集成基本一路绿灯。希望这份记录能帮你少走两步弯路。如果你还碰到别的幺蛾子欢迎在评论区把报错信息贴出来我看到能帮的一定帮。
