Heroku生产环境Action Mailer配置Gmail发信失败如何解决

排查解决步骤（按问题出现概率从高到低排序） #

• 第一步：校验Heroku环境变量配置
  90%以上的同类问题都是环境变量配置错误导致：
  • 执行heroku config命令查看已配置的环境变量，确认gmail_username是完整的Gmail邮箱地址（格式为xxx@gmail.com，不能只填@前缀的用户名），gmail_password是Gmail开启2FA后生成的16位应用专用密码，不要填写账号日常登录密码，复制时注意不要带入首尾空格
  • 如果变量值错误，执行heroku config:set gmail_username=你的完整Gmail地址 gmail_password=你的16位应用专用密码重新设置，修改后必须执行heroku restart重启dyno让新配置生效
• 第二步：修正production.rb中的SMTP配置
  你当前的配置存在三个容易触发Gmail拒信的问题，修正后的配置段如下：

  config.action_mailer.delivery_method = :smtp
  config.action_mailer.smtp_settings = {
    address:              'smtp.gmail.com',
    port:                 587,
    domain:               'MY-APP.herokuapp.com', # 不要填gmail.com，替换为你的Heroku应用实际域名
    user_name:            ENV['gmail_username'],
    password:             ENV['gmail_password'],
    authentication:       'plain',
    starttls:             true, # 替换旧的enable_starttls_auto参数，兼容新版本Rails
    open_timeout:         15, # 原5秒超时设置过短，Heroku网络波动容易触发断连
    read_timeout:         15
  }
  
  config.action_mailer.perform_deliveries = true
  config.action_mailer.raise_delivery_errors = true
  config.action_mailer.default_options = {from: 'xxxxx@gmail.com'}
  # default_url_options补充https协议，避免Gmail判定来源可疑拦截邮件
  config.action_mailer.default_url_options = { host: 'MY-APP.herokuapp.com', protocol: 'https' }
  

• 第三步：排查Gmail侧拦截规则
  • 登录Gmail账号查看最近的安全活动记录，如果有来自Heroku服务器IP的登录被拦截，手动标记为「本人操作」
  • 新生成的Gmail应用专用密码存在10-15分钟的生效延迟，不要刚生成就立刻测试
  • 个人Gmail账号有严格的发信频率限制，单日发信超过500封就会临时限制发信权限，新注册账号阈值更低，生产环境长期使用不建议依赖个人Gmail账号发信
• 第四步：本地预验证配置正确性
  不要每次改完代码就推到Heroku盲测，本地先模拟生产环境验证：
  1. 本地终端执行RAILS_ENV=production rails c进入生产环境控制台
  2. 控制台内调用发信方法执行TestMailer.test_email.deliver!测试发信
     如果本地生产环境可以正常发信，推送到Heroku后失败，基本可以确定是Heroku环境变量配置错误、或者代码推送后没重启dyno导致的。
• 兜底方案
  如果以上步骤全部验证后仍然无法发信，直接使用Heroku平台官方推荐的邮件发信插件，新用户有免费可用额度，不需要额外处理Gmail的反垃圾拦截规则，配置简单稳定性更高，不会出现突然被封禁发信权限的问题。

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