叹为观止

适用于 PowerShell 5.1 及以上版本

长时间运行的脚本如果不给用户任何反馈，就像一个”黑盒”——用户不知道脚本在做什么、进度如何、是否卡死了。良好的进度反馈是区分”能用”和”好用”脚本的关键。PowerShell 提供了 Write-Progress 命令用于显示进度条、Write-Verbose 用于详细输出、Write-Debug 用于调试信息，合理使用这些机制可以大幅提升脚本的用户体验。

本文将讲解 PowerShell 的反馈机制、进度条设计，以及如何构建用户友好的自动化脚本。

Write-Progress 进度条

# 基础进度条
1..100 | ForEach-Object {
    $pct = $_
    Write-Progress -Activity "处理数据" -Status "进度：$pct%" -PercentComplete $pct
    Start-Sleep -Milliseconds 50
}
Write-Progress -Activity "处理数据" -Completed

# 带子任务的进度条
$servers = @('SRV01', 'SRV02', 'SRV03', 'SRV04', 'SRV05')
$tasks = @('检查服务', '验证磁盘', '测试网络', '收集日志')

for ($i = 0; $i -lt $servers.Count; $i++) {
    $serverPct = [math]::Round(($i / $servers.Count) * 100)

    for ($j = 0; $j -lt $tasks.Count; $j++) {
        $taskPct = [math]::Round(($j / $tasks.Count) * 100)

        Write-Progress -Activity "服务器巡检 ($($i+1)/$($servers.Count))" `
            -Status "正在处理：$($servers[$i])" `
            -PercentComplete $serverPct `
            -CurrentOperation $tasks[$j] `
            -Id 1

        Start-Sleep -Milliseconds 300
    }
}

Write-Progress -Activity "服务器巡检" -Completed

执行结果示例：

# 在控制台中显示动态进度条
处理数据
  进度：75% [████████████████████░░░░░░░]

嵌套进度条

当有多个层级的任务时，可以使用嵌套进度条：

$environments = @('dev', 'staging', 'production')
$servers = @('web-01', 'web-02', 'db-01')

foreach ($env_idx in 0..($environments.Count - 1)) {
    $env = $environments[$env_idx]
    $envPct = [math]::Round(($env_idx / $environments.Count) * 100)

    Write-Progress -Id 1 -Activity "部署环境：$env" `
        -Status "环境进度：$($env_idx + 1)/$($environments.Count)" `
        -PercentComplete $envPct

    foreach ($srv_idx in 0..($servers.Count - 1)) {
        $srv = $servers[$srv_idx]
        $srvPct = [math]::Round(($srv_idx / $servers.Count) * 100)

        Write-Progress -Id 2 -ParentId 1 -Activity "部署服务器：$srv" `
            -Status "服务器进度：$($srv_idx + 1)/$($servers.Count)" `
            -PercentComplete $srvPct

        # 模拟部署步骤
        $steps = @('拉取镜像', '停止容器', '更新配置', '启动服务', '健康检查')
        foreach ($step_idx in 0..($steps.Count - 1)) {
            $stepPct = [math]::Round(($step_idx / $steps.Count) * 100)

            Write-Progress -Id 3 -ParentId 2 -Activity $steps[$step_idx] `
                -PercentComplete $stepPct

            Start-Sleep -Milliseconds 200
        }
    }
}

Write-Progress -Id 1 -Completed

执行结果示例：

# 显示嵌套进度条
部署环境：production
  部署服务器：db-01
    启动服务 [80%]

Verbose 和 Debug 输出

# 高级函数自动支持 -Verbose 和 -Debug
function Deploy-Application {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [string]$AppName,

        [string]$Version = 'latest'
    )

    Write-Verbose "开始部署 $AppName v$Version"

    Write-Verbose "停止服务..."
    Stop-Service $AppName -ErrorAction SilentlyContinue

    Write-Verbose "更新文件..."
    # Copy-Item ...

    Write-Verbose "启动服务..."
    Start-Service $AppName

    Write-Verbose "部署完成"
}

# 普通调用（不显示 Verbose）
Deploy-Application -AppName "MyApp"

# 带 -Verbose 调用
Deploy-Application -AppName "MyApp" -Verbose

# 带调试断点
function Test-Connection2 {
    [CmdletBinding()]
    param([string]$ComputerName)

    Write-Debug "开始测试连接：$ComputerName"
    $result = Test-Connection -ComputerName $ComputerName -Count 1 -Quiet

    Write-Debug "测试结果：$result"
    return $result
}

# -Debug 会在每个 Write-Debug 处暂停
Test-Connection2 -ComputerName "localhost" -Debug

执行结果示例：

# 普通调用 - 无输出
# -Verbose 调用
VERBOSE: 开始部署 MyApp vlatest
VERBOSE: 停止服务...
VERBOSE: 更新文件...
VERBOSE: 启动服务...
VERBOSE: 部署完成

# -Debug 调用
DEBUG: 开始测试连接：localhost
确认
是否继续执行此操作?
[Y] 是  [A] 全是  [H] 停止命令  [?] 帮助

自定义状态指示器

对于不确定进度的长时间操作，可以使用旋转指示器：

function Write-Spinner {
    param(
        [string]$Message = "处理中",
        [int]$DurationSeconds = 10
    )

    $spinChars = @('|', '/', '-', '\')
    $startTime = Get-Date

    while (((Get-Date) - $startTime).TotalSeconds -lt $DurationSeconds) {
        foreach ($char in $spinChars) {
            Write-Host "`r$char $message..." -NoNewline
            Start-Sleep -Milliseconds 100
        }
    }
    Write-Host "`r  $message 完成    " -ForegroundColor Green
}

Write-Spinner -Message "正在连接数据库" -DurationSeconds 5

# 带颜色的状态输出
function Write-Status {
    param(
        [string]$Message,
        [ValidateSet('Info', 'Success', 'Warning', 'Error')]
        [string]$Level = 'Info'
    )

    $icon = switch ($Level) {
        'Info'    { '[INFO]' }
        'Success' { '[OK]' }
        'Warning' { '[WARN]' }
        'Error'   { '[FAIL]' }
    }

    $color = switch ($Level) {
        'Info'    { 'Cyan' }
        'Success' { 'Green' }
        'Warning' { 'Yellow' }
        'Error'   { 'Red' }
    }

    $timestamp = Get-Date -Format 'HH:mm:ss'
    Write-Host "[$timestamp] " -NoNewline -ForegroundColor DarkGray
    Write-Host "$icon " -NoNewline -ForegroundColor $color
    Write-Host $Message
}

Write-Status -Level Info    "开始部署"
Write-Status -Level Success "配置文件已更新"
Write-Status -Level Warning "磁盘空间低于 20%"
Write-Status -Level Error   "数据库连接失败"

执行结果示例：

  正在连接数据库 完成
[08:30:15] [INFO]  开始部署
[08:30:16] [OK]    配置文件已更新
[08:30:17] [WARN]  磁盘空间低于 20%
[08:30:18] [FAIL]  数据库连接失败

注意事项

1. Write-Progress 性能：大量快速更新进度条会显著降低脚本性能，在循环中控制更新频率
2. -NoNewline：使用 Write-Host -NoNewline 实现行内更新，但完成后要输出换行符
3. 日志 vs 显示：Write-Host 只显示不记录，Write-Output 进入管道。进度信息应使用 Write-Host 或 Write-Progress
4. CI/CD 兼容：在 CI/CD 管道中，Write-Progress 可能不显示。改用 Write-Host 输出带时间戳的状态
5. 颜色可访问性：不要仅依赖颜色传达信息，同时使用图标或文字前缀
6. 静默模式：为脚本添加 -Quiet 参数，在自动化场景中关闭所有非必要输出