关于 PowerShell 配置

简短描述

PowerShell 的配置文件，替换注册表配置。

详细描述

powershell.config.json 文件包含 PowerShell 的配置设置。 PowerShell 在启动时加载此配置。这些设置也可以在运行时修改。以前，这些设置存储在 PowerShell 的 Windows 注册表中，但现在包含在一个文件中，以便在 macOS 和 Linux 上启用配置。

设置摘要

powershell.config.json 文件可以包含以下键：

DisableImplicitWinCompat

WindowsPowerShellCompatibilityModuleDenyList

WindowsPowerShellCompatibilityNoClobberModuleList

ExperimentalFeatures

LogChannels

LogIdentity

LogKeywords

LogLevel

Microsoft.PowerShell:ExecutionPolicy

PSModulePath

ExecutionPolicy

ConsoleSessionConfiguration

ModuleLogging

ProtectedEventLogging

ScriptBlockLogging

ScriptExecution

Transcription

UpdatableHelp

并非所有密钥都适用于所有平台。 PowerShellPolicies 键包含反映 Window 组策略管理的设置的子键。当在 JSON 文件的根级别定义时，这些子项也适用于所有平台。

警告

配置文件中无法识别的键或无效值将被忽略。如果 powershell.config.json 文件包含无效的 JSON，PowerShell 无法启动交互式会话。如果发生这种情况，您必须修复配置文件。

配置范围

可以为所有用户或单个用户级别定义配置设置。

所有用户（共享）配置

$PSHOME 目录中的 powershell.config.json 文件定义从该 PowerShell 安装运行的所有 PowerShell 会话的配置。

笔记

$PSHOME 位置定义为与执行 System.Management.Automation.dll 程序集相同的目录。这也适用于托管的 PowerShell SDK 实例。

当前用户（每用户）配置

您还可以通过将文件放置在用户范围的配置目录中来基于每个用户配置 PowerShell。可以使用命令 Split-Path $PROFILE.CurrentUserCurrentHost 跨平台找到用户配置目录。

范围优先级

在 Windows 上，Windows 组策略管理的设置优先于配置文件中的设置。非 Windows 平台上不存在组策略。

在组策略之后，在AllUsers 级别定义的设置优先于为CurrentUser 级别定义的设置。

Windows 特定设置

以下设置仅适用于 Windows 平台。

DisableImplicitWinCompat

WindowsPowerShellCompatibilityModuleDenyList

WindowsPowerShellCompatibilityNoClobberModuleList

ExecutionPolicy

PowerShellPolicies

禁用ImplicitWinCompat

当设置为 true 时，此设置将禁用 Windows PowerShell 兼容性功能。 Windows PowerShell 兼容性允许 PowerShell 7 以兼容模式加载 Windows PowerShell 5.1 模块。

有关详细信息，请参阅 about_Windows_PowerShell_Compatibility。

WindowsPowerShellCompatibilityModuleDenyList

此设置是您想要排除在 Windows PowerShell 兼容性功能之外的模块名称数组。

有关详细信息，请参阅 about_Windows_PowerShell_Compatibility。

WindowsPowerShellCompatibilityNoClobberModuleList

此设置是一个模块名称数组，不应通过加载 Windows PowerShell 5.1 版本的模块来破坏这些名称。

有关详细信息，请参阅 about_Windows_PowerShell_Compatibility。

ExecutionPolicy

这很重要

此配置仅适用于 Windows 平台。

配置 PowerShell 会话的执行策略，确定可以运行哪些脚本。默认情况下，PowerShell 使用现有的执行策略。

对于AllUsers配置，这会设置LocalMachine执行策略。对于 CurrentUser 配置，这会设置 CurrentUser 执行策略。

以下示例将 PowerShell 的执行策略设置为 RemoteSigned。

{
  "Microsoft.PowerShell:ExecutionPolicy": "RemoteSigned"
}

有关更多信息，请参阅 about_Execution_Policies。

PowerShell策略

Windows 有多个可以通过组策略管理的设置。通常，这些设置存储在 Windows 注册表中。这些设置也可以在 powershell.config.json 文件中定义。

PowerShellPolicies 是一个 JSON 对象，其中包含各种策略设置的键值对。这些策略设置还可以在 PowerShellPolicies 对象外部的 JSON 文件的根级别列出。此设置可以包含以下子项：

ConsoleSessionConfiguration

ModuleLogging

ProtectedEventLogging

ScriptBlockLogging

ScriptExecution

Transcription

UpdatableHelp

ScriptExecution 设置用于设置 PowerShell 执行策略。这优先于上面描述的 ExecutionPolicy 设置。

例子 ：

{
    "PowerShellPolicies": {
        "ScriptExecution": {
            "ExecutionPolicy": "RemoteSigned"
        }
    }
}

有关其他策略设置的说明，请参阅通用配置设置部分中的说明。

在 Windows 上，PowerShell 会查找注册表中的设置。在注册表中找到的任何设置都具有优先权。接下来 PowerShell 读取 JSON 配置。在 PowerShellPolicies 下找到且未在注册表中定义的任何设置都优先于在 JSON 配置的根级别找到的设置。

有关详细信息，请参阅 about_Group_Policy_Settings。

非 Windows 平台的设置

以下设置仅适用于 Linux 和 macOS 平台。

以下键用于配置 Linux 和 macOS 的 PowerShell 日志记录。

LogChannels

LogIdentity

LogKeywords

LogLevel

有关非 Windows 系统的 PowerShell 日志记录的完整说明，请参阅 about_Logging_Non-Windows。

通用配置设置

以下设置在所有支持的平台上均可用。

ConsoleSessionConfiguration

ExperimentalFeatures

ModuleLogging

ProtectedEventLogging

PSModulePath

ScriptBlockLogging

ScriptExecution

Transcription

UpdatableHelp

控制台会话配置

此设置指定用于所有 PowerShell 会话的会话配置。这可以是在本地计算机上注册的任何端点，包括默认的 PowerShell 远程处理端点或具有特定用户角色功能的自定义端点。

该键包含两个子键：

• EnableConsoleSessionConfiguration - 要启用会话配置，请将值设置为true。默认情况下，该值为 false。

• ConsoleSessionConfigurationName - 指定运行 PowerShell 的配置端点的名称。默认情况下，没有定义会话。

{
  "ConsoleSessionConfiguration": {
    "EnableConsoleSessionConfiguration": false,
    "ConsoleSessionConfigurationName" : []
  }
}

有关更多信息，请参阅 about_Session_Configurations。

ExperimentalFeatures

要在 PowerShell 中启用的实验性功能的名称。默认值为空数组。

以下示例在 PowerShell 启动时启用 PSCommandNotFoundSuggestion 和 PSSubsystemPluginModel 实验性功能。

例子 ：

{
  "ExperimentalFeatures": [
    "PSCommandNotFoundSuggestion",
    "PSSubsystemPluginModel"
  ]
}

有关实验性功能的更多信息，请参阅使用实验性功能。

ModuleLogging

此设置控制 PowerShell 模块的日志记录行为。该设置包含两个子项：

• EnableModuleLogging - 要启用会话配置，请将值设置为true。启用后，指定模块成员的管道执行事件将记录在 PowerShell 日志文件中。
• ModuleNames - 指定应记录的模块的名称。

例子 ：

{
  "ModuleLogging": {
    "EnableModuleLogging": true,
    "ModuleNames" : [
        "PSReadLine",
        "PowerShellGet"
    ]
  }
}

受保护的事件记录

此设置允许您配置受保护的事件日志记录。该设置包含两个子项：

• EnableProtectedEventLogging - 如果启用此策略设置，支持它的组件将使用您提供的证书来加密日志数据，然后再将其写入日志。数据使用加密消息语法 (CMS) 标准进行加密。如果您有权访问证书的私钥，则可以使用 Unprotect-CmsMessage 解密这些加密消息。
• EncryptionCertificate - 提供用于加密的证书名称列表。

例子 ：

{
  "ProtectedEventLogging": {
    "EnableProtectedEventLogging": false,
    "EncryptionCertificate": [
      "Joe"
    ]
  }
}

PS模块路径

覆盖此 PowerShell 会话的 PSModulePath 设置。如果配置针对当前用户，请设置 CurrentUser 模块路径。如果配置适用于所有用户，请设置 AllUsers 模块路径。

警告

此处配置 AllUsers 或 CurrentUser 模块路径不会更改 PowerShellGet cmdlet（如 Install-Module）的范围安装位置。这些 cmdlet 始终使用默认模块路径。

如果未设置值，PowerShell 将使用相应模块路径设置的默认值。有关这些默认值的详细信息，请参阅 about_PSModulePath。

此设置允许通过将环境变量嵌入 % 字符之间来使用环境变量，例如 "%HOME%\Documents\PowerShell\Modules"，与 Windows 命令的方式相同壳牌允许。此语法也适用于 Linux 和 macOS。请参阅下面的示例。

此示例显示 Windows 环境的 PSModulePath 配置：

{
  "PSModulePath": "C:\Program Files\PowerShell\6\Modules"
}

此示例显示 macOS 或 Linux 环境的 PSModulePath 配置：

{
  "PSModulePath": "/opt/powershell/6/Modules"
}

此示例显示在 PSModulePath 配置中嵌入环境变量。请注意，使用 HOME 环境变量和 / 目录分隔符，此语法适用于 Windows、macOS 和 Linux。

{
  "PSModulePath": "%HOME%/Documents/PowerShell/Modules"
}

此示例使用仅适用于 macOS 和 Linux 的环境变量：

{
  "PSModulePath": "%XDG_CONFIG_HOME%/powershell/Modules"
}

笔记

PowerShell 变量无法嵌入到 PSModulePath 配置中。 Linux 和 macOS 上的 PSModulePath 配置区分大小写。 PSModulePath 配置必须使用平台的有效目录分隔符。在 macOS 和 Linux 上，这意味着 /。在 Windows 上，/ 和 \ 都可以工作。

脚本块日志记录

此设置控制所有 PowerShell 脚本输入的日志记录。该设置包含两个子项：

• EnableScriptBlockLogging - 如果启用此策略设置，PowerShell 会记录命令、脚本块、函数和脚本的处理，无论是交互调用还是通过自动化调用。
• EnableScriptBlockInvocationLogging - 启用脚本块启动和停止事件的日志记录。

例子 ：

"ScriptBlockLogging": {
  "EnableScriptBlockInvocationLogging": true,
  "EnableScriptBlockLogging": false
}

转录

此策略设置允许您在基于文本的记录中捕获 PowerShell 命令的输入和输出。如果启用此策略设置，PowerShell 将为所有 PowerShell 会话启用转录。

此设置控制转录在 PowerShell 中的工作方式。该设置包含三个子项：

• EnableTranscripting - 启用此设置后，PowerShell 将在配置的位置创建转录日志文件。
• EnableInvocationHeader - 默认情况下，PowerShell 在转录日志文件的顶部包含一个标头。您可以使用此设置禁用标头。
• OutputDirectory - 此设置允许您在中央位置而不是默认位置收集转录日志文件。

例子 ：

{
    "Transcription": {
        "EnableTranscripting": true,
        "EnableInvocationHeader": true,
        "OutputDirectory": "c:\tmp"
      }
}

有关详细信息，请参阅开始记录。

UpdatableHelp

此策略设置允许您设置 Update-Help cmdlet 上的 SourcePath 参数的默认值。可以通过使用 SourcePath 参数指定不同的值来覆盖此默认值。

例子 ：

{
    "UpdatableHelp": {
      "DefaultSourcePath": "f:\temp"
    }
}