把函数、类、资源和命令打包成可发现、可版本管理的模块

适用场景

当一组函数会被多个脚本复用、需要版本控制、需要分发到不同机器，或要安装第三方能力（如 Az、Pester）时，用模块而不是复制 .ps1 文件。排查“命令为什么找不到、加载的是哪个版本、为什么和文档不一致”也依赖模块知识。

一次性脚本不需要模块化；把几十行函数硬做成模块只会增加清单和发布成本。模块适合有稳定接口、需要长期维护的逻辑。

核心概念

• 模块形态：脚本模块是 .psm1，清单是 .psd1，二进制模块是 .dll，还有嵌套模块和复合模块。清单描述版本、作者、依赖、导出命令和兼容的 PowerShell 版本。
• 发现与加载：$env:PSModulePath 是一组目录，按顺序搜索；用户目录优先于系统目录，同名命令先命中靠前的模块。Import-Module 显式加载，命令首次被调用时也会自动加载 PSModulePath 中的模块。
• 导出规则：模块里定义不等于对外可见。用 Export-ModuleMember 或清单的 FunctionsToExport、AliasesToExport、CmdletsToExport 控制边界，未导出的函数只在模块作用域内可用。
• 版本与依赖：模块可以并存多个版本，用 -RequiredVersion 精确加载、-MinimumVersion 限定下限；脚本头部用 #Requires -Modules 声明依赖，让缺依赖时尽早失败。
• 分发渠道：5.1 常用 PowerShellGet 的 Find-Module、Install-Module、Save-Module；7.4 起内置 PSResourceGet，优先 Install-PSResource。安装前确认仓库和发布者，不要默认信任任意源。

5.1 与 7.x 差异

• 5.1 的默认用户模块目录是 Documents\WindowsPowerShell\Modules，7.x 是 Documents\PowerShell\Modules。7.x 会保留系统级 5.1 模块路径（如 %ProgramFiles%\WindowsPowerShell\Modules、%SystemRoot%\System32\WindowsPowerShell\v1.0\Modules）以兼容旧模块，但不会自动把 5.1 的用户级 Documents\WindowsPowerShell\Modules 加入搜索路径；需要时手动加入 PSModulePath。
• 5.1 安装模块依赖 PowerShellGet 和 NuGet 提供程序，旧系统还可能要先启用 TLS 1.2；7.4 起 PSResourceGet 是首选工具链。
• 二进制模块和 using module 引入的类型绑定具体运行时：5.1 是 .NET Framework，7.x 是 .NET，不能假设同一个 DLL 两边都能加载。

常用操作

# 1. 看清模块搜索路径和顺序，Windows 用分号分隔，Linux/macOS 用冒号
PS C:\> $env:PSModulePath -split [IO.Path]::PathSeparator

# 2. 列出已安装模块及版本，排查“装了但加载错版本”
PS C:\> Get-Module -ListAvailable | Sort-Object Name, Version | Select-Object Name, Version, Path
PS C:\> Get-Module -ListAvailable Pester

# 3. 显式导入清单并查看它导出了什么
PS C:\> Import-Module .\MyModule.psd1 -Force -Verbose
PS C:\> Get-Command -Module MyModule

# 4. 不写 Import-Module 也能调用，首次调用会从 PSModulePath 自动加载
PS C:\> Get-Widget -Name api
PS C:\> Get-Module MyModule

# 5. 在脚本头部声明依赖，缺模块或版本不够时不继续执行
#Requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '5.0.0' }

# 6. 查找、安装到当前用户、离线保存（5.1 的 PowerShellGet 写法）
PS C:\> Find-Module -Name Pester
PS C:\> Install-Module -Name Pester -Scope CurrentUser -MinimumVersion 5.0
PS C:\> Save-Module -Name Pester -Path C:\offline\modules

# 7. PowerShell 7.4+ 用 PSResourceGet，参数更清晰
PS C:\> Install-PSResource -Name Pester -Scope CurrentUser

# 8. 脚本模块的最小导出示例
# MyModule.psm1
function Get-Widget { param([string] $Name) [pscustomobject]@{ Name = $Name } }
Export-ModuleMember -Function Get-Widget

易错点

• 5.1 首次 Install-Module 可能要求安装 NuGet 提供程序并信任 PSGallery；这是安装来源问题，不是网络坏了。先看提示，再决定是否信任该源。
• Import-Module -Force 能重新加载脚本模块，但已经存在的对象引用不会自动更新；类类型还需要在脚本顶部用 using module，普通 Import-Module 不足以让类型在解析阶段可见。
• 同一模块多版本并存时，命令解析和 Import-Module 的默认选择可能不同。排查时同时看 Get-Module、Get-Module -ListAvailable 和 Get-Command -Module，不要只看文件名。
• 清单里写 FunctionsToExport = '*' 会把内部辅助函数也暴露出去，后续重构容易破坏调用方；显式列出导出项，内部函数保持未导出。
• 自动加载会掩盖部署缺失：开发机因为旧模块在用户目录而正常，服务器上却找不到命令。上线前用干净会话验证，或显式 Import-Module 并固定版本。

相关命令

• powershell-errors — 模块加载失败时的错误处理
• powershell-security — 模块来源、签名和最小权限
• powershell-remoting — 远程端模块可用性
• where — 在 CMD 中定位可执行文件，和模块解析不是一回事
• setx — 持久化 PSModulePath 时要谨慎覆盖
• linux-vs-windows — 两个平台的路径和工具链差异

参考链接

• Microsoft Learn: Understanding a Windows PowerShell module
• Microsoft Learn: Import-Module

读完自测

合上页面，先回答，再展开对照。

1. 一条命令能正常运行，但 Get-Module 里一开始看不到对应模块，为什么？
2. 同一模块装了 1.2 和 2.0 两个版本，怎样确保脚本加载 1.2？
3. 为什么脚本模块里的类，调用方用 Import-Module 后仍然报“找不到类型”？