使用gspread连接时突发RefreshError问题求助

可能触发问题的原因 #

• 本地缓存令牌过期/失效：gspread 用 OAuth 认证时会自动生成 token.json 缓存授权令牌，就算重置了 credentials.json，程序还是会优先读取旧的失效令牌，导致认证失败。
• OAuth 客户端类型与运行环境不匹配：如果你的 credentials.json 是桌面应用类型，但最近把代码部署到了服务器、容器这类无界面环境，谷歌会判定客户端环境异常，抛出 invalid_client 错误。
• OAuth consent screen 测试期到期：如果你的谷歌云项目 OAuth consent screen 处于测试状态，默认测试用户权限只有 7 天有效期，到期后授权会被自动收回。

具体解决步骤 #

1. 清理本地令牌缓存：找到项目文件夹里的 token.json 直接删掉，重新运行代码，会弹出新的 OAuth 授权窗口，完成后生成新的有效令牌。
2. 调整客户端凭据类型：
   • 若代码在服务器/无界面环境运行：去谷歌云控制台的 API 与服务→凭据，创建服务账号凭据，下载 service_account.json，改用 gspread.service_account() 方式认证（代码示例见下文）。
   • 若为本地桌面环境：确认客户端 ID 类型是「桌面应用」，且没有跨平台迁移代码（比如从 Windows 转到 Linux 后未重新授权）。
3. 更新 OAuth consent screen 状态：
   • 若要长期使用，把测试状态的 consent screen 发布为生产模式；
   • 若仍需测试，在 consent screen 页面添加新的测试用户，延长授权有效期。
4. 核对权限范围：检查 credentials.json 里的 scopes 字段，确保包含 https://www.googleapis.com/auth/spreadsheets（访问表格）和 https://www.googleapis.com/auth/drive（如果需要通过 Drive 打开文件），缺少必要权限也会导致授权失败。

服务账号认证代码示例 #

如果改用服务账号，替换原有代码：

import gspread

# 用服务账号凭据初始化
gc = gspread.service_account(filename='service_account.json')
master = "filename"
master_file_sh = gc.open(master)

⚠️ 注意：需要把服务账号的邮箱地址添加到目标谷歌表格的共享列表里，至少赋予查看权限。

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