在 Windows 11 上从零装好 Carapace BIN：一次真实操作记录

上周我把主力机从 Win10 升到了 Win11 24H2，结果发现原来的 PowerShell 自动补全脚本全废了------不是报错就是卡顿。折腾了两天，最后用 Carapace BIN 解决了问题。这篇记录一下我实际踩过的坑和最终可行的流程，全部基于我手头这台 ThinkPad X1 Carbon（Intel i7-1365U，16GB RAM）的真实操作。

先确认系统状态，别急着装

Win11 的终端环境比 Win10 更"干净"，但默认 PowerShell 5.1 和 Windows Terminal 的配置路径容易混淆。我第一步是检查版本和策略：

powershell 复制代码

# 在 PowerShell 5.1 或 7.x 中执行
$PSVersionTable.PSVersion.ToString()
Get-ExecutionPolicy -List | Format-Table -AutoSize

我遇到的情况是：系统默认 Restricted 策略，导致脚本一律无法运行。如果你也是这样，先以管理员身份打开 PowerShell，执行：

powershell 复制代码

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

注意：不要用 Unrestricted，那会绕过签名检查，后续装模块时容易混入不明来源的脚本。改完策略后，我用 winget --version 确认了包管理器可用------Win11 自带 winget，但版本太老的话装 Carapace 会报错。升级命令：

powershell 复制代码

winget upgrade --id Microsoft.DesktopAppInstaller --source winget --accept-source-agreements

安装 Carapace BIN 的两种路径

我最初尝试直接用 winget install，但发现仓库里的版本不是最新的 BIN 包。后来查了文档，Carapace BIN 其实是预编译的二进制发行版，不需要 Go 环境。最稳妥的方式是从 GitVaults 下载。

我实际执行的是：

powershell 复制代码

# 先建一个专用目录，避免污染用户目录
New-Item -ItemType Directory -Path "$env:LOCALAPPDATA\carapace" -Force
Set-Location "$env:LOCALAPPDATA\carapace"

# 用 curl 下载（Win11 自带 curl.exe）
curl.exe -L -o carapace-bin.zip "https://gitvaults.com/download/carapace-bin/"

注意：这里我一开始直接用 Invoke-WebRequest，结果下载速度极慢（可能因为 TLS 协商问题），换 curl.exe 后秒下。下载完成后解压：

powershell 复制代码

Expand-Archive -Path carapace-bin.zip -DestinationPath .\bin -Force

解压后检查目录结构，确保 carapace.exe 在 bin 下。我遇到过 zip 里嵌套一层文件夹的情况，所以用 Get-ChildItem -Recurse -Filter carapace.exe 定位一下。

配置 PowerShell 补全，解决"命令找不到"的坑

装好二进制只是第一步，关键是把补全脚本挂到 PowerShell 的 profile 里。我的 profile 路径是 $PROFILE，但 Win11 上如果之前装过 oh-my-posh，profile 里可能已经有冲突内容。

我先备份再编辑：

powershell 复制代码

if (Test-Path $PROFILE) { Copy-Item $PROFILE "$PROFILE.bak" }
notepad $PROFILE

在 profile 末尾追加：

powershell 复制代码

# Carapace BIN 初始化
$env:CARAPACE_BIN = "$env:LOCALAPPDATA\carapace\bin\carapace.exe"
& $env:CARAPACE_BIN --init powershell | Out-String | Invoke-Expression

这里有个关键坑：如果直接写 carapace --init powershell，PowerShell 可能找不到命令，因为环境变量没生效。所以我用绝对路径。保存后，重新打开终端，执行 git co<tab> 测试补全------正常会弹出分支列表。

我遇到的失败场景是：执行 Invoke-Expression 时报"无法加载文件，因为在此系统上禁止运行脚本"。原因是我刚才改的 ExecutionPolicy 只对 CurrentUser 生效，但 profile 脚本的加载可能被组策略覆盖。解决方法是检查：

powershell 复制代码

Get-ExecutionPolicy -List | Select-Object -First 5

如果 LocalMachine 还是 Restricted，用管理员 PowerShell 再执行一次 Set-ExecutionPolicy RemoteSigned -Scope LocalMachine。

边界情况：Windows Terminal 和 VS Code 内嵌终端

在 Windows Terminal 里，默认会加载 profile，补全正常。但在 VS Code 的内嵌终端里，如果 VS Code 是以管理员权限启动的，而你的 PowerShell 是普通权限，profile 加载路径会不同。我实测发现，VS Code 的终端会读取 $PROFILE，但环境变量 CARAPACE_BIN 可能没继承。

解决办法是在 VS Code 的 settings.json 里给终端加一条环境变量：

json 复制代码

"terminal.integrated.env.windows": {
    "CARAPACE_BIN": "C:\\Users\\你的用户名\\AppData\\Local\\carapace\\bin\\carapace.exe"
}

改完重启 VS Code 终端，补全才生效。这个坑我查了半小时才确认。

一点说明

以上流程完全基于我个人的 Win11 环境，不同版本的 Windows 预览版或精简版可能行为有差异。如果你在安装或配置过程中遇到其他坑------比如补全命令延迟、profile 被覆盖、或者和 PSReadLine 冲突------欢迎在评论区补充你的环境信息和解决步骤。我特别想知道有没有人在 ARM 版 Win11 上跑通的，因为我自己没有那类设备可测。

在 Windows 11 上从零装好 Carapace BIN：一次真实操作记录