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 檢查模式

存取前務必進行檢查

❌ 錯誤	✅ 正確
$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	存取前先檢查是否為 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 字元以及 Null 檢查都是不可妥協的基本原則。

何時使用

當需要執行概述中所描述的工作流程或操作時，即可套用此 Skill。

使用限制

• 僅在任務明確符合上述適用範圍時使用此 Skill。
• 請勿將輸出結果視為替代特定環境驗證、測試或專家審查的依據。
• 若缺少必要的輸入資料、權限、安全界限或成功標準，請立即停止並尋求進一步確認。