在 macOS 上安裝 Azure CLI - 預覽版本

Azure CLI 是一款跨平台的命令列工具，可透過互動式或腳本管理 Azure 資源。

在 macOS 上，Azure CLI 正從 Homebrew Core 的公式轉型為更易維護且具彈性的安裝模式。 新模式包括：

  • Homebrew Cask（建議大多數使用者使用）
  • Tarball（建議離線或空中隔斷環境使用）

此體驗目前處於預覽階段，未來版本將成為標準安裝方式。

為什麼要用自釀桶？

  • 最簡單的安裝與升級體驗
  • 自動管理相依性
  • 與未來支援的安裝模式相符

變更事項

Azure CLI 正在演進以支援更安全的認證，包括基於經紀人的認證。 這些能力需要基於 Cask 的安裝模式。 因此，我們正從 Homebrew Core 轉向 Homebrew Cask。 此變更並未移除或限制任何現有的 Azure CLI 功能。 Homebrew Cask 完全相容於所有目前 Azure CLI 的功能與版本。

此變更提升了各環境間的一致性，並提供更佳的離線安裝與受控部署環境支援。

Important

Azure CLI 目前正處於 Homebrew Cask 安裝模型的預覽階段。 在此階段，安裝僅能透過自訂的 Homebrew tap 進行。

  • 目前的方法： brew install azure-cli
  • 新方法（預覽階段）：
    • 自製桶裝自製水龍頭
      1. brew tap azure/azure-cli
      2. brew install --cask azure-cli-preview
    • 以瀝青為基礎的安裝

選擇安裝方法

請參考以下指引，選擇最適合您情況的安裝方法：

狀況 建議的方法
大多數使用者 自釀桶
離線系統或物理隔離系統 瀝青球
需自訂安裝位置 瀝青球

使用 Homebrew Cask 來安裝 Azure CLI

Homebrew 提供 macOS 上 Azure CLI 最簡單且易於維護的安裝體驗。 它透過標準套件管理工作流程處理安裝、升級與移除。

先決條件

  • macOS（Apple Silicon 或 Intel）
  • Homebrew 安裝

如果已經用 Homebrew 公式安裝了 Azure CLI，請先先卸載，避免衝突：

brew uninstall azure-cli

安裝 Azure CLI

此操作將使用 Azure CLI 自訂 tap 的 Homebrew Cask 來安裝 Azure CLI。 這是預覽階段唯一支援的 Homebrew 安裝方法。

brew tap azure/azure-cli
brew install --cask azure-cli-preview

確認安裝

安裝後，確認 Azure CLI 可用：

az --version

升級 Azure CLI

要升級到最新版本：

brew update && brew upgrade --cask azure-cli-preview

解除安裝 Azure CLI

移除Azure CLI：

brew uninstall --cask azure-cli-preview
brew untap azure/azure-cli

預覽階段結束後

當 Homebrew Cask 安裝系統普遍可用時：

  • 預覽安裝方式（azure-cli-preview 透過自訂點擊）將會停止。
  • Azure CLI 將可從官方 Homebrew Cask 儲存庫取得。

透過以下指令安裝 Azure CLI：

brew install --cask azure-cli
# Or
brew install azure-cli

現有使用 Homebrew Core 公式的安裝必須遷移到 Cask 基礎安裝。 自製核心公式在此轉換後將不再支援。

使用 Tarball 安裝 Azure CLI

如果有以下情況，請使用此方法：

  • Homebrew 無法取得
  • 網路存取受限
  • 你需要完全掌控安裝地點

此方法常用於企業、管制或空氣隔離環境。

先決條件

  • macOS（Apple Silicon 或 Intel）
  • Python 3.13 可透過任何方式安裝（python.org、pyenv 等）。

下載瀝青球

在連上網路的機器上，你可以自動下載針對你的系統架構的最新 Azure CLI 壓縮文件：

ARCH=$(uname -m)
VER=$(curl -s https://api.github.com/repos/Azure/azure-cli/releases/latest | grep tag_name | cut -d '"' -f4 | sed 's/azure-cli-//')
curl -L -o az.tar.gz "https://github.com/Azure/azure-cli/releases/download/azure-cli-$VER/azure-cli-$VER-macos-$ARCH.tar.gz"

這個腳本會偵測你的架構，並從 Azure CLI releases 頁面下載最新的 Azure CLI tarball。

  • arm64 表示蘋果矽晶片
  • x86_64 表示 Intel

選擇合適的架構能確保相容性與最佳效能。

小提示

離線環境下，先在有網路連線的機器上執行此指令，然後將下載的 tarball 傳送到目標系統。

解壓到安裝目錄

選擇一個應該安裝 Azure CLI 的目錄：

mkdir -p $HOME/lib/azure-cli
tar -xzf az.tar.gz -C $HOME/lib/azure-cli

設定環境變數

Azure CLI 需要存取 Python 執行環境。 設定你的環境指向 Python 和 Azure CLI 二進位檔。

在你的殼體配置檔中加入以下項目（~/.zshrc 或 ~/.bashrc）：

export AZ_PYTHON="/path_to_python"
export PATH="/target_directory_path/bin:$PATH"

重新裝填你的彈殼配置：

source ~/.zshrc

確認安裝

az --version

升級 Azure CLI

若要在離線環境中升級 Azure CLI，請下載較新的 Tarball 並從現有安裝中解壓：

sudo tar -xzf az.tar.gz -C /target_directory_path

解除安裝 Azure CLI

移除安裝目錄：

sudo rm -rf /target_directory_path

然後從你的 Shell 檔案中移除 AZ_PYTHON 並 PATH 條目。

Troubleshooting

如果你在安裝或使用 Azure CLI 搭配 Homebrew Cask 或 Tarball 方法時遇到問題，以下是一些常見錯誤（其中許多是 Homebrew 特有的）。 如果您遇到此處未涵蓋的問題， 請在 GitHub 上提出問題。

找不到 Azure CLI

確保您的 PATH 包含安裝目錄：

echo $PATH

"完成功能無法運作"

Azure CLI Homebrew 安裝（無論是配方還是桶裝）會在 Homebrew 的管理完成目錄中提供一個名為 az 的完成檔案。 要完成該程序，請依照 Homebrew 的指示操作。

針對 Zsh，將下列兩行新增至檔案 .zshrc 底部，然後儲存並重載您的 Zsh 配置檔。

autoload bashcompinit && bashcompinit
source $(brew --prefix)/etc/bash_completion.d/az

找不到 Python 或已安裝的套件

在安裝 homebrew 的過程中，可能會遇到小版本號不相符或其他問題。 Azure CLI 不使用 Python 虛擬環境，因此依賴找到已安裝的 Python 版本。 可能的修正是安裝並重新連結 Homebrew 的 python@3.13 相依性。

brew update && brew install python@3.13 && brew upgrade python@3.13
brew link --overwrite python@3.13

代理伺服器阻擋連線

除非您將 Homebrew 設定為使用代理伺服器，否則可能無法取得資源。 請遵循 Homebrew Proxy 設定指示。

Important

如果透過代理伺服器，必須設定 HTTP_PROXY 和 HTTPS_PROXY 以透過 Azure CLI 連接到 Azure 服務。 如果您沒有使用基本身份驗證，您應該在檔案中 .bashrc 匯出這些變數。 請一律遵循您企業的安全策略和系統管理員的需求。

若要從 Homebrew 取得瓶裝資源，您的 Proxy 必須允許 HTTPS 連線到下列位址：

  • https://formulae.brew.sh
  • https://homebrew.bintray.com

後續步驟

現在你在 macOS 上安裝了 Azure CLI，簡單介紹一下它的功能和常見指令。

開始使用 Azure CLI

  • Last updated on