Gmail OAuth Setup 是一个专为无头服务器环境设计的 Gmail API 认证工具，通过 `gog` CLI 实现自动化 OAuth 2.0 流程配置。该方案适用于首次集成 Gmail API、续期即将过期的访问令牌，或在无法使用图形界面的服务器上完成身份验证等场景。与传统手动复制粘贴授权码的方式不同，此工具提供了一套完整的命令行交互流程，支持生成授权链接、快速交换一次性验证码，并自动管理刷新令牌。其核心优势在于兼容 headless 环境，用户可通过本地终端操作完成整个 OAuth 授权过程，无需依赖浏览器自动化或第三方脚本注入。此外，该工具特别针对 Google Cloud 控制台新政策调整进行了适配，例如处理 `redirect_uri_mismatch` 错误和弃用旧版 `oob` 重定向方式的问题。
核心功能特点
- 基于 gog CLI 的无头服务器友好型 OAuth 流程
- 支持生成授权 URL 并快速交换一次性验证码
- 自动处理刷新令牌以维持长期访问权限
- 内置对 Google 应用验证状态错误的解决方案（如发布应用或添加测试用户）
- 提供详细的错误排查指南，涵盖常见认证失败原因及修复方法
- 推荐使用最小权限范围（如 gmail.modify），简化授权界面并提升安全性
适用场景
该工具主要面向开发者和技术运维人员，在多种实际开发与维护场景中发挥关键作用。例如，当需要在 CI/CD 流水线中集成 Gmail 邮件发送功能时，传统浏览器弹窗方式不可行，此时可通过本工具在无图形界面的服务器上完成初始 OAuth 配置，后续利用刷新令牌实现静默认证。又如，当企业或个人项目中的 Gmail API 应用仍处于‘测试模式’且未通过 Google 审核时，常会遇到‘应用未经验证’的拦截页面，导致普通用户无法授权。本工具明确指导用户将应用发布为正式应用，从而获得永久有效的刷新令牌，避免每七天重新授权的繁琐操作。对于远程服务器部署的应用，尤其是运行于 Docker 容器或云函数中的服务，无法弹出浏览器窗口进行交互式登录，本方案通过本地终端引导用户完成授权，极大提升了部署效率与用户体验。