about_PSModulePath

發行項
11/06/2024

簡短描述

本文說明環境變數的 $env:PSModulePath 用途和使用方式。

詳細描述

$env:PSModulePath環境變數包含資料夾位置的清單。 PowerShell 會以遞歸方式搜尋每個資料夾的模組（.psd1 或 .psm1）檔案。

根據預設，指派給 $env:PSModulePath 的有效位置如下：

在 CurrentUser 範圍中安裝的模組：
- 在 Windows 上，這些模組會儲存在中 $HOME\Documents\PowerShell\Modules。資料夾的特定位置 Documents 會因 Windows 版本和使用資料夾重新導向而有所不同。此外，Microsoft OneDrive 可以變更資料夾 Documents 的位置。若要確認資料夾 Documents 的位置，請執行下列命令： [Environment]::GetFolderPath('MyDocuments')。
- 在非 Windows 系統上，這些模組會儲存在 $HOME/.local/share/powershell/Modules 資料夾中。
安裝在 AllUsers 範圍內的模組：
- 在 Windows 上，這些模組會儲存在中 $env:ProgramFiles\PowerShell\Modules。
- 在非 Windows 系統上，這些模組會儲存在中 /usr/local/share/powershell/Modules。
隨附於PowerShell的模組會儲存在中 $PSHOME\Modules。

注意

包含 PowerShell 模組的應用程式可以在 Windows 上的其他目錄中安裝模組，例如 Program Files 資料夾。安裝套件可能不會將位置附加至 $env:PSModulePath。

Windows PowerShell 5.1 的預設位置與 PowerShell 7 不同。

CurrentUser 範圍中安裝的模組會儲存在中$HOME\Documents\WindowsPowerShell\Modules。
安裝在 AllUsers 範圍中的模組會儲存在中$env:ProgramFiles\WindowsPowerShell\Modules。
隨附於儲存在中 $PSHOME\Modules之 Windows PowerShell 的模組，也就是 $env:SystemRoot\System32\WindowsPowerShell\1.0\Modules。

PowerShell PSModulePath 建構

每次 PowerShell 啟動時，都會建構的值 $env:PSModulePath 。此值會因 PowerShell 版本以及您啟動它的方式而有所不同。

Windows PowerShell 啟動

Windows PowerShell 會使用下列邏輯在啟動時建構 PSModulePath ：

如果 PSModulePath 不存在，請結合 CurrentUser、 AllUsers 和 $PSHOME 模塊路徑
如果 PSModulePath 存在：
- 如果 PSModulePath 包含 $PSHOME 模組路徑：
  - AllUsers 模組路徑會在模組路徑之前 $PSHOME 插入
- 還：
  - 只要依定義使用 PSModulePath ，因為使用者刻意移除 $PSHOME 位置

只有當用戶範圍$env:PSModulePath不存在時，CurrentUser 模組路徑才會加上前置詞。否則，會如定義使用用戶範圍 $env:PSModulePath 。

PowerShell 7 啟動

在 Windows 中，對於大多數環境變數而言，如果使用者範圍的變數存在，新進程只會使用該值，即使相同名稱的計算機範圍變數存在也一樣。路徑環境變數會以不同的方式處理。

在 Windows 上， PSModulePath 會被視為類似處理環境變數的方式 Path 。 Path 處理方式與其他環境變數不同。啟動程式時，Windows 會結合使用者範圍 Path 與電腦範圍 Path。

擷取用戶範圍 PSModulePath
與處理繼承的 PSModulePath 環境變數比較
- 如果相同：
  - 將 AllUsers PSModulePath 附加至環境變數語意的 Path 結尾
  - Windows System32 路徑來自定義的 PSModulePath 機器，因此不需要明確新增
- 如果不同，請視為使用者明確修改它，且不要附加 AllUsers PSModulePath
依該順序加上 PS7 用戶、 $PSHOME 系統和路徑的前置詞
- 如果 powershell.config.json 包含用戶範圍 PSModulePath，請使用該使用者，而不是用戶的預設值
- 如果 powershell.config.json 包含系統範圍 PSModulePath，請使用，而不是系統的預設

非 Windows 系統沒有使用者和系統環境變數的區隔。 PSModulePath 是繼承的，如果尚未定義 PS7 特定路徑，則會加上前置詞。

從 PowerShell 7 啟動 Windows PowerShell

在此討論中， Windows PowerShell 表示 powershell.exe 和 powershell_ise.exe。

的值 $env:PSModulePath 會隨著下列修改而複製到 WinPSModulePath ：

拿掉 PS7 使用者模組路徑
拿掉 PS7 系統模組路徑
拿掉 PS7 模組 $PSHOME 路徑

會移除 PS7 路徑，讓 PS7 模組不會在 Windows PowerShell 中載入。啟動 WinPSModulePath Windows PowerShell 時會使用此值。

從 Windows PowerShell 啟動 PowerShell 7

PowerShell 7 啟動會依目前情況繼續，並新增 Windows PowerShell 新增的繼承路徑。由於 PS7 特定路徑已加上前置詞，因此沒有功能問題。

模組搜尋行為

PowerShell 會以遞歸方式搜尋 PSModulePath 中的每個資料夾，以取得模組（.psd1或 .psm1）檔案。此搜尋模式可讓相同模組的多個版本安裝在不同的資料夾中。例如：

    Directory: C:\Program Files\WindowsPowerShell\Modules\PowerShellGet

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
d----           8/14/2020  5:56 PM                1.0.0.1
d----           9/13/2019  3:53 PM                2.1.2

根據預設，PowerShell 會在找到多個版本時載入模組的最高版本號碼。若要載入特定版本，請搭配 FullyQualifiedName 參數使用。Import-Module 如需詳細資訊，請參閱 Import-Module。

修改 PSModulePath

在大部分情況下，您應該在預設模組位置安裝模組。不過，您可能需要變更環境變數的值 PSModulePath 。

例如，若要暫時將目錄新增 C:\Program Files\Fabrikam\Modules 至 $env:PSModulePath 目前的會話，請輸入：

$Env:PSModulePath = $Env:PSModulePath+";C:\Program Files\Fabrikam\Modules"

命令中的分號（;）會將新路徑與清單中前面的路徑分隔開來。在非 Windows 平臺上，冒號（:）會分隔環境變數中的路徑位置。

在非 Windows 中修改 PSModulePath

若要變更非 Windows 環境中每個會話的值 PSModulePath ，請將上一個命令新增至 PowerShell 配置檔。

在 Windows 中修改 PSModulePath

若要變更每個會話中的值 PSModulePath ，請編輯儲存 PSModulePath 值的登錄機碼。這些PSModulePath值會以未展開的字串的形式儲存在登錄中。若要避免將值永久儲存 PSModulePath 為展開的字串，請在 GetValue() 子機碼上使用方法，並直接編輯值。

下列範例會將 C:\Program Files\Fabrikam\Modules 路徑新增至環境變數的值 PSModulePath ，而不展開未展開的字串。

$key = (Get-Item 'HKLM:\SYSTEM\CurrentControlSet\Control\Session Manager\Environment')
$path = $key.GetValue('PSModulePath','','DoNotExpandEnvironmentNames')
$path += ';%ProgramFiles%\Fabrikam\Modules'
$key.SetValue('PSModulePath',$path,[Microsoft.Win32.RegistryValueKind]::ExpandString)

若要將路徑新增至使用者設定，請使用下列程式代碼：

$key = (Get-Item 'HKCU:\Environment')
$path = $key.GetValue('PSModulePath','','DoNotExpandEnvironmentNames')
$path += ';%ProgramFiles%\Fabrikam\Modules'
$key.SetValue('PSModulePath',$path,[Microsoft.Win32.RegistryValueKind]::ExpandString)

共用方式為