了解 VS Code 和 PowerShell 中的文件编码

使用 VS Code 创建和编辑 PowerShell 脚本时,务必使用正确的字符编码格式保存文件。

什么是文件编码以及它为什么很重要?

VS Code 管理人员向缓冲区中输入字符串与对文件系统读取/写入字节块之间的接口。 当 VS Code 保存文件时,它会使用文本编码来确定每个字符变为哪些字节。 有关详细信息,请参阅 about_Character_Encoding

同样,当 PowerShell 运行脚本时,必须将文件中的字节转换为字符以将文件重新构造为 PowerShell 程序。 由于 VS Code 写入文件,而 PowerShell 读取文件,因此它们需要使用相同的编码系统。 分析 PowerShell 脚本的这一过程是:字节 -> 字符 -> 标记 -> 抽象语法树 -> 执行 。

VS Code 和 PowerShell 都使用合理的默认编码配置进行安装。 但是,PowerShell 使用的默认编码已随着 PowerShell Core (v6.x) 的发布而更改。 若要确保在 VS Code 中使用 PowerShell 或 PowerShell 扩展时不会出现问题,需要正确配置 VS Code 和 PowerShell 设置。

编码问题的常见原因

当 VS Code 或脚本文件的编码与 PowerShell 的期望编码不匹配时,会出现编码问题。 PowerShell 无法自动确定文件编码。

如果使用的字符不在 7 位 ASCII 字符集中,则更可能出现编码问题。 例如:

  • 扩展的非字母字符,如长破折号 ()、不间断空格 ( ) 或左双引号 (")
  • 重音拉丁字符(Éü
  • 非拉丁字符,如西里尔文(ДЦ
  • CJK 字符(

编码问题的常见原因有:

  • VS Code 和 PowerShell 的编码尚未更改,仍使用默认设置。 对于 PowerShell 5.1 及更低版本,默认编码与 VS Code 的编码不同。
  • 另一个编辑器已打开,并采用新编码覆盖了文件。 ISE 通常会发生这种情况。
  • 文件采用与 VS Code 或 PowerShell 应使用的编码不同的编码签入了源代码管理。 当协作者使用具有不同编码配置的编辑器时,可能会发生这种情况。

如何判断出现了编码问题

编码错误通常表现为脚本中的分析错误。 如果在脚本中发现奇怪的字符序列,则这可能是问题所在。 在以下示例中,短划线 () 显示为字符 â€"

Send-MailMessage : A positional parameter cannot be found that accepts argument 'Testing FuseMail SMTP...'.
At C:\Users\<User>\<OneDrive>\Development\PowerShell\Scripts\Send-EmailUsingSmtpRelay.ps1:6 char:1
+ Send-MailMessage â&euro;"From $from â&euro;"To $recipient1 â&euro;"Subject $subject  ...
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : InvalidArgument: (:) [Send-MailMessage], ParameterBindingException
    + FullyQualifiedErrorId : PositionalParameterNotFound,Microsoft.PowerShell.Commands.SendMailMessage

发生此问题的原因是 VS Code 将采用 UTF-8 的字符 编码为字节 0xE2 0x80 0x93。 当这些字节解码为 Windows-1252 时,它们会被解释为字符 â&euro;"

可能会看到的一些奇怪字符序列包括:

  • â&euro;"(而不是
  • â&euro;"(而不是
  • Ä2(而不是 Ä
  • Â(而不是 (不间断空格))
  • Ã&copy;(而不是 é

此便捷参考列出了指示 UTF-8/Windows-1252 编码问题的常见模式。

VS Code 中的 PowerShell 扩展与编码的交互方式

PowerShell 扩展通过多种方式与脚本进行交互:

  1. 在 VS Code 中编辑脚本时,内容由 VS Code 发送到扩展。 语言服务器协议要求此内容采用 UTF-8 进行传输。 因此,扩展不可能获取错误的编码。
  2. 当脚本直接在集成控制台中执行时,它们直接由 PowerShell 从文件读取。 如果 PowerShell 的编码与 VS Code 的编码不同,则可能会出错。
  3. 当在 VS Code 中打开的一个脚本引用未在 VS Code 中打开的另一个脚本时,扩展会回退到从文件系统加载该脚本的内容。 PowerShell 扩展默认为 UTF-8 编码,但使用字节顺序标记(或 BOM)检测来选择正确编码。

当采用无 BOM 式格式的编码(如没有 BOM 的 UTF-8Windows-1252)时,会出现问题。 PowerShell 扩展默认为 UTF-8。 扩展无法更改 VS Code 的编码设置。 有关详细信息,请参阅问题 #824

选择正确编码

不同的系统和应用程序可以使用不同的编码:

  • 在 .NET Standard 中、Web 上以及 Linux 领域中,UTF-8 现在是主流编码。
  • 许多 .NET Framework 应用程序使用 UTF-16。 由于历史原因,这有时称为“Unicode”,该术语现在是指包括 UTF-8 和 UTF-16 在内的广泛标准
  • 在 Windows 中上,早于 Unicode 出现的许多本机应用程序在默认情况下继续使用 Windows-1252。

Unicode 编码也具有字节顺序标记 (BOM) 的概念。 BOM 在文本开头出现,用于向解码器告知文本所使用的编码。 对于多字节编码,BOM 还指示编码的字节顺序。 BOM 设计为很少出现在非 Unicode 文本中的字节,从而当 BOM 存在时可以合理地猜测文本是 Unicode。

BOM 是可选的,其采用在 Linux 领域中并不普遍,因为到处都在使用可靠的 UTF-8 约定。 大多数 Linux 应用程序假设文本输入采用 UTF-8 进行编码。 虽然许多 Linux 应用程序可识别并正确处理 BOM,不过有一些应用程序无法这样做,从而导致使用这些应用程序操作的文本中出现异常。

因此

  • 如果主要使用 Windows 应用程序和 Windows PowerShell,则应优先使用诸如具有 BOM 的 UTF-8 或 UTF-16 这类编码。
  • 如果跨平台工作,则应优先使用具有 BOM 的 UTF-8。
  • 如果主要在与 Linux 关联的环境中工作,则应优先使用不具有 BOM 的 UTF-8。
  • Windows-1252 和拉丁语-1 本质上是旧编码,应尽可能避免使用。 但是,某些较旧的 Windows 应用程序可能依赖于它们。
  • 另外值得注意的是,脚本签名依赖于编码,这意味着签名脚本中的编码更改需要重新签名。

配置 VS Code

VS Code 的默认编码是不具有 BOM 的 UTF-8。

若要设置 VS Code 的编码,请转到 VS Code 设置 (Ctrl+,) 并设置 "files.encoding" 设置:

"files.encoding": "utf8bom"

一些可能值有:

应在 GUI 视图中看到适用于此内容的下拉列表,或是在 JSON 视图中看到其完成。

还可以添加以下内容以尽可能自动检测编码:

"files.autoGuessEncoding": true

如果不希望这些设置影响所有文件类型,则 VS Code 还允许按语言进行配置。 创建在 [<language-name>] 字段中放置设置,可以配置特定于语言的设置。 例如:

"[powershell]": {
    "files.encoding": "utf8bom",
    "files.autoGuessEncoding": true
}

你可能还要考虑为 Visual Studio Code 安装 Gremlins 跟踪器。 此扩展显示某些很容易损坏的 Unicode 字符,因为它们不可见或看起来像其他普通字符。

配置 PowerShell

PowerShell 的默认编码因版本而异:

  • 在 PowerShell 6+ 中,默认编码在所有平台上都是不具有 BOM 的 UTF-8。
  • 在 Windows PowerShell 中,默认编码通常是 Windows-1252,这是latin-1 的扩展,也称为 ISO 8859-1。

在 PowerShell 5+ 中,可以使用以下方法查找默认编码:

[psobject].Assembly.GetTypes() | Where-Object { $_.Name -eq 'ClrFacade'} |
  ForEach-Object {
    $_.GetMethod('GetDefaultEncoding', [System.Reflection.BindingFlags]'nonpublic,static').Invoke($null, @())
  }

以下脚本用于确定 PowerShell 会话对不具有 BOM 的脚本推断出何种编码。

$badBytes = [byte[]]@(0xC3, 0x80)
$utf8Str = [System.Text.Encoding]::UTF8.GetString($badBytes)
$bytes = [System.Text.Encoding]::ASCII.GetBytes('Write-Output "') + [byte[]]@(0xC3, 0x80) + [byte[]]@(0x22)
$path = Join-Path ([System.IO.Path]::GetTempPath()) 'encodingtest.ps1'

try
{
    [System.IO.File]::WriteAllBytes($path, $bytes)

    switch (& $path)
    {
        $utf8Str
        {
            return 'UTF-8'
            break
        }

        default
        {
            return 'Windows-1252'
            break
        }
    }
}
finally
{
    Remove-Item $path
}

可以更普遍地使用配置文件设置将 PowerShell 配置为使用给定编码。 请参阅以下文章:

无法强制 PowerShell 使用特定输入编码。 如果未提供 BOM,则在 Windows(区域设置为 en-US)上运行的 PowerShell 5.1 及更低版本默认使用 Windows-1252 编码。 其他区域设置可能使用不同的编码。 为了确保互操作性,最好使用具有 BOM 的 Unicode 格式保存脚本。

重要

涉及 PowerShell 脚本的任何其他工具都可能会受到编码选择的影响,或是将脚本重新编码为另一种编码。

现有脚本

文件系统上已有的脚本可能需要重新编码为新的所选编码。 在 VS Code 底部栏中,会看到 UTF-8 标签。 单击它可打开操作栏并选择“保存时使用编码” 。 现在可以为该文件选取新编码。 有关完整说明,请参阅 VS Code 的编码

如果需要重新编码多个文件,则可以使用以下脚本:

Get-ChildItem *.ps1 -Recurse | ForEach-Object {
    $content = Get-Content -Path $_
    Set-Content -Path $_.Fullname -Value $content -Encoding UTF8 -PassThru -Force
}

PowerShell 集成脚本环境 (ISE)

如果还使用 PowerShell ISE 编辑脚本,则需要在其中同步编码设置。

ISE 应遵循 BOM,但也可以使用反射来设置编码。 请注意,这不会在启动之间保持。

源代码管理软件

一些源代码管理工具(如 git)会忽略编码;git 只跟踪字节。 其他工具(如 Azure DevOps 或 Mercurial)可能不会忽略编码。 甚至一些基于 git 的工具也依赖于文本解码。

在这种情况下,请确保:

  • 在源代码管理中配置文本编码以匹配 VS Code 配置。
  • 确保所有文件都采用相关编码签入到源代码管理中。
  • 应注意通过源代码管理收到的编码更改。 这种情况的一个重要迹象是有差异指示更改,但似乎没有任何内容发生更改(因为字节更改,但字符未更改)。

协作者环境

在配置源代码管理的基础上,确保你所共享的任何文件上的协作者没有通过重新编码 PowerShell 文件来替代你的编码的设置。

其他程序

读取或写入 PowerShell 脚本的其他任何程序都可能会对它重新编码。

一些示例如下:

  • 使用剪贴板复制和粘贴脚本。 这是以下这类情形中十分常见:
    • 将脚本复制到 VM 中
    • 从电子邮件或网页中复制脚本
    • 将脚本复制到 Microsoft Word 或 PowerPoint 文档中,或从这类文档中复制脚本
  • 其他文本编辑器,如:
    • 记事本
    • vim
    • 任何其他 PowerShell 脚本编辑器
  • 文本编辑实用工具,如:
    • Get-Content/Set-Content/Out-File
    • PowerShell 重定向运算符,如 >>>
    • sed/awk
  • 文件传输程序,如:
    • Web 浏览器(下载脚本时)
    • 文件共享

其中一些工具以字节(而不是文本)进行处理,而其他工具提供编码配置。 在需要配置编码的情况下,需要使它与编辑器编码相同,以防止出现问题。

有关 PowerShell 中的编码的其他资源

有其他几篇有关在 PowerShell 中编码和配置编码的很好的文章值得一读: