PowerShell脚本开发实战：参数、函数、异常处理、日志与自动化测试

原创于 2026-11-05 14:12:12 发布 · 782 阅读

3 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

收录于

Windows 开发环境与 PowerShell 实战

本文系统讲解PowerShell脚本的工程化实践，涵盖参数验证（Mandatory、ValidateSet等）、CmdletBinding高级特性（WhatIf/Confirm/Verbose）、异常处理机制（非终止错误捕获与$ErrorActionPreference）、外部程序退出码（$LASTEXITCODE）检查、结构化日志与输出流设计、以及基于Pester的自动化测试方法。通过安全文件复制工具实战，演示如何构建可复用、可测试、可审计的生产级脚本。

PowerShell脚本开发实战：参数、函数、异常处理、日志与自动化测试

在前面的文章中，我们已经介绍了 PowerShell 开发环境搭建、执行策略、数字签名，以及 UNC 网络共享脚本无法执行的排查方法。

但当我们真正开始编写 PowerShell 自动化工具时，还会遇到更多问题。

例如：

脚本只能在自己的电脑上运行，换一台电脑就出错。
输入参数不正确时，脚本执行到一半才失败。
发生异常后，脚本没有明确告诉用户哪里出错。
执行文件操作时，无法提前预览会修改什么。
运行结果只显示在终端，无法保存成结构化报告。
修改脚本之后，不知道原来的功能是否受到影响。
自动化任务提示执行完成，但实际上部分操作已经失败。

这些问题并不只是 PowerShell 语法问题，而是脚本的工程化设计问题。

一份能够长期使用的 PowerShell 脚本，不应该仅仅满足“在当前电脑上能运行”，还应该具备参数验证、明确的错误处理、安全的操作边界、可观察的执行结果，以及可重复的测试。

本文将通过一个完整的文件复制工具，介绍如何逐步建立这些能力。

适用环境： Windows PowerShell 5.1、PowerShell 7.x。

本文采用本地临时目录进行实验，不要求管理员权限。核心代码使用兼容 PowerShell 5.1 的语法，测试示例采用 Pester 5 及兼容版本。PowerShell 脚本与测试文件已完成静态检查，但尚未在 Windows 上进行完整实机验证。

一、先理解：命令、函数、脚本和模块有什么区别？

刚开始使用 PowerShell 时，通常直接在终端中输入命令。

例如：

Get-Process

或者：

Get-ChildItem

随着任务复杂度增加，我们可能把多条命令保存到 .ps1 文件。

之后还会遇到函数和 PowerShell 模块。

它们之间是什么关系？

1.1 四种常见组织形式

形式	示例	主要用途
命令	`Get-Process`	完成单个操作
函数	`function Get-Status {}`	封装可复用逻辑
脚本	`Check-System.ps1`	执行完整任务
模块	`SystemTools.psm1`	组织、导出和复用多个功能

例如，我们可以定义一个简单函数：

function Get-ProcessSummary {
    Get-Process |
        Select-Object ProcessName, Id, CPU
}

然后直接调用：

Get-ProcessSummary

如果把它保存到脚本文件中，就可以在需要时加载和使用。

随着功能增加，可以再将多个函数组织成模块。

1.2 从简单脚本到工程化工具

图1：PowerShell 自动化工具从简单命令到模块化工程的演进过程。

这里有一个实用建议：

不是所有 PowerShell 代码都需要开发成模块。

如果只是一个独立任务，使用 .ps1 完全足够。

当多个脚本开始共享函数、需要版本管理和统一发布时，再考虑开发 .psm1 模块。

二、PowerShell脚本应该具备什么结构？

我们先看一个简单脚本。

$source = "C:\Data"
$destination = "D:\Backup"

Copy-Item -Path $source -Destination $destination -Recurse

这段代码能够实现复制，但作为长期使用的工具，还存在不少问题。

例如：

路径被写死；
没有验证源目录是否存在；
没有说明目标目录是否可以覆盖；
复制失败时没有明确的错误处理；
不支持操作预览；
无法直接生成结构化执行结果。

因此，我们需要逐步完善。

2.1 推荐的脚本基本结构

#Requires -Version 5.1

<#
.SYNOPSIS
    Short description.
.DESCRIPTION
    Detailed description.
.EXAMPLE
    .\Example.ps1 -Name Demo
#>

[CmdletBinding()]
param(
    [Parameter(Mandatory = $true)]
    [string]$Name
)

Set-StrictMode -Version Latest
$ErrorActionPreference = 'Stop'

function Invoke-Task {
    param(
        [string]$TaskName
    )

    Write-Verbose "Processing: $TaskName"

    [PSCustomObject]@{
        Name   = $TaskName
        Status = 'Success'
    }
}

Invoke-Task -TaskName $Name

执行：

.\Example.ps1 -Name "Demo" -Verbose

这份结构比直接堆砌命令更加清晰。

其中：

#Requires

声明脚本的最低 PowerShell 版本要求。

注释式帮助

为脚本提供简介、详细说明和使用示例。

CmdletBinding

让脚本具备高级命令的部分行为，并支持相应通用参数。

param()

声明输入参数。

Set-StrictMode

帮助发现未初始化变量、错误属性访问等问题。

$ErrorActionPreference

设置当前脚本作用域中的非终止错误处理偏好。

函数

封装具体业务逻辑。

结构化输出

使用 PowerShell 对象返回结果，而不是仅仅在终端打印“成功”。

需要注意，Set-StrictMode -Version Latest 适合用于新开发的受控脚本，但对于依赖宽松语法的旧脚本，开启后可能暴露兼容性问题，应逐项处理。

三、参数设计：不要把配置写死在脚本中

PowerShell 脚本的可复用性，很大程度上取决于参数设计。

3.1 使用param声明参数

例如：

param(
    [string]$SourcePath,
    [string]$DestinationPath
)

这样就可以运行：

.\Copy-Files.ps1 `
    -SourcePath "C:\Data" `
    -DestinationPath "D:\Backup"

相比硬编码路径，参数化脚本更适合重复执行。

3.2 Mandatory：必填参数

param(
    [Parameter(Mandatory = $true)]
    [string]$SourcePath
)

当用户没有指定该参数时，PowerShell 会要求用户输入。

对于非交互式自动化，应在调用脚本时明确传入必需参数，避免任务因等待交互输入而挂起。

3.3 参数类型

PowerShell 支持参数类型声明。

例如：

param(
    [string]$Name,

    [int]$RetryCount = 3,

    [bool]$Enabled = $true,

    [switch]$VerboseMode
)

其中：

string：字符串；
int：整数；
bool：布尔值；
switch：开关型参数。

对于只需要“启用或不启用”的参数，switch 往往比布尔值更符合 PowerShell 使用习惯。

例如：

.\Example.ps1 -VerboseMode

3.4 ValidateNotNullOrEmpty

如果参数不允许为空，可以使用：

param(
    [Parameter(Mandatory = $true)]
    [ValidateNotNullOrEmpty()]
    [string]$FolderPath
)

这样能在脚本正式执行之前，拒绝空值或空字符串等不符合要求的输入。

3.5 ValidateRange

对于整数参数：

param(
    [ValidateRange(1, 10)]
    [int]$RetryCount = 3
)

限制重试次数在 1～10 之间。

3.6 ValidateSet

对于只能选择固定值的参数：

param(
    [ValidateSet('Copy', 'Move', 'Check')]
    [string]$Action = 'Check'
)

调用时：

.\Example.ps1 -Action Copy

如果传入不允许的值，PowerShell 会直接报告参数验证错误。

3.7 ValidateScript

如果希望验证某个路径是否存在，可以使用：

param(
    [Parameter(Mandatory = $true)]
    [ValidateScript({
        Test-Path -LiteralPath $_ -PathType Container
    })]
    [string]$SourcePath
)

这里的 $_ 表示正在验证的参数值。

如果目录不存在，参数验证失败。

不过，在复杂的文件系统操作中，我通常更建议将部分路径检查放在脚本的初始化阶段。

因为除了“路径是否存在”，可能还需要检查：

路径是否属于文件系统；
是否为目录；
是否是符号链接或连接点；
是否与目标目录重叠；
是否具有必要权限。

这些问题不适合全部堆进一个 ValidateScript 表达式中。

四、CmdletBinding：从普通脚本到高级脚本

前面出现过：

[CmdletBinding()]

它不仅是装饰性代码。

添加后，脚本或函数可以使用更多 PowerShell 通用参数，并与 PowerShell 的错误处理、管道及确认机制更好地集成。

4.1 使用Verbose输出调试信息

例如：

[CmdletBinding()]
param(
    [string]$Name = 'Demo'
)

Write-Verbose "Starting task: $Name"

Write-Output "Completed: $Name"

普通执行：

.\Example.ps1

只显示常规结果。

增加：

.\Example.ps1 -Verbose

则可以看到详细过程。

这比在脚本中到处添加 Write-Host 更适合长期维护。

4.2 不要自己手工定义WhatIf和Confirm参数

如果脚本需要支持安全预览与确认，应使用：

[CmdletBinding(SupportsShouldProcess = $true)]

PowerShell 会自动提供相应的 -WhatIf 和 -Confirm 参数。

不应该自己再声明：

param(
    [switch]$WhatIf,
    [switch]$Confirm
)

后面我们会通过文件复制案例，详细说明这两个参数如何正确工作。

五、异常处理：为什么try/catch有时捕获不到错误？

这也是 PowerShell 开发中非常容易出现的问题。

PowerShell 存在不同类型的错误。

其中一个重要区别是：

非终止错误（Non-terminating Error）与终止错误（Terminating Error）。

5.1 非终止错误

例如：

Get-Item -LiteralPath "C:\NotExisting\File.txt"

如果文件不存在，通常会产生错误记录。

但某些 Cmdlet 产生的非终止错误不会自动停止整个脚本。

这可能导致后续代码继续运行。

5.2 为什么try/catch可能没有捕获错误？

例如：

try {
    Get-Item -LiteralPath "C:\NotExisting\File.txt"
}
catch {
    Write-Host "Caught error"
}

对于非终止错误，如果没有升级为终止错误，catch 可能不会执行。

更可靠的写法是：

try {
    Get-Item `
        -LiteralPath "C:\NotExisting\File.txt" `
        -ErrorAction Stop
}
catch {
    Write-Warning "Operation failed: $($_.Exception.Message)"
}

-ErrorAction Stop 会将适用的非终止错误升级为可被 catch 捕获的终止错误。

这也是很多脚本虽然使用了 try/catch，却仍然出现“报错后继续执行”的原因。

5.3 try/catch/finally的作用

try {
    Write-Output "Start"

    throw "Simulated failure"
}
catch {
    Write-Warning "Error: $($_.Exception.Message)"
}
finally {
    Write-Verbose "Cleanup completed" -Verbose
}

三个部分分别负责：

try：执行可能失败的操作；
catch：处理捕获到的错误；
finally：执行必要的清理逻辑。

实际项目中，finally 特别适合释放文件句柄、网络资源和其他需要显式关闭的对象。

5.4 什么时候应该使用throw？

如果发生的问题意味着任务不能继续，就应该考虑抛出终止错误。

例如：

if (-not (Test-Path -LiteralPath $SourcePath)) {
    throw "Source path does not exist: $SourcePath"
}

这样可以阻止脚本在错误前提下继续处理数据。

但如果只是某个文件已经存在，脚本可以安全跳过它，则未必需要终止整个任务。

因此，应根据错误的实际影响设计处理方式。

5.5 不要捕获错误后直接假装成功

不推荐：

try {
    # Important operation
}
catch {
    Write-Host "Ignored"
}

如果重要操作失败，而脚本仍然返回成功状态，自动化平台就可能误以为任务已经完成。

更可靠的方法是明确区分：

可恢复错误；
可跳过错误；
需要停止任务的错误。

对于无法安全恢复的失败，应保留错误信息并让调用方知道任务失败。

六、外部程序错误： $? 与$ LASTEXITCODE有什么区别？

PowerShell 调用 Git、Node.js、Python、Codex 等程序时，还需要处理外部程序退出码。

例如：

git --version

执行之后：

$LASTEXITCODE

通常可以得到外部程序的退出码。

6.1 两个重要的自动变量

变量	作用
`$?`	上一条 PowerShell 操作是否成功
`$LASTEXITCODE`	最近一次适用的原生程序退出码

对于通常遵循常见约定的外部命令，退出码 0 表示成功，非零值表示某种失败。

但具体退出码的解释需要参考对应程序文档。

6.2 为什么try/catch无法代替退出码检查？

例如：

try {
    git status
}
catch {
    Write-Warning "Git command failed"
}

外部程序返回非零退出码时，并不一定会按照 PowerShell 终止错误的形式进入 catch。

因此，对于需要可靠判断结果的脚本，应在调用之后立即检查退出码。

git status

$exitCode = $LASTEXITCODE

if ($exitCode -ne 0) {
    throw "Git command failed with exit code $exitCode"
}

这样可以避免“Git 已经失败，但 PowerShell 脚本仍继续报告成功”的情况。

6.3 为什么建议立即保存退出码？

因为 $LASTEXITCODE 记录的是最近一次适用的原生程序退出码。

如果后续又运行了其他外部程序，变量值可能改变。

因此：

git status
$gitExitCode = $LASTEXITCODE

比执行很多条其他命令之后，再去读取 $LASTEXITCODE 更可靠。

还需要注意，PowerShell 7 的原生命令错误处理机制与 Windows PowerShell 5.1 存在一些差异。

为了兼容两种环境，对于重要外部程序，显式检查退出码通常更容易理解和维护。

七、日志设计：不要把所有信息都写到Write-Host

一个真正可靠的自动化工具，需要让开发者知道：

执行了什么操作；
操作对象是什么；
哪些操作成功；
哪些操作被跳过；
哪些操作失败；
失败的原因是什么。

PowerShell 本身提供了多种输出流。

7.1 PowerShell常见输出流

命令	主要用途
`Write-Output`	返回正常结果
`Write-Error`	输出错误记录
`Write-Warning`	输出警告
`Write-Verbose`	输出详细诊断信息
`Write-Debug`	输出调试信息
`Write-Information`	输出一般信息
`Write-Host`	面向交互终端显示信息

例如：

Write-Verbose "Checking source directory"

Write-Warning "Destination already exists"

Write-Output ([PSCustomObject]@{
    File   = "demo.txt"
    Status = "Copied"
})

这里有一个重要的设计原则：

机器需要继续处理的结果，应通过结构化对象输出；用户需要了解的过程，则使用 Verbose、Warning 等适当的消息流。

例如，不应该只输出：

Copy successful!

更适合自动化处理的结果是：

[PSCustomObject]@{
    Time        = (Get-Date).ToString('o')
    Status      = 'Copied'
    Source      = 'C:\Source\demo.txt'
    Destination = 'C:\Backup\demo.txt'
}

这样后续就可以筛选、导出和分析。

7.2 将结果保存为CSV

假设脚本已经返回一组结果对象：

$results | Export-Csv `
    -LiteralPath ".\copy-results.csv" `
    -NoTypeInformation `
    -Encoding UTF8

需要注意，Windows PowerShell 5.1 与 PowerShell 7 的 UTF-8 BOM 行为可能不同。

如果需要将报告交给严格要求 UTF-8 无 BOM 的系统，应进一步明确文件编码。

7.3 使用Start-Transcript记录会话

PowerShell 还提供：

Start-Transcript

用于记录终端会话。

例如：

$logPath = Join-Path $env:TEMP "PowerShell-Session.log"

Start-Transcript -Path $logPath -NoClobber

执行需要记录的命令后：

Stop-Transcript

如果开发的是正式脚本，可以通过 try/finally 确保在正常结束或异常发生时尽量关闭 Transcript。

例如：

$logPath = Join-Path $env:TEMP "PowerShell-Lab.log"

Start-Transcript -Path $logPath -NoClobber |
    Out-Null

try {
    Write-Output "Running diagnostic task"
}
finally {
    Stop-Transcript | Out-Null
}

这里有两个注意事项。

第一，Transcript 可能记录命令参数、路径甚至敏感信息，不能直接当作公开日志上传。

第二，Transcript 记录会写入文件，即使被包装的业务脚本使用了 -WhatIf，也不能认为独立启动的日志记录命令不会产生文件。

因此，日志操作本身也应该有明确的安全边界。

八、WhatIf与Confirm：文件操作前为什么应该先预览？

对于文件删除、复制、权限修改、服务停止等具有副作用的操作，我建议优先支持两个 PowerShell 标准参数：

-WhatIf
-Confirm

8.1 WhatIf的作用

-WhatIf 用于预览受支持的操作。

例如：

Remove-Item -LiteralPath ".\demo.txt" -WhatIf

它会显示计划执行的删除操作，但不会真正删除目标文件。

8.2 Confirm的作用

-Confirm 用于请求用户确认。

例如：

Remove-Item -LiteralPath ".\demo.txt" -Confirm

它适合交互式文件管理操作。

但要注意：

在无人值守的自动化任务中，交互确认可能导致程序等待输入。

因此，正式自动化工具应明确区分交互模式与非交互模式。

8.3 自定义脚本如何支持WhatIf？

关键代码如下：

[CmdletBinding(
    SupportsShouldProcess = $true,
    ConfirmImpact = 'Medium'
)]
param(
    [string]$TargetPath
)

if ($PSCmdlet.ShouldProcess($TargetPath, "Process target")) {
    Write-Output "Processing $TargetPath"
}

SupportsShouldProcess 负责提供标准的 -WhatIf 和 -Confirm 参数。

ShouldProcess() 决定当前操作是否应该继续。

这里还有一个很重要的细节：

仅声明 SupportsShouldProcess，并不意味着脚本中所有代码都会自动获得 WhatIf 保护。

例如，直接调用某个 .NET 文件写入方法，它不会自动知道 PowerShell 正处于 -WhatIf 模式。

必须将真正产生副作用的操作放在正确的 ShouldProcess() 判断之后。

九、完整实战：开发一个安全的文件复制工具

下面将前面的知识组合成一个独立工具：

Copy-SafeFiles.ps1

本例不追求实现完整备份系统，而是重点建立工程化脚本结构。

9.1 需求定义

工具需要满足：

从指定源目录复制匹配的文件；
源目录和目标目录必须已经存在；
默认只处理当前目录中的 .txt 文件；
不递归处理子目录；
目标文件已存在时不覆盖；
支持 -WhatIf；
支持 -Confirm；
支持 -Verbose；
复制成功后返回结构化结果；
发生不可恢复错误时明确终止；
不删除源文件。

为了控制示例复杂度，本版不处理递归复制、增量备份、断点续传和完整事务回滚。

9.2 项目目录

PowerShell-SafeFileOps/
├── Copy-SafeFiles.ps1
├── Copy-SafeFiles.Tests.ps1
└── README.md

9.3 完整源码：Copy-SafeFiles.ps1

#Requires -Version 5.1

<#
.SYNOPSIS
    Copy files without overwriting existing files.

.DESCRIPTION
    Copy top-level files matching Filter between
    two existing filesystem directories.

.EXAMPLE
    .\Copy-SafeFiles.ps1 `
        -SourcePath .\source `
        -DestinationPath .\backup `
        -WhatIf
#>

[CmdletBinding(
    SupportsShouldProcess = $true,
    ConfirmImpact = 'Medium'
)]
param(
    [Parameter(Mandatory = $true)]
    [ValidateNotNullOrEmpty()]
    [string]$SourcePath,

    [Parameter(Mandatory = $true)]
    [ValidateNotNullOrEmpty()]
    [string]$DestinationPath,

    [ValidateNotNullOrEmpty()]
    [string]$Filter = '*.txt'
)

Set-StrictMode -Version Latest
$ErrorActionPreference = 'Stop'

# 1. Resolve source and destination
$source = Get-Item `
    -LiteralPath $SourcePath `
    -ErrorAction Stop

$destination = Get-Item `
    -LiteralPath $DestinationPath `
    -ErrorAction Stop

# 2. Validate directories
if (-not $source.PSIsContainer -or
    -not $destination.PSIsContainer) {

    throw "Source and destination must be directories."
}

if ($source.PSProvider.Name -ne 'FileSystem' -or
    $destination.PSProvider.Name -ne 'FileSystem') {

    throw "Only FileSystem paths are supported."
}

# 3. Reject direct reparse-point directories
$reparsePoint = [System.IO.FileAttributes]::ReparsePoint

if ((($source.Attributes -band $reparsePoint) -ne 0) -or
    (($destination.Attributes -band $reparsePoint) -ne 0)) {

    throw "Direct symlinks or junctions are not supported."
}

# 4. Reject destination inside source
$srcCanonical = [System.IO.Path]::GetFullPath(
    $source.FullName
).TrimEnd([char[]]@('\', '/'))

$dstCanonical = [System.IO.Path]::GetFullPath(
    $destination.FullName
).TrimEnd([char[]]@('\', '/'))

$srcPrefix = $srcCanonical +
    [System.IO.Path]::DirectorySeparatorChar

if (
    [string]::Equals(
        $srcCanonical,
        $dstCanonical,
        [System.StringComparison]::OrdinalIgnoreCase
    ) -or
    $dstCanonical.StartsWith(
        $srcPrefix,
        [System.StringComparison]::OrdinalIgnoreCase
    )
) {
    throw "Destination must not be inside source."
}

# 5. Enumerate matching files
$items = @(
    Get-ChildItem `
        -LiteralPath $source.FullName `
        -File `
        -Filter $Filter `
        -ErrorAction Stop
)

Write-Verbose "Found $($items.Count) matching files."

# 6. Process files
foreach ($item in $items) {

    if (($item.Attributes -band $reparsePoint) -ne 0) {
        Write-Warning "Skipping file link: $($item.Name)"
        continue
    }

    $target = Join-Path `
        -Path $destination.FullName `
        -ChildPath $item.Name

    if (Test-Path -LiteralPath $target) {
        Write-Warning "Destination exists; skipped: $target"
        continue
    }

    if ($PSCmdlet.ShouldProcess(
        $target,
        "Copy from '$($item.FullName)'"
    )) {
        try {
            # Never overwrite existing destination files
            [System.IO.File]::Copy(
                $item.FullName,
                $target,
                $false
            )

            Write-Verbose "Copied: $($item.Name)"

            [PSCustomObject]@{
                Time        = (Get-Date).ToString('o')
                Status      = 'Copied'
                Source      = $item.FullName
                Destination = $target
            }
        }
        catch {
            throw (
                "Copy failed for '{0}': {1}" -f
                $item.Name,
                $_.Exception.Message
            )
        }
    }
}

9.4 为什么使用File.Copy而不是直接Copy-Item？

这里主要为了实现一个明确的安全要求：

目标文件已经存在时，不允许覆盖。

使用：

[System.IO.File]::Copy(
    $item.FullName,
    $target,
    $false
)

最后一个参数 $false 表示不允许覆盖目标文件。

如果目标文件在检查之后、复制之前被其他进程创建，复制仍会失败，而不是直接替换它。

这比仅通过：

Test-Path

判断目标文件是否存在更加可靠。

不过，这不意味着示例已经具备完整事务能力。发生磁盘写入错误时，仍可能留下不完整的目标文件，需要进一步设计临时文件、校验和恢复机制。

另外，示例拒绝直接指定为符号链接或连接点的源、目标目录，但并未完整验证全部祖先目录中的重解析点，也没有提供安全边界级的路径防护。

因此，它适合在可信的本地实验目录中学习脚本工程化，而不应未经额外强化直接用于处理不可信路径或重要生产备份。

9.5 创建实验文件

在 PowerShell 中执行：

$lab = Join-Path $env:TEMP (
    "ps-safe-copy-" + (Get-Date -Format "yyyyMMdd-HHmmss")
)

$src = Join-Path $lab "source"
$dst = Join-Path $lab "destination"

New-Item -ItemType Directory `
    -Path $src, $dst `
    -Force | Out-Null

Set-Content `
    -LiteralPath (Join-Path $src "demo.txt") `
    -Value "hello" `
    -Encoding ASCII

Set-Content `
    -LiteralPath (Join-Path $src "notes.log") `
    -Value "log" `
    -Encoding ASCII

现在源目录中有两个文件：

source/
├── demo.txt
└── notes.log

目标目录为空。

9.6 第一次运行：只预览

在保存了 Copy-SafeFiles.ps1 的目录执行：

.\Copy-SafeFiles.ps1 `
    -SourcePath $src `
    -DestinationPath $dst `
    -WhatIf `
    -Verbose

预期：

能识别匹配的文件；
显示计划执行的复制操作；
不真正创建目标文件。

可以检查：

Get-ChildItem -LiteralPath $dst

目标目录仍应为空。

这里的 -WhatIf 只控制本脚本通过 ShouldProcess() 保护的复制操作。

如果在调用脚本之外额外运行 Export-Csv 或 Start-Transcript，这些独立命令仍可能创建文件。

9.7 第二次运行：确认后执行

.\Copy-SafeFiles.ps1 `
    -SourcePath $src `
    -DestinationPath $dst `
    -Confirm `
    -Verbose

确认相应操作后，脚本执行复制。

由于默认筛选条件为：

*.txt

因此应只复制：

demo.txt

而不会复制：

notes.log

9.8 第三次运行：验证不覆盖

再次运行：

.\Copy-SafeFiles.ps1 `
    -SourcePath $src `
    -DestinationPath $dst `
    -Verbose

此时目标文件已经存在。

预期脚本显示警告并跳过该文件，不覆盖已有内容。

可以通过：

Get-Content -LiteralPath (Join-Path $dst "demo.txt")

检查文件内容。

9.9 保存结构化结果

如果已经明确确认本次操作可以执行，在受控测试环境中可以使用：

$results = @(
    .\Copy-SafeFiles.ps1 `
        -SourcePath $src `
        -DestinationPath $dst `
        -Confirm:$false
)

$results | Format-Table

如果没有实际复制任何文件，$results 可能为空。

这时不能把“没有返回 Copied 记录”直接当作成功复制。

如果要保存报告：

$results |
    Export-Csv `
        -LiteralPath (Join-Path $lab "results.csv") `
        -NoTypeInformation `
        -Encoding UTF8

这里的 CSV 记录只包含本次成功复制的结果。

跳过信息通过 Write-Warning 输出，不自动进入成功结果对象。

如需正式用于任务审计，还应该增加结构化的 Skipped、Failed 记录和任务级完成状态。

十、Pester自动化测试：怎样证明脚本修改后仍然可靠？

前面的脚本已经可以运行，但还缺少一个重要能力：

如何验证它的行为符合设计？

在 PowerShell 中，可以使用 Pester 编写自动化测试。

Pester 是 PowerShell 生态中常用的测试框架。

它支持：

单元测试；
集成测试；
Mock；
参数化测试；
测试报告；
CI 自动化集成。

10.1 检查Pester版本

Get-Module Pester -ListAvailable |
    Sort-Object Version -Descending |
    Select-Object Name, Version, Path

部分 Windows 系统自带较旧的 Pester 3.x。

但本文使用的是 Pester 5+ 风格。

如果没有合适版本，可以从经过批准的 PowerShell 模块源安装。

例如，采用 PowerShellGet 的环境：

Install-Module Pester -Scope CurrentUser

对于系统自带 Pester 3.4 的情况，可能需要按照 Pester 官方文档进行并行安装及发布者签名检查。

不要为了安装测试框架，直接删除系统内置的 Pester 模块或随意关闭模块签名检查。

当前 Pester 6 支持 Windows PowerShell 5.1 和受支持的较新 PowerShell 7 版本。较旧 PowerShell 7 环境应选择兼容的 Pester 版本，或者优先升级到受支持版本。

安装后检查：

Import-Module Pester -MinimumVersion 5.0 -ErrorAction Stop

Get-Module Pester |
    Select-Object Name, Version

10.2 测试应该验证哪些行为？

对于刚才的文件复制工具，至少需要验证：

测试项目	预期行为
WhatIf	不创建目标文件
正常复制	正确复制匹配的文件
过滤规则	不复制不匹配的文件
目标已存在	不覆盖
目标目录位于源目录内部	拒绝
源目录不存在	失败并报告错误

10.3 创建测试文件

新建：

Copy-SafeFiles.Tests.ps1

内容如下：

#Requires -Version 5.1

BeforeAll {
    $scriptFile = Join-Path `
        -Path $PSScriptRoot `
        -ChildPath 'Copy-SafeFiles.ps1'
}

Describe 'Copy-SafeFiles.ps1' {

    BeforeEach {
        $src = Join-Path $TestDrive 'source'
        $dst = Join-Path $TestDrive 'destination'

        New-Item -ItemType Directory `
            -Path $src, $dst `
            -Force | Out-Null

        [System.IO.File]::WriteAllText(
            (Join-Path $src 'demo.txt'),
            'hello'
        )

        [System.IO.File]::WriteAllText(
            (Join-Path $src 'notes.log'),
            'log'
        )
    }

    It 'Does not write in WhatIf mode' {

        & $scriptFile `
            -SourcePath $src `
            -DestinationPath $dst `
            -WhatIf | Out-Null

        Test-Path `
            -LiteralPath (Join-Path $dst 'demo.txt') |
            Should -BeFalse
    }

    It 'Copies only matching files' {

        $result = @(
            & $scriptFile `
                -SourcePath $src `
                -DestinationPath $dst `
                -Confirm:$false
        )

        Test-Path `
            -LiteralPath (Join-Path $dst 'demo.txt') |
            Should -BeTrue

        Test-Path `
            -LiteralPath (Join-Path $dst 'notes.log') |
            Should -BeFalse

        $result.Count | Should -Be 1
        $result[0].Status | Should -Be 'Copied'
    }

    It 'Does not overwrite an existing file' {

        [System.IO.File]::WriteAllText(
            (Join-Path $dst 'demo.txt'),
            'existing'
        )

        & $scriptFile `
            -SourcePath $src `
            -DestinationPath $dst `
            -Confirm:$false 3>$null |
            Out-Null

        [System.IO.File]::ReadAllText(
            (Join-Path $dst 'demo.txt')
        ) | Should -Be 'existing'
    }

    It 'Rejects nested destination' {

        $nested = Join-Path $src 'nested'

        New-Item `
            -ItemType Directory `
            -Path $nested | Out-Null

        {
            & $scriptFile `
                -SourcePath $src `
                -DestinationPath $nested `
                -Confirm:$false
        } | Should -Throw
    }

    It 'Rejects missing source directory' {

        $missing = Join-Path $TestDrive 'missing'

        {
            & $scriptFile `
                -SourcePath $missing `
                -DestinationPath $dst `
                -Confirm:$false
        } | Should -Throw
    }
}

这个测试文件使用 Pester 的 $TestDrive 测试目录组织临时文件，避免直接修改真实工作目录。

10.4 执行自动化测试

进入项目目录：

Invoke-Pester `
    -Path .\Copy-SafeFiles.Tests.ps1 `
    -Output Detailed

正常情况下，应该依次运行五组测试。

这里不直接提供虚构的 5 Passed 输出。

正式发布时，应在 Windows PowerShell 5.1 和 PowerShell 7 中分别执行，记录真实测试结果。

10.5 测试失败怎么办？

应根据具体失败用例调查。

例如：

WhatIf 测试失败

说明脚本可能在 ShouldProcess() 保护范围之外进行了文件写入。

不覆盖测试失败

说明文件存在性检查或实际复制操作不满足“不覆盖”的要求。

异常测试失败

说明脚本可能没有正确区分文件不存在和正常任务完成。

PowerShell 版本不同导致测试行为变化

应检查参数解析、文件路径、编码、模块版本和依赖环境。

不建议为了让测试通过而直接删除失败用例。

十一、从实验工具走向真实项目，还需要补充什么？

前面的 Copy-SafeFiles.ps1 是一个有意控制范围的教学示例。

它已经演示了参数验证、错误处理、安全预览和自动化测试，但距离生产级文件备份工具仍有差距。

11.1 需要进一步考虑的工程能力

能力	当前示例	生产环境可能需要
参数验证	基础检查	更完整的路径与权限验证
操作预览	WhatIf	包含完整变更清单
执行确认	Confirm	按任务或批次确认
错误处理	终止错误	错误分类、重试与恢复
日志	Verbose / Warning / 对象输出	持久化结构化日志
文件复制	单目录、按过滤器	递归、增量、校验
已有文件处理	跳过	冲突策略与版本管理
失败恢复	未实现	临时文件、原子提交或回滚
并发	未处理	锁、竞争条件管理
安全	基础边界	ACL、符号链接、路径安全
自动化测试	5 个基础测试	异常注入与兼容性矩阵

这里需要特别注意：

WhatIf 不是安全审计的全部，也不等于文件操作具有事务性。

同样，脚本存在自动化测试，不意味着已经覆盖所有异常情况。

真正的工程化，需要逐步明确每种操作的前提、失败语义和恢复机制。

11.2 推荐的项目目录组织

随着脚本数量增加，可以采用下面的结构：

PowerShell-Tools/
├── README.md
├── AGENTS.md
├── src/
│   ├── Copy-SafeFiles.ps1
│   └── ...
├── tests/
│   ├── Copy-SafeFiles.Tests.ps1
│   └── ...
├── examples/
├── docs/
└── reports/

其中：

src 保存功能源码；
tests 保存 Pester 自动化测试；
examples 保存无副作用使用示例；
docs 保存设计说明；
reports 保存测试和诊断结果。

如果项目使用 Codex 等 AI 编程工具，还可以通过 AGENTS.md 明确项目规则，例如要求先阅读源码、默认使用 WhatIf、禁止对生产路径直接执行文件删除操作，以及修改后必须运行测试。

11.3 推荐的开发流程

图2：PowerShell 自动化脚本从需求到测试、审查和发布的工程化流程。

这也是我比较推荐的开发方式。

先建立安全边界，再实现功能；先验证行为，再发布脚本。

十二、常见问题与经验总结

12.1 为什么CmdletBinding已经声明，WhatIf仍然修改了文件？

因为脚本可能在 ShouldProcess() 判断之外执行了文件写入操作。

必须检查所有产生副作用的代码，包括 .NET 文件 API、外部程序和其他没有正确传递 WhatIf 语义的子操作。

12.2 为什么try/catch没有捕获错误？

可能是 Cmdlet 产生了非终止错误，或者外部程序只返回了非零退出码。

应根据错误来源选择 -ErrorAction Stop 或显式退出码检查。

12.3 为什么脚本运行结束，却没有任何结果？

可能没有文件匹配过滤条件，也可能全部被跳过，或者使用了 WhatIf。

生产工具应明确输出任务摘要，例如匹配数量、复制数量、跳过数量和失败数量。

12.4 为什么不建议大量使用Write-Host？

因为 Write-Host 更偏向交互显示，不适合作为唯一的机器可读结果。

建议使用 PowerShell 对象输出业务结果，使用 Verbose、Warning 和 Error 等流表达执行过程与问题。

12.5 Pester测试能否代替人工验证？

不能完全代替。

自动化测试能够验证预先定义的行为，但无法保证所有文件权限、磁盘异常、并发访问和实际运行环境都已经覆盖。

尤其对涉及文件权限和网络共享的脚本，仍然需要在隔离环境中进行集成测试。

十三、总结：让PowerShell脚本从能运行走向可靠

通过本文的完整实验，可以总结出几条重要原则。

第一，脚本应该有明确的参数接口。

不要将工作目录、文件路径和运行配置全部写死在源码中。

第二，重要的输入必须先验证。

不要等到执行文件操作时，才发现路径不存在或目标不符合要求。

第三，错误不能被随意忽略。

要明确区分非终止错误、终止错误与外部程序退出码。

第四，具有副作用的操作应支持预览和确认。

-WhatIf 和 -Confirm 是 PowerShell 提供的重要工程机制，应该正确使用，而不是手工模拟。

第五，日志和业务结果应当分离。

让人理解执行过程，也让其他程序可以读取结构化结果。

第六，脚本需要自动化测试。

Pester 可以帮助我们建立基本的回归验证能力，减少修改脚本后引入新问题的风险。

对于 Codex、Windows 系统维护、MCP Server、本地 AI Agent 和其他自动化项目，这些原则同样适用。

真正可靠的 PowerShell 工具，不只是能完成任务，还应该能够解释：

它接收了什么参数、执行了哪些操作、为什么某一步失败，以及如何证明最终结果符合预期。

参考资料

Microsoft — PowerShell Advanced Functions
https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions_advanced
Microsoft — Advanced Function Parameters
https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions_advanced_parameters
Microsoft — PowerShell Error Handling
https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_error_handling
Microsoft — Try/Catch/Finally
https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_try_catch_finally
Microsoft — Everything about ShouldProcess
https://learn.microsoft.com/powershell/scripting/learn/deep-dives/everything-about-shouldprocess
Microsoft — PowerShell Output Streams
https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_output_streams
Microsoft — Start-Transcript
https://learn.microsoft.com/powershell/module/microsoft.powershell.host/start-transcript
Pester 官方文档
https://pester.dev/docs/quick-start
Pester Invoke-Pester
https://pester.dev/docs/commands/Invoke-Pester

本文属于《Windows 开发环境与 PowerShell 实战》系列。

下一篇将继续深入 Windows 文件夹权限管理，使用本文介绍的参数验证、WhatIf、异常处理和自动化测试方法，开发一套更加可靠的 NTFS ACL 文件夹权限管理工具。

标签

#windows

PowerShell脚本开发实战：参数、函数、异常处理、日志与自动化测试

PowerShell脚本开发实战：参数、函数、异常处理、日志与自动化测试

一、先理解：命令、函数、脚本和模块有什么区别？

1.1 四种常见组织形式

1.2 从简单脚本到工程化工具

二、PowerShell脚本应该具备什么结构？

2.1 推荐的脚本基本结构

三、参数设计：不要把配置写死在脚本中

3.1 使用param声明参数

3.2 Mandatory：必填参数

3.3 参数类型

3.4 ValidateNotNullOrEmpty

3.5 ValidateRange

3.6 ValidateSet

3.7 ValidateScript

四、CmdletBinding：从普通脚本到高级脚本

4.1 使用Verbose输出调试信息

4.2 不要自己手工定义WhatIf和Confirm参数

五、异常处理：为什么try/catch有时捕获不到错误？

5.1 非终止错误

5.2 为什么try/catch可能没有捕获错误？

5.3 try/catch/finally的作用

5.4 什么时候应该使用throw？

5.5 不要捕获错误后直接假装成功

六、外部程序错误：?与?与?与LASTEXITCODE有什么区别？

6.1 两个重要的自动变量

6.2 为什么try/catch无法代替退出码检查？

6.3 为什么建议立即保存退出码？

七、日志设计：不要把所有信息都写到Write-Host

7.1 PowerShell常见输出流

7.2 将结果保存为CSV

7.3 使用Start-Transcript记录会话

八、WhatIf与Confirm：文件操作前为什么应该先预览？

8.1 WhatIf的作用

8.2 Confirm的作用

8.3 自定义脚本如何支持WhatIf？

九、完整实战：开发一个安全的文件复制工具

9.1 需求定义

9.2 项目目录

9.3 完整源码：Copy-SafeFiles.ps1

9.4 为什么使用File.Copy而不是直接Copy-Item？

9.5 创建实验文件

9.6 第一次运行：只预览

9.7 第二次运行：确认后执行

9.8 第三次运行：验证不覆盖

9.9 保存结构化结果

十、Pester自动化测试：怎样证明脚本修改后仍然可靠？

10.1 检查Pester版本

10.2 测试应该验证哪些行为？

10.3 创建测试文件

10.4 执行自动化测试

10.5 测试失败怎么办？

十一、从实验工具走向真实项目，还需要补充什么？

11.1 需要进一步考虑的工程能力

11.2 推荐的项目目录组织

11.3 推荐的开发流程

十二、常见问题与经验总结

12.1 为什么CmdletBinding已经声明，WhatIf仍然修改了文件？

12.2 为什么try/catch没有捕获错误？

12.3 为什么脚本运行结束，却没有任何结果？

12.4 为什么不建议大量使用Write-Host？

12.5 Pester测试能否代替人工验证？

十三、总结：让PowerShell脚本从能运行走向可靠

参考资料

六、外部程序错误： $? 与$ LASTEXITCODE有什么区别？