PSModulePath 是干什么的
PSModulePath 是一个用分号分隔的目录清单，PowerShell 在自动发现模块时按顺序到这些目录里找。它包含用户级目录（我的文档下的 PowerShell\Modules）、PowerShell 安装目录下的 Modules，以及系统级共享目录（Program Files 下的模块路径）。当这个变量被改坏或被覆盖，就会出现“明明装了模块却提示找不到命令”的经典故障。
基本信息
| 适用平台 | Windows PowerShell 5.1 与 PowerShell 7+（路径不同） |
|---|---|
| 查看 | $env:PSModulePath -split ';' |
| 默认位置 | $env:USERPROFILE\Documents\PowerShell\Modules、$PSHOME\Modules、Program Files 下系统模块目录 |
| 持久化 | [Environment]::SetEnvironmentVariable('PSModulePath', $value, 'User') |
典型使用场景
- 自研模块放哪里：放进用户级模块目录即可被自动发现
- 排查“模块找不到”：确认路径列表是否被覆盖或缺少关键目录
- 更换 PowerShell 版本：5.1 与 7 的模块路径不同，需要同时覆盖
- 多版本并存：把自研模块放到共享目录供多版本共用
- 自动化部署：安装脚本中安全地追加模块路径
常用示例
常用示例
# 查看当前搜索路径（逐行列出更直观）
$env:PSModulePath -split ';'
# 当前会话追加自研模块目录
$env:PSModulePath += ';D:\Tools\Modules'
# 确认模块目录结构是否符合约定（目录名=模块名，内含 .psd1/.psm1）
Test-Path (Join-Path $env:USERPROFILE 'Documents\PowerShell\Modules')
Get-ChildItem (Join-Path $env:USERPROFILE 'Documents\PowerShell\Modules') -Directory | Select-Object Name
# 验证模块能否被发现
Get-Module -ListAvailable | Where-Object Name -like 'MyMod*'
# 持久化（先备份原值再写）
[Environment]::SetEnvironmentVariable('PSModulePath', $env:PSModulePath + ';D:\Tools\Modules', 'User')路径与顺序
| 位置 | 典型路径 | 优先级说明 |
|---|---|---|
| 用户模块目录 | %USERPROFILE%\Documents\PowerShell\Modules | 仅当前用户可见 |
| PowerShell 安装目录 | $PSHOME\Modules | 随 PowerShell 版本变化 |
| 系统共享目录 | Program Files\PowerShell\Modules | 全机可用，需管理员写入 |
| 追加的自定义目录 | 按需指定 | 列表靠前时优先命中 |
同名模块在多个路径下都存在时，先匹配到列表靠前的那一个。调试“为什么加载的是旧版本”时，用 Get-Module -ListAvailable 看全部候选及版本，再看路径顺序。
追加路径只影响当前会话；要长期生效必须写环境变量。写入前先导出原值，避免把一长串路径改错后无法还原。
PSModulePath 的分隔符在 Windows 上是分号。照抄 Linux 上以冒号分隔的写法会导致整串被当成一个目录，结果是所有模块都找不到，而报错信息完全指不到这里。