PowerShell Windows 脚本编写最佳实践与常见陷阱解决方案 | 开发运维指南

powershell-windows by davila7/claude-code-templates

261 周安装量

24,300 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/davila7/claude-code-templates --skill 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

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

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

3. 空值检查模式

访问前务必检查

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

❌ 错误	✅ 正确
`"Value: $($obj.prop.sub)"`	先存储在变量中

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

ErrorActionPreference

值	用途
Stop	开发（快速失败）
Continue	生产脚本
SilentlyContinue	预期会出现错误时

不要在 try 块内返回
使用 finally 进行清理
在 try/catch 之后返回

Windows 路径规则

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

规则： 为跨平台安全性，使用 Join-Path。

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

关键：Depth 参数

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

规则： 对于嵌套对象，始终指定 -Depth。

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

错误信息	原因	修复方法
"parameter 'or'"	缺少括号	将 cmdlet 用 () 包裹
"Unexpected token"	Unicode 字符	仅使用 ASCII
"Cannot find property"	空对象	先检查空值
"Cannot convert"	类型不匹配	使用 .ToString()

# 严格模式
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 字符以及空值检查是不可妥协的。

🇺🇸English

PowerShell Windows Patterns

Critical patterns and pitfalls for Windows PowerShell.

1. Operator Syntax Rules

CRITICAL: Parentheses Required

❌ Wrong	✅ Correct
`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))`

Rule: Each cmdlet call MUST be in parentheses when using logical operators.

2. Unicode/Emoji Restriction

CRITICAL: No Unicode in Scripts

Purpose	❌ Don't Use	✅ Use
Success	✅ ✓	[OK] [+]
Error	❌ ✗ 🔴	[!] [X]
Warning	⚠️ 🟡	[*] [WARN]
Info	ℹ️ 🔵	[i] [INFO]
Progress	⏳	[...]

Rule: Use ASCII characters only in PowerShell scripts.

3. Null Check Patterns

Always Check Before Access

❌ Wrong	✅ Correct
`$array.Count -gt 0`	`$array -and $array.Count -gt 0`
`$text.Length`	`if ($text) { $text.Length }`

4. String Interpolation

Complex Expressions

❌ Wrong	✅ Correct
`"Value: $($obj.prop.sub)"`	Store in variable first

Pattern:

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

5. Error Handling

ErrorActionPreference

Value	Use
Stop	Development (fail fast)
Continue	Production scripts
SilentlyContinue	When errors expected

Try/Catch Pattern

Don't return inside try block
Use finally for cleanup
Return after try/catch

6. File Paths

Windows Path Rules

Pattern	Use
Literal path	`C:\Users\User\file.txt`
Variable path	`Join-Path $env:USERPROFILE "file.txt"`
Relative	`Join-Path $ScriptDir "data"`

Rule: Use Join-Path for cross-platform safety.

7. Array Operations

Correct Patterns

Operation	Syntax
Empty array	`$array = @()`
Add item	`$array += $item`
ArrayList add	`$list.Add($item)

8. JSON Operations

CRITICAL: Depth Parameter

❌ Wrong	✅ Correct
`ConvertTo-Json`	`ConvertTo-Json -Depth 10`

Rule: Always specify -Depth for nested objects.

File Operations

Operation	Pattern
Read	`Get-Content "file.json" -Raw
Write	`$data

9. Common Errors

Error Message	Cause	Fix
"parameter 'or'"	Missing parentheses	Wrap cmdlets in ()
"Unexpected token"	Unicode character	Use ASCII only
"Cannot find property"	Null object	Check null first
"Cannot convert"	Type mismatch	Use .ToString()

10. Script Template

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

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

# Main
try {
    # Logic here
    Write-Output "[OK] Done"
    exit 0
}
catch {
    Write-Warning "Error: $_"
    exit 1
}

Remember: PowerShell has unique syntax rules. Parentheses, ASCII-only, and null checks are non-negotiable.

Weekly Installs

150

Repository

davila7/claude-…emplates

GitHub Stars

22.6K

First Seen

Jan 25, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

opencode126

claude-code120

gemini-cli118

codex113

github-copilot113

cursor109

Azure 升级评估与自动化工具 - 轻松迁移 Functions 计划、托管层级和 SKU

104,900 周安装

PowerShell Windows 脚本编写最佳实践与常见陷阱解决方案 | 开发运维指南

🇨🇳中文介绍

PowerShell Windows 模式

1. 运算符语法规则

关键：必须使用括号

2. Unicode/Emoji 限制

关键：脚本中禁止使用 Unicode

相关 Skills

3. 空值检查模式

访问前务必检查

4. 字符串插值

复杂表达式

5. 错误处理

ErrorActionPreference

Try/Catch 模式

6. 文件路径

Windows 路径规则

7. 数组操作

正确模式

8. JSON 操作

关键：Depth 参数

文件操作

9. 常见错误

10. 脚本模板

🇺🇸English

PowerShell Windows Patterns

1. Operator Syntax Rules

CRITICAL: Parentheses Required

2. Unicode/Emoji Restriction

CRITICAL: No Unicode in Scripts

3. Null Check Patterns

Always Check Before Access

4. String Interpolation

Complex Expressions

5. Error Handling

ErrorActionPreference

Try/Catch Pattern

6. File Paths

Windows Path Rules

7. Array Operations

Correct Patterns

8. JSON Operations

CRITICAL: Depth Parameter

File Operations

9. Common Errors

10. Script Template

最新 Skills