Google Sheets中Apps Script访问Gmail的授权问题排查

问题背景 #

我在个人Google表格中通过自有Google账号开发脚本，想要展示指定邮箱的最新邮件正文，但执行getMostRecentEmailInfo函数时触发授权类执行错误，已在appsscript.json中配置https://www.googleapis.com/auth/gmail.readonly权限。

可能的错误原因及修复方案 #

1. 权限配置未生效或格式错误 #

• 检查appsscript.json的权限配置格式是否正确，确保oauthScopes为数组结构，示例配置：

  {
    "oauthScopes": [
      "https://www.googleapis.com/auth/gmail.readonly",
      "https://www.googleapis.com/auth/spreadsheets"
    ],
    "runtimeVersion": "V8"
  }
  

• 修改配置后必须重新部署脚本（绑定表格的脚本需重新运行并完成授权流程），否则旧权限配置会残留。

2. 触发器类型导致权限限制 #

• 若通过onOpen/onEdit等简单触发器调用目标函数，这类触发器仅拥有有限权限，无法访问Gmail服务，需改用可安装触发器（手动创建的onOpen/onEdit触发器），或先手动运行一次getMostRecentEmailInfo完成授权后再使用。
• 若通过自定义菜单、按钮触发，需删除现有授权记录（在Google账号的「安全」-「第三方应用权限」中移除脚本权限），重新运行函数并完成授权。

3. Gmail API未启用 #

• 尽管Apps Script默认集成Gmail服务，部分场景下仍需手动启用Gmail API：
  1. 打开脚本编辑器，点击左侧菜单栏「服务」选项
  2. 点击「添加服务」，找到「Gmail API」并添加
  3. 确认服务状态显示为已启用

4. 代码逻辑超出权限范围 #

• 检查getMostRecentEmailInfo函数是否存在修改Gmail数据的操作（如标记已读、移动邮件），readonly权限仅支持读取，此类操作需更换为https://www.googleapis.com/auth/gmail.modify权限。

5. 账号权限限制 #

• 若使用工作/教育类Google账号，需确认管理员未限制Gmail API的访问权限；个人账号一般无此问题。

快速排查测试 #

简化函数逻辑，仅保留基础读取操作，测试是否仍报错：

function getMostRecentEmailInfo() {
  // 仅获取收件箱最新1条邮件的正文
  const threads = GmailApp.getInboxThreads(0, 1);
  if (threads.length === 0) return "无可用邮件";
  const latestMsg = threads[0].getMessages()[0];
  return latestMsg.getPlainBody();
}

同时查看脚本编辑器的「执行记录」，获取具体错误提示，缩小排查范围。

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