---

提升效率：掌握 PowerShell Gallery 的使用技巧

在现代 IT 运维和自动化领域，PowerShell 已经成为不可或缺的利器。它强大的脚本能力、与 Windows 生态系统的深度集成以及跨平台的支持，使其备受系统管理员、DevOps 工程师和开发人员的青睐。然而，要真正发挥 PowerShell 的威力，仅仅掌握其基础语法是远远不够的。高效利用社区资源、复用现有解决方案、规范化脚本管理，是提升效率的关键。而这一切的核心，便是 PowerShell Gallery。

PowerShell Gallery (powershellgallery.com) 是微软官方运营的 PowerShell 内容中央存储库。它汇集了由社区和微软贡献的大量 PowerShell 模块（Modules）、脚本（Scripts）、DSC 资源（Desired State Configuration Resources）以及角色功能（Role Capabilities）。可以把它想象成 PowerShell 世界的“应用商店”或“包管理器”，为用户提供了一个发现、获取、分享和管理 PowerShell 代码的便捷平台。

掌握 PowerShell Gallery 的使用技巧，不仅能让你快速找到解决特定问题的现成工具，避免“重复造轮子”，更能让你接触到更广泛的 PowerShell 实践，学习优秀的代码规范，甚至将自己的成果贡献给社区，从而极大地提升工作效率和专业技能。本文将详细探讨 PowerShell Gallery 的使用方法、核心命令、最佳实践以及一些高级技巧，助你成为 PowerShell Gallery 的应用高手。

一、 PowerShell Gallery 的核心价值与优势

为什么我们需要 PowerShell Gallery？它的价值体现在以下几个方面：

1. 代码发现与复用： Gallery 上拥有数以万计的模块和脚本，涵盖了从系统管理、云服务（Azure, AWS, GCP）、数据库操作、网络配置到各种特定应用（如 Active Directory, Exchange, VMware）的管理。通过简单的搜索，就能找到满足需求的工具，直接安装使用，节省大量开发时间。
2. 社区驱动与协作： Gallery 是一个开放的平台，汇聚了全球 PowerShell 用户的智慧。你可以从中受益，也可以将自己的优秀代码打包发布，与他人分享，共同推动 PowerShell 生态的发展。
3. 标准化与版本控制： Gallery 对发布的包有明确的结构要求（如模块清单文件 .psd1），并支持版本管理。这意味着你可以安装特定版本的模块，轻松管理依赖关系，实现环境的一致性，并在需要时回滚到旧版本。
4. 可信度与安全性： 虽然 Gallery 是开放的，但微软提供了一些机制来增强安全性。例如，发布者可以对代码进行签名，用户可以配置安装策略（Trusted, Untrusted），并且可以查看模块的下载量、评分、依赖项等信息来辅助判断其可靠性。
5. 简化部署与管理： 通过 Install-Module, Update-Module 等命令，可以轻松地在目标机器上安装、更新和卸载 Gallery 中的包，极大地简化了脚本和模块的分发与维护过程。

二、 必备基础：PowerShellGet 模块

要与 PowerShell Gallery 交互，你需要使用 PowerShellGet 模块。这个模块包含了一系列用于发现、安装、更新和发布 PowerShell 包的 cmdlet。

• 检查与安装/更新 PowerShellGet：
  在现代版本的 Windows PowerShell (5.1) 和 PowerShell Core (6.0 及以上) 中，PowerShellGet 通常是内置的。你可以通过以下命令检查其版本：
  powershell
Get-Module PowerShellGet -ListAvailable
  如果版本较低或未安装，建议更新到最新稳定版，以获得更好的性能、安全性和功能支持。更新或安装 PowerShellGet 可能需要管理员权限：
  powershell
# 以管理员身份运行 PowerShell
Install-Module PowerShellGet -Force -SkipPublisherCheck
Update-Module PowerShellGet
# 更新后可能需要重启 PowerShell 会话
  • -Force 参数用于强制重新安装，即使已存在相同版本。
  • -SkipPublisherCheck 在某些环境下可能需要，用于跳过发布者验证（但请谨慎使用）。

三、 核心操作：发现、安装与管理

掌握以下核心 cmdlet 是使用 PowerShell Gallery 的基础：

1. 发现包 (Find-* 系列)

• Find-Module: 查找 PowerShell 模块。
  “`powershell
  # 查找名称包含 “Azure” 的模块
  Find-Module -Name Azure

  查找精确名称为 “Az” 的模块 (Azure PowerShell 的新模块)

  Find-Module -Name Az

  查找带有特定标签 (Tag) 的模块，例如用于 Active Directory 的

  Find-Module -Tag ActiveDirectory

  查找特定作者发布的模块

  Find-Module -Filter “Author -eq ‘Microsoft'”

  查找包含特定命令的模块

  Find-Module -Command Get-AzVM, New-AzResourceGroup

  查看模块的所有版本

  Find-Module -Name Pester -AllVersions

  查找预发布版本 (Prerelease)

  Find-Module -Name SomeBetaModule -AllowPrerelease
  * **`Find-Script`**: 查找独立的 PowerShell 脚本文件 (.ps1)。用法与 `Find-Module` 类似。powershell

  查找名称包含 “Report” 的脚本

  Find-Script -Name Report

  查找用于清理日志的脚本

  Find-Script -Tag LogCleanup
  ``
* **Find-DscResource**: 查找 DSC (Desired State Configuration) 资源。
* **Find-Command**: 可以查找模块中的命令、函数或别名，并指出它们所在的模块。
* **Find-RoleCapability`**: 查找 JEA (Just Enough Administration) 的角色功能文件。

常用参数说明：

• -Name: 指定要查找的包名，支持通配符 (*, ?)。
• -Tag: 根据标签进行筛选。标签由发布者添加，用于分类。
• -Filter: 提供更复杂的 OData 筛选表达式，例如按作者、描述内容等筛选。
• -Command: 查找包含指定命令的模块。
• -AllVersions: 显示所有可用版本，而不仅仅是最新稳定版。
• -AllowPrerelease: 包含预发布版本（通常带有 -beta, -alpha, -preview 等后缀）。
• -Repository: 指定要搜索的存储库（默认为 PSGallery）。

2. 安装包 (Install-* 系列)

• Install-Module: 安装 PowerShell 模块。
  “`powershell
  # 安装最新稳定版的 Pester 模块 (用于测试)
  Install-Module -Name Pester

  安装特定版本的 Az.Compute 模块

  Install-Module -Name Az.Compute -RequiredVersion 4.20.0

  安装最低版本为 7.0.0 的 PowerShell Desired State Configuration 模块

  Install-Module -Name PSDesiredStateConfiguration -MinimumVersion 7.0.0

  安装最新预发布版本的模块

  Install-Module -Name SomeBetaModule -AllowPrerelease

  安装模块，并跳过依赖项检查 (不推荐，除非明确知道原因)

  Install-Module -Name MyModule -SkipDependenciesCheck

  将模块安装到当前用户范围 (不需要管理员权限)

  Install-Module -Name PSScriptAnalyzer -Scope CurrentUser

  如果已安装，强制重新安装 (覆盖)

  Install-Module -Name Az -Force

  允许覆盖现有命令 (例如，新模块包含与已加载命令同名的函数)

  Install-Module -Name ConflictingModule -AllowClobber
  * **`Install-Script`**: 安装 PowerShell 脚本。脚本通常安装在特定路径下，可以通过 `Get-InstalledScriptLocation` 查看。powershell
  Install-Script -Name Invoke-MyCoolScript -Scope CurrentUser
  “`

常用参数说明：

• -Name: 必须指定要安装的包名。
• -RequiredVersion: 安装指定的精确版本。
• -MinimumVersion: 安装不低于此版本的最新稳定版。
• -MaximumVersion: 安装不高于此版本的最新稳定版。
• -AllowPrerelease: 允许安装预发布版本。
• -Scope: 指定安装范围。
  • CurrentUser: 安装到当前用户目录 ($env:USERPROFILE\Documents\PowerShell\Modules)，不需要管理员权限。
  • AllUsers: 安装到系统范围 ($env:ProgramFiles\PowerShell\Modules)，需要管理员权限，所有用户可用。默认为 AllUsers。
• -Force: 强制安装，即使已存在。常用于更新或修复安装。
• -AllowClobber: 允许新安装的包中的命令覆盖内存中已有的同名命令。
• -SkipDependenciesCheck: 跳过自动安装依赖项。
• -Repository: 指定从哪个存储库安装。

关于信任与执行策略：
首次从 PowerShell Gallery 安装时，可能会提示存储库 PSGallery 未被设置为受信任。你可以选择 [Y] Yes 或 [A] Yes to All 来继续安装。如果希望永久信任 PSGallery（请确保理解安全风险），可以运行：
powershell
Set-PSRepository -Name PSGallery -InstallationPolicy Trusted
另外，脚本的执行可能受到执行策略 (Execution Policy) 的限制。使用 Get-ExecutionPolicy 查看当前策略，使用 Set-ExecutionPolicy (需要管理员权限) 进行更改，例如 Set-ExecutionPolicy RemoteSigned 或 Set-ExecutionPolicy Unrestricted (后者风险较高)。对于 CurrentUser 范围安装的脚本，可能需要 RemoteSigned 或更宽松的策略。

3. 更新包 (Update-* 系列)

• Update-Module: 将已安装的模块更新到最新的稳定版（或最新预发布版，如果指定了 -AllowPrerelease）。
  “`powershell
  # 更新所有可更新的模块 (可能需要管理员权限，取决于安装范围)
  Update-Module

  更新指定的模块 Az

  Update-Module -Name Az

  更新 Pester 模块，并查看详细输出

  Update-Module -Name Pester -Verbose
  ``
* **Update-Script`**: 更新已安装的脚本。

注意: Update-Module 只会安装新版本，不会卸载旧版本。一个模块可以有多个版本并存。Import-Module 默认加载最新版本，但也可以指定加载特定版本 (Import-Module -Name MyModule -RequiredVersion 1.2.3)。

4. 卸载包 (Uninstall-* 系列)

• Uninstall-Module: 卸载 PowerShell 模块的特定版本或所有版本。
  “`powershell
  # 卸载模块 Pester 的所有版本
  Uninstall-Module -Name Pester -AllVersions

  卸载模块 Az 的特定版本 5.0.0

  Uninstall-Module -Name Az -RequiredVersion 5.0.0

  强制卸载 (例如，如果模块正在使用中可能需要)

  Uninstall-Module -Name MyLockedModule -Force
  ``
* **Uninstall-Script`**: 卸载脚本。

注意: 卸载时要小心，特别是卸载被其他模块或脚本依赖的包。PowerShellGet 目前没有内置强大的依赖关系卸载检查。

5. 查看已安装的包 (Get-Installed* 系列)

• Get-InstalledModule: 列出已安装的模块及其版本。
  “`powershell
  # 列出所有已安装的模块
  Get-InstalledModule

  查看特定模块 Pester 的安装信息

  Get-InstalledModule -Name Pester

  查看 Pester 的所有已安装版本

  Get-InstalledModule -Name Pester -AllVersions
  ``
* **Get-InstalledScript`**: 列出已安装的脚本。

四、 存储库管理 (*-PSRepository)

虽然 PSGallery 是默认且最常用的存储库，但 PowerShellGet 支持管理多个存储库。这在企业内部搭建私有 Gallery 或使用其他公共/第三方 Gallery 时非常有用。

• Get-PSRepository: 查看已注册的存储库。
  powershell
Get-PSRepository
# 输出会显示 Name, SourceLocation, InstallationPolicy 等信息
• Register-PSRepository: 注册一个新的存储库。
  powershell
# 注册一个名为 MyInternalRepo 的内部 NuGet 源
Register-PSRepository -Name MyInternalRepo -SourceLocation "https://nuget.internal.mycompany.com/nuget" -InstallationPolicy Trusted

• Set-PSRepository: 修改已注册存储库的属性。
  “`powershell
  # 将 PSGallery 设置为受信任 (如前所述)
  Set-PSRepository -Name PSGallery -InstallationPolicy Trusted

  将 MyInternalRepo 设置为优先级较高 (虽然 PowerShellGet 目前不直接使用 Priority 字段)

  Set-PSRepository -Name MyInternalRepo -Priority 50

  * **`Unregister-PSRepository`**: 注销一个存储库。powershell
  Unregister-PSRepository -Name MyInternalRepo
  “`

当存在多个存储库时，Find-*, Install-*, Update-* 等命令可以通过 -Repository 参数指定操作的目标存储库。例如：
powershell
Install-Module -Name MyCompany.InternalTool -Repository MyInternalRepo

五、 高级技巧与最佳实践

1. 离线环境使用 (Save-* 系列):
   如果需要在无法访问互联网的环境中使用 Gallery 包，可以在有网的机器上使用 Save-Module 或 Save-Script 将包及其依赖项下载到本地目录，然后拷贝到目标机器进行安装。
   “`powershell
   # 将 Az 模块及其所有依赖项下载到 C:\Temp\OfflineModules 目录
   Save-Module -Name Az -Path C:\Temp\OfflineModules -Recurse

   将脚本下载到指定目录

   Save-Script -Name Backup-SystemFiles -Path C:\Temp\OfflineScripts
   ``
在离线机器上，可以将包含这些模块的路径添加到$env:PSModulePath环境变量中，或者直接从该路径使用Install-Module -Name Az -Source C:\Temp\OfflineModules` 进行本地安装（需要确保路径在可信位置或调整执行策略）。

2. 理解模块清单 (.psd1 文件):
   每个发布到 Gallery 的模块都包含一个模块清单文件（.psd1）。这个文件包含了模块的元数据，如版本、作者、描述、依赖项、导出的函数/命令等。在安装模块后，可以在模块目录下找到它。查看清单文件有助于了解模块的详细信息和结构。
   “`powershell
   # 找到 Pester 模块的安装路径
   (Get-InstalledModule Pester).InstalledLocation

   导航到该目录并查看 Pester.psd1 文件内容

   Get-Content (Join-Path (Get-InstalledModule Pester).InstalledLocation “Pester.psd1”) | Out-String | Write-Host

   或者直接导入清单获取信息

   Import-PowerShellDataFile (Join-Path (Get-InstalledModule Pester).InstalledLocation “Pester.psd1”)
   “`

3. 谨慎处理依赖关系：
   安装模块时，PowerShellGet 会自动尝试安装其声明的依赖项。有时，不同模块可能依赖同一模块的不同版本，这可能导致冲突。使用 Get-InstalledModule -Name DependencyModule -AllVersions 查看已安装版本。虽然 PowerShell 允许同一模块多版本并存，但在脚本中显式导入所需版本 (Import-Module -Name MyModule -RequiredVersion 1.2.3) 是个好习惯，可以避免因默认加载最新版本而引发的兼容性问题。

4. 安全第一：审查与信任：

   • 检查发布者： 尽量使用来自可信发布者（如 Microsoft、知名社区项目）的模块。
   • 查看评分与下载量： Gallery 页面提供了这些信息，可以作为参考。
   • 审阅代码： 对于关键任务或来源不明的模块/脚本，强烈建议在安装或执行前审查其源代码。使用 Save-Module/Save-Script 下载后进行检查，或者直接在 Gallery 网站上查看。
   • 使用 CurrentUser 范围： 尽可能将模块安装到 CurrentUser 范围，以限制其潜在影响，并避免需要管理员权限。
   • 代码签名： 如果可能，优先使用经过数字签名的模块。企业内部可以建立策略，只允许安装来自特定可信签名者的模块。

5. 贡献你的代码：
   如果你编写了通用性强、质量高的 PowerShell 模块或脚本，考虑将其发布到 PowerShell Gallery。这需要：

   • 遵循模块开发最佳实践（包括编写清单文件、帮助文档）。
   • 在 PowerShell Gallery 网站注册账户并获取 API 密钥。
   • 使用 Publish-Module 或 Publish-Script 命令进行发布。
     “`powershell

   假设你已经在当前目录准备好了 MyAwesomeModule 及其 .psd1 文件

   Publish-Module -Path .\MyAwesomeModule -NuGetApiKey “YOUR_API_KEY”
   “`
   发布前务必仔细测试，并遵循 Gallery 的发布指南和策略。

六、 常见问题与故障排除

• 网络问题： Install-Module 等命令失败，提示无法连接到源。
  • 检查网络连接和防火墙设置。
  • 确保 PowerShell 使用的 TLS 版本符合 Gallery 要求（通常需要 TLS 1.2）。可以通过以下命令在当前会话启用：
    powershell
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
    可以将其加入 PowerShell Profile 文件使其永久生效。
  • 尝试使用 -Verbose 参数获取更详细的错误信息。
• 权限问题： 安装到 AllUsers 范围时提示权限不足。
  • 请以管理员身份运行 PowerShell。
• 执行策略阻止： 安装脚本后无法运行。
  • 检查执行策略 (Get-ExecutionPolicy)，并根据需要调整 (Set-ExecutionPolicy)。注意不同范围（MachinePolicy, UserPolicy, Process, CurrentUser, LocalMachine）的优先级。
• 模块无法加载： Import-Module 失败。
  • 确认模块已正确安装 (Get-InstalledModule)。
  • 检查模块路径是否在 $env:PSModulePath 中。
  • 使用 Import-Module -Name ModuleName -Verbose 查看详细加载过程和错误信息。
  • 可能是依赖项问题或模块内部代码错误。

七、 总结

PowerShell Gallery 是 PowerShell 生态系统的核心枢纽，它极大地促进了代码共享、标准化和效率提升。通过熟练掌握 Find-*, Install-*, Update-*, Uninstall-*, Get-Installed* 等核心 cmdlet，结合对存储库管理、版本控制、安全策略和最佳实践的理解，你可以：

• 快速找到并利用高质量的社区模块和脚本，解决实际问题。
• 规范化团队或个人的 PowerShell 工具集，确保环境一致性。
• 通过管理私有存储库，安全地分发内部工具。
• 紧跟 PowerShell 生态的发展，学习先进技术和实践。
• 甚至将自己的成果回馈社区，提升个人影响力。

花时间探索 PowerShell Gallery，将其融入日常工作流程，你会发现 PowerShell 的能力边界被大大拓宽，自动化和管理任务的效率得到显著提升。现在就开始你的 PowerShell Gallery 之旅吧！

---