【实战】macOS装Google Cloud CLI遇到SSL证书问题？一文解决！

本文记录了在 macOS 系统上安装 Google Cloud CLI 时遇到的 SSL 证书验证失败问题，以及最终的完美解决方案。如果你也遇到了类似问题，这篇文章将为你节省大量时间。

🖥️ 环境说明

  • 操作系统：macOS
  • Python环境：通过 Homebrew 安装
  • 目标：安装 Google Cloud CLI 并获取访问令牌

📖 官方安装步骤

根据 Google Cloud CLI 官方文档，标准安装流程如下：

  1. 检查Python版本
  2. 下载安装包
    1
    2
    # 下载对应架构的安装包
    wget https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-darwin-x86_64.tar.gz
  3. 解压文件
    1
    tar -xf google-cloud-cli-darwin-x86_64.tar.gz
  4. 执行安装脚本
    1
    ./google-cloud-sdk/install.sh
  5. 初始化CLI
    1
    ./google-cloud-sdk/bin/gcloud init

看起来很简单对吧？然而现实往往比理想骨感…

🚫 踩坑记录：SSL证书验证失败

按照官方步骤，前面几步都很顺利，但在执行 ./google-cloud-sdk/install.sh 时遇到了问题：

错误信息

1
2
3
4
5
WARNING: Retrying (Retry(total=0, connect=None, read=None, redirect=None, status=None)) after connection broken by 'SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1000)'))': /googleapis/enterprise-certificate-proxy/releases/download/v0.3.2/cryptography-42.0.7-cp39-abi3-macosx_10_12_universal2.whl

ERROR: Could not install packages due to an OSError: HTTPSConnectionPool(host='github.com', port=443): Max retries exceeded with url: /googleapis/enterprise-certificate-proxy/releases/download/v0.3.2/cryptography-42.0.7-cp39-abi3-macosx_10_12_universal2.whl (Caused by SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1000)'))

ERROR: Virtual env setup failed.

问题分析

这个错误的根本原因是：Python虚拟环境中的SSL证书验证失败。安装脚本在创建虚拟环境时无法从GitHub下载必要的依赖包。

❌ 错误的解决尝试

尝试1：手动更新证书包

根据网上的建议，我尝试通过以下命令强制更新证书包：

1
python3 -m pip install --upgrade certifi --trusted-host pypi.org --trusted-host files.pythonhosted.org --break-system-packages

执行结果：

1
Requirement already satisfied: certifi in /opt/homebrew/lib/python3.13/site-packages (2025.6.15)

看起来成功了，证书包已经是最新版本。

为什么这个方法无效？

重新执行安装脚本后，问题依然存在。原因是：

Google Cloud CLI 安装时会创建一个全新的、隔离的Python虚拟环境，这个虚拟环境不会继承系统级Python的证书配置。

即使我们修复了系统Python的证书问题，安装脚本创建的虚拟环境仍然会遇到同样的SSL验证问题。

✅ 完美解决方案：使用Homebrew

既然Python是通过Homebrew安装的，那么使用Homebrew来安装Google Cloud CLI就是最佳选择！

安装步骤

  1. 清理旧的安装文件（如果有的话）

    1
    rm -rf google-cloud-sdk/

  2. 使用Homebrew安装

    1
    brew install --cask google-cloud-sdk

  3. 初始化CLI

    1
    gcloud init

为什么Homebrew方案更好？

对比项 官方脚本安装 Homebrew安装
依赖管理 需要手动处理Python环境问题 自动处理所有依赖
证书问题 容易遇到SSL验证失败 无证书问题
系统集成 需要手动配置PATH 自动配置环境变量
维护更新 需要手动重新下载安装 brew upgrade 一键更新
成功率 在某些环境下可能失败 几乎100%成功

🔑 获取Google Cloud Token

安装成功后，我们需要获取访问令牌来调用Google Cloud API。这里提供两种方式：

方式一：个人账号认证（适合开发测试）

1. 登录并授权

1
gcloud init
  • 命令会自动打开浏览器进行Google账号登录
  • 选择启用了相关API的Google Cloud项目
  • 完成授权流程

2. 获取访问令牌

1
gcloud auth print-access-token

3. 使用令牌调用API

1
2
3
4
5
6
7
8
9
10
11
curl \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "contents": [{
      "parts": [{
        "text": "用中文简单解释一下什么是量子计算"
      }]
    }]
  }' \
  "https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash-latest:generateContent"

方式二：服务账号认证（适合生产环境）

1. 创建服务账号

  1. 访问 Google Cloud Console 服务账号页面
  2. 点击 “+ CREATE SERVICE ACCOUNT”
  3. 填写服务账号信息：
    • 名称：例如 gemini-api-caller
    • 描述：例如 “Used to call Gemini API from my application”

2. 分配权限

  • 选择角色：“Vertex AI User” (roles/aiplatform.user)
  • 这个角色提供了调用Gemini API所需的最小权限

3. 创建并下载密钥

  1. 在服务账号列表中找到刚创建的账号
  2. 点击”操作”菜单 → “管理密钥”
  3. 点击 “ADD KEY” → “Create new key”
  4. 选择 JSON 格式
  5. 下载并妥善保管密钥文件

⚠️ 安全提醒：密钥文件相当于永久密码，绝不要上传到公开代码仓库！

4. 使用服务账号

方法A：通过gcloud激活

1
2
gcloud auth activate-service-account --key-file=/path/to/your/keyfile.json
gcloud auth print-access-token

方法B：通过环境变量（推荐）

1
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/keyfile.json"

两种认证方式对比

特性 个人账号 服务账号
适用场景 本地开发、手动测试 生产环境、自动化脚本
认证方式 浏览器交互式登录 JSON密钥文件
时效性 需要定期重新登录 永久有效
安全性 个人账户完整权限 可精细控制权限
推荐度 开发阶段 生产部署

📝 总结与建议

核心要点

  1. 在macOS上安装Google Cloud CLI，强烈推荐使用Homebrew方式
  2. 官方脚本安装容易遇到SSL证书问题，特别是在使用Homebrew管理的Python环境时
  3. 生产环境建议使用服务账号，开发测试可以使用个人账号

最佳实践

  • ✅ 使用 brew install --cask google-cloud-sdk 安装
  • ✅ 为不同环境选择合适的认证方式
  • ✅ 妥善保管服务账号密钥文件
  • ✅ 定期更新CLI版本：brew upgrade google-cloud-sdk

避免的坑

  • ❌ 不要在SSL证书问题上浪费时间，直接用Homebrew
  • ❌ 不要将服务账号密钥上传到代码仓库
  • ❌ 不要在生产环境使用个人账号认证

希望这篇文章能帮助你顺利安装Google Cloud CLI，避免我踩过的坑！如果你还有其他问题，欢迎在评论区交流。

相关链接：