安裝 gsutil

本頁面說明如何安裝及設定 gsutil,這項工具可讓您透過 HTTPS 從指令列存取 Cloud Storage。

安裝 gsutil 後,您就能立即存取公開資料,並視需要讀取及寫入資料。如要與他人與您共用的受保護資料互動,必須通過 Cloud Storage 服務驗證。啟用計費功能則讓您建立及管理自己的值區。

系統需求

  • gsutil 工具可以在 Linux/Unix、Mac OS 和 Windows (XP 或更新版本) 上執行。

  • 如要使用 5.35 以上版本的 gsutil,必須安裝 Python 3.9 至 3.13,您可以透過 Python 版本管理工具取得,或安裝適當版本。

下列操作說明顯示如何管理 Python 版本:

Linux

必要條件:安裝 Python 版本管理工具 (pyenv),並安裝合適的 Python 版本。

  1. 設定全域 Python 版本:
    • 如要將 Python 3.13 設為全域版本:
      pyenv global 3.13
    • 或者,為特定專案資料夾在本機設定 Python 版本:
      pyenv local 3.13
  2. 確認使用正確的 Python 版本:
    python --version

    畫面上會顯示下列訊息:

    Python 3.13
macOS

方法 1:使用 Homebrew (brew)

必要條件:安裝 Homebrew,並透過 Homebrew 安裝合適的 Python 版本。

  1. 將特定 Python 版本設為預設版本:
    • 將所需版本新增至 $PATH。舉例來說,如要使用 Python 3.13,請執行下列指令:
      export PATH="/usr/local/opt/python@3.13/bin:$PATH"
    • 如要永久變更,請將路徑新增至殼層設定檔 (~/.bash_profile~/.zshrc~/.bashrc)。
  2. 確認使用正確的 Python 版本:
    python --version

    畫面上會顯示下列訊息:

    Python 3.13

方法 2:使用 pyenv

必要條件:安裝 Python 版本管理工具 (pyenv),並透過 pyenv 安裝合適的 Python 版本。

  1. 設定全域 Python 版本:
    • 如要全域設定 Python 版本 (適用於所有終端機):
      pyenv global 3.13
    • 或者,為特定專案資料夾在本機設定 Python 版本:
      pyenv local 3.13
  2. 確認使用正確的 Python 版本:
    python --version

    畫面上會顯示下列訊息:

    Python 3.13
Windows

必要條件:安裝 Python 版本管理工具 (pyenv-win),並透過 pyenv 安裝合適的 Python 版本。

  1. 設定全域 Python 版本:
    • 如要將 Python 3.13 設為全域版本:
      pyenv global 3.13
    • 或者,為特定專案資料夾在本機設定 Python 版本:
      pyenv local 3.13
  2. 確認使用正確的 Python 版本:
    python --version

    畫面上會顯示下列訊息:

    Python 3.13
  • 如要使用複合物件,則必須安裝經過編譯的 crcmod。在 Windows 上,這種做法僅適用於 32 位元 Python。如要進一步瞭解 crcmod,請安裝 gsutil,然後使用 gsutil help crc32c 指令查看說明主題。

安裝 gsutil

Google Cloud CLI 包含官方支援的 gsutil 安裝及更新方法。

事前準備

Google Cloud CLI 和 gsutil 具有 Python 版本依附元件,可能會導致相容性問題。Google Cloud CLI 需要 Python 3.9 至 3.14,而 gsutil 需要 Python 3.9 至 3.13。

如要安裝 gsutil,建議安裝內含 gsutil 的 Google Cloud CLI。如果選擇直接安裝 gsutil,請使用 Python 3.9 至 3.13,以免發生相容性問題。

安裝 Google Cloud CLI 內含的 gsutil:

按照適用於您作業系統的操作說明,安裝 Google Cloud CLI 內含的 gsutil:

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

    (x86_64)

    google-cloud-cli-linux-x86_64.tar.gz 203.0 MB 81320cc3042faadbff2875c8b55c6bdcf6ccd439599c6645c27a5a6f213b4736
    Linux 64 位元

    (Arm)

    google-cloud-cli-linux-arm.tar.gz 57.9 MB 2fced601e0a494e6dcf6dbfb39130aefacabe541d5bcf0a5d53a8c44e71515e9
    Linux 32 位元

    (x86)

    google-cloud-cli-linux-x86.tar.gz 57.9 MB 8fb22634022aa74d23e877279e034e56d4fed4b5883cbfc51b9dd7134a1b96f0

    如要下載 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,請開啟新的終端機,讓變更生效。
  6. 執行 gcloud init 來初始化、授權及設定 gcloud CLI。
  7. 選用:使用元件管理員安裝其他元件。
Debian/Ubuntu

套件內容

套件格式的 gcloud CLI 可安裝於 Debian 和 Ubuntu 系統。這個套件只包含 gcloudgcloud alphagcloud betagsutilbq 指令列工具,不包含 kubectl 或使用 gcloud 指令部署應用程式所需的 App Engine 擴充功能。如需這些元件,您必須另行安裝

事前準備

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

  • Ubuntu 版本尚未終止服務,或 Debian 穩定版本尚未終止服務
  • 該服務最近更新了套件。如要立即執行這項操作,請執行下列指令:
    sudo apt-get update
  • 已安裝 apt-transport-httpsca-certificatesgnupgcurl。如要安裝這些套件,請執行下列指令:
    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-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 CLI。

降級 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 和 10;Fedora 41 和 42;以及 CentOS 7 和 8 系統上安裝。這個套件只包含 gcloudgcloud alphagcloud betagsutilbq 指令,不包含 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
  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-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 CLI。

降級 gcloud CLI 版本

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

sudo dnf downgrade google-cloud-cli-123.0.0

存放區中提供最近十個版本。如果是 371.0.0 之前的版本,請使用 google-cloud-sdk 做為套件名稱。

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

    如要檢查 Python 版本,請執行 python3 -Vpython -V

    如有需要,安裝指令碼可以為您安裝 Python。這需要 Xcode 指令列工具。如要安裝這些應用程式,請執行 sudo xcode-select --install。或者,您也可以從 python.org 安裝支援的 Python 版本。

    如要進一步瞭解如何設定 Python 解譯器 (特別是安裝多個版本時),請參閱 gcloud topic startup 說明文件

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

    (x86_64)

    google-cloud-cli-darwin-x86_64.tar.gz 58.0 MB 9f4b289e4545d146410e87363489d11ce30c1326eae0930cd77c81a499336682
    macOS 64 位元

    (ARM64, Apple silicon)

    google-cloud-cli-darwin-arm.tar.gz 57.9 MB 20aa219e61d7ac2b4bf78f9080c0fcf2c0b79d48ce47b9833d4087a468d749d9
    macOS 32 位元

    (x86)

    google-cloud-cli-darwin-x86.tar.gz 56.4 MB 979b7f6e4014d41222b8354495d4e89285021c1b69bf07f751aecdf929024422

    或者,您也可以從指令列下載封存檔。 請將 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.13 和建議的模組。
    • 將 gcloud CLI 新增至 PATH,並啟用指令完成功能。
    • 選擇傳送匿名使用統計資料,協助我們改善 gcloud CLI。
    您也可以提供旗標,以非互動方式執行安裝作業。 如要查看可用旗標,請執行:
    ./google-cloud-sdk/install.sh --help
    如要啟用螢幕閱讀器模式並執行安裝指令碼,請按照下列步驟操作:
    ./google-cloud-sdk/install.sh --screen-reader=true
  5. 選用:如果您在上一個步驟中更新了 PATH,請開啟新的終端機,讓變更生效。
  6. 執行 gcloud init 來初始化、授權及設定 gcloud CLI。
  7. 選用:使用元件管理員安裝其他元件。
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.9 至 3.14。Google Cloud CLI 的 Windows 版本預設會隨附 Python 3。如要使用 Google Cloud CLI,作業系統必須能夠執行支援的 Python 版本。
    • 安裝程式會安裝所有必要的依附元件,包括所需的 Python 版本。Google Cloud CLI 預設會安裝及管理 Python 3,但如有需要,您可以取消勾選「安裝隨附 Python」選項,使用現有的 Python 安裝版本。請參閱gcloud topic startup,瞭解如何使用現有的 Python 安裝項目。
  3. 安裝完成後,安裝程式會提供選項,讓您建立「開始」功能表和桌面捷徑、啟動 Google Cloud CLI 殼層,以及設定 gcloud CLI。保留啟動殼層和設定安裝作業的選項。安裝程式會開啟終端機視窗並執行 gcloud init 指令,初始化、授權及設定 gcloud CLI。
  4. 預設安裝不包括使用 gcloud 指令部署應用程式所需的 App Engine 擴充功能。您可利用 gcloud CLI 元件管理員來安裝這些元件。

疑難排解提示

  • 如果系統無法識別 find 指令而導致安裝失敗,請確保 PATH 環境變數設定為納入含有 find 的資料夾。通常是 C:\WINDOWS\system32;
  • 如果您解除安裝 gcloud CLI,必須先重新啟動系統,才能再次安裝 gcloud CLI。
  • 如果解壓縮失敗,請以管理員身分執行安裝程式。

安裝 gsutil 時,您必須設定 CLOUDSDK_PYTHON 環境變數,才能使用正確的 Python 版本。詳情請參閱gcloud startup topic

使用 components update 指令執行更新:gcloud components update

設定憑證以存取受保護的資料

如要存取受保護的資料或寫入受保護的值區,您需要設定憑證 (驗證)。舉例來說,如果某位使用者建立了 Cloud Storage 帳戶,並且上傳只提供您或其他特定使用者存取的資料,那麼您必須向 Cloud Storage 服務設定憑證,才能存取這類資料。

使用 Google Cloud CLI 中的 gsutil 時,您會透過 OAuth2 對 Cloud Storage 資源存取進行驗證和授權。如要建立存取權,請執行 gcloud init 指令,並按照指令列中提供的操作說明登入使用者帳戶。請注意,如果您已按照安裝步驟操作,可能已經完成這項設定。如果您先前執行過 gcloud init,再次執行該指令時,系統會詢問您要重新初始化設定,或是要建立新的設定。詳情請參閱「初始化 Google Cloud CLI」。

大功告成,您現在可以開始存取受保護的資料。如要查看 gsutil 指令的清單,請在命令提示字元視窗中輸入 gsutil

疑難排解

如果您嘗試使用 gcloud init 指令驗證 gsutil,但仍無法存取預期中的 bucket 或物件,您的系統可能同時安裝了舊版獨立的 gsutil,以及與 Google Cloud CLI 綁定的 gsutil。執行 gsutil version -l 指令,並檢查 using cloud sdk 的值。如果顯示 False,表示系統在執行指令時,使用的是獨立版本的 gsutil。建議您從系統中移除獨立版本的 gsutil,但也可以使用 gsutil config -agsutil config -e 進行驗證。

透過 HMAC 進行驗證

雖然我們建議您使用 OAuth 2.0 來驗證 gsutil,但是您也可以使用 HMAC 金鑰輸入憑證。如要透過 HMAC 進行驗證,請使用下列指令:

gsutil config -a

使用這個指令進行驗證程序時,系統會提示您輸入與 HMAC 金鑰相關聯的「存取 ID」和「密鑰」

使用 HMAC 金鑰進行驗證時,請使用下列指令,從 Google Cloud CLI 停用憑證傳遞功能:gcloud config set pass_credentials_to_gsutil false

啟用 mTLS

您也可以啟用雙向傳輸層安全標準 (mTLS)。在裝置上啟用 mTLS 後,裝置會嘗試連線至 JSON API 的 mTLS 要求端點。Cloud Storage 會先驗證裝置上的憑證,再允許連線。

取得憑證最簡單的方式是透過 Google Cloud CLI。 您可以在 .boto 檔案中手動設定,方法是在「Credentials」底下設定下列值:

  1. use_client_certificate:控制是否使用 mTLS 的旗標。
  2. cert_provider_command:將憑證列印至 stdout 以供 gsutil 讀取的殼層指令。

歡迎試用

如果您未曾使用過 Google Cloud,歡迎建立帳戶,親自體驗實際使用 Cloud Storage 平台的成效。新客戶還能獲得價值 $300 美元的免費抵免額,用於執行、測試及部署工作負載。

免費試用 Cloud Storage