本文說明如何判斷、診斷並修復使用 Microsoft Entra PowerShell 時可能遇到的問題。
在排除任何錯誤之前，請確保你使用的是最新版本的 Microsoft Entra PowerShell。 要檢查你安裝模組的版本，請執行：
Get-InstalledModule -Name Microsoft.Entra
Microsoft.Entra 模組的版本應為最新版本，並與 PowerShell 資源庫 中的最新發行版本一致。 如果你安裝的模組不是最新的，請透過以下方式更新：
Update-Module -Name Microsoft.Entra
安裝問題
安裝過程中，可能會遇到一些錯誤，導致模組無法正確安裝。 以下是一些常見問題及其解決方案。
找不到 AllowPrerelease 參數
如果你使用較舊版本的 Install-Module，可能會收到錯誤：「Install-Module： 找不到與參數名稱 AllowPrerelease相符的參數。」要修正此錯誤，請執行以下指令升級：
## Update Nuget Package and PowerShellGet Module
Install-PackageProvider NuGet -Scope CurrentUser -Force
Install-Module PowerShellGet -Scope CurrentUser -Force -AllowClobber
## Remove old modules from existing session
Remove-Module PowerShellGet,PackageManagement -Force -ErrorAction Ignore
## Import updated module
Import-Module PowerShellGet -MinimumVersion 2.0 -Force
Import-PackageProvider PowerShellGet -MinimumVersion 2.0 -Force
此範圍內的函式容量已超過 4096 的上限
在 PowerShell 5.1 中，你可能會看到錯誤：「函式 {cmdlet-name} 無法建立，因為函式容量 4096 已被超越。」要修正此錯誤，請執行以下指令增加函式限制，然後嘗試再次匯入模組。
$MaximumFunctionCount = 32768
模組中已可取得的指令
如果已安裝 Beta 或 v1.0 而發生衝突，您可能會看到下列錯誤訊息：「此系統上已可使用下列命令：Enable-EntraAzureADAlias、Get-EntraUnsupportedCommand、Test-EntraScript。」請新增 -AllowClobber 參數，然後重新執行該命令以修正此錯誤。
遺漏相依性
當 Microsoft Entra PowerShell 相依性未安裝時，你可能會看到錯誤：「此電腦上未安裝依賴模組module-name。使用目前Microsoft.Entra模組時，請確保其相依模組module-name已安裝。「要解決此錯誤，請使用以下腳本安裝相依關係：
- 安裝 Microsoft Graph PowerShell SDK
v1.0相依關係。
$RequiredModules = (@'
Microsoft.Graph.DirectoryObjects
Microsoft.Graph.Users
Microsoft.Graph.Users.Actions
Microsoft.Graph.Users.Functions
Microsoft.Graph.Groups
Microsoft.Graph.Identity.DirectoryManagement
Microsoft.Graph.Identity.Governance
Microsoft.Graph.Identity.SignIns
Microsoft.Graph.Applications
'@).Split("`n")
# Check if the pre-requisite modules are installed and install them if needed
foreach ($module in $RequiredModules) {
Write-Host -ForegroundColor Yellow -BackgroundColor DarkBlue "Checking for $module"
if (!(Get-Module -Name $module -ListAvailable)) {
Install-Module -Name $module -Scope CurrentUser
}
}
<# Attribution: https://github.com/SamErde and https://github.com/alexandair #>
驗證問題
未能驗證或接收令牌可能會導致「401 未授權」回應。 發生這個錯誤的原因有下列幾種。 要修正這個錯誤，請確保你使用正確的憑證並擁有足夠的權限。 檢查你的應用程式註冊（如果適用）是否正確設定，並有 Microsoft Entra ID 中所需的 API 權限。
無法辨識 Cmdlet
PowerShell 無法辨識你正在執行的 cmdlet。 要修正這個錯誤，請確保 Microsoft Entra PowerShell 模組安裝正確。 您可以透過以下方式查詢此狀態：
Get-Module -Name Microsoft.Entra -ListAvailable
如果模組沒有列出，請用以下方法安裝：
Install-Module -Name Microsoft.Entra -Repository PSGallery -Force
版本衝突
你可能會遇到錯誤，顯示模組已安裝多個版本，例如「同名的組合檔已載入」。要解決這個錯誤，請先卸載所有衝突版本的模組，然後安裝最新版本：
Install-Module <Module-Name> -Required Version x.x
權限錯誤
執行指令或腳本時，可能會收到權限不足的錯誤。 要修正這個錯誤，請確保你擁有執行該操作所需的權限。 你可能需要在 Microsoft Entra 系統管理中心 調整權限。
模組更新問題
你在嘗試更新 Microsoft Entra PowerShell 模組時可能會遇到問題。 要修正這個錯誤，請使用該摘要來安裝最新版本。 如果有錯誤，試著 卸載 再重新安裝模組。
Install-Module -Name Microsoft.Entra -Repository PSGallery -Force
效能問題
你的腳本或指令可能執行得很慢，或沒有如預期完成。 為了解決這個問題，可以考慮調整你的查詢，只取得必要的資料，使用篩選器並選擇特定屬性。 必要時增加暫停時間。
處理錯誤
你可能會收到來自 Microsoft Entra PowerShell 模組的錯誤，這些錯誤難以理解或管理。
要修正這個錯誤，請使用 $Error[0].Exception | Format-List -Force 以獲取詳細的錯誤資訊。 這些資訊有助於理解 API 回應並進一步排除故障。
代理伺服器阻擋連線
如果你從 Install-Module 收到指出 PowerShell 資源庫 無法連線的錯誤，則你可能位於 Proxy 伺服器後方。 不同的操作系統和網路環境對於配置全域代理有不同的要求。 請聯絡您的系統管理員以獲取您的代理設定及如何在您的環境中進行配置。
PowerShell 本身可能沒有自動設定使用這個代理。 使用 PowerShell 5.1 和更新版本時，請使用下列命令，將 PowerShell 會話設定為使用 Proxy：
$webClient = New-Object -TypeName System.Net.WebClient
$webClient.Proxy.Credentials = [System.Net.CredentialCache]::DefaultNetworkCredentials
如果您的作業系統憑證已正確設定，此設定會透過代理路由傳送 PowerShell 要求。 若要使此設定在會話之間保持不變，請將這些命令加入到你的PowerShell 配置檔案中。
要安裝此套件，您的代理伺服器需要允許到 www.powershellgallery.com 的 HTTPS 連接。
其他問題
如果您在使用 Microsoft Entra PowerShell 時遇到本文未列出的產品問題，或需要進一步協助，請在 GitHub 上提出問題。