本页面介绍了 gsutil 的安装和设置,该工具可让您从命令行使用 HTTPS 访问 Cloud Storage。
安装 gsutil 后,您可以立即访问公开数据,并根据权限进行读取和写入。如需使用与您共享的受保护数据进行交互,您必须向 Cloud Storage 服务进行身份验证。通过启用结算功能,您可以创建和管理自己的存储桶。
系统要求
gsutil 工具在 Linux/Unix、Mac OS、Windows(XP 或更高版本)上运行。
gsutil 5.35 版及更高版本需要使用 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"
-
如需使此更改永久生效,请添加 shell 配置文件的路径(
~/.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 系统中,已编译的 crcmod 仅适用于 32 位 Python。如需详细了解 crcmod,请安装 gsutil 并使用
gsutil help crc32c命令查看帮助主题。
安装 gsutil
官方支持的 gsutil 安装和更新方法已包含在 Google Cloud CLI 中。
准备工作
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 以避免兼容性问题。
将 gsutil 作为 Google Cloud CLI 的一部分进行安装
按照您的操作系统对应的说明操作,将 gsutil 作为 Google Cloud CLI 的一部分进行安装:
- 确认您拥有受支持的 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.2 MB 00ad1adc3ee30ead317cce7176011ce4fa984339d5c41a08eff9504301f9ee85 Linux 64 位 (Arm)
google-cloud-cli-linux-arm.tar.gz 58.0 MB 19394fc05dbc4984533a2eea57ff007a8c8dad428d0d283fec1349ffda4941a5 Linux 32 位 (x86)
google-cloud-cli-linux-x86.tar.gz 58.0 MB 8d67ea49ddddfe86ac889acd32fe709ed1af82759cdceef61debcd99ee98c1c5 如需下载 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。 - 可选:使用组件管理器安装其他组件。
软件包内容
对于 Debian 和 Ubuntu 系统,可以通过软件包格式的 gcloud CLI 进行安装。此软件包仅包含 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.1 MB f495ade56c47e0a8026d47efe32fda493f94a59cf00ea83527a386acded8b789 macOS 64 位 (ARM64, Apple silicon)
google-cloud-cli-darwin-arm.tar.gz 58.0 MB 5204d57d199187b19b95b977fcf1b03e962cf5a531a9aba99c4f498b9342e791 macOS 32 位 (x86)
google-cloud-cli-darwin-x86.tar.gz 56.5 MB 01e3b9110fef34ea29bca9e11f24137df0ae9240ebc119ce089680147283bb0a 或者,您也可以从命令行下载归档文件。 将
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。默认情况下,Windows 版本的 Google Cloud CLI 捆绑了 Python 3。如需使用 Google Cloud CLI,您的操作系统必须能够运行受支持的 Python 版本。
- 安装程序会安装所有必需的依赖项(包括所需的 Python 版本)。
虽然 Google Cloud CLI 默认安装和管理 Python 3,但您可以根据需要通过取消选中“安装捆绑的 Python”选项来使用现有 Python 安装。
请参阅
gcloud topic startup,了解如何使用现有 Python 安装。
- 如果您使用的是屏幕阅读器,请选中启用屏幕阅读器模式复选框。此选项会将
- 安装完成后,安装程序会为您提供创建开始菜单和桌面快捷方式、启动 Google Cloud CLI shell 以及配置 gcloud CLI 的选项。将用于启动 shell 并配置安装的选项保持选中状态。安装程序会启动终端窗口并运行
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 服务设置凭据才能访问此数据。
将 gsutil 作为 Google Cloud CLI 的一部分时,系统将使用 OAuth2 来对 Cloud Storage 资源访问进行身份验证和授权。如需建立访问,请运行命令 gcloud init 并按照命令行中提供的说明操作,包括登录用户账号。请注意,如果您已完成安装步骤,则可能已经执行了此设置。如果您之前运行过 gcloud init,则再次运行该命令时,系统会询问您是要重新初始化配置还是要创建新配置。如需了解详情,请参阅初始化 Google Cloud CLI。
大功告成!您已准备好访问受保护的数据。如需查看 gsutil 命令列表,请在命令提示符处输入 gsutil。
问题排查
如果您尝试使用 gcloud init 命令对 gsutil 进行身份验证,但仍无法访问预期的存储桶或对象,则您的系统可能同时安装了独立的旧版 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
您可能还需要启用双向 TLS (mTLS)。在设备上启用 mTLS 后,您的设备会尝试连接到 JSON API 的 mTLS 请求端点。在允许连接之前,Cloud Storage 会验证您设备上的证书。
获取证书的最简单方法是使用 Google Cloud CLI。您可以手动在 .boto 文件的“Credentials”下设置以下值以设置一个证书:
-
use_client_certificate:用于控制是否使用 mTLS 的标志。 -
cert_provider_command:一个 shell 命令,用于将证书输出到 stdout,供 gsutil 读取。
亲自尝试
如果您是 Google Cloud 新手,请创建一个账号来评估 Cloud Storage 在实际场景中的表现。新客户还可获享 $300 赠金,用于运行、测试和部署工作负载。
免费试用 Cloud Storage