about_PowerShell_Config

简短说明

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
• PowerShellPolicies
  • ExecutionPolicy
  • ConsoleSessionConfiguration
  • ModuleLogging
  • ProtectedEventLogging
  • ScriptBlockLogging
  • ScriptExecution
  • Transcription
  • UpdatableHelp

并非所有键都适用于所有平台。 PowerShellPolicies 键包含用于镜像 Windows 组策略托管的设置的子项。 当在 JSON 文件的根级别定义时，这些子项也适用于所有平台。

警告

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

配置作用域

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

AllUsers（共享）配置

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

注意

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

CurrentUser（每用户）配置

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

作用域优先级

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

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

特定于 Windows 的设置

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

• DisableImplicitWinCompat
• WindowsPowerShellCompatibilityModuleDenyList
• WindowsPowerShellCompatibilityNoClobberModuleList
• ExecutionPolicy
• PowerShellPolicies

DisableImplicitWinCompat

设置为 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。

PowerShellPolicies

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

ConsoleSessionConfiguration

此设置指定要用于所有 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"
    ]
  }
}

ProtectedEventLogging

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

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

示例：

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

PSModulePath

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

警告

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

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

此设置允许通过将环境变量嵌入 % 字符（例如 "%HOME%\Documents\PowerShell\Modules"）之间来使用环境变量，与 Windows Command Shell 允许的方式相同。 此语法也适用于 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 上，/ 和 \ 都有效。

ScriptBlockLogging

此设置控制所有 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"
      }
}

有关详细信息，请参阅 Start-Transcript。

UpdatableHelp

通过此策略设置，可以在 cmdlet 上设置 Update-Help 参数的默认值。 可以通过使用 SourcePath 参数指定其他值来重写此默认值。

示例：

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