手把手教你用自定义Google OAuth连接Gmail与n8n

n8n 的 Gmail 节点开箱即用，但如果你希望完全掌控授权流程——比如用于团队内部工具、避免共享凭据，或者单纯想搞清楚 OAuth 的每一步——用自己的 Google Cloud 凭据来连接会更稳妥。这个教程不讲 AI Agent，也不涉及复杂编排，只聚焦一件事：从零创建 Google OAuth 凭据，并让 n8n 的 Gmail 节点成功发出第一封邮件。

为什么需要自定义 OAuth 凭据

n8n 默认提供了一套 OAuth 应用，点击「Sign in with Google」就能快速授权。但这种方式下，授权范围、测试用户名单、凭据生命周期都由 n8n 管理，你无法审计或迁移。使用自己的 Google Cloud 项目则不同：Client ID 和 Client Secret 握在自己手里，可以随时撤销、轮换，也能精确控制哪些邮箱能通过测试。据 YouTube 教程作者演示，整个流程不需要写一行代码，核心操作集中在 Google Cloud Console 和 n8n 两个界面之间切换。

第一步：在 Google Cloud 创建项目并启用 Gmail API

登录 Google Cloud Console，新建一个项目，名称可以随意，教程中用的是 n8n gmail demo。项目创建完成后，进入「API 和服务」→「库」，搜索 Gmail API 并点击启用。这一步容易被跳过，但如果没有启用，后续 n8n 授权时会直接报错。

配置 Google Auth

启用 API 之后，还需要配置 OAuth 同意屏幕。选择「外部」用户类型，填写应用名称（同样可以用 n8n gmail demo），然后一路下一步完成创建。这里不需要上传 Logo 或填写隐私政策，测试阶段保持最简即可。

Google Cloud Console 是 Google 提供的云端资源管理平台，一个「项目」是其中资源、API 和计费的基础容器。每个项目拥有独立的 API 启用状态、配额和凭据体系，因此为 n8n 单独建一个项目可以避免与其他应用相互干扰。Gmail API 则是允许程序化读写邮箱的接口，未启用时所有来自该项目的 Gmail 请求都会被拒绝，这正是 n8n 授权阶段报错的常见原因。启用 API 本身不产生费用，但 Google 对调用频次设有配额，个人或小团队的发信场景通常远低于限制。

OAuth 同意屏幕是 Google 在用户授权前展示的告知页面，用于说明哪个应用、请求哪些权限。用户类型分为「内部」和「外部」：「内部」仅限同一 Google Workspace 组织内的账号，无需 Google 验证；「外部」面向任何 Google 账号，在未发布为「生产」前处于「测试」状态，有测试用户数量和令牌有效期的限制。教程选择「外部」是为了兼容普通个人 Gmail 账号，代价就是必须手动维护测试用户名单。

第二步：创建 OAuth 客户端 ID 并配置回调地址

在「凭据」页面点击「创建凭据」，选择「OAuth 客户端 ID」，应用类型选「Web 应用」。名称填 n8n demo 之类的标识即可。关键的一步是已获授权的重定向 URI：回到 n8n 的 Gmail 节点，复制它显示的 OAuth Redirect URL，粘贴到 Google Cloud 的这个字段里，然后保存。

完成 OAuth 创建

创建成功后，页面会弹出 Client ID 和 Client Secret。这两个值只显示一次，务必立即复制到 n8n 的凭据配置中。据教程演示，n8n 侧只需把这两个值填入对应输入框并保存，凭据就建好了。

复制 Client ID 和 Secret

OAuth 2.0 的授权码流程中，重定向 URI（Redirect URI）是用户同意授权后浏览器被跳转回的地址，授权码会附加在其后交给应用。Google 要求应用在创建客户端时预先登记该地址，授权时严格比对，任何字符差异都会被拒绝，这是防止授权码被劫持到恶意地址的关键机制。因此 n8n 显示的 Redirect URL 需要原样复制，包括协议、端口和路径，不能凭记忆手写。

第三步：添加测试用户，解决「访问被阻止」

第一次点击「Sign in with Google」时，大概率会遇到「访问被阻止」的提示。这不是配置错误，而是因为 OAuth 同意屏幕处于「测试」状态，只有被列入测试用户名单的邮箱才能授权。回到 Google Cloud 的「OAuth 同意屏幕」→「测试用户」，把你的 Gmail 地址加进去并保存。

再次回到 n8n 点击登录，选择账号、确认权限，授权就能顺利通过。这个细节在官方文档里往往一笔带过，但对初次配置的人来说是最容易卡住的地方。

「访问被阻止」（Access blocked）是 Google 针对未验证应用的保护策略：当 OAuth 同意屏幕处于测试状态时，只有明确登记为测试用户的账号才能完成授权，其他账号会看到错误页。测试用户上限为 100 个，且测试状态下的刷新令牌通常在 7 天后失效，长期运行的工作流可能需要定期重新授权。若要让任意用户使用，需将应用发布为「生产」；如果申请了 Gmail 这类敏感权限，还需通过 Google 的 OAuth 验证流程，包括隐私政策与域名验证。

第四步：搭建最小工作流并验证发信

工作流本身极简：一个 Manual Trigger 节点，加一个 Gmail 节点，操作选「Send a message」。在 Gmail 节点里配置收件人（可以填自己的邮箱）、主题和正文，比如主题写「test」，正文写一句简单的话。

配置邮件内容

点击执行工作流，n8n 显示执行成功后，打开 Gmail 收件箱就能看到那封测试邮件。至此，Gmail 已经通过你自建的 OAuth 凭据完整接入 n8n。

几个值得注意的实践细节

回调地址必须完全一致。n8n 生成的 Redirect URL 包含端口和路径，粘贴到 Google Cloud 时多一个斜杠或少一个字符都会导致授权失败。

测试用户上限是 100 个。对于个人或小团队足够用，但如果要上线给更多用户使用，需要将 OAuth 同意屏幕发布为「生产」状态，并可能需要经过 Google 的验证流程。

凭据可以复用。建好一次之后，同一个 n8n 实例里的其他 Gmail 节点可以直接选用这份凭据，不必重复创建。教程作者也强调，这套流程就是纯粹的认证与自动化，没有 AI Agent 参与——把基础打通，后续叠加任何逻辑都会更顺手。

常见问题

授权后仍然提示权限不足？ 检查 Gmail API 是否已启用，以及测试用户是否包含当前登录的邮箱。

Client Secret 泄露了怎么办？ 在 Google Cloud 凭据页面重置 Secret，然后到 n8n 里更新对应字段即可，不需要重建整个项目。

能否用于多个 Gmail 账号？ 可以，为每个账号单独走一次授权流程，n8n 会保存多份凭据供不同节点选择。