PowerShell 写入文件："Out-File" 与文件输出技巧

PowerShell 中输出的入门

熟悉 PowerShell 的人都知道：PowerShell 命令的输出默认会显示在终端中。不过，可能会有一些情况让你希望将输出重定向或保存到文件。

• 命令可能会返回大量数据，而这些数据在实时处理时会比较难处理。你可以将这些数据重定向或保存起来，以便在方便的时候进行处理或查看。
• 为了在另一个进程或脚本中使用某个命令的结果，你可以使用“PowerShell output to file”命令将输出保存到文件或变量中，方便后续重复使用。
• 计划任务或其他自动化任务通常都在后台运行。你可能无法实时看到输出，因此将其保存下来可以让你稍后再查看。
• 有时，输出内容可能包含比你所需更多的信息。因此，你可以将其重定向或保存，以便进行筛选和格式化。
• 当你在远程系统上运行命令时，可能无法访问控制台来查看实时输出。保存或重定向可以为你提供远程系统发生了什么的记录。
• 组织会根据系统状态、配置或性能指标生成报告。使用 PowerShell，他们可以查询系统数据，生成报告，并将其输出到文件中以便将来审阅。
• PowerShell 可用于收集硬件和软件清单信息，用于资产管理和合规。随后，可以将这些数据输出到文件中，以提高可视性并简化管理。
• 在自动化任务时，必须跟踪所采取的操作以及结果。将输出重定向到文件有助于为审计创建日志。
• 如果脚本失败，你需要知道根本原因。通过保存输出，你可以在之后回顾，以进行错误处理、调试和故障排查。

简而言之，重定向或保存 PowerShell 输出可以提高工作效率，帮助调试，提供有用的日志，并促进自动化，尤其是在复杂工作流程或处理大型数据集时。

将 PowerShell 结果输出到文件的核心方法

Out-File Cmdlet

在 PowerShell 中将内容写入文本文件的方法通常使用 Out-File cmdlet，将命令结果（输出）直接发送到文件中。在最简单的用法中，Out-File 需要指定用于写入输出的路径和文件名。

默认情况下，如果在指定路径下存在同名文件，则该 cmdlet 会覆盖该文件；如果不存在，则会创建一个新文件。

Out-File 语法

以下是 Out-File cmdlet 的基本语法：

      Out-File
[-FilePath] <cadena>
[[-Encoding] <Encoding>]
[-Append]
[-Force]
[-NoClobber]
[-Width <int>]
[-NoNewline]
[-InputObject <psobject>]
[-WhatIf]
[-Confirmar]
[<CommonParameters>]
      

参数

PowerShell 的 Out-File cmdlet 接受以下参数：

使用案例

要将输出直接写入文件而不是显示在屏幕上，你可以使用 PowerShell 将输出写入文件的方法：将 Out-File cmdlet 追加到 PowerShell 命令或变量后面。通过将 Out-File 直接追加到字符串上，这种技术同样可用于将文本字符串写入文件。

将 Out-File 追加到 PowerShell cmdlet

要获取正在运行的进程列表，并使用 PowerShell 的 save output to file 方法，请按照以下示例将输出保存到 C:\Temp 文件夹中的名为 “Processes” 的文本文件中：

Get-Process | Out-File -FilePath C:\Temp\processes.txt

在这里，Get-Process cmdlet 会列出所有正在运行的进程。借助 PowerShell 将管道输出写入文件的功能，你可以将命令输出立即保存到文本文件中，以便稍后进行分析。

将 Out-File 追加到文本字符串

要使用 PowerShell 的“写入字符串到文件”(write string to file) 方法来写入字符串，例如将“Hello, World!”添加到 C:\Temp 位置下名为“Test”的文本文件中，请使用以下 cmdlet：

"Hello, World!" | Out-File -FilePath C:\Temp\Test.txt

如果文件不存在，将会创建。 如果文件已存在，默认情况下会覆盖其内容。

将 Out-File 追加到变量

您也可以将 Out-File cmdlet 与变量一起使用。例如：

$variable | Out-File -FilePath "C:\path\to\file.txt"

这里，$variable 是要发送到文件的数据变量（例如，将 PowerShell 输出到文本文件，或命令输出）。

重定向运算符（> 和 >>）

PowerShell 中的重定向运算符（> 和 >>）是 Out-File cmdlet 的一种简单且快速的替代方案，使您能够将输出重定向到文件。

• > 运算符等同于不带任何额外参数的 Out-File cmdlet。若文件已存在则会覆盖该文件；若不存在则会创建一个新的文件。
• >> 运算符等同于 Out-File -Append。若文件已存在，则会将输出追加到文件末尾；若文件不存在，则会创建一个新的文件。

这些运算符还有其他用途，例如重定向错误或详细输出流，但这超出了本文的范围。

基本语法

使用运算符的基本语法如下：

<Command> > <Path> # 覆盖

<Command> >> <Path> # 追加

请注意，重定向运算符不使用任何参数。

示例 1 – 使用 > 运算符

此 cmdlet 会将 Get-Process 的输出写入 Processes.txt 文件，并在目标位置已存在同名文件时覆盖其现有内容。

Get-Process > C:\Temp\Processes.txt

示例 2 – 使用 >> 运算符

此 cmdlet 会在不覆盖现有内容的情况下，将当前日期和时间追加到 log.txt 文件末尾。

Get-Date >> C:\Temp\log.txt

如果在指定路径下不存在名为 log.txt 的文件，则会创建该文件，并将当前日期和时间写入其中。

Out-File Cmdlet 与重定向运算符（> 和 >>）的区别

Out-File cmdlet 和重定向运算符都可以将 PowerShell 的输出写入文件并追加。两者之间的关键区别如下所述。

何时使用各方法

相比之下，Out-File cmdlet 更灵活，适合用于复杂脚本，并提供编码、宽度（Width）以及覆盖控制等选项。然而，重定向运算符对于不需要自定义的快速输出任务来说更快、更方便。以下是简要指南，帮助你了解何时应该使用各自的方法。

何时使用 Out-File cmdlet

• 需要指定特定编码（例如 ASCII、UTF8、Unicode）
• 避免覆盖文件（使用 -NoClobber）
• 需要控制输出的行宽（使用 -Width）
• 在追加模式下，同时保持其他输出控制选项

何时使用 > 和 >>

• 当你希望在不进行额外格式化或编码的情况下，快速将输出重定向时
• 希望在覆盖（>）或追加（>>）现有文件时

高级文件输出技术

管理覆盖写入

默认情况下，Out-File cmdlet 如果在指定路径下存在同名文件，则会覆盖该文件；如果不存在，则会创建一个新文件。

为了防止覆盖现有文件，可以使用 PowerShell 的写入文件追加方法，方式有两种：

• 将输出追加到现有文件
• 防止覆盖写入：因此现有文件不会被覆盖，输出也不会保存到文件中。

追加输出

在 Out-File cmdlet 中使用 -Append 参数，可在不覆盖指定文件现有内容的情况下，将新的输出追加到该文件末尾。例如，当你希望在不丢失先前数据的情况下增量记录事件时，这尤其有用。

此命令会将 System 日志中最新的 5 条记录追加到 event_log.txt 文件中。

Get-EventLog -LogName System -Newest 5 | Out-File -FilePath C:\Temp\event_log.txt -Append

你也可以使用重定向运算符 >> 将输出追加到现有文件中。在下面的示例中，你本地计算机上的服务状态及详细信息会追加到 log.txt 文件的内容中。

Get-Service >> C:\Temp\log.txt

防止覆盖

使用 Out-File cmdlet 时搭配 -NoClobber 参数以防止覆盖。因此，如果在指定位置已存在同名文件，PowerShell 将不会覆盖它，而是抛出错误。这有助于保护重要文件。

以下命令会尝试在 Temp 文件夹中创建一个名为 log.txt 的文件。但如果该名称的文件已存在，将显示错误，并且不会将输出保存到文件中。

Get-Service | Out-File -FilePath C:\Temp\log.txt -NoClobber

强制覆盖

有时由于文件是只读的，你无法使用 PowerShell cmdlet 的输出来覆盖现有文件的内容。遇到这种情况，请在 Out-File cmdlet 中使用 -Force 参数来覆盖只读文件。

该 cmdlet 会将服务信息写入 Services.txt 文件，并确保如果 Services.txt 已存在，即使它是只读文件也会被覆盖。

Get-Service | Out-File -FilePath C:\Temp\Services.txt -Force

输出格式和编码

PowerShell 的 Out-File cmdlet 提供选项，可自定义输出格式和编码。

格式化输出

Out-File cmdlet 可能无法按预期显示输出，尤其是在输出包含多列时。要获得格式化、易读的输出，你可以调整宽度或使用 Format-Table cmdlet。

示例 1 – 设置宽度

使用带有 Out-File 的 -Width 参数来指定输出文件的行宽（默认是 80 个字符）。

此 cmdlet 会将服务信息写入 Services.txt 文件，并将行宽设置为 200 个字符。这使得输出更宽而不需要换行。

Get-Service | Out-File -FilePath C:\Temp\Services.txt -Width 200

示例 2 – 使用 Format-Table 进行格式化

在将数据发送到 Out-File cmdlet 之前，请使用 Format-Table cmdlet 对数据进行结构化。

此 cmdlet 使用 Format-Table -AutoSize，可自动调整列宽以提高可读性。

Get-Service | Format-Table -AutoSize | Out-File -FilePath C:\Temp\Services.txt

设置编码

在使用 Out-File cmdlet 时对 PowerShell 的输出进行编码，可以确保数据在不同系统和应用程序中被正确解析、显示，并保持兼容性。

-Encoding 参数用于指定输出文本在文件中的编码方式。常见的编码类型包括：

• UTF8 – 常用于 Web 应用，支持所有字符。
• ASCII – 仅限基础英文字符，体积紧凑但限制较多。
• Unicode (UTF-16) – 适用于 Windows 兼容性，能够处理多种特殊字符、符号和国际文本，但占用空间更大。
• Default – 使用系统的默认编码，可能会因情况而不同，并且在不同平台上可能难以预测。

示例 1 — 使用 UTF-8 编码

如果输出文件包含特殊字符，或该文件将用于 UTF-8 作为标准编码的环境，建议使用 UTF-8 编码。

该 cmdlet 会检索系统中的服务列表，并在将文件编码设置为 UTF-8 的同时，将相关信息输出到 Services.txt 文件。

Get-Service | Out-File -FilePath C:\Temp\Services.txt -Encoding UTF8

示例 2 — 使用 ASCII 编码

ASCII 编码通常用于更简单的文本文件。

此 cmdlet 会检索系统中的服务列表，并将输出结果通过管道传送到 Services.txt 文件。-Encoding 参数用于将输出转换为 ASCII 格式。

Get-Service | Out-File -FilePath C:\Temp\Services.txt -Encoding ASCII

处理特定的输出流

Out-File cmdlet 会将命令或脚本的成功结果写入文件。但它不会将错误、警告或特定类型的消息写入文件。可以使用重定向运算符实现这一点，该运算符允许你指定要将哪个流输出到文件。

示例 1 — 将错误消息发送到文件

此命令尝试列出（ls）名为 Readme 的文件。如果你不指定路径，它会在当前目录中查找该文件。若文件不存在，将生成错误消息。2> 运算符会将该错误重定向到名为 error.log 的文件。结果是：错误不会在屏幕上显示，而是保存到 Temp 文件夹中的 error.log。

ls Readme 2> C:\Temp\error.log

示例 2 — 将警告发送到文件

在 PowerShell 中，警告流是编号为 3 的流。你可以使用 3> 将警告重定向到文件：如下所示：

# 生成警告的命令

<Your-Command> 3> C:\Temp\warning_log.txt

用于输出的替代方法

Set-Content 和 Add-Content Cmdlet

Set-Content 和 Add-Content cmdlet 是将输出写入文件的另一种方法。

• Set-Content 会用提供的新内容覆盖文件中现有的内容。如果文件不存在，它会创建该文件。
• Add-Content 会将新内容追加到现有文件内容的末尾。如果文件不存在，它会创建该文件，但不会替换现有内容。

Set-Content cmdlet

使用 Set-Content cmdlet 将文件内容写入或用新内容替换。

此 cmdlet 会覆盖 Test.txt 文件中的现有内容。-Value 参数指定将用于替换现有内容的内容或文本。

Set-Content -Path C:\Temp\Test.txt -Value "在此处添加内容"

Add-Content cmdlet

使用 Add-Content cmdlet 可向文件添加内容，这意味着你可以在不覆盖现有文件的情况下，将新数据追加到已有文件中。Add-Content 也可以一次向多个文件追加内容。

就像 Out-File cmdlet 和重定向运算符一样，如果不存在同名文件，Add-Content cmdlet 会创建一个新文件。

示例 1 — 向文件追加文本

此 cmdlet 会向 Test.txt 文件添加新的文本。-Value 参数指定要追加到文件中的内容或文本。

Add-Content -Path C:\Temp\Test.txt -Value "要添加的新行"

如果文件是只读的，则必须使用 -Force 参数以允许添加内容。

示例 2 — 向多个文件追加文本

要将相同内容添加到多个文件，您有几种选择。

• 在路径中使用通配符以指定要更新的文件
• 排除不想更新的文件名称

此 cmdlet 会将当前日期添加到 Temp 文件夹中所有 .txt 文件中，但不包括文件名中包含 test 的文件：

Add-Content -Path C:\Temp\files\*.txt -Value (Get-Date) -Exclude "test*"

示例 3 — 添加多行文本

该命令会向 Test.txt 文件添加多行文本。

      $lines = @(
"Line 1: Details",
"Line 2: Specific Details"
)
Add-Content -Path C:\Temp\Test.txt -Value $lines
      

.NET 类

您可以使用 .NET 类将输出生成到文件中，尤其是在涉及大数据处理的高级场景中。 这些类包括：

• BinaryWriter – 将基础数据类型以二进制形式写入流。
• StreamWriter – 用于以特定编码将字符写入流。通常用于创建或修改文本文件。
• StringWriter – 将信息写入字符串。使用该类时，PowerShell 会将字符串信息存储到 StringBuilder 对象中。

在 C# 中使用 StreamWriter 类将输出发送到文件非常简单。下面的示例展示了你可以如何使用它。

      # Get the directories in C:\
$Dirs = Get-ChildItem -Path C:\ -Directory
# Open a stream writer
$File = 'C:\Temp\Dirs.txt'
$Stream = [System.IO.StreamWriter]::new($File)
# Write the folder names for these folders to the file
foreach($Dir in $Dirs) {
$Stream.WriteLine($Dir.FullName)
}
# Close the stream
$Stream.Close()
      

该脚本执行以下步骤：列出 C:\ 驱动器上的目录，并将它们的路径保存到文本文件中：

步骤 1：

$Dirs = Get-ChildItem -Path C:\ -Directory

这一行使用带有 -Directory 参数的 Get-ChildItem，只获取 C:\ 驱动器中的目录（不包含文件）。结果会以目录对象列表的形式存储到 $Dirs 变量中。

步骤 2：

$File = 'C:\Temp\Dirs.txt'

$Stream = [System.IO.StreamWriter]::new($File)

这些行会设置一个文件路径（C:\Temp\Dirs.txt），用于保存目录列表，然后初始化一个 StreamWriter 对象以写入该文件。该对象会被分配给 $Stream。

步骤 3：

foreach($Dir in $Dirs) {

$Stream.WriteLine($Dir.FullName)

}

该循环会遍历 $Dirs 中的每个目录对象。对于每个目录，它都会使用 $Stream.WriteLine 将完整路径（$Dir.FullName）写入文件。

第 4 步：

$Stream.Close()

在写入所有目录路径之后，脚本会关闭 StreamWriter。

PowerShell 文件输出最佳实践

设置正确的行宽以避免内容被截断

应在 PowerShell 中使用 -Width 参数设置正确的行宽，以防止长行被截断，并确保文件输出按预期进行格式化。

Out-File cmdlet 中的 -Width 参数用于控制输出中每行的最大字符数。默认情况下它设置为 80 个字符，这可能会截断更长的行。例如，你可以将宽度增加到 200 个字符，如下所示：

Get-Process | Out-File -FilePath "output.txt" -Width 200

请考虑以下内容：

• 为避免不必要的空白或内容被截断，请设置 -Width 以匹配最长的行。对大多数输出而言，120–200 个字符的宽度通常就能很好地工作。
• 对于列很多的数据（例如 CSV 文件），请设置更大的宽度以容纳整行内容。
• 在管道（pipeline）中，使用 Out-String -Width 控制行宽，确保在通过管道传递到 Out-File 之前，整行都能落在指定宽度内。

设置正确的编码

PowerShell 使用的默认编码会因所使用的 cmdlet 和 PowerShell 版本而有所不同。下表显示了所使用的默认编码：

建议使用 UTF-8 编码以确保跨系统兼容性。然而，对于旧版系统，你可能需要指定 -Encoding ASCII 或 -Encoding Unicode。

使用 $PSDefaultParameterValues 在各脚本中设置默认值

PowerShell 中的 $PSDefaultParameterValues 允许你为脚本和会话中的参数设置默认值，从而在不反复指定选项的情况下实现一致性。

下面介绍如何为 Out-File 设置全局默认值，使其使用 UTF8 编码并采用更宽的宽度。

$PSDefaultParameterValues["Out-File:Encoding"] = "UTF8"

$PSDefaultParameterValues["Out-File:Width"] = 200

将 Out-File 与 Format-Table 和 Format-List 结合，以获得更清晰的结构化输出

将 Out-File cmdlet 与 Format-Table 或 Format-List 结合，是生成结构清晰、易于阅读的文本输出文件的好方法。

Format-Table

Format-Table 最适合具有清晰“行与列”结构的数据。它会生成有条理、易于阅读的类似表格的格式。不过，要将其与 Out-File cmdlet 一起使用，请考虑以下内容：

• 使用 -Property 参数只指定所需的列。这将防止输出文件变得杂乱无章。
• 使用 -AutoSize 参数优化列宽以适配内容。这样可以减少多余的空白或被截断的情况。
• 使用 -Width 参数防止内容被截断，并保持输出对齐。

下面是一个示例：

Get-Process | Format-Table -Property Name, ID, CPU, WS -AutoSize | Out-File -FilePath "ProcessList.txt" -Width 200

Format-List

Format-List 以纵向方式显示数据，每行显示一个属性。 当你有很多属性或包含较长数值的字段时，可使用该格式以避免截断这些值。该格式适用于报表和详细日志。

下面是将 Format-List 与 Out-File 一起使用的示例：

Get-Process | Format-List -Property Name, ID, CPU, StartTime | Out-File -FilePath "DetailedProcessList.txt"

与 Format-Table 一样，只选择你需要的属性。

使用 Test-Path 在写入前先验证文件是否存在，以防止文件冲突

在尝试向文件写入之前先检查文件是否存在始终是明智的做法。这样可以避免意外覆盖，并在文件已存在时决定该怎么处理。PowerShell 中的 Test-Path cmdlet 可让你检查文件是否存在。

以下是你应当遵循的步骤：

1. 将文件路径分配给一个变量。
2. 使用 Test-Path cmdlet 检查文件是否存在。
3. 决定要追加（append）、覆盖（overwrite）、重命名（rename）还是跳过写入。
4. 使用 Out-File cmdlet 来创建文件或写入文件。

常见陷阱与解决方案

PowerShell 中的 Out-File cmdlet 有时会导致常见陷阱，尤其是在文件处理、编码以及追加内容（appending content）方面。下面将讨论一些常见问题及其解决方案。

通过覆盖操作避免数据丢失

默认情况下，如果已存在同名文件，Out-File cmdlet 会在不警告的情况下覆盖现有文件的内容。避免这种情况的方法包括：

• 使用 -Append 参数将输出追加到现有文件，而不是覆盖它。
• 使用 Test-Path 检查文件是否存在，然后决定如何使用 Out-File 继续操作。

通过不当的编码避免数据丢失

默认情况下，Out-File 在 PowerShell 5.1 及更早版本中使用 Unicode 编码。在 PowerShell Core 及更高版本中使用 UTF-8 编码。

默认编码可能与您的系统或期望使用其他编码的应用程序不兼容。因此，您应使用 -Encoding 参数显式指定编码。

在长时间运行的脚本中管理输出，以确保性能

在诸如 PowerShell ISE 这类受限环境中，使用 Out-File cmdlet 运行脚本可能会导致例如以下问题：

• 未能按预期处理复杂的数据结构
• 较长的输出会被截断

要管理较长的输出，可以：

• 使用 -Width 参数设置合适的宽度
• 使用 Export-Csv 或 ConvertTo-Json cmdlet 将复杂数据导出为结构化格式，如 CSV 或 JSON

在 PowerShell 脚本中处理日志记录和错误处理

有时文件正在被使用，或被其他进程锁定。此时，由于无法写入该文件，Out-File cmdlet 会抛出错误。你可以使用 try/catch 块来处理这种以及其他错误。示例如下：

      $content = "Write content to file"
$filePath = "C:\Temp\Errors.txt"
try {
$content | Out-File -FilePath $filePath
Write-Host "File written successfully."
} catch {
Write-Host "File is in use or locked by another process."
}