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. Unicode / Emoji 字符限制

致命踩坑点：脚本内严禁包含 Unicode 字符

用途	❌ 严禁使用	✅ 推荐使用
成功提示	✅ ✓	[OK] [+]
报错提示	❌ ✗ 🔴	[!] [X]
警告提示	⚠️ 🟡	[*] [WARN]
信息提示	ℹ️ 🔵	[i] [INFO]
进度提示	⏳	[...]

硬性规则： PowerShell 脚本中仅允许使用纯 ASCII 字符。

---

3. 空值检查模式 (Null Check)

属性访问前务必先校验判空

❌ 错误示范	✅ 正确写法
$array.Count -gt 0	$array -and $array.Count -gt 0
$text.Length	if ($text) { $text.Length }

---

4. 字符串插值

复杂表达式的处理

❌ 错误示范	✅ 正确写法
"Value: $($obj.prop.sub)"	先存入临时变量再引用

推荐写法：

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

---

5. 错误处理

ErrorActionPreference 参数设置

属性值	适用场景
Stop	开发阶段（快速失败，暴露问题）
Continue	生产环境脚本
SilentlyContinue	预期会出现非致命错误时

Try/Catch 异常捕获模式

• 切勿在 try 块内部直接使用 return 退出
• 使用 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"	脚本存在 Unicode 字符	全面替换为纯 ASCII 字符
"Cannot find property"	对象为 Null	操作前先进行判空校验
"Cannot convert"	类型不匹配	调用 .ToString() 进行显式转换

---

10. 标准脚本模板

# 严格模式
Set-StrictMode -Version Latest
$ErrorActionPreference = "Continue"

# 脚本路径获取
$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path

# 主逻辑入口
try {
    # 业务逻辑代码放置处
    Write-Output "[OK] Done"
    exit 0
}
catch {
    Write-Warning "Error: $_"
    exit 1
}

---

避坑提醒： PowerShell 的语法规则非常硬核，必须加括号、全纯 ASCII 字符以及对象判空都是不可逾越的底线。

适用场景

当需要执行概述中所述的流程或具体操作时，使用本 Skill。

使用限制

• 仅当任务明确符合上述定义的适用范围时，才可使用本 Skill。
• 不得将输出结果直接替代针对特定环境的校验、实际测试或专家评审。
• 若缺少必要的输入参数、权限、安全边界或验收标准，应立即停止操作并寻求进一步明确。