本頁面說明如何安裝及設定 gsutil,這項工具可讓您透過 HTTPS 從指令列存取 Cloud Storage。
安裝 gsutil 後,您就能立即存取公開資料,並視需要讀取及寫入資料。如要與他人與您共用的受保護資料互動,必須通過 Cloud Storage 服務驗證。啟用計費功能則讓您建立及管理自己的值區。
系統需求
gsutil 工具可以在 Linux/Unix、Mac OS 和 Windows (XP 或更新版本) 上執行。
如要使用 5.35 以上版本的 gsutil,必須安裝 Python 3.9 至 3.13,您可以透過 Python 版本管理工具取得,或安裝適當版本。
下列操作說明顯示如何管理 Python 版本:
必要條件:安裝 Python 版本管理工具 (pyenv),並安裝合適的 Python 版本。
-
設定全域 Python 版本:
-
如要將 Python 3.13 設為全域版本:
pyenv global 3.13
-
或者,為特定專案資料夾在本機設定 Python 版本:
pyenv local 3.13
-
如要將 Python 3.13 設為全域版本:
-
確認使用正確的 Python 版本:
python --version
畫面上會顯示下列訊息:
Python 3.13
方法 1:使用 Homebrew (brew)
必要條件:安裝 Homebrew,並透過 Homebrew 安裝合適的 Python 版本。
-
將特定 Python 版本設為預設版本:
-
將所需版本新增至
$PATH。舉例來說,如要使用 Python 3.13,請執行下列指令:export PATH="/usr/local/opt/python@3.13/bin:$PATH"
-
如要永久變更,請將路徑新增至殼層設定檔 (
~/.bash_profile、~/.zshrc或~/.bashrc)。
-
將所需版本新增至
-
確認使用正確的 Python 版本:
python --version
畫面上會顯示下列訊息:
Python 3.13
方法 2:使用 pyenv
必要條件:安裝 Python 版本管理工具 (pyenv),並透過 pyenv 安裝合適的 Python 版本。
-
設定全域 Python 版本:
-
如要全域設定 Python 版本 (適用於所有終端機):
pyenv global 3.13
-
或者,為特定專案資料夾在本機設定 Python 版本:
pyenv local 3.13
-
如要全域設定 Python 版本 (適用於所有終端機):
-
確認使用正確的 Python 版本:
python --version
畫面上會顯示下列訊息:
Python 3.13
必要條件:安裝 Python 版本管理工具 (pyenv-win),並透過 pyenv 安裝合適的 Python 版本。
-
設定全域 Python 版本:
-
如要將 Python 3.13 設為全域版本:
pyenv global 3.13
-
或者,為特定專案資料夾在本機設定 Python 版本:
pyenv local 3.13
-
如要將 Python 3.13 設為全域版本:
-
確認使用正確的 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:
- 確認您使用的是支援的 Python 版本。Google Cloud CLI 需要 Python 3.9 至 3.14。x86_64 Linux 套件包含預設會優先使用的 Python 解譯器。如要瞭解如何選擇及設定 Python 解譯器,請參閱
gcloud topic startup說明文件。 - 下載下列其中一個檔案:
平台 套件名稱 大小 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套件名稱。 - 如要將檔案內容解壓縮至檔案系統,請執行下列指令:
如要取代現有安裝項目,請刪除現有的tar -xf google-cloud-cli-linux-x86_64.tar.gz
google-cloud-sdk目錄,然後將封存解壓縮到相同位置。 - 從解壓縮的資料夾根目錄執行安裝指令碼:
指令碼會提示您執行下列設定動作。如要接受,請在系統提示時說出「接聽」./google-cloud-sdk/install.sh
Y。- 將 gcloud CLI 新增至
PATH。 - 啟用指令完成功能。
- 選擇傳送匿名使用統計資料,協助我們改善 gcloud CLI。
./google-cloud-sdk/install.sh --help - 將 gcloud CLI 新增至
- 選用:如果您在上一個步驟中更新了
PATH,請開啟新的終端機,讓變更生效。 -
執行
gcloud init來初始化、授權及設定 gcloud CLI。 - 選用:使用元件管理員安裝其他元件。
套件內容
套件格式的 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、ca-certificates、gnupg和curl。如要安裝這些套件,請執行下列指令:sudo apt-get install apt-transport-https ca-certificates gnupg curl
安裝
- 匯入 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 金鑰檔案。
- 新增 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
- 如為較新的發行版本 (Debian 9 以上或 Ubuntu 18.04 以上),請執行下列指令:
- 更新並安裝 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
- 選用:安裝下列任一
附加元件:
google-cloud-cli-anthos-authgoogle-cloud-cli-app-engine-gogoogle-cloud-cli-app-engine-grpcgoogle-cloud-cli-app-engine-javagoogle-cloud-cli-app-engine-pythongoogle-cloud-cli-app-engine-python-extrasgoogle-cloud-cli-bigtable-emulatorgoogle-cloud-cli-cbtgoogle-cloud-cli-cloud-build-localgoogle-cloud-cli-cloud-run-proxygoogle-cloud-cli-config-connectorgoogle-cloud-cli-datastore-emulatorgoogle-cloud-cli-firestore-emulatorgoogle-cloud-cli-gke-gcloud-auth-plugingoogle-cloud-cli-kptgoogle-cloud-cli-kubectl-oidcgoogle-cloud-cli-local-extractgoogle-cloud-cli-minikubegoogle-cloud-cli-nomosgoogle-cloud-cli-pubsub-emulatorgoogle-cloud-cli-skaffoldgoogle-cloud-cli-spanner-emulatorgoogle-cloud-cli-terraform-validatorgoogle-cloud-cli-testskubectl
例如,您可以按照以下方式安裝
google-cloud-cli-app-engine-java元件:sudo apt-get install google-cloud-cli-app-engine-java
-
執行
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
套件內容
您可以取得套件格式的 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 擴充功能 (這些項目能夠單獨安裝,詳情請見本節稍後內容)。
安裝
- 使用 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
-
-
安裝「
libxcrypt-compat.x86_64」。sudo dnf install libxcrypt-compat.x86_64
- 安裝 gcloud CLI:
sudo dnf install google-cloud-cli
- 選用:安裝下列任一附加元件:
google-cloud-cli-anthos-authgoogle-cloud-cli-app-engine-gogoogle-cloud-cli-app-engine-grpcgoogle-cloud-cli-app-engine-javagoogle-cloud-cli-app-engine-pythongoogle-cloud-cli-app-engine-python-extrasgoogle-cloud-cli-bigtable-emulatorgoogle-cloud-cli-cbtgoogle-cloud-cli-cloud-build-localgoogle-cloud-cli-cloud-run-proxygoogle-cloud-cli-config-connectorgoogle-cloud-cli-datastore-emulatorgoogle-cloud-cli-firestore-emulatorgoogle-cloud-cli-gke-gcloud-auth-plugingoogle-cloud-cli-kptgoogle-cloud-cli-kubectl-oidcgoogle-cloud-cli-local-extractgoogle-cloud-cli-minikubegoogle-cloud-cli-nomosgoogle-cloud-cli-pubsub-emulatorgoogle-cloud-cli-skaffoldgoogle-cloud-cli-spanner-emulatorgoogle-cloud-cli-terraform-validatorgoogle-cloud-cli-testskubectl
舉例來說,如要安裝
google-cloud-cli-app-engine-java元件,請執行下列指令:sudo dnf install google-cloud-cli-app-engine-java
-
執行
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 做為套件名稱。
- 確認您使用的是支援的 Python 版本。Google Cloud CLI 需要 Python 3.9 至 3.14。
如要檢查 Python 版本,請執行
python3 -V或python -V。如有需要,安裝指令碼可以為您安裝 Python。這需要 Xcode 指令列工具。如要安裝這些應用程式,請執行
sudo xcode-select --install。或者,您也可以從 python.org 安裝支援的 Python 版本。如要進一步瞭解如何設定 Python 解譯器 (特別是安裝多個版本時),請參閱
gcloud topic startup說明文件。 -
下載下列其中一個項目:
平台 套件 大小 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
- 將檔案內容解壓縮到檔案系統中的偏好位置,常見做法是將檔案解壓縮至主目錄。
在 macOS 上,您可以在偏好位置開啟下載的
.tar.gz檔案,或者,您也可以從指令列執行:tar -xf FILE_NAME
如要取代現有安裝項目,請刪除現有的
google-cloud-sdk目錄,然後將封存檔解壓縮到相同位置。 - 從解壓縮的資料夾根目錄執行安裝指令碼:
指令碼會提示您執行下列設定動作。如要接受,請在系統提示時說出「接聽」./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
- 選用:如果您在上一個步驟中更新了
PATH,請開啟新的終端機,讓變更生效。 -
執行
gcloud init來初始化、授權及設定 gcloud CLI。 - 選用:使用元件管理員安裝其他元件。
在 Windows 上使用 Google Cloud CLI 時,必須安裝 Windows 8.1 以上版本,或 Windows Server 2012 以上版本。
-
或者,開啟 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
-
啟動安裝程式並按照提示操作。這個安裝程式是由 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 安裝項目。
- 如果使用螢幕閱讀器,請勾選「開啟螢幕閱讀器模式」核取方塊。這個選項會設定
- 安裝完成後,安裝程式會提供選項,讓您建立「開始」功能表和桌面捷徑、啟動 Google Cloud CLI 殼層,以及設定 gcloud CLI。保留啟動殼層和設定安裝作業的選項。安裝程式會開啟終端機視窗並執行
gcloud init指令,初始化、授權及設定 gcloud CLI。 - 預設安裝不包括使用
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 -a 或 gsutil 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」底下設定下列值:
-
use_client_certificate:控制是否使用 mTLS 的旗標。 -
cert_provider_command:將憑證列印至 stdout 以供 gsutil 讀取的殼層指令。
歡迎試用
如果您未曾使用過 Google Cloud,歡迎建立帳戶,親自體驗實際使用 Cloud Storage 平台的成效。新客戶還能獲得價值 $300 美元的免費抵免額,用於執行、測試及部署工作負載。
免費試用 Cloud Storage