PSCompletions + PSReadLine：打造更顺手的 PowerShell Tab 补全体验

如果你经常在 PowerShell 里敲命令，大概经历过这些场景：输错一个字母只能重敲、补全菜单超出屏幕直接失效、git 的分支和 npm 的脚本永远补不出来。PowerShell 自带的 Tab 补全能用，但离“好用”还有一段距离。

PSCompletions 是一个补全管理器，基于 Rust + Lua 构建，为 PowerShell 带来更完善的 Tab 补全菜单。它和 PSReadLine 配合，可以显著改善命令行的补全体验。下面是一份从零开始的配置指南。

先理解一个关键点

PSCompletions 的官方文档只规定了三步核心流程：直接 Import-Module PSCompletions、运行 psc update 同步补全库、用 psc add 启用具体补全。它本身不要求你配置 PSReadLine。

本文涉及的 PSReadLine 配置（历史搜索、行内预测等）是补充增强，让补全体验更完整，并非 PSCompletions 的硬性依赖。如果你只想快速用上 PSCompletions，看完安装部分就可以直接跳到最后。

安装 PSCompletions

假设你已经装好 Scoop 并配置了基础 bucket。官方推荐的 Scoop 途径是通过 abyss bucket 安装：

scoop bucket add abyss https://github.com/abgox/abyss
scoop install abyss/abgox.PSCompletions

安装完成后，Scoop 会自动完成三件事：把模块链接到 Scoop 的 modules 目录、将 modules 目录写入用户级 PSModulePath、建立持久化数据目录。

注意：不要同时安装 extras bucket 的 pscompletions 和 abyss 的 abgox.PSCompletions，两者提供同一个模块，会冲突。选一个即可。

配置 `$PROFILE`

核心原则：直接导入，不要包装

这是 PSCompletions 最关键的约束：Import-Module PSCompletions 必须直接调用。

以下写法都会导致模块失效：

# ❌ 包在函数里
function Load-Module { Import-Module PSCompletions }
Load-Module

# ❌ 用变量传路径
$path = "D:\scoop\modules\PSCompletions\PSCompletions.psd1"
Import-Module $path

# ✅ 只有这一种是正确的
Import-Module PSCompletions

官方 FAQ 明确说明了这一点，嵌套调用或相对导入顺序不当都会出问题。

完整的 profile 配置

打开 $PROFILE（PowerShell 7 路径通常是 Documents\PowerShell\Microsoft.PowerShell_profile.ps1），加入以下内容：

# ==================== PSReadLine 增强 ====================
# PSCompletions 的补全菜单构建在 PSReadLine 之上，先配置基础。

# 行内历史预测：输入时显示灰色建议，右方向键接受。
# 需要终端支持虚拟终端（Windows Terminal / VS Code 终端均可）。
try {
    Set-PSReadLineOption -PredictionSource HistoryAndPlugin
    # 保持 InlineView；ListView 会与 PSCompletions 的 Tab 菜单抢屏幕空间
    Set-PSReadLineOption -PredictionViewStyle InlineView
}
catch { }

# 关闭 Tab 触发补全菜单时的提示音
Set-PSReadLineOption -BellStyle None

# 上下键按前缀搜索历史（空前缀时等同于逐条翻历史）
Set-PSReadLineKeyHandler -Key UpArrow -Function HistorySearchBackward
Set-PSReadLineKeyHandler -Key DownArrow -Function HistorySearchForward

# ==================== PSCompletions ====================
# 官方要求：必须直接调用，不要包在函数或脚本块里。
Import-Module PSCompletions

关于 `try/catch` 的说明

预测功能在不支持虚拟终端的终端里会抛异常。$Host.UI.SupportsVirtualTerminal 这个判据不太可靠——实测它可能返回 True 但 PSReadLine 仍然报错。所以直接用 try/catch 包住，以 PSReadLine 自己的行为为准。

同步与启用补全

配置好 profile 后，新开一个终端（PSModulePath 的变更需要新会话才能生效），然后执行：

# 同步内置补全库（首次必做）
psc update

# 启用单个补全
psc add git

# 查看已启用的补全
psc list

批量启用：按实际安装的工具匹配

如果你不想盲目全装，只启用本机 PATH 里真实存在的命令对应的补全，可以用这段脚本：

$idx   = Get-Content "D:\scoop\persist\pscompletions\data\temp\completions.json" -Raw | ConvertFrom-Json
$names = $idx.update.PSObject.Properties.Name
$target = @($names | Where-Object { 
    (Get-Command $_ -ErrorAction SilentlyContinue) -and $_ -ne "psc" -and $_ -ne "git" 
})
psc add @target

PSCompletions 内置补全库覆盖数百个常用命令，按需启用是最省心的做法。

补全菜单的用法

过滤语法

菜单默认使用通配匹配（不区分大小写）：

输入	效果
`co`	匹配包含 `co` 的项，如 `config`、`completion`
`a*d`	`*` 匹配任意字符，匹配 `add`、`and`
`^add`	只匹配以 `add` 开头的项
`*vscode`	单个 `*` 开头切换为子序列匹配，匹配 `Visual Studio Code`

如果想默认使用子序列匹配：

psc config menu filter_mode subsequence

常用按键

操作	按键
选中上一个/下一个	`Up`/`Down`，或 `Tab` 循环
选用当前项	`Space` 或 `Enter`
退出菜单	`Esc` 或 `Ctrl+c`

菜单支持鼠标滚轮浏览、单击选中、双击选用。

路径补全

用路径标识符显式获取路径补全：/、./、../、~/、\、.\ 等。

验证配置

新开终端后，执行以下命令确认一切正常：

# 模块加载 + 补全数量
Get-Module PSCompletions | Select-Object -Last 1 -ExpandProperty Version
(psc list | Measure-Object).Count

# PSReadLine 设置
Get-PSReadLineOption | Select-Object PredictionSource, PredictionViewStyle, BellStyle

# Tab 键应被 PSCompletions 接管，显示为 CustomAction
Get-PSReadLineKeyHandler | Where-Object { $_.Key -eq "Tab" } | Select-Object Key, Function

预期看到：

PredictionSource    : HistoryAndPlugin
PredictionViewStyle : InlineView
BellStyle           : None

Key Function
--- --------
Tab CustomAction

最后

PSCompletions 的价值在于它把“补全”这件事从零散的工具脚本提升到了统一管理的层面——动态补全（git 分支、npm 脚本按需生成）、滚动菜单、通配符过滤、按历史排序，这些都是原生 Tab 补全缺失的能力。

配合 PSReadLine 的历史搜索和行内预测，整个命令行交互的流畅度会上一个台阶。

原文 https://blog.csdn.net/2301_79518550/article/details/166012228