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 键包含镜像由窗口组策略管理的设置的子项。 在 JSON 文件的根级别定义时，这些子项也适用于所有平台。

警告

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

配置范围

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

AllUsers （共享） 配置

$PSHOME 目录中的 powershell.config.json 文件定义从该 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。

JSON

{
  "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 设置。

例：

JSON

{
    "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 的配置终结点的名称。 默认情况下，没有定义会话。

JSON

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

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

ExperimentalFeatures

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

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

例：

JSON

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

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

ModuleLogging

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

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

例：

JSON

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

ProtectedEventLogging

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

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

例：

JSON

{
  "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 配置：

JSON

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

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

JSON

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

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

JSON

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

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

JSON

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

备注

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

ScriptBlockLogging

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

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

例：

JSON

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

转录

通过此策略设置，可以在基于文本的脚本中捕获 PowerShell 命令的输入和输出。 如果启用此策略设置，PowerShell 将为所有 PowerShell 会话启用听录。

此设置控制听录在 PowerShell 中的工作原理。 此设置包含三个子项：

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

例：

JSON

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

有关详细信息，请参阅 开始脚本。

UpdateableHelp

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

例：

JSON

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