Heroku部署Django应用时Google OAuth2.0认证报localhost连接错误

云原生阿岚

2026-8-29

问题产生原因

该报错核心是OAuth2.0认证流程的回调地址配置和部署环境不匹配，本地运行正常、Heroku部署失败的具体触发逻辑如下：

本地开发时，要么你在代码里硬编码了http://localhost:8080作为OAuth回调地址，要么调用了Google API客户端自带的run_local_server(port=8080)方法，该方法会在你本地电脑启动8080端口监听认证结果，和你本地运行环境适配，所以能正常完成认证。
部署到Heroku之后，Heroku的服务运行在云端容器中，localhost指向容器自身的内部回环地址，既没有公网访问权限，普通用户的浏览器访问localhost:8080时实际是请求用户自己电脑的8080端口，根本连不上部署在Heroku上的服务；如果你用了本地服务器监听的认证方法，该方法只会在Heroku容器内部启动8080端口，公网无法访问，认证流程直接断裂。
额外常见诱因：Google Cloud控制台的OAuth客户端配置里，没有添加Heroku应用的正式域名作为合法回调地址，认证时被Google拦截或者回退到你配置的本地测试地址。

修复步骤

第一步：更新Google Cloud OAuth客户端配置
打开Google Cloud控制台对应项目的「API和服务-凭据」页，找到你当前使用的OAuth 2.0客户端ID，在「已授权的重定向URI」列表中添加你Heroku应用的完整回调地址，格式为https://<你的Heroku应用名>.herokuapp.com/<你Django项目中配置的回调路径>，注意生产环境回调必须使用HTTPS协议，不要带多余的斜杠或路径后缀，和代码中写的回调路径完全一致。

第二步：移除代码中硬编码的本地回调地址
不要在代码里写死localhost相关的回调地址，通过环境变量+DEBUG状态区分开发、生产环境的配置，示例配置如下：

# Django settings.py 中的Google OAuth相关配置
import os
DEBUG = os.getenv("DEBUG", "False") == "True"

if DEBUG:
    # 本地开发环境用本地回调地址，端口和你本地Django运行端口一致即可
    GOOGLE_OAUTH_REDIRECT_URI = "http://localhost:8000/google/auth/callback"
else:
    # 生产环境读取Heroku配置的应用域名，拼接回调路径
    GOOGLE_OAUTH_REDIRECT_URI = f"https://{os.getenv('HEROKU_APP_DOMAIN')}/google/auth/callback"

对应的Heroku环境变量可以在Heroku后台的应用设置-Config Vars里添加，分别配置DEBUG=False、HEROKU_APP_DOMAIN=<你的Heroku应用名>.herokuapp.com即可。

第三步：替换生产环境不适用的本地认证逻辑
如果你之前在代码里调用了run_local_server(port=8080)这类自动启动本地端口监听的认证方法，必须在生产环境移除该逻辑，改用标准Web服务OAuth流程：用户访问你的Django页面触发认证 -> 后端拼接认证参数跳转Google授权页 -> 用户授权后Google重定向到你配置的公网回调地址 -> 后端接收回调请求的授权码，调用接口换取access token完成认证。
第四步：配置校验
所有配置修改完成后，重新部署Heroku应用，清空浏览器缓存后测试认证流程；注意Google Cloud的OAuth配置更新后通常有1-3分钟的生效延迟，刚改完测试如果提示回调地址不合法可以稍等片刻再重试。

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