$PSBoundParameters 是高级函数中存储显式传入参数名及值的哈希表，仅含调用时指定的参数，不含默认值、未传参数或管道输入；需用 param() 和 [CmdletBinding()] 定义才有效。
$psboundparameters 是 powershell 中一个自动变量，它在函数或脚本块（如 param 块定义的高级函数）中可用，用于保存**实际被调用时传入的参数名及其对应值**的哈希表（[hashtable]）。它只包含用户显式指定的参数，不包括默认值、未传入的参数，也不包含通过管道传入的对象（除非该参数明确支持管道绑定）。
确保脚本/函数支持高级函数特性
要使用 $PSBoundParameters，脚本或函数必须是“高级函数”（advanced function），即包含 param() 块，并建议加上 [CmdletBinding()] 属性。否则该变量为空或不可用。
✅ 正确写法示例：
[CmdletBinding()]
param(
[string]$Name,
[int]$Age,
[switch]$VerboseOutput
)
Write-Host "传入的参数：" -ForegroundColor Green
$PSBoundParameters.GetEnumerator() | ForEach-Object { "$($_.Key) = $($_.Value)" } | Write-Host
常见用途与实用技巧
$PSBoundParameters 最常用于以下场景：
Windows TTS (WSL2)
下载
在 Windows 11 上"直接发声"的 TTS（从 WSL2/TUI 调用 powershell.exe + System.Speech）。适用于用户说"说出来/读出来/语音播报/用TTS"，或反馈"没声音/tts 生成的 mp3 是空的/播不出来"，以及需要中文语音但 OpenClaw 内置 tts 不可用时。
- 日志或调试：快速查看哪些参数被调用者实际传入，尤其适合多参数、可选参数较多的工具函数。
-
条件逻辑判断：比如“只有当
-Path和-Filter同时提供时才执行某操作”——可检查$PSBoundParameters.ContainsKey('Path') -and $PSBoundParameters.ContainsKey('Filter')。 -
参数透传（splatting）：将当前函数接收到的参数原样转发给另一个 cmdlet，例如：
Get-ChildItem @PSBoundParameters（注意：需确保参数名兼容）。 -
排除某个参数后转发：如想把除
-WhatIf外的所有参数传给内部命令，可先复制哈希表再移除：$params = $PSBoundParameters.Clone(); $params.Remove('WhatIf')。
注意事项与易错点
使用时需注意几个关键细节：
-
$PSBoundParameters不包含未传值的参数，即使它们有默认值（例如[string]$LogPath = "C:\log.txt"，但调用时没写-LogPath，则该键不会出现在哈希表中）。 - 开关参数（
[switch]）如果被指定（如-VerboseOutput），其值为$true；若未指定，则整个键不存在（不是$false）。 - 数组参数若只传一个值（如
-Tag "web"），$PSBoundParameters.Tag是字符串；若传多个（-Tag "web", "prod"），则是[object[]]数组。 - 在脚本文件（.ps1）顶层直接使用
$PSBoundParameters是无效的——它只在param块作用域内有效；必须包装成函数或使用param()块启动脚本。
快速验证的小技巧
写个最小可运行测试脚本，方便随时验证行为：
[CmdletBinding()]
param(
[string]$User,
[int]$Count = 5,
[switch]$Force
)
"PSBoundParameters 内容："
$PSBoundParameters | Out-String | Write-Host -ForegroundColor Cyan
"Keys: $($PSBoundParameters.Keys -join ', ')"
然后分别运行：.\test.ps1 -User "Alice" -Force → 输出 User 和 Force.\test.ps1 -User "Bob" → 只输出 User.\test.ps1 → 输出空哈希表（无 Keys）
