安裝 Google Cloud CLI

本快速入門導覽課程會逐步引導您安裝及初始化 Google Cloud CLI，並執行幾個核心 gcloud CLI 指令。

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

逐步引導

事前準備

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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

    Go to project selector

  3. Make sure 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.

    Go to project selector

  5. Make sure that billing is enabled for your Google Cloud project.

    6. 完成本文所述工作後，您可以刪除已建立的資源，避免繼續計費。詳情請參閱清除所用資源一節。

安裝最新版 gcloud CLI (530.0.0)

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

    (x86_64)

    		 google-cloud-cli-linux-x86_64.tar.gz 149.7 MB 1ec7d351de14277c00c430f9fb939255c4b63940417da2f24ff6413a9e221c2f
    Linux 64 位元

    (Arm)

    		 google-cloud-cli-linux-arm.tar.gz 56.3 MB e6153461e3154ebce61d35b73005bdd14a0ecacd42e5008f66e25b4ad231e5c9
    Linux 32 位元

    (x86)

    		 google-cloud-cli-linux-x86.tar.gz 56.3 MB 09690f1b126ccc8e777c4a1ef2c0b74a08103d89329b03856d688071baa9fc07

    如要下載 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. (選用) 將 gcloud CLI 新增至 PATH。 您也可以選擇為殼層啟用指令補齊功能，並收集使用統計資料。使用下列指令執行安裝指令碼 (來自您在上一步驟中解壓縮的資料夾根目錄)： 
    ./google-cloud-sdk/install.sh
     您也可以非互動式地執行這項操作 (例如使用指令碼)，並以旗標形式提供偏好設定。如要查看可用旗標，請執行： 
    ./google-cloud-sdk/install.sh --help
    • 如要傳送匿名使用統計資料，協助我們改善 gcloud CLI，請在系統提示時回答 Y。
    • 如要將 gcloud CLI 新增至 PATH 並啟用指令完成功能，請在系統提示時回答 Y。
  5. 如果您在上一個步驟中更新了 PATH，請開啟新的終端機，讓變更生效。
  6. 如要初始化 gcloud CLI，請執行 gcloud init： 
    7. ./google-cloud-sdk/bin/gcloud init
  7. 選用：使用元件管理員安裝其他元件。
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
  • 已安裝 apt-transport-https 和 curl： 
    sudo apt-get install apt-transport-https 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
    • 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-kpt
    • 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
  5. 執行 gcloud init 即可開始使用： 
    gcloud init

降級 gcloud CLI 版本

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

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

存放區一律會提供最近十個版本。

注意：如果是 371.0.0 之前的版本，套件名稱為 google-cloud-sdk

Red Hat/Fedora/CentOS

套件內容

您可以取得套件格式的 gcloud CLI，以在 Red Hat Enterprise Linux 7、8 和 9；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 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
  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
    • 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-kpt
    • 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
  5. 執行 gcloud init 即可開始使用： 
    gcloud init

降級 gcloud CLI 版本

如要還原至特定版本的 gcloud CLI (其中 VERSION 的格式為 123.0.0)，請執行： sudo dnf downgrade google-cloud-cli-VERSION 存放區一律會提供最近十個版本。注意：如果是 371.0.0 之前的版本，套件名稱為 google-cloud-sdk

macOS
  1. 確認您使用的是支援的 Python 版本：
    • 如要查看目前的 Python 版本，請執行 python3 -V 或 python -V。支援的版本為 Python 3.9 至 3.13。
    • 主要安裝指令碼會提供安裝 CPython 的 Python 3.12 版。
      • 安裝 Python 時需要 Xcode 指令列工具。
      • 執行 xcode-select -p，確認 Xcode 指令列工具是否已安裝。
      • 如果未安裝 Xcode Command Line Tools，請執行 sudo xcode-select --install 安裝。
    • 如要安裝支援的 Python 版本，請前往 Python.org 的「Python Releases for macOS」。
    • 如果電腦上安裝了多個 Python 解譯器，請在殼層中設定 CLOUDSDK_PYTHON 環境變數，指向偏好解譯器的路徑。
    • 如要進一步瞭解如何選擇及設定 Python 解譯器，請參閱 gcloud topic startup。
  2. 下載下列其中一個檔案：

    3. 平台 套件 大小 SHA256 總和檢查碼
    macOS 64 位元

    (x86_64)

    		 google-cloud-cli-darwin-x86_64.tar.gz 56.4 MB 0c0101a65f3473a5db6a2ebc1867c3294cdbd88fef34da91050869f76149a822
    macOS 64 位元

    (ARM64, Apple silicon)

    		 google-cloud-cli-darwin-arm.tar.gz 56.4 MB 80cfba6da278d0ce8a8a0625bec9648ea5a39ea42daf2536068f19edb175dc70
    macOS 32 位元

    (x86)

    		 google-cloud-cli-darwin-x86.tar.gz 54.9 MB 53c23a16a66a2d38966fc7080cd2e29afe1d5c85b1c52985c19f7fd2c09f995a
  3. 將封存檔解壓縮到您檔案系統上的任何位置 (最好是主目錄)。在 macOS 上，可以在偏好位置開啟下載的 .tar.gz 封存檔來完成此作業。或執行下列指令： 
    tar -xf google-cloud-cli-darwin-arm.tar.gz

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

  4. 使用下列指令執行安裝指令碼 (來自您在上一步驟中解壓縮的資料夾根目錄)：
    ./google-cloud-sdk/install.sh

    指令碼會提示安裝 Python 3.12 和某些建議模組。

    您也可以提供偏好設定做為標記，以非互動方式 (例如使用指令碼) 進行安裝。如要說明可用的旗標，請執行： 
    ./google-cloud-sdk/install.sh --help
     如要在開啟螢幕閱讀器模式的情況下執行安裝指令碼，請按照下列步驟操作： 
    ./google-cloud-sdk/install.sh --screen-reader=true
     選用：
    • 如要傳送匿名使用統計資料，協助我們改善 gcloud CLI，請在系統提示時回答 Y。
    • 如要將 gcloud CLI 新增至 PATH 並啟用指令完成功能，請在系統提示時回答 Y。
  5. 如果您在上一個步驟中更新了 PATH，請開啟新的終端機，讓變更生效。
  6. 如要初始化 gcloud CLI，請執行 gcloud init： 
    7. ./google-cloud-sdk/bin/gcloud init
  7. (選用步驟) 使用元件管理員安裝其他元件。
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 旋轉符號，並以百分比顯示進度，以及將表格扁平化。詳情請參閱無障礙功能指南。

  3. Google Cloud CLI 需要 Python，支援的版本為 Python 3.9 至 3.13。Google Cloud CLI 的 Windows 版本預設會隨附 Python 3。如要使用 Google Cloud CLI，作業系統必須能夠執行支援的 Python 版本。

    安裝程式會安裝所有必要的依附元件，包含所需的 Python 版本。Google Cloud CLI 預設會安裝及管理 Python 3，但如有需要，您可以取消勾選「安裝隨附 Python」選項，使用現有的 Python 安裝版本。請參閱 gcloud topic startup，瞭解如何使用現有的 Python 安裝版本。

  4. 安裝完成後，安裝程式會提供選項，讓您建立「開始」功能表和桌面捷徑、啟動 Google Cloud CLI 殼層，以及設定 gcloud CLI。請務必保留啟動殼層和設定安裝作業的選項。安裝程式會開啟終端機視窗並執行 gcloud init 指令。

  5. 預設的安裝不包括使用 gcloud 指令部署應用程式所需的 App Engine 擴充功能。您可利用 gcloud CLI 元件管理員來安裝這些元件。
疑難排解訣竅：
  • 如果系統無法識別 find 指令而導致安裝失敗，請確保 PATH 環境變數設定為納入含有 find 的資料夾。通常是 C:\WINDOWS\system32;。
  • 如果您解除安裝 gcloud CLI，必須先重新啟動系統，才能再次安裝 gcloud CLI。
  • 如果解壓縮失敗，請以管理員身分執行安裝程式。
Chromebook
  1. 在 Chromebook 上啟用 Linux 功能。 在 Chromebook 上安裝 Google Cloud CLI 時，需要使用這項功能。
  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 apt-key --keyring /usr/share/keyrings/cloud.google.gpg add -
  4. 更新並安裝 gcloud CLI： 
    sudo apt-get update && sudo apt-get install google-cloud-cli
  5. (選用) 安裝下列任一 附加元件：
    • google-cloud-cli
    • 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-kpt
    • 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
  6. 執行 gcloud init 即可開始使用： 
    gcloud init

降級 gcloud CLI 版本

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

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

存放區一律會提供最近十個版本。

注意：如果是 371.0.0 之前的版本，套件名稱為 google-cloud-sdk

選用：安裝最新版 Cloud 用戶端程式庫

您可下載 Cloud 用戶端資料庫支援的語言版本

初始化 gcloud CLI

使用 gcloud init 指令執行幾項常見的 gcloud CLI 設定工作。包括授權 gcloud CLI 使用您的使用者帳戶憑證存取 Google Cloud ，以及設定預設設定。

  1. 初始化 gcloud CLI：

    gcloud init

  2. 使用 Google 使用者帳戶並接受登入選項：

    To continue, you must log in. Would you like to log in (Y/n)? Y

  3. 在瀏覽器中，於系統提示時登入 Google 使用者帳戶，然後按一下「允許」，授予存取 Google Cloud 資源的權限。

  4. 在命令提示字元中，從具有擁有者、編輯者或檢視者權限的專案清單中，選取一項專案： Google Cloud 

    Pick cloud project to use:
 [1] [my-project-1]
 [2] [my-project-2]
 ...
 Please enter your numeric choice:

    如果您只有一項專案，則 gcloud init 會自動為您選取。

    如果您有超過 200 個專案的存取權，系統會提示您輸入專案 ID、建立新專案或列出專案。

    This account has a lot of projects! Listing them all can take a while.
 [1] Enter a project ID
 [2] Create a new project
 [3] List projects
Please enter your numeric choice:

  5. 如果您已啟用 Compute Engine API，gcloud init 可讓您選擇預設的 Compute Engine 區域：

    Which compute zone would you like to use as project default?
 [1] [asia-east1-a]
 [2] [asia-east1-b]
 ...
 [14] Do not use default zone
 Please enter your numeric choice:

    gcloud init 會確認您已成功完成設定步驟：

    Run `gcloud help config` to learn how to change individual settings

This gcloud configuration is called [default]. You can create additional configurations if you work with multiple accounts and/or projects.
Run `gcloud topic configurations` to learn more.

Some things to try next:

* Run `gcloud --help` to see the Cloud Platform services you can interact with. And run `gcloud help COMMAND` to get help on any gcloud command.
* Run `gcloud topic --help` to learn about advanced features of the SDK like arg files and output formatting
* Run `gcloud cheat-sheet` to see a roster of go-to `gcloud` commands.

  6. (選用) 如要提升螢幕閱讀器體驗，請啟用 accessibility/screen_reader 屬性：

    gcloud config set accessibility/screen_reader true

    如要進一步瞭解 gcloud CLI 隨附的無障礙功能，請參閱啟用無障礙功能指南。

執行核心指令

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

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

    gcloud auth list

    gcloud CLI 會顯示已通過驗證的帳戶清單：

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

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

    gcloud config list

    gcloud CLI 會顯示屬性清單：

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

  3. 查看 gcloud CLI 安裝作業和有效設定的相關資訊：

    gcloud info

    gcloud CLI 會顯示安裝相關摘要資訊，這包含您系統中的相關資訊、已安裝的元件、使用中的使用者帳戶與目前專案，以及使用中設定的屬性。

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

    gcloud help

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

    gcloud help compute instances create

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

清除所用資源

如要避免系統向您的 Google Cloud 帳戶收取本頁所用資源的費用，請按照下列步驟操作。

  1. In the Google Cloud console, go to the Manage resources page.

    Go to Manage resources

  2. In the project list, select the project that you want to delete, and then click Delete.
  3. In the dialog, type the project ID, and then click Shut down to delete the project.

後續步驟

  • 如要瞭解 gcloud CLI 的總覽資訊，請參閱 gcloud CLI 指南，包括重要概念、指令慣例和實用提示的快速簡介。
  • 請參閱 gcloud CLI 參考指南，瞭解各項 gcloud CLI 指令的詳細介紹頁面，包含說明、標記和範例等等。您可以使用這些指令在 Google Cloud上執行各種工作。
  • 如要查看常用指令和重要概念的清單，請參閱 gcloud CLI 一覽表。
  • 使用 gcloud CLI 元件管理員安裝如 App Engine 模擬器或 kubectl 等的附加元件。