如何在 Flarum 2.0 中开启 Google 登录？

如何在 Flarum 2.0 中开启 Google 登录？目前最省事、也最靠谱的方案，是安装 FriendsOfFlarum 维护的 fof/oauth 扩展，然后在 Google Cloud 创建一个 Web OAuth 客户端。配置完成后，访客可以直接使用 Google 账号注册或登录 Flarum，不必再记一套论坛密码。

这件事看着只是多一个按钮，真正容易翻车的地方却不少：Flarum 2.0 仍处于 RC 阶段、OAuth 扩展使用 Beta 版本、回调地址必须逐字一致，反向代理和页面缓存还可能把 OAuth 的 state 弄丢。别急着在生产论坛上点点点，先把版本和回调地址看明白。

先说版本：现在的 Flarum 2.0 还不是最终稳定版

截至 2026 年 8 月 3 日，Packagist 上最新的 Flarum 2.0 版本是 v2.0.0-rc.5，发布于 2026 年 7 月 8 日，要求 PHP 8.3 或更高版本。可以在 flarum/core 的 Packagist 页面核对当前版本。

Google 登录推荐使用 FoF OAuth。它已经把 Google、GitHub、GitLab、Discord、Facebook 和 LinkedIn 等提供商打包在同一个扩展里。当前面向 Flarum 2.x 的版本是 2.0.0-beta.3，依赖 flarum/core:^2.0.0。

这两个版本号不是废话。如果你直接照搬 Flarum 1.x 的老教程，Composer 很可能不给装；即使硬装进去，也可能把整个论坛送进 500 错误。

Flarum Google 登录是怎么工作的？

FoF OAuth 使用 Google 的 OAuth 2.0 与 OpenID Connect 流程。用户点击“使用 Google 登录”后：

1. Flarum 把用户重定向到 Google 的授权页面；
2. 用户选择 Google 账号并同意授权；
3. Google 把授权码送回论坛的 /auth/google 地址；
4. FoF OAuth 在服务器端用授权码交换并验证登录凭据；
5. 扩展登录已有用户、关联相同邮箱的账户，或者引导新用户完成注册。

论坛拿不到用户的 Google 密码。它拿到的是 Google 签发的身份凭据，以及用户授权提供的基本资料。Google 的 OpenID Connect 官方文档要求使用 HTTPS、准确匹配回调地址，并只申请业务真正需要的权限。

开始前先准备这几样东西

• 已经可以正常访问的 Flarum 2.0 论坛；
• PHP 8.3、8.4 或 8.5 环境；
• 论坛已经启用 HTTPS；
• Flarum 管理员权限；
• 服务器 SSH 和 Composer 权限，或者已启用 Extension Manager；
• 一个可管理 Google Cloud 项目的 Google 账号；
• 论坛首页、隐私政策和服务条款页面；
• 数据库与网站文件备份。

先在论坛根目录确认版本：

php -v
php flarum info
composer show flarum/core

如果还在 Flarum 1.x，就先停手。本文讲的是 Flarum 2.x，不能把两个大版本的扩展混着装。

第一步：安装 Flarum 2.x 兼容的 FoF OAuth

进入包含 composer.json 和 flarum 命令文件的论坛根目录，执行：

composer require fof/oauth:"^2.0@beta"
php flarum cache:clear

这个约束会让 Composer 选择与 Flarum 2.x 兼容的 FoF OAuth 2.x 版本。如果你的项目已经按 Flarum 官方方式把 minimum-stability 设置为 Beta，也可以依照 Flarum 2.x 扩展文档使用：

composer require fof/oauth:"*"

装完后执行 composer show fof/oauth 检查实际版本。不要安装 johnhearfield/flarum-ext-oauth-google、saleksin/flarum-auth-google 这类为早期 Flarum Beta 编写的老扩展。名字里带 Google，不代表它活到了 2026 年。

没有 SSH 的托管环境，可以在 Flarum 后台的 Extension Manager 中搜索 Composer 包名 fof/oauth。但要记住，Extension Manager 本质上允许管理员安装 Composer 软件包，因此只有受信任的管理员才能获得这个权限。

第二步：在 Flarum 后台启用 Google 提供商

1. 登录 Flarum 管理后台；
2. 进入 Extensions，找到并启用 FoF OAuth；
3. 打开 FoF OAuth 的设置页面；
4. 找到 Google 提供商；
5. 先记下设置页面显示的 Callback URL；
6. 暂时不要急着启用给所有用户，先完成 Google Cloud 配置。

Flarum 2.x 版 FoF OAuth 会根据论坛实际基础网址生成回调地址，标准格式是：

https://forum.example.com/auth/google

如果论坛装在子目录，地址可能是：

https://example.com/community/auth/google

以 FoF OAuth 后台显示的地址为准。不要擅自加 /callback，也别把网上老教程中的 /login/google 原样搬过来。FoF OAuth 2.0.0-beta.3 的实际路由是 /auth/{provider}。

第三步：创建 Google Cloud 项目

1. 打开 Google Cloud Console；
2. 在顶部项目选择器中创建新项目，或选择现有项目；
3. 项目名称建议使用论坛名称，方便以后维护；
4. 进入 Google Auth Platform。

一个论坛单独用一个 OAuth 客户端，后续改域名、轮换密钥和排查错误都会轻松很多。把十几个毫不相干的网站塞进同一个客户端，省下的不是时间，是未来排错时的理智。

第四步：配置 Branding、Audience 和 Data Access

1. Branding

• App name：用户授权时看到的应用名称；
• User support email：处理登录问题的邮箱；
• App logo：论坛或品牌 Logo；
• Application home page：论坛首页；
• Privacy policy：隐私政策页面；
• Terms of service：服务条款页面；
• Authorized domains：填写自己拥有并可验证的主域名；
• Developer contact：接收 Google 通知的邮箱。

面向公开用户的生产应用必须有可访问的首页、隐私政策和服务条款，并使用自己拥有或获授权使用的域名。具体要求以 Google OAuth 2.0 政策为准。

2. Audience

• Internal：一般只适用于同一 Google Workspace 组织的用户；
• External：面向普通论坛访客时通常选择这一项。

配置阶段先保持 Testing，并把管理员自己的 Google 账号加入 Test users。测试完成、准备让所有访客使用时，再按 Google 控制台要求发布应用。

3. Data Access

登录只需要最小身份范围：openid、email 和 profile。不要顺手申请 Gmail、Google Drive 或联系人权限。一个论坛登录按钮突然想读用户网盘，谁看了都想跑。

第五步：创建 Web OAuth 客户端

1. 进入 Google Auth Platform 的 Clients 页面；
2. 点击 Create client；
3. Application type 选择 Web application；
4. 填写一个容易识别的客户端名称；
5. 在 Authorized redirect URIs 中添加 FoF OAuth 后台显示的完整回调地址；
6. 创建客户端，并复制 Client ID 与 Client Secret。

这是服务器端 OAuth 授权码流程，核心配置是 Authorized redirect URIs。除非同一个项目还有前端 JavaScript 登录业务，否则不要把“Authorized JavaScript origins”当成回调地址使用。

Google 要求请求中的 redirect_uri与登记值完全一致，包括 HTTPS、域名、子目录、大小写和结尾斜杠。官方 OpenID Connect 文档也明确指出，不一致会返回 redirect_uri_mismatch。

第六步：把 Client ID 和 Client Secret 填回 Flarum

1. 回到 Flarum 管理后台的 FoF OAuth 设置；
2. 打开 Google 提供商设置；
3. 粘贴 Client ID；
4. 粘贴 Client Secret；
5. 按需要选择新用户加入的论坛用户组；
6. 启用 Google 提供商并保存；
7. 执行 php flarum cache:clear，或者从后台清理缓存。

Client Secret 只能保存在服务器端。不要放进截图、前端代码、公开 Git 仓库或论坛帖子。发现泄露就立即在 Google Cloud 轮换密钥，再更新 FoF OAuth 配置。

第七步：检查 Flarum 注册与账户关联设置

如果希望新访客通过 Google 创建论坛账户，Flarum 必须允许新用户注册。关闭普通注册后，OAuth 新用户也可能无法完成账户创建。只想让已有用户绑定 Google，则需要先用现有账户登录，再到用户的 Security 设置页面关联 Google。

FoF OAuth 2.x 支持账户关联、相同邮箱自动匹配和用户自行管理已连接的登录提供商。上线前要重点测试“Google 邮箱与现有 Flarum 账户相同”的情况，确认不会生成重复账户。

第八步：用无痕窗口完成真实测试

• 一个从未注册过的新 Google 账号；
• 一个邮箱与现有 Flarum 用户相同的账号；
• 退出后再次使用 Google 登录；
• 拒绝授权后能否正常返回论坛；
• 手机和电脑各测试一次；
• 检查新用户被分配到哪个用户组；
• 检查用户能否在 Security 页面解除和重新绑定；
• 管理员密码登录和恢复入口是否仍然可用。

别只用已经登录 Flarum 和 Google 的管理员浏览器测试。管理员电脑上一秒成功，访客手机上原地转圈，这种戏码在 OAuth 世界里天天上演。

Flarum Google 登录常见错误怎么解决？

错误一：Error 400 redirect_uri_mismatch

原因：Google Cloud 登记的回调地址与 Flarum 实际发送的地址不一致。

处理：从 FoF OAuth 设置页重新复制 Callback URL，逐项检查 HTTPS、www、子目录、域名和斜杠。不要凭记忆手打。

错误二：Error 403 access_denied 或 org_internal

原因：应用仍在 Testing，当前账号没有加入测试用户；或者 Audience 被设置成 Internal，只允许 Workspace 组织成员。

处理：测试时添加 Test users；公开论坛选择 External，并完成品牌信息与应用发布。

错误三：missing required parameter client_id

原因：Client ID 没有保存、填错位置，或者 Google 提供商没有正确启用。

处理：重新打开 FoF OAuth 设置，确认 Google 开关、Client ID 和 Client Secret，再清理 Flarum 缓存。

错误四：访问 /auth/google 返回 404

原因：FoF OAuth 没有启用、扩展版本不兼容、论坛 URL 重写失败，或者 config.php 中的 url与真实域名不一致。

处理：确认扩展已启用，运行 composer show fof/oauth 与 php flarum info，检查 Nginx/Apache 重写规则并执行 php flarum cache:clear。

错误五：Invalid state、循环跳转或登录后回到原地

原因：OAuth 流程中的 Session 或 Cookie 丢失，常见于 HTTP/HTTPS 判断错误、反向代理头不正确、论坛基础 URL 配错，或 CDN/超级缓存错误缓存了 /auth/*。

处理：让 CDN、反向代理和全页缓存绕过 /auth/*；确认代理正确传递 HTTPS；核对 config.php 中的论坛 URL；清理服务器缓存与浏览器 Cookie 后重新测试。

错误六：500 Internal Server Error

先别重装全站。查看 storage/logs/ 中最新的 Flarum 日志，检查 PHP 版本、Composer 依赖、文件权限和服务器能否通过 HTTPS 访问 Google。生产站关闭调试信息，日志只给管理员看。

论坛更换域名后，需要同步修改哪些地方？

• 更新 Flarum config.php 中的 url；
• 在 Google OAuth 客户端添加新域名的 /auth/google；
• 更新 Branding 中的首页、隐私政策、服务条款和授权域名；
• 检查反向代理、HTTPS 和 Cookie 域；
• 清理 Flarum、CDN 与浏览器缓存；
• 新域名验证成功后，再删除旧回调地址。

回调地址跟着论坛基础 URL 走。域名换了，Google 不会“理解你的意思”，它只会冷静地丢给你一个 400。

上线前的安全检查清单

• Flarum、FoF OAuth 和 PHP 版本相互兼容；
• 网站全程使用 HTTPS；
• 回调地址与后台显示内容完全一致；
• 只申请 openid email profile 最小权限；
• Client Secret 没有出现在前端和公开仓库；
• 普通新用户只获得最低必要权限；
• /auth/* 已排除全页缓存；
• 新用户、已有用户、拒绝授权、解绑和再次登录均已测试；
• 管理员保留独立密码与恢复方式；
• 定期执行 composer audit 并关注 Flarum 与 FoF 的更新。

庄朋龙的建议：先把登录跑稳，再考虑只保留 Google 登录

Google 登录确实能降低论坛注册门槛，但不要一上线就把邮箱密码登录和管理员恢复入口全部砍掉。先让新用户、老用户和管理员分别跑几天，确认账户关联、邮件通知、用户组和注销都正常，再决定是否收紧传统注册。

如果你使用的是 WordPress 而不是 Flarum，可以阅读另一篇教程：WordPress 网站如何开启 Google 登录功能？。两个系统都用 Google OAuth，但插件、回调路由和账户模型完全不同，千万别把配置地址串台。