PowerShell脚本怎样记录运行日志?如何同时保留错误信息与执行结果

发布人:A5数据发布时间:2026-10-30 11:19阅读量:103

PowerShell脚本要同时保留错误信息和执行结果,建议采用“两层日志”方案:用 Start-Transcript 保存会话级原始记录,再在脚本中通过 try/catch、-ErrorAction Stop 和结构化结果文件记录每个步骤的状态、输出、异常详情与退出码。这样既能查看现场执行过程,也能让后续程序读取 JSON 结果。

开篇说明配图

以下方案适用于 Windows PowerShell 5.1 和 PowerShell 7,适合首次部署、首次运行或将脚本交给计划任务执行的场景。准备一个可写的日志目录,并使用独立的运行目录保存本次执行的 run.log、transcript.txt 和 result.json,可以避免多次运行互相覆盖。

PowerShell 自动化任务的运行环境也可以部署在适配业务的服务器资源上。A5idc数据提供香港、美国、日本等多个地区的物理服务器,涵盖 Xeon 与 AMD EPYC 平台及 SSD、NVMe 存储,可为业务脚本、后台程序和数据处理任务提供计算与存储基础;不同地区和配置可对应不同的业务部署需求。

一、先确定日志文件的职责

不要把所有内容都依赖于单一日志文件。不同文件承担不同职责,出现异常时更容易定位。

文件记录内容主要用途
run.log时间、级别、步骤名称、摘要信息人工快速查看
transcript.txtPowerShell 会话中的命令和屏幕输出还原执行过程
result.json运行状态、退出码、步骤结果、错误详情计划任务、监控程序或其他脚本读取

每次运行使用一个单独目录,例如:

C:\ProgramData\A5IDC\PowerShellLogs\
└─ 20250220-143015-123\
   ├─ run.log
   ├─ transcript.txt
   └─ result.json

使用运行编号作为目录名有两个好处:

  • 不会因为多个实例同时运行而覆盖同一个日志文件。
  • 可以根据运行时间快速定位对应的结果和错误。

如果脚本由普通用户手动运行,首次部署可以把日志放在脚本目录下的 logs 文件夹。如果脚本由计划任务、服务账号或自动化平台执行,则应选择该账号明确拥有写入权限的目录,例如:

C:\ProgramData\A5IDC\PowerShellLogs

不要直接假设运行账号一定能写入 C:\、C:\Windows 或其他受保护目录。

二、准备 PowerShell 环境和写入权限

1. 检查 PowerShell 版本

在即将执行脚本的同一个账号和同一个终端中运行:

$PSVersionTable | Select-Object PSVersion, PSEdition, OS, Platform

预期可以看到类似结果:

PSVersion PSEdition OS                         Platform
--------- --------- --                         --------
5.1.20348 Desktop   Microsoft Windows Server   Win32NT

或者在 PowerShell 7 中看到:

PSVersion PSEdition OS                         Platform
--------- --------- --                         --------
7.4.6     Core      Microsoft Windows Server   Win32NT

本文使用的 Start-Transcript、try/catch、ConvertTo-Json 和 Add-Content 在这两个版本中均可使用。首次部署时,应确认计划任务实际调用的是哪个解释器:

Get-Command powershell.exe, pwsh.exe -ErrorAction SilentlyContinue |
    Select-Object Name, Source, Version

Windows PowerShell 5.1 通常使用 powershell.exe,PowerShell 7 通常使用 pwsh.exe。不要在测试时使用 PowerShell 7,生产计划任务却指向 Windows PowerShell 5.1,否则编码、模块路径和可用命令可能出现差异。

2. 检查脚本执行策略

查看当前策略及其作用域:

Get-ExecutionPolicy -List

优先使用现有策略运行可信脚本,不建议为了让脚本运行而修改 LocalMachine 作用域。如果只是首次测试本地脚本,并且已经确认脚本来源可信,可以临时在当前 PowerShell 进程中设置:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

Process 作用域只对当前 PowerShell 进程有效,关闭窗口后自动失效,不会改变服务器的持久策略。验证当前进程的策略:

Get-ExecutionPolicy -Scope Process

预期结果:

Bypass

如果脚本来自外部文件或下载包,还应先检查文件来源和内容。不要把“临时绕过执行策略”作为长期权限方案,也不要对不明脚本直接执行。

3. 创建并测试日志目录

以脚本目录下的 logs 为例:

$logRoot = Join-Path (Get-Location) 'logs'

New-Item -ItemType Directory -Path $logRoot -Force | Out-Null

$testFile = Join-Path $logRoot 'write-test.txt'
'log write test' | Set-Content -LiteralPath $testFile -Encoding UTF8

Get-Item -LiteralPath $testFile |
    Select-Object FullName, Length, LastWriteTime

如果能够看到文件路径、文件长度和修改时间,说明当前账号具备基本写入权限。确认后可以删除这个测试文件:

Remove-Item -LiteralPath $testFile -Force

该删除命令只针对刚刚创建的测试文件。不要使用通配符删除整个日志目录。

三、部署可复用的日志脚本

创建文件 Invoke-LoggedTask.ps1,将以下内容保存到脚本目录。代码中的“检查脚本目录”只是一个无副作用的示例任务,实际部署时可以替换为需要执行的业务命令。

[CmdletBinding()]
param(
    [string]$LogRoot = (Join-Path $PSScriptRoot 'logs'),

    [switch]$TestFailure
)

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

$startedAt = Get-Date
$runId = $startedAt.ToString('yyyyMMdd-HHmmss-fff')
$runDir = Join-Path $LogRoot $runId

$logFile = Join-Path $runDir 'run.log'
$transcriptFile = Join-Path $runDir 'transcript.txt'
$resultFile = Join-Path $runDir 'result.json'

$transcriptStarted = $false
$runStatus = 'FAILED'
$exitCode = 1
$fatalError = $null
$steps = New-Object System.Collections.ArrayList

New-Item -ItemType Directory -Path $runDir -Force | Out-Null

function Write-RunLog {
    param(
        [Parameter(Mandatory)]
        [string]$Level,

        [Parameter(Mandatory)]
        [string]$Message
    )

    $timestamp = Get-Date -Format 'yyyy-MM-dd HH:mm:ss.fffK'
    $line = '{0} [{1}] {2}' -f $timestamp, $Level.ToUpper(), $Message

    Add-Content -LiteralPath $script:logFile `
        -Value $line `
        -Encoding UTF8

    Write-Host $line
}

function Convert-ErrorRecord {
    param(
        [Parameter(Mandatory)]
        [System.Management.Automation.ErrorRecord]$Record
    )

    $position = ''
    if ($null -ne $Record.InvocationInfo) {
        $position = $Record.InvocationInfo.PositionMessage
    }

    return [ordered]@{
        Message              = $Record.Exception.Message
        Category             = [string]$Record.CategoryInfo
        FullyQualifiedId    = $Record.FullyQualifiedErrorId
        Position             = $position
        ScriptStackTrace    = $Record.ScriptStackTrace
    }
}

function Add-StepResult {
    param(
        [Parameter(Mandatory)]
        [string]$Name,

        [Parameter(Mandatory)]
        [ValidateSet('SUCCESS', 'FAILED')]
        [string]$Status,

        [long]$DurationMs = 0,

        [string]$OutputText = '',

        [string]$ErrorText = ''
    )

    $entry = [ordered]@{
        Name       = $Name
        Status     = $Status
        DurationMs = $DurationMs
        Output     = $OutputText
        Error      = $ErrorText
    }

    $null = $script:steps.Add([pscustomobject]$entry)

    if ($Status -eq 'SUCCESS') {
        Write-RunLog -Level 'INFO' -Message "$Name succeeded in ${DurationMs}ms"
    }
    else {
        Write-RunLog -Level 'ERROR' -Message "$Name failed in ${DurationMs}ms"
    }
}

function Invoke-LoggedStep {
    param(
        [Parameter(Mandatory)]
        [string]$Name,

        [Parameter(Mandatory)]
        [scriptblock]$Action
    )

    $stopwatch = [System.Diagnostics.Stopwatch]::StartNew()

    try {
        $output = @(& $Action)

        $stopwatch.Stop()

        $outputText = '(no output)'
        if ($output.Count -gt 0) {
            $outputText = ($output | Out-String -Width 4096).Trim()
        }

        Add-StepResult `
            -Name $Name `
            -Status 'SUCCESS' `
            -DurationMs $stopwatch.ElapsedMilliseconds `
            -OutputText $outputText

        return $output
    }
    catch {
        $stopwatch.Stop()

        $errorInfo = Convert-ErrorRecord -Record $_
        $errorText = $errorInfo | ConvertTo-Json -Compress -Depth 5

        Add-StepResult `
            -Name $Name `
            -Status 'FAILED' `
            -DurationMs $stopwatch.ElapsedMilliseconds `
            -ErrorText $errorText

        throw
    }
}

try {
    Start-Transcript -Path $transcriptFile -Force | Out-Null
    $transcriptStarted = $true

    Write-RunLog -Level 'INFO' -Message "Run started. RunId=$runId"
    Write-RunLog -Level 'INFO' -Message "PowerShell=$($PSVersionTable.PSVersion)"
    Write-RunLog -Level 'INFO' -Message "LogDirectory=$runDir"

    $executionResult = Invoke-LoggedStep `
        -Name '检查脚本目录' `
        -Action {
            if ($TestFailure) {
                Get-Item -LiteralPath (
                    Join-Path $PSScriptRoot '__file_should_not_exist__.txt'
                ) -ErrorAction Stop
            }

            Get-ChildItem -LiteralPath $PSScriptRoot -ErrorAction Stop |
                Select-Object Name, Length, LastWriteTime
        }

    Write-RunLog -Level 'INFO' -Message 'All steps completed.'
    $runStatus = 'SUCCESS'
    $exitCode = 0
}
catch {
    $fatalError = Convert-ErrorRecord -Record $_

    try {
        Write-RunLog `
            -Level 'ERROR' `
            -Message ("Run failed: " + $fatalError.Message)
    }
    catch {
        # 日志写入本身失败时,避免覆盖原始异常
    }
}
finally {
    if ($transcriptStarted) {
        try {
            Stop-Transcript | Out-Null
        }
        catch {
            # Transcript 停止失败不覆盖原始任务错误
        }
    }
}

$endedAt = Get-Date

$resultObject = [ordered]@{
    RunId          = $runId
    Status         = $runStatus
    ExitCode       = $exitCode
    StartedAt      = $startedAt.ToString('o')
    EndedAt        = $endedAt.ToString('o')
    LogFile        = $logFile
    TranscriptFile = $transcriptFile
    ResultFile     = $resultFile
    FatalError     = $fatalError
    Steps          = @($steps)
}

$resultObject |
    ConvertTo-Json -Depth 8 |
    Set-Content -LiteralPath $resultFile -Encoding UTF8

Write-Host "Result file: $resultFile"

if ($exitCode -ne 0) {
    exit $exitCode
}

exit 0

代码中几个关键点

1. 使用独立运行目录

$runId 精确到毫秒,即使同一脚本连续运行,也不会直接覆盖之前的结果。日志路径通过参数传入,部署到不同服务器时无需修改核心逻辑。

2. 把非终止错误转成可捕获异常

PowerShell 中有些命令默认只写入错误流,并不会进入 catch。例如,文件不存在时,如果没有指定错误处理方式,脚本可能继续执行。

因此关键命令应明确指定:

Get-Item -LiteralPath 'C:\not-exist.txt' -ErrorAction Stop

脚本全局设置 $ErrorActionPreference = 'Stop',同时在关键命令上保留 -ErrorAction Stop,可以减少调用层级变化造成的行为差异。

3. 不只记录错误消息

Convert-ErrorRecord 同时保存以下内容:

  • 异常消息;
  • 错误类别;
  • FullyQualifiedErrorId;
  • 出错位置;
  • 脚本堆栈。

只记录 $_.Exception.Message 往往无法判断是哪一行、哪一个命令失败。对于首次部署,位置和堆栈信息尤其重要。

4. 用结果对象保存业务输出

Invoke-LoggedStep 会把步骤输出转换为文本写入 result.json,同时保留步骤名称、状态和耗时。对于需要被其他程序读取的结果,建议进一步在业务代码中返回自定义对象,而不是只输出一段人类可读文本。

四、首次运行和逐步验证

1. 先执行成功路径

使用 -File 方式启动,避免当前交互式会话受到脚本退出码处理的影响:

$scriptPath = (Resolve-Path .\Invoke-LoggedTask.ps1).Path
$logRoot = 'C:\ProgramData\A5IDC\PowerShellLogs'

powershell.exe -NoLogo -NoProfile `
    -File $scriptPath `
    -LogRoot $logRoot

$LASTEXITCODE

如果使用 PowerShell 7:

pwsh.exe -NoLogo -NoProfile `
    -File $scriptPath `
    -LogRoot $logRoot

$LASTEXITCODE

成功时预期退出码为:

0

控制台可能显示如下格式,时间和路径仅为结果格式示例:

2025-02-20 14:30:15.125+08:00 [INFO] Run started. RunId=20250220-143015-123
2025-02-20 14:30:15.180+08:00 [INFO] 检查脚本目录 succeeded in 42ms
2025-02-20 14:30:15.181+08:00 [INFO] All steps completed.
Result file: C:\ProgramData\A5IDC\PowerShellLogs\20250220-143015-123\result.json
0

2. 定位本次运行目录

$latestRun = Get-ChildItem -LiteralPath $logRoot -Directory |
    Sort-Object LastWriteTime -Descending |
    Select-Object -First 1

$latestRun | Select-Object FullName, LastWriteTime

检查目录中的三个文件:

Get-ChildItem -LiteralPath $latestRun.FullName |
    Select-Object Name, Length, LastWriteTime

预期至少包含:

Name             Length LastWriteTime
----             ------ -------------
run.log             ...
transcript.txt      ...
result.json         ...

3. 查看普通日志和结构化结果

Get-Content -LiteralPath (
    Join-Path $latestRun.FullName 'run.log'
)

读取 JSON:

$result = Get-Content -LiteralPath (
    Join-Path $latestRun.FullName 'result.json'
) -Raw | ConvertFrom-Json

$result | Select-Object RunId, Status, ExitCode, StartedAt, EndedAt
$result.Steps | Select-Object Name, Status, DurationMs

成功时重点确认:

Status   : SUCCESS
ExitCode : 0

如果后续由监控程序判断脚本是否成功,应优先读取 result.json 中的 Status 和 ExitCode,不要通过搜索 run.log 中是否出现某个中文词语来判断。

五、验证错误信息是否被保留

首次部署不能只验证成功路径,还应验证失败路径。脚本提供了 -TestFailure 参数,它会访问一个明确不存在的文件,不会修改系统内容。

执行:

powershell.exe -NoLogo -NoProfile `
    -File .\Invoke-LoggedTask.ps1 `
    -LogRoot 'C:\ProgramData\A5IDC\PowerShellLogs' `
    -TestFailure

$LASTEXITCODE

预期退出码为:

1

再次定位最新目录并读取结果:

$latestRun = Get-ChildItem -LiteralPath 'C:\ProgramData\A5IDC\PowerShellLogs' -Directory |
    Sort-Object LastWriteTime -Descending |
    Select-Object -First 1

$result = Get-Content -LiteralPath (
    Join-Path $latestRun.FullName 'result.json'
) -Raw | ConvertFrom-Json

$result | Select-Object RunId, Status, ExitCode
$result.FatalError
$result.Steps | Select-Object Name, Status, Error

预期应满足以下条件:

五、验证错误信息是否被保留配图

  • Status 为 FAILED;
  • ExitCode 为 1;
  • FatalError.Message 包含文件不存在或路径相关信息;
  • Steps[0].Status 为 FAILED;
  • run.log 中存在 ERROR 行;
  • transcript.txt 中保留本次会话的执行过程。

如果错误只出现在屏幕上,却没有出现在 result.json 或 run.log,说明实际业务命令没有进入统一的 try/catch,或者命令使用了非终止错误处理方式。

六、外部程序需要额外检查退出码

$ErrorActionPreference = 'Stop' 主要影响 PowerShell 命令和 PowerShell 错误流,不一定会因为外部程序返回非零退出码而自动触发 catch。

例如,执行 robocopy.exe、7z.exe 或其他命令行程序时,应同时保存输出并检查 $LASTEXITCODE:

$nativeResult = Invoke-LoggedStep `
    -Name '执行外部程序' `
    -Action {
        $output = @(
            & 'C:\Tools\example.exe' '--input' 'C:\Data\input.txt' 2>&1
        )

        $nativeExitCode = $LASTEXITCODE
        $outputText = ($output | Out-String -Width 4096).Trim()

        if ($nativeExitCode -ne 0) {
            throw "外部程序失败,退出码=$nativeExitCode,输出=$outputText"
        }

        $output
    }

这里的 2>&1 将标准错误合并到捕获变量中,便于在失败时把外部程序输出写入错误详情。判断外部程序是否成功时,应以它的退出码规则为准。

某些工具会使用非零退出码表示“有差异但不一定是故障”,例如文件比较、同步或扫描工具。此时不能机械地把所有非零值都当成失败,应根据该工具的退出码定义增加允许值,并在结果文件中明确记录:

$allowedExitCodes = @(0, 1)

if ($nativeExitCode -notin $allowedExitCodes) {
    throw "外部程序返回未允许的退出码:$nativeExitCode"
}

七、常见失败处理

日志目录无法写入

典型表现是:

Access to the path ... is denied.

处理顺序如下:

七、常见失败处理:日志目录无法写入配图

  1. 确认脚本实际由哪个账号运行;
  2. 检查日志目录的父目录是否存在;
  3. 使用该账号手动创建测试文件;
  4. 将日志路径改为该账号明确可写的目录;
  5. 只有在权限边界明确时,才调整目录权限。

不要直接给整个磁盘根目录或广泛用户组授予写入权限。若必须调整 ACL,应先记录原有权限,限定到具体目录,并在回滚时恢复原设置。

业务命令失败但脚本仍显示成功

通常有以下原因:

  • 命令没有使用 -ErrorAction Stop;
  • 业务函数捕获异常后没有重新 throw;
  • 外部程序返回非零退出码,但未检查 $LASTEXITCODE;
  • 只查看了屏幕输出,没有检查脚本退出码。

错误处理函数不应这样写:

try {
    Get-Item -LiteralPath 'C:\missing.txt' -ErrorAction Stop
}
catch {
    Write-Error $_
}

如果调用者需要感知失败,应在记录后继续抛出:

try {
    Get-Item -LiteralPath 'C:\missing.txt' -ErrorAction Stop
}
catch {
    Write-Error $_
    throw
}

中文日志出现乱码

先确认写入和读取使用的是同一套编码参数:

Get-Content -LiteralPath .\run.log -Encoding UTF8

Windows PowerShell 5.1 与 PowerShell 7 在默认编码行为上存在差异,因此脚本中已经显式指定:

-Encoding UTF8

如果日志要被旧版工具读取,需先确认该工具是否要求带 BOM 的 UTF-8,不能只根据文本编辑器显示结果判断编码正确。

transcript.txt 缺失但 run.log 存在

这通常表示 Start-Transcript 失败,可能原因包括:

  • 文件已被其他进程占用;
  • 传入的路径无效;
  • 运行账号没有创建文件的权限;
  • 同一目录被多个实例同时使用。

本文使用独立运行目录降低了并发覆盖风险。排查时先看 run.log 和 result.json,因为显式日志不应完全依赖 Transcript。

日志中出现密码或访问令牌

Start-Transcript 可能记录命令行中的参数和屏幕输出。不要把密码、令牌、连接字符串中的敏感字段直接拼接到命令或日志中。

例如,不要直接记录:

Write-RunLog -Level 'INFO' -Message "连接字符串=$connectionString"

应只记录不敏感的标识:

Write-RunLog -Level 'INFO' -Message "开始连接目标数据库:$serverName"

错误对象本身也可能包含敏感路径、请求地址或参数。写入日志前,应根据业务场景进行脱敏。

八、结果检查与上线前验收

首次运行完成后,至少检查以下内容:

  • PowerShell 版本与计划任务实际调用版本一致;
  • 日志根目录由运行账号可写;
  • 每次运行生成独立目录;
  • 成功运行的 result.json 中 Status 为 SUCCESS;
  • 成功运行的 ExitCode 为 0;
  • 失败测试的 Status 为 FAILED;
  • 失败测试的 ExitCode 不为 0;
  • 失败步骤包含错误消息、错误类别和出错位置;
  • run.log 能快速读懂执行顺序;
  • transcript.txt 可以还原会话过程;
  • 业务结果没有把密码、令牌或完整凭据写入日志;
  • 计划任务账号读取日志时使用的是绝对路径;
  • 日志文件路径没有依赖某个交互式用户的当前目录。

如果后续接入计划任务,建议使用绝对路径调用:

C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe `
    -NoLogo `
    -NoProfile `
    -File C:\A5IDC\Scripts\Invoke-LoggedTask.ps1 `
    -LogRoot C:\ProgramData\A5IDC\PowerShellLogs

计划任务的“起始于”目录不是可靠的路径来源,脚本、日志和依赖文件都应使用绝对路径或基于 $PSScriptRoot 计算的路径。

九、回滚和恢复检查项

本方案只增加脚本日志能力,不应修改数据库、服务配置或防火墙规则。首次部署失败时,可以按以下顺序回滚:

  1. 停止计划任务或自动化平台对该脚本的调用,避免回滚过程中继续产生新日志。
  2. 保留失败运行目录,先将其整体归档,不要立即删除。
  3. 将业务脚本恢复到部署前的备份版本。
  4. 如果只测试了 Process 作用域的执行策略,关闭对应 PowerShell 进程即可恢复;不需要修改计算机级策略。
  5. 如果新建的日志目录不再使用,只删除确认属于本次部署的空目录或已归档目录。
  6. 重新执行原有脚本或原有调用方式,确认业务功能恢复。
  7. 保留 result.json、run.log 和 transcript.txt,作为回滚后的问题记录。

删除目录前应明确影响范围,并先备份:

$runDir = 'C:\ProgramData\A5IDC\PowerShellLogs\20250220-143015-123'
$archive = 'C:\Temp\20250220-143015-123.zip'

Compress-Archive -LiteralPath $runDir -DestinationPath $archive -Force

确认压缩包可读取后,才考虑删除指定运行目录:

Remove-Item -LiteralPath $runDir -Recurse -Force

该命令只适用于已经确认路径准确、日志已备份且不再需要保留现场的目录。不要把 Remove-Item 与通配符组合后直接作用于整个日志根目录。

最终验收以“成功结果可读、失败结果可追踪、退出码可判断、敏感信息不泄露、原有业务可恢复”为准。

本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/6564.html

相关推荐