命令行与文本处理 / 系统课时

创建与管理模块

创建与管理模块

本课把散落的函数整理成可安装、可导入、可版本化的 PowerShell 模块。你将创建实现文件和模块清单,限制公共命令,验证并导入模块,同时掌握依赖声明、版本选择以及命令触发自动加载的条件。

学习目标

  • 区分 .psm1 实现文件与 .psd1 模块清单的职责
  • 创建、验证并导入只暴露公共函数的脚本模块
  • 管理模块依赖、版本目录和自动加载策略

认识模块组成与加载关系

脚本模块通常以同名目录组织。.psm1 保存函数、变量和初始化逻辑;.psd1 是数据文件,用于声明根模块、版本、兼容要求、依赖与导出列表。模块被导入后会创建独立的模块作用域,未导出的内部函数不会进入调用者会话。

PowerShell 模块发现、验证与加载流程图

推荐的发布目录形态如下。版本目录不是本地直接按路径导入的硬性要求,但放入 PSModulePath 后,它能让多个版本并存并支持按版本选择。

text
WidgetTools/
└── 1.0.0/
    ├── WidgetTools.psd1
    └── WidgetTools.psm1

创建并验证最小模块

下面的完整示例在当前目录创建模块,实现两个函数,但只导出 Get-WidgetStatus。清单和实现文件同时使用导出白名单,可降低以后新增内部函数时被意外公开的风险。

powershell
$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 ',')"

预期输出:

text
{"Name":"api","Status":"Ready"}
Exported commands: Get-WidgetStatus

Reset-WidgetInternal 已加载到模块内部,但不会出现在调用者可用命令中。示例目录的完整路径取决于当前工作目录,可通过 $moduleRoot 查看实际值。验收时还应在新会话中重新导入,确认结果不依赖旧变量或旧模块实例。

管理依赖、版本与自动加载

模块自身版本写在清单的 ModuleVersion。发布多个版本时,建议使用 <PSModulePath>/WidgetTools/1.0.0/WidgetTools.psd1 这类目录结构;导入时可使用 Import-Module WidgetTools -RequiredVersion 1.0.0 精确选择版本,避免不同机器解析到不同实现。

依赖模块写入 RequiredModules。以下是清单片段示例,只有目标环境已经提供 Company.Logging 时才能通过验证;RequiredVersion 表示必须精确匹配,若只需要最低版本则改用 ModuleVersion。

powershell
@{
    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,不要使用通配符导出全部函数。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

创建与管理模块

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通