Win10/树莓派Python调用Gmail API桌面应用授权及凭证获取问题

适用场景：

• 运行环境：搭载Raspbian系统的树莓派、Windows 10设备
• 实现目标：通过Python对接Gmail API访问个人Gmail账户

1. 基础客户端凭证获取（即credentials.json/client_secret.json） #

这一步拿到的文件就是所有教程里提到的核心配置文件，两个名字只是不同教程的命名习惯差异，本质是同一个文件，不用纠结叫法：

• 打开Google Cloud Platform控制台，新建独立项目，在API库中搜索找到Gmail API并启用
• 进入OAuth同意屏幕配置页，用户类型选「外部」，按提示填完应用名称、开发者联系邮箱等必填项，把你要用来授权的个人Gmail账号添加到测试用户列表，保存配置
• 跳转至凭据管理页，选择「创建凭据-OAuth客户端ID」，应用类型必须选桌面应用，随便填个可识别的名称后确认创建
• 创建完成后直接下载生成的JSON凭证文件，放到你的Python脚本同级目录，按照你用的代码里的读取要求重命名为credentials.json或者client_secret.json即可，不要手动修改文件里的任何字段。

踩坑提示：如果创建凭证时选成了Web应用，后续授权一定会报redirect_uri不匹配的错误，桌面应用类型不需要手动配置任何回调地址，授权流程会自动监听本地随机端口完成回调。

2. 完整授权操作流程 #

• 先安装官方依赖包，执行命令：pip install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib
• 运行你的quickstart.py脚本，终端会打印带授权参数的URL，格式和你贴出的示例一致
  • 如果是Windows10设备直接运行脚本，直接点击该URL就能唤起默认浏览器打开授权页
  • 如果是无图形界面的树莓派，把这个URL复制到同网络下的任意设备浏览器打开即可
• 打开授权页后会弹出Google未验证应用的安全提示，点击页面左下角的「高级」按钮，再选择「转到[你的应用名]（不安全）」，按页面提示选中要授权的Gmail账号，勾选邮件访问权限后确认授权
• 授权完成后浏览器会自动跳转到本地回调地址：
  • 如果你是在运行脚本的Windows设备上操作的浏览器，官方的OAuth库会自动捕获回调请求，脚本会自动继续执行，脚本同级目录会自动生成token.json文件，存储访问令牌和刷新令牌，后续运行脚本不需要重复走授权流程
  • 如果你是在其他设备上打开的授权页（比如树莓派场景），跳转后浏览器会提示无法访问localhost地址，这时候直接把浏览器地址栏里完整的回调URL整段复制，回到运行脚本的终端，按照提示粘贴该URL后按回车，同样会自动生成token.json完成授权。

3. 常见问题处理 #

• 授权时提示「访问被拒绝」：回到GCP控制台的OAuth同意屏幕配置页，检查你当前用来授权的Gmail账号是否已经被添加到测试用户列表，未添加的测试阶段账号没有授权权限
• 重启脚本后提示凭证失效：删除旧的token.json文件，重新走一遍授权流程即可，个人账号的刷新令牌有效期很长，只要不主动撤销授权，生成一次可以用很久
• 安全提示：credentials.json和自动生成的token.json都包含你的账号授权敏感信息，不要把这两个文件提交到公开代码仓库或者发给其他人，否则对方可以直接访问你的Gmail账户内容。

内容的提问来源于stack exchange，提问作者scriptDaddy