安裝 Google Cloud CLI

本快速入門指南說明安裝及初始化 Google Cloud CLI 的建議方法。初始化完成後，請執行幾個核心 gcloud CLI 指令，查看安裝相關資訊並確認安裝成功。

如要直接在 Google Cloud 控制台中，按照這項工作的逐步指南操作，請按一下「Guide me」(逐步引導)：

「Guide me」(逐步引導)

事前準備

  1. 登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎 建立帳戶，親自體驗產品的實際應用成效。新客戶還能獲得價值 $300 美元的免費抵免額，能用於執行、測試及部署工作負載。

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

安裝 gcloud CLI 588.0.0 版

Linux
  1. 確認您使用的是支援的 Python 版本。Google Cloud CLI 需使用 Python 3.10 至 3.15 版。x86_64 Linux 套件內含預設會優先使用的 Python 解譯器。如要瞭解如何選擇及設定 Python 解譯器，請參閱 gcloud topic startup 說明文件。
  2. 下載下列其中一個檔案：
    平台 套件名稱 大小 SHA256 總和檢查碼
    Linux 64 位元

    (x86_64)

    		 google-cloud-cli-linux-x86_64.tar.gz 88.0 MB 73b6678401811a8a1b8d0ce29e043834308d9263ae6d9577c5aadc55621cd7d3
    Linux 64 位元

    (Arm)

    		 google-cloud-cli-linux-arm.tar.gz 53.9 MB e1e41985e1f0461f325793ceb64b3c5d12bf0f6235cd580bfc891d836d3d1efc
    Linux 32 位元

    (x86)

    		 google-cloud-cli-linux-x86.tar.gz 54.0 MB 628412e03eea8d1d698b924d09ad89ad835fb322fdebb5df7541c8c3f147516c

    如要下載 Linux 封存檔，請執行下列指令： 

    curl -O https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-linux-x86_64.tar.gz

    請參閱上表，並將 google-cloud-cli-linux-x86_64.tar.gz 替換為適用於您設定的 *.tar.gz 套件名稱。

  3. 如要將檔案內容解壓縮至檔案系統，請執行下列指令： 
    tar -xf google-cloud-cli-linux-x86_64.tar.gz
     如要取代現有安裝項目，請刪除現有的 google-cloud-sdk 目錄，然後將封存檔解壓縮到相同位置。
  4. 從解壓縮的資料夾根目錄執行安裝指令碼： 
    ./google-cloud-sdk/install.sh
     指令碼會提示您執行下列設定動作。如要接受，請在系統提示時回答 Y。
    • 將 gcloud CLI 新增至 PATH。
    • 啟用指令完成功能。
    • 選擇傳送匿名使用統計資料，協助改善 gcloud CLI。
    您也可以提供旗標，以非互動方式執行安裝作業。 如要查看可用的旗標，請執行下列指令： 
    ./google-cloud-sdk/install.sh --help
  5. 選用：如果您在上一步更新了 PATH，請開啟新的終端機，讓變更生效。
Debian/Ubuntu

套件內容

gcloud CLI 提供套件格式，可安裝在 Debian 和 Ubuntu 系統上。這個套件只包含 gcloud、gcloud alpha、gcloud beta、gsutil 和 bq 指令列工具。這不包括 kubectl，也不包括使用 gcloud 指令部署應用程式時所需的 App Engine 擴充功能。如要使用這些元件，請另外安裝。

事前準備

安裝 gcloud CLI 前，請確認您的作業系統符合下列需求：

  • 這是尚未終止服務的 Ubuntu 版本，或是尚未終止服務的 Debian 穩定版本。
  • 該服務最近更新了套件。如要立即執行這項操作，請執行下列指令： 
    sudo apt-get update
  • 已安裝 ca-certificates、gnupg 和 curl。如要安裝這些套件，請執行下列指令： 
    sudo apt-get install ca-certificates gnupg curl

安裝

  1. 匯入 Google Cloud 公開金鑰。

    • 如為較新的發行版本 (Debian 9 以上或 Ubuntu 18.04 以上)，請執行下列指令：

      curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo gpg --dearmor -o /usr/share/keyrings/cloud.google.gpg
    • 如為舊版發行版本，請執行下列指令： 
      curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key --keyring /usr/share/keyrings/cloud.google.gpg add -

    • 如果發布版本的 apt-key 指令不支援 --keyring 引數，請執行下列指令：

      curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key add -

    • 如果金鑰過期而無法取得最新更新，請取得最新的 apt-get.gpg 金鑰檔案。

  2. 將 gcloud CLI 發布 URI 新增為套件來源。
    • 如為較新的發行版本 (Debian 9 以上或 Ubuntu 18.04 以上)，請執行下列指令： 
      echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" | sudo tee -a /etc/apt/sources.list.d/google-cloud-sdk.list

    • 如為不支援 signed-by 選項的舊版發行版本，請執行下列指令：

      echo "deb https://packages.cloud.google.com/apt cloud-sdk main" | sudo tee -a /etc/apt/sources.list.d/google-cloud-sdk.list
  3. 更新並安裝 gcloud CLI： 
    sudo apt-get update && sudo apt-get install google-cloud-cli
     如需其他 apt-get 選項 (例如停用提示或試運轉)，請參閱 apt-get 手冊頁面。

    Docker 提示：如果在 Docker 映像檔中安裝 gcloud CLI，請改用單一 RUN 步驟：

    RUN echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" | tee -a /etc/apt/sources.list.d/google-cloud-sdk.list && curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | gpg --dearmor -o /usr/share/keyrings/cloud.google.gpg && apt-get update -y && apt-get install google-cloud-cli -y
    對於不支援 gpg --dearmor 指令的舊版基礎映像檔： 
    RUN echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" | tee -a /etc/apt/sources.list.d/google-cloud-sdk.list && curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | apt-key --keyring /usr/share/keyrings/cloud.google.gpg  add - && apt-get update -y && apt-get install google-cloud-cli -y
  4. 選用：安裝下列任一額外元件：
    • google-cloud-cli-anthos-auth
    • google-cloud-cli-app-engine-go
    • google-cloud-cli-app-engine-grpc
    • google-cloud-cli-app-engine-java
    • google-cloud-cli-app-engine-python
    • google-cloud-cli-app-engine-python-extras
    • google-cloud-cli-bigtable-emulator
    • google-cloud-cli-cbt
    • google-cloud-cli-cloud-build-local
    • google-cloud-cli-cloud-run-proxy
    • google-cloud-cli-config-connector
    • google-cloud-cli-datastore-emulator
    • google-cloud-cli-firestore-emulator
    • google-cloud-cli-gke-gcloud-auth-plugin
    • google-cloud-cli-kubectl-oidc
    • google-cloud-cli-local-extract
    • google-cloud-cli-minikube
    • google-cloud-cli-nomos
    • google-cloud-cli-pubsub-emulator
    • google-cloud-cli-skaffold
    • google-cloud-cli-spanner-emulator
    • google-cloud-cli-terraform-tools
    • google-cloud-cli-tests
    • kubectl

    例如，您可以按照以下方式安裝 google-cloud-cli-app-engine-java 元件：

    sudo apt-get install google-cloud-cli-app-engine-java

降級 gcloud CLI 版本

如要還原至特定版本的 gcloud CLI (其中 VERSION 的格式為 123.0.0)，請執行下列指令：

sudo apt-get update && sudo apt-get install google-cloud-cli=123.0.0-0

在過去 365 天內發布的套件版本會保留在存放區中。

Red Hat/Fedora/CentOS

套件內容

gcloud CLI 提供套件格式，可安裝在 Red Hat Enterprise Linux 7、8、9 和 10；Fedora 41 和 42；以及 CentOS 7 和 8 系統。這個套件只包含 gcloud、gcloud alpha、gcloud beta、gsutil 和 bq 指令。其中不包含 kubectl，也不包含使用 gcloud 指令部署應用程式時所需的 App Engine 擴充功能。如本節稍後所述，這些擴充功能可以另外安裝。

安裝

  1. 使用 gcloud CLI 存放區資訊更新 DNF。

    • 下列範例指令適用於 Red Hat Enterprise Linux 7、8 或 9 相容的安裝作業，但請務必視需要更新設定：

      sudo tee -a /etc/yum.repos.d/google-cloud-sdk.repo << EOM
[google-cloud-cli]
name=Google Cloud CLI
baseurl=https://packages.cloud.google.com/yum/repos/cloud-sdk-el9-x86_64
enabled=1
gpgcheck=1
repo_gpgcheck=0
gpgkey=https://packages.cloud.google.com/yum/doc/rpm-package-key.gpg
EOM

    • 如要安裝與 RHEL 10 相容的套件，請使用下列指令，並更新 gpgkey：

      sudo tee -a /etc/yum.repos.d/google-cloud-sdk.repo << EOM
[google-cloud-cli]
name=Google Cloud CLI
baseurl=https://packages.cloud.google.com/yum/repos/cloud-sdk-el10-x86_64
enabled=1
gpgcheck=1
repo_gpgcheck=0
gpgkey=https://packages.cloud.google.com/yum/doc/rpm-package-key-v10.gpg
EOM

    • 如為 ARM64 (aarch64) 安裝作業，請使用 https://packages.cloud.google.com/yum/repos/cloud-sdk-el9-aarch64 (與 RHEL 7、8 或 9 相容) 或 https://packages.cloud.google.com/yum/repos/cloud-sdk-el10-aarch64 (與 RHEL 10 相容) 做為 baseurl 值。

  2. 安裝 libxcrypt-compat.x86_64。 
    sudo dnf install libxcrypt-compat.x86_64
  3. 安裝 gcloud CLI： 
    sudo dnf install google-cloud-cli
  4. 選用：安裝下列任一額外元件：
    • google-cloud-cli-anthos-auth
    • google-cloud-cli-app-engine-go
    • google-cloud-cli-app-engine-grpc
    • google-cloud-cli-app-engine-java
    • google-cloud-cli-app-engine-python
    • google-cloud-cli-app-engine-python-extras
    • google-cloud-cli-bigtable-emulator
    • google-cloud-cli-cbt
    • google-cloud-cli-cloud-build-local
    • google-cloud-cli-cloud-run-proxy
    • google-cloud-cli-config-connector
    • google-cloud-cli-datastore-emulator
    • google-cloud-cli-firestore-emulator
    • google-cloud-cli-gke-gcloud-auth-plugin
    • google-cloud-cli-kubectl-oidc
    • google-cloud-cli-local-extract
    • google-cloud-cli-minikube
    • google-cloud-cli-nomos
    • google-cloud-cli-pubsub-emulator
    • google-cloud-cli-skaffold
    • google-cloud-cli-spanner-emulator
    • google-cloud-cli-terraform-validator
    • google-cloud-cli-tests
    • kubectl

    舉例來說，如要安裝 google-cloud-cli-app-engine-java 元件，請執行下列指令：

    sudo dnf install google-cloud-cli-app-engine-java

降級 gcloud CLI 版本

如要還原至特定版本的 gcloud CLI，請執行下列指令。將 123.0.0 替換為要安裝的版本：

sudo dnf downgrade google-cloud-cli-123.0.0

在過去 365 天內發布的套件版本會保留在存放區中。

macOS
  1. 確認您使用的是支援的 Python 版本。Google Cloud CLI 需使用 Python 3.10 至 3.15 版。

    如要檢查 Python 版本，請執行 python3 -V 或 python -V。

    gcloud 安裝程式預設會安裝 Python 3.14 版和必要的擴充功能模組。

    如要進一步瞭解如何設定 Python 解譯器，請參閱 gcloud topic startup 說明文件。

  2. 下載下列其中一個檔案：
    平台 套件 大小 SHA256 總和檢查碼
    macOS 64 位元

    (x86_64)

    		 google-cloud-cli-darwin-x86_64.tar.gz 54.1 MB 9cc45ce0538ec18971001f57bba3471cad97436db3c58452579d8bd1215ce64b
    macOS 64 位元

    (ARM64, Apple silicon)

    		 google-cloud-cli-darwin-arm.tar.gz 54.0 MB e05807bee530449ed42f896e724f4c1c4d656dd9f41e1bcdada60bfd80e583f2
    macOS 32 位元

    (x86)

    		 google-cloud-cli-darwin-x86.tar.gz 52.4 MB f18a2900f901a7514345737603f9c88d049c775b6296c65475dcefe86548feb9

    或者，您也可以從指令列下載封存檔。 將 FILE_NAME 替換為上表中您平台的套件名稱。

    curl -O https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/FILE_NAME
  3. 將檔案內容解壓縮至檔案系統中偏好的位置。常見做法是將檔案解壓縮至主目錄。

    在 macOS 上，只要在偏好的位置開啟下載的 .tar.gz 檔案，或者，您也可以從指令列執行： 

    tar -xf FILE_NAME

    如要取代現有安裝項目，請刪除現有的 google-cloud-sdk 目錄，然後將封存檔解壓縮到相同位置。

  4. 從解壓縮的資料夾根目錄執行安裝指令碼： 
    ./google-cloud-sdk/install.sh
     指令碼會提示您執行下列設定動作。如要接受，請在系統提示時回答 Y。
    • 視需要安裝 Python 3.14 和建議的模組。
    • 將 gcloud CLI 新增至 PATH，並啟用指令完成功能。
    • 選擇傳送匿名使用統計資料，協助改善 gcloud CLI。
    您也可以提供旗標，以非互動方式執行安裝作業。 如要查看可用的旗標，請執行下列指令： 
    ./google-cloud-sdk/install.sh --help
     如要啟用螢幕閱讀器模式並執行安裝指令碼，請按照下列步驟操作： 
    ./google-cloud-sdk/install.sh --screen-reader=true
  5. 選用：如果您在上一步更新了 PATH，請開啟新的終端機，讓變更生效。
Windows

在 Windows 上使用 Google Cloud CLI 時，必須安裝 Windows 8.1 以上版本或 Windows Server 2012 以上版本。

  1. 下載 Google Cloud CLI 安裝程式。

    或者，開啟 PowerShell 終端機並執行下列 PowerShell 指令： 

    (New-Object Net.WebClient).DownloadFile("https://dl.google.com/dl/cloudsdk/channels/rapid/GoogleCloudSDKInstaller.exe", "$env:Temp\GoogleCloudSDKInstaller.exe")

& $env:Temp\GoogleCloudSDKInstaller.exe

  2. 啟動安裝程式並按照提示操作。這個安裝程式是由 Google LLC 簽署。

    • 如果使用螢幕閱讀器，請勾選「開啟螢幕閱讀器模式」核取方塊。這個選項會設定 gcloud 使用狀態追蹤器而非 Unicode 旋轉符號，以百分比顯示進度，並將表格扁平化。詳情請參閱無障礙功能指南。
    • Google Cloud CLI 需要 Python，支援的版本為 Python 3.10 至 3.15。根據預設，Windows 版 Google Cloud CLI 會隨附 Python 3。如要使用 Google Cloud CLI，作業系統必須能夠執行支援的 Python 版本。
    • 安裝程式會安裝所有必要依附元件，包括所需的 Python 版本。 Google Cloud CLI 預設會安裝及管理 Python 3，但如有需要，您可以取消勾選「Install Bundled Python」(安裝隨附的 Python) 選項，使用現有的 Python 安裝項目。請參閱gcloud topic startup，瞭解如何使用現有的 Python 安裝項目。

  3. 安裝完成後，安裝程式會提供建立「開始」選單和桌面捷徑的選項，並啟動 Google Cloud CLI 殼層。取消勾選啟動殼層的選項。您將在後續步驟中執行及設定 gcloud CLI。

疑難排解提示

  • 如果系統無法辨識 find 指令，導致安裝失敗，請確認環境變數 PATH 已設為包含 find 的資料夾。通常是 C:\WINDOWS\system32;。
  • 如果解除安裝 gcloud CLI，必須先重新啟動系統，才能再次安裝 gcloud CLI。
  • 如果解壓縮失敗，請以管理員身分執行安裝程式。
Chromebook
  1. 在 Chromebook 上設定 Linux 開發環境。
  2. 將 gcloud CLI 發布 URI 新增為套件來源。執行下列指令： 
    echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" | sudo tee -a /etc/apt/sources.list.d/google-cloud-sdk.list
  3. 匯入 Google Cloud 公開金鑰： 
    curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo gpg --dearmor -o /usr/share/keyrings/cloud.google.gpg
  4. 更新並安裝 gcloud CLI： 
    sudo apt-get update && sudo apt-get install google-cloud-cli
  5. 選用：安裝下列任一額外元件：
    • google-cloud-cli-anthos-auth
    • google-cloud-cli-app-engine-go
    • google-cloud-cli-app-engine-grpc
    • google-cloud-cli-app-engine-java
    • google-cloud-cli-app-engine-python
    • google-cloud-cli-app-engine-python-extras
    • google-cloud-cli-bigtable-emulator
    • google-cloud-cli-cbt
    • google-cloud-cli-cloud-build-local
    • google-cloud-cli-cloud-run-proxy
    • google-cloud-cli-config-connector
    • google-cloud-cli-datastore-emulator
    • google-cloud-cli-firestore-emulator
    • google-cloud-cli-gke-gcloud-auth-plugin
    • google-cloud-cli-kubectl-oidc
    • google-cloud-cli-local-extract
    • google-cloud-cli-minikube
    • google-cloud-cli-nomos
    • google-cloud-cli-pubsub-emulator
    • google-cloud-cli-skaffold
    • google-cloud-cli-spanner-emulator
    • google-cloud-cli-terraform-validator
    • google-cloud-cli-tests
    • kubectl

    舉例來說，如要安裝 google-cloud-cli-app-engine-java 元件，請執行下列指令：

    sudo apt-get install google-cloud-cli-app-engine-java

將 gcloud CLI 版本降級

如要還原至特定版本的 gcloud CLI，請執行下列指令。將 123.0.0 替換為要安裝的版本：

sudo apt-get update && sudo apt-get install google-cloud-cli=123.0.0-0

在過去 365 天內發布的套件版本會保留在存放區中。

初始化並授權 gcloud CLI

如果您使用 Proxy 或防火牆，請參閱「Proxy 設定」，為 gcloud CLI 啟用網路存取權。

安裝 gcloud CLI 後，請初始化 gcloud CLI，授權存取 Google Cloud 並設定預設設定。如要瞭解詳情，請參閱 gcloud init。

  1. 執行 gcloud init 來初始化 gcloud CLI：

    gcloud init

    根據預設，這個指令會開啟網路瀏覽器來授權存取權。如要改為透過指令列授權，請新增 --console-only 標記。如要進行非互動式授權，請在 Google Cloud 控制台中建立服務帳戶，並設定適當的範圍，然後使用 gcloud auth activate-service-account 搭配 JSON 金鑰檔案。

  2. 按照提示授權及設定：

    • 當系統提示登入時，請接受並在瀏覽器中登入 Google 帳戶。按一下「允許」，授予存取資源的權限。

    • 從您具備「擁有者」、「編輯者」或「檢視者」權限的專案清單中，選取一個專案。如果只有一個專案，系統會為你選取該專案。gcloud init

      如果您有超過 200 個專案，系統會提示您輸入專案 ID、建立專案或列出專案。如果選擇建立專案，也必須啟用計費功能。

    • 如果已啟用 Compute Engine API，請選取預設的 Compute Engine 可用區。

  3. 選用：如要提升螢幕閱讀器體驗，請使用下列指令啟用 accessibility/screen_reader 屬性：

    gcloud config set accessibility/screen_reader true

    詳情請參閱「啟用無障礙功能」指南。

執行核心指令

執行核心指令，查看 gcloud CLI 安裝相關資訊：

  1. 列出憑證儲存在本機系統的帳戶：

    gcloud auth list

    gcloud CLI 會顯示已儲存憑證的帳戶清單：

    Credentialed Accounts
ACTIVE             ACCOUNT
*                  example-user-1@example.com
                   example-user-2@example.com

  2. 列出 gcloud CLI 有效設定中的屬性：

    gcloud config list

    gcloud CLI 會顯示屬性清單：

    [core]
account = example-user-1@example.com
disable_usage_reporting = False
project = example-project

  3. 查看 gcloud 指令和其他主題的相關資訊：

    gcloud help

    舉例來說，如要查看 gcloud compute instances create 的說明：

    gcloud help compute instances create

    gcloud CLI 會顯示說明主題，其中包含指令說明、指令旗標和引數清單，以及指令使用範例。

選用：安裝其他元件

如要安裝其他元件，例如 App Engine 模擬器、kubectl，或 Alpha 版或 Beta 版的 gcloud CLI 指令，請參閱「管理 gcloud CLI 元件」。

後續步驟

  • 請參閱 gcloud CLI 指南，瞭解 gcloud CLI 總覽，包括重要概念、指令慣例和實用提示的快速簡介。
  • 請參閱 gcloud CLI 參考指南，瞭解各項 gcloud CLI 指令的詳細說明，包括說明、旗標和範例，可用於在 Google Cloud上執行各種工作。
  • 如要查看常用指令和重要概念的清單，請參閱 gcloud CLI 一覽表。