powershell-windows

PowerShell Windows 模式

Windows PowerShell 的关键模式与易踩问题。

---

1. 运算符语法规则

重要：必须使用括号

❌ 错误	✅ 正确
if (Test-Path "a" -or Test-Path "b")	if ((Test-Path "a") -or (Test-Path "b"))
if (Get-Item $x -and $y -eq 5)	if ((Get-Item $x) -and ($y -eq 5))

规则： 使用逻辑运算符时，每个 cmdlet 调用都必须放在括号中。

---

2. 编码兼容性

优先使用可移植的日志标记

用途	❌ 不要使用	✅ 使用
成功	✅ ✓	[OK] [+]
错误	❌ ✗ 🔴	[!] [X]
警告	⚠️ 🟡	[*] [WARN]
信息	ℹ️ 🔵	[i] [INFO]
进度	⏳	[...]

PowerShell 支持 Unicode。使用 ASCII 日志标记是出于可移植性的考虑，并非语法要求。Windows PowerShell 5.1 读取的非 ASCII 脚本应使用带 BOM 的 UTF-8；PowerShell 7 默认使用不带 BOM 的 UTF-8。选择文件编码前，请检查使用该文件的工具。

---

3. Null 检查模式

访问前务必检查

❌ 错误	✅ 正确
$array.Count -gt 0	($null -ne $array) -and (@($array).Count -gt 0)
$text.Length	if ($null -ne $text) { $text.Length }

---

4. 字符串插值

复杂表达式

"Value: $($obj.prop.sub)" 是有效的子表达式插值。如果将复杂表达式存入变量能提升可读性，就应这样做。

模式：

$value = $obj.prop.sub
Write-Output "Value: $value"

---

5. 错误处理

ErrorActionPreference

值	用途
Stop	必须让 cmdlet 故障进入 catch
Continue	报告非终止错误，并有意继续执行
SilentlyContinue	适用于预期会发生错误的情况

Try/Catch 模式

• 在 try 中使用 return 是有效的；finally 仍会运行
• 使用 finally 执行清理
• 在 try/catch 后 return

---

6. 文件路径

Windows 路径规则

模式	用途
字面路径	C:\Users\User\file.txt
变量路径	Join-Path $env:USERPROFILE "file.txt"
相对路径	Join-Path $ScriptDir "data"

规则： 使用 Join-Path 确保跨平台安全。

---

7. 数组操作

正确模式

操作	语法
空数组	$array = @()
添加项	$array += $item
ArrayList 添加项	`$list.Add($item)

---

8. JSON 操作

重要：Depth 参数

❌ 错误	✅ 正确
ConvertTo-Json	ConvertTo-Json -Depth 10

规则： 对嵌套对象务必指定 -Depth。

文件操作

操作	模式
读取	`Get-Content "file.json" -Raw
写入	`$data

---

9. 常见错误

错误消息	原因	修复方法
"parameter 'or'"	缺少括号	将 cmdlet 放入 () 中
"Unexpected token"	解析或引号错误	检查报告的令牌和文件编码
"Cannot find property"	对象为 Null	先检查 Null
"Cannot convert"	类型不匹配	验证输入，并转换为所需类型

---

10. 脚本模板

# Strict mode
Set-StrictMode -Version Latest
$ErrorActionPreference = "Stop"

# Paths
$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path

# Main
try {
    # Cmdlet logic here; check $LASTEXITCODE after native executables.
    Write-Output "[OK] Done"
    exit 0
}
catch {
    Write-Warning "Error: $_"
    exit 1
}

---

请记住： 检查 shell 版本、编码、Null 语义和原生命令退出代码。单靠 try/catch 无法可靠地将原生命令故障转换为异常。

参考：编码、引号规则。

适用场景

编写或调试 Windows PowerShell 或 PowerShell 7 脚本时使用，尤其适用于命令表达式、编码、路径和错误处理。

限制

• 仅当任务明确符合上述范围时，才使用此技能。
• 不要将输出视为特定环境验证、测试或专家评审的替代品。
• 如果缺少必需的输入、权限、安全边界或成功标准，请停止并请求澄清。