命令行与文本处理 / 系统课时
创建与管理模块
创建与管理模块
本课把散落的函数整理成可安装、可导入、可版本化的 PowerShell 模块。你将创建实现文件和模块清单,限制公共命令,验证并导入模块,同时掌握依赖声明、版本选择以及命令触发自动加载的条件。
学习目标
- 区分
.psm1实现文件与.psd1模块清单的职责 - 创建、验证并导入只暴露公共函数的脚本模块
- 管理模块依赖、版本目录和自动加载策略
认识模块组成与加载关系
脚本模块通常以同名目录组织。.psm1 保存函数、变量和初始化逻辑;.psd1 是数据文件,用于声明根模块、版本、兼容要求、依赖与导出列表。模块被导入后会创建独立的模块作用域,未导出的内部函数不会进入调用者会话。

推荐的发布目录形态如下。版本目录不是本地直接按路径导入的硬性要求,但放入 PSModulePath 后,它能让多个版本并存并支持按版本选择。
WidgetTools/
└── 1.0.0/
├── WidgetTools.psd1
└── WidgetTools.psm1创建并验证最小模块
下面的完整示例在当前目录创建模块,实现两个函数,但只导出 Get-WidgetStatus。清单和实现文件同时使用导出白名单,可降低以后新增内部函数时被意外公开的风险。
$moduleRoot = Join-Path $PWD 'WidgetTools'
New-Item -ItemType Directory -Path $moduleRoot -Force | Out-Null
@'
function Get-WidgetStatus {
[CmdletBinding()]
param(
[Parameter(Mandatory)]
[string]$Name
)
[pscustomobject]@{
Name = $Name
Status = 'Ready'
}
}
function Reset-WidgetInternal {
[CmdletBinding()]
param(
[Parameter(Mandatory)]
[string]$Name
)
"Resetting $Name"
}
# 只公开稳定的公共命令,内部函数保留在模块作用域
Export-ModuleMember -Function Get-WidgetStatus
'@ | Set-Content -Path (Join-Path $moduleRoot 'WidgetTools.psm1') -Encoding utf8
$manifestPath = Join-Path $moduleRoot 'WidgetTools.psd1'
Remove-Item -Path $manifestPath -Force -ErrorAction SilentlyContinue
New-ModuleManifest `
-Path $manifestPath `
-RootModule 'WidgetTools.psm1' `
-ModuleVersion '1.0.0' `
-Guid '9b5f5d0d-3f8c-4d19-a0c1-09b6f4e0a701' `
-Author 'Anystack' `
-Description 'Widget status commands' `
-PowerShellVersion '7.2' `
-FunctionsToExport @('Get-WidgetStatus') | Out-Null
# 导入前先验证清单语法、根模块和声明
$null = Test-ModuleManifest -Path $manifestPath
Import-Module -Name $manifestPath -Force
Get-WidgetStatus -Name 'api' | ConvertTo-Json -Compress
"Exported commands: $((Get-Command -Module WidgetTools).Name -join ',')"预期输出:
{"Name":"api","Status":"Ready"}
Exported commands: Get-WidgetStatusReset-WidgetInternal 已加载到模块内部,但不会出现在调用者可用命令中。示例目录的完整路径取决于当前工作目录,可通过 $moduleRoot 查看实际值。验收时还应在新会话中重新导入,确认结果不依赖旧变量或旧模块实例。
管理依赖、版本与自动加载
模块自身版本写在清单的 ModuleVersion。发布多个版本时,建议使用 <PSModulePath>/WidgetTools/1.0.0/WidgetTools.psd1 这类目录结构;导入时可使用 Import-Module WidgetTools -RequiredVersion 1.0.0 精确选择版本,避免不同机器解析到不同实现。
依赖模块写入 RequiredModules。以下是清单片段示例,只有目标环境已经提供 Company.Logging 时才能通过验证;RequiredVersion 表示必须精确匹配,若只需要最低版本则改用 ModuleVersion。
@{
RootModule = 'WidgetTools.psm1'
ModuleVersion = '1.0.0'
PowerShellVersion = '7.2'
RequiredModules = @(
@{
ModuleName = 'Company.Logging'
RequiredVersion = '2.1.0'
}
)
FunctionsToExport = @('Get-WidgetStatus')
}正式安装时,应把模块目录复制到 $env:PSModulePath 列出的某个可写位置,并保持“模块名目录、版本目录、同名清单”的结构。调用已导出命令时,PowerShell 才能通过命令发现机制定位并自动导入模块。
$PSModuleAutoLoadingPreference 控制自动加载行为。默认行为等同于 All,允许首次调用命令时自动导入;ModuleQualified 只在使用 WidgetTools\Get-WidgetStatus 这类模块限定名称时自动导入;None 完全禁用自动加载,此时必须显式运行 Import-Module。
模块更新后,当前会话仍可能保留旧版本。开发时可以先执行 Remove-Module WidgetTools,再按目标版本导入;-Force 会重新加载,但不能代替正确的版本目录和依赖约束。部署前应运行 Test-ModuleManifest,确认依赖、根模块和字段格式,再用 Get-Command -Module WidgetTools 检查导出边界。
若出现“找不到模块”,先检查目录是否位于 PSModulePath,再检查目录名、清单名与模块名是否一致。若出现“找不到依赖”,核对 RequiredModules 的名称与版本。若内部函数意外可见,应同时检查 Export-ModuleMember 和 FunctionsToExport,不要使用通配符导出全部函数。