我的首个PowerShell项目：如何管理脚本与相邻模块的互操作？

一、规范项目文件夹结构（兼容Git/后续发布） #

当前PowerShell模块开发的标准结构（2024年仍适用）如下，兼顾模块化、可维护性与协作需求：

MyPSModule/
├── MyPSModule.psd1          # 核心模块清单，配置元数据、导出项、依赖
├── MyPSModule.psm1          # 模块入口脚本，统一加载所有子模块/类/枚举
├── Classes/
│   ├── Enums/
│   │   ├── DockerState.ps1
│   │   └── FileSystemType.ps1
│   ├── DockerHelper.ps1
│   └── FileSystemHelper.ps1
├── Modules/
│   ├── Docker/
│   │   └── DockerFunctions.ps1
│   ├── FileSystem/
│   │   └── FileSystemFunctions.ps1
│   └── Utilities/
│       └── UtilityFunctions.ps1
└── Tests/                   # 可选但推荐，Pester测试脚本
    ├── Docker.Tests.ps1
    └── FileSystem.Tests.ps1

• psd1：必须文件，定义模块名称、版本、作者、导出的函数/类/枚举、依赖项等，是模块识别的核心配置。
• psm1：入口脚本，负责按依赖顺序加载所有子模块、类和枚举，避免手动控制文件名前缀的麻烦。
• Classes：集中存放枚举与类定义，按类型拆分文件夹便于管理。
• Modules：按业务功能拆分独立脚本文件，每个子模块对应一个业务域。
• Tests：用Pester编写测试用例，保证代码质量，适合团队协作与Git版本控制。

二、导出类与枚举的实操方法 #

PowerShell中类和枚举默认不会自动对外暴露，需通过以下步骤实现导出：

1. 按依赖顺序加载：在psm1中用点源方式加载所有枚举和类文件，无需依赖文件名前缀或非官方的Optimize-Module：

   # 先加载枚举
   . $PSScriptRoot/Classes/Enums/DockerState.ps1
   . $PSScriptRoot/Classes/Enums/FileSystemType.ps1
   
   # 再加载类
   . $PSScriptRoot/Classes/DockerHelper.ps1
   . $PSScriptRoot/Classes/FileSystemHelper.ps1
   

2. 显式导出：在psm1末尾用Export-ModuleMember指定对外暴露的内容，PowerShell 5.1+支持直接导出类和枚举：

   # 导出指定函数、所有类和枚举
   Export-ModuleMember -Function Get-DockerContainer, Get-FileSystemItem -Type Class, Enum
   
   # 若需指定具体类/枚举，可单独声明
   # Export-ModuleMember -Function ... -Class DockerHelper -Enum DockerState
   

3. 模块清单配置：在psd1中确保RootModule指向psm1，并可通过NestedModules列出所有需加载的脚本（但用psm1统一加载更灵活）。

三、模块间依赖导入的正确方式 #

针对同一项目内的子模块依赖（如Docker模块依赖Utilities），推荐两种可靠方案：

方案1：主入口统一加载（推荐） #

在psm1中按依赖顺序加载所有子模块，确保Utilities先于Docker加载：

# 先加载通用工具模块
. $PSScriptRoot/Modules/Utilities/UtilityFunctions.ps1

# 再加载依赖它的Docker模块
. $PSScriptRoot/Modules/Docker/DockerFunctions.ps1

这种方式无需每个子模块自行处理依赖，由主入口统一控制加载顺序，维护成本更低。

方案2：子模块内相对路径加载 #

若需在Docker模块脚本中直接加载Utilities，可通过$PSScriptRoot（当前脚本所在目录）构造相对路径：

# 在DockerFunctions.ps1开头添加
. $PSScriptRoot/../Utilities/UtilityFunctions.ps1

若后续将Utilities拆分为独立模块，可在Docker模块的psd1中配置RequiredModules = @('MyPSModule.Utilities')，确保安装Docker模块时自动拉取依赖。

四、共享与发布建议 #

• Git协作：上述结构天然兼容Git，每个文件职责单一，便于提交、冲突解决与版本回溯。
• 私有Artifactory发布：将模块打包为NuGet包（可使用Publish-Module命令，或手动用NuGet CLI打包），推送到Artifactory的NuGet仓库，同事可通过Install-Module -Repository <私有仓库名>安装使用。

参考资料 #

• PowerShell官方模块开发指南：重点关注模块清单（psd1）、模块脚本（psm1）的配置规范。
• Pester官方文档：用于编写测试用例，保障模块质量。
• PowerShell Gallery模块结构规范：参考主流模块的组织方式，确保兼容性。

内容的提问来源于stack exchange，提问作者Solonotix