排除 Az PowerShell 模組的故障

2025-06-05

啟用偵錯記錄

排除 Az PowerShell 模組問題時，您應採取的第一步之一是啟用除錯日誌記錄。

若要根據每個命令啟用偵錯記錄，請指定 Debug 參數。

Get-AzResource -Name 'DoesNotExist' -Debug

若要啟用整個 PowerShell 工作階段的偵錯記錄，請將 DebugPreference 變數的值設定為 Continue。

$DebugPreference = 'Continue'

自動化情境中的公告訊息

使用 Azure PowerShell 連線到 Azure 時，會使用 PowerShell 的資訊數據流來顯示公告訊息，以防止訊息改變傳回的對象型輸出。雖然我們已盡一切努力確保公告訊息不會影響您的體驗，但有些自動化案例可能會影響使用量。如果您遇到問題，我們建議您在這些情況下抑制信息流。

Connect-AzAccount -Subscription '<subscription name or id>' -InformationAction Ignore

網路帳戶管理員 (WAM)

互動式登入方法無法為WAM開啟視窗並返回錯誤：使用者取消了驗證。
使用使用者名稱和密碼或裝置程式代碼登入之後，就無法執行 Azure PowerShell Cmdlet。
WAM 彈出視窗未顯示工作和學校帳戶選項。
互動式登入方法無法在 Windows PowerShell ISE 控制台中開啟 WAM 視窗。

解決這些問題的替代方法是禁用WAM：

Update-AzConfig -EnableLoginByWam $false

選取帳戶的 WAM 彈出視窗並不容易找到。將其他視窗最小化以找出彈出視窗。

安裝

本節包含安裝 Az PowerShell 模組時常見問題的解決方案清單。

Az 和 AzureRM 共存

警告

我們不支援在 Windows PowerShell 5.1 中同時安裝 AzureRM 和 Az PowerShell 模組。

在需要在同一台 Windows 系統上安裝 AzureRM 和 Az PowerShell 模組的情況下：

AzureRM 只能安裝在 Windows PowerShell 5.1 的目前用戶範圍中。
在 PowerShell 7.2 或更高版本中安裝 Az PowerShell 模組。

警告

自 2024 年 2 月 29 日起，AzureRM PowerShell 模組已正式淘汰。建議使用者從 AzureRM 遷移到 Az PowerShell 模組，以確保獲得持續的支援和更新。

雖然 AzureRM 模組可能仍可運作，但它已不再維護或支援，若繼續使用則需由用戶自行承擔風險和責任。請參考我們的遷移資源，以獲取關於轉換至 Az 模組的指引。

Visual Studio

舊版 Visual Studio 可能會安裝 Azure PowerShell 作為 Azure 開發工作負載的一部分，以安裝 AzureRM 模組。您可以使用 Visual Studio 安裝程式或使用應用程式 & 功能的「卸載」來移除 Azure PowerShell。如果您已經安裝了 PowerShell 7.x，您可能需要手動安裝 Az PowerShell 模組。

代理伺服器阻擋連線

如果您收到 Install-Module 錯誤，表示無法連線到 PowerShell 畫廊，這可能是因為您位於代理伺服器後面。不同的操作系統和網路環境對於配置全域代理有不同的要求。請聯絡您的系統管理員以獲取您的代理設定及如何在您的環境中進行配置。

PowerShell 本身可能未設定為自動使用此 Proxy。使用 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 連接。

未將物件參考設定為一個物件實例

該訊息「物件參考未設定為物件的實例」表示您正在引用一個為 null 的物件，或引用一個不存在的 Azure 資源，或您沒有權限存取該資源。

$resourceId =  '/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/<resource-group-name>/providers/Microsoft.Web/sites/<webapp-name>/privateEndpointConnections/<endpoint-name>'
Get-AzPrivateEndpointConnection -ResourceId $resourceId

Get-AzPrivateEndpointConnection: Object reference not set to an instance of an object.

您可以使用 Get-AzResource Cmdlet 來驗證指定的 Azure 資源是否存在。

Get-AzResource -ResourceId $resourceId

AzAD cmdlets 的權限問題

Az PowerShell 模組會使用 Microsoft Graph API。使用 Az PowerShell 模組在 Azure 中管理或管理資源需要與從 Azure 入口網站或任何其他 Azure 命令行工具執行相同工作相同的許可權。若有關於權限的具體問題，請參閱 Microsoft Graph 權限參考。

Microsoft Graph 查詢參數

Az.Resources 下的 AzAd 命令現已支援查詢參數和搜索查詢參數。關於語法的詳細資訊，請參閱先前提到的鏈接。

Get-AzAdGroupMember 不會返回服務主體

由於目前 Graph API 的限制，Get-AzAdGroupMember 在 Az 7.x 中不會傳回服務主體。因應措施是，Invoke-AzRestMethod 可以搭配 Microsoft Graph API 的 Beta 版本使用。

以下範例需要 Az PowerShell 模組。以群組名稱取代第一行中的 myGroupName。

$Group = Get-AzADGroup -DisplayName myGroupName
((Invoke-AzRestMethod -Uri "https://graph.microsoft.com/beta/groups/$($Group.id)/members").Content |
  ConvertFrom-Json).value |
  Select-Object -Property DisplayName, Id, @{label='OdataType';expression={$_.'@odata.type'}}

找到但無法載入的命令

當您嘗試執行任何 Az PowerShell 命令時，PowerShell 會傳回下列訊息。

Connect-AzAccount: The 'Connect-AzAccount' command was found in the module 'Az.Accounts', but the module could not be loaded. For more information, run 'Import-Module Az.Accounts'.

當您在同一個基於 Windows 的系統上安裝了 Az 和 AzureRM PowerShell 模組，並且它們存在於相同版本的 PowerShell 的 $env:PSModulePath 中時，會出現此訊息。

這很重要

當 AzureRM 安裝在 Windows PowerShell 的 AllUsers 範圍時，它會被安裝在屬於 PowerShell 7 的 $env:PSModulePath 中的一個位置。由於 AzureRM 與 Az PowerShell 模組之間的衝突，因此不支援此功能。

Az 和 AzureRM 可以同時存在於相同的 Windows 系統上，但前提是 AzureRM 安裝在 Windows PowerShell 的 CurrentUser 範圍內，而 Az 則安裝在 PowerShell 7 中。如需詳細資訊，請參閱安裝 Az PowerShell 模組。

警告

自 2024 年 2 月 29 日起，AzureRM PowerShell 模組已正式淘汰。建議使用者從 AzureRM 遷移到 Az PowerShell 模組，以確保獲得持續的支援和更新。

在 MacOS 上，當 KeyChain 授權失敗時會返回錯誤。

在 MacOS 上執行 Azure PowerShell 時，您可能會在嘗試從 PowerShell 會話中登入您的 Azure 帳戶時遇到錯誤訊息。

DeviceCodeCredential authentication failed: Persistence check failed. Reason: KeyChain authorization/authentication failed. .Error code: -25293. OS error code -25293.

為了應對此問題，您可以執行以下命令來禁用在會話之間儲存憑據的功能。不過，進行這項變更之後，每次啟動新的PowerShell會話時，都必須執行 Connect-AzAccount。

Disable-AzContextAutosave

此網站的連線不安全

當您的預設瀏覽器是 Microsoft Edge 時，您可能會在互動式登入 Azure 時遇到以下錯誤："Connect-AzAccount" 要解決此問題，請造訪 Microsoft Edge 的 edge://net-internals/#hsts。在「localhost」的下方添加，然後點擊刪除。

服務主體識別符Uri已驗證網域錯誤

錯誤：。

由於 Microsoft 的重大變更要求單一租戶應用程式中的 AppId URI 必須使用預設方案或已驗證網域，因此您必須將 Az.Resources 模組升級到 4.1.0 版或更新版本，以便繼續使用 New-AzADServicePrincipal 或 New-AzADApplication Cmdlet。

您也可以升級至 Az PowerShell 模組 6.0 版或更新版本。

時程表

該要求於2021年10月15日生效。

受影響的版本

下列版本的 Azure PowerShell 會受到 AzureAD 重大變更的影響：

Az.Resources PowerShell 模組版本為 3.5.1-preview 或更低。
Az PowerShell 模組版本 5.9.0 或更早版本。

如果您在升級後仍遇到問題，歡迎開一個問題。

因應措施

如果您無法升級至先前所述的 PowerShell 模組，您可以在建立服務主體時遵循這些步驟：

如有需要，使用 Microsoft Entra 管理中心添加您的自訂網域名稱
使用公認的IdentifierUri建立應用程式
建立指向此應用程式的服務主體

其他問題

如果您遇到未在本文中列出的 Azure PowerShell 產品問題或需要進一步協助，請在 GitHub 上提交問題。

共用方式為