如何无错部署Laravel+React（InertiaJS）应用到Heroku并解决419错误

问题背景 #

使用Laravel Breeze Starter Kit创建应用，前端采用React版InertiaJS，推送到Heroku后注册和登录时出现419错误。本地运行无问题，使用Blade模板时也正常工作，已配置Heroku环境变量，需修正配置解决该错误。

当前Heroku环境变量配置：

APP_DEBUG:                true
APP_ENV:                  local
APP_KEY:                  base64:ISeJ/2xxxc6rKOYnITKlliwslW5LW4Xi1M=
APP_LOCALE:               en
APP_NAME:                 Testing Heroku
APP_URL:                  https://xxx.herokuapp.com
ASSET_URL:                https://xxx.herokuapp.com
BCRYPT_ROUNDS:            12
DB_CONNECTION:            pgsql
DB_DATABASE:              production
DB_HOST:                  host.ccc
DB_PASSWORD:              pass
DB_PORT:                  17093
DB_USERNAME:              admin
LOG_CHANNEL:              errorlog
SANCTUM_STATEFUL_DOMAINS: .xxx.herokuapp.com
SESSION_DOMAIN:           .xxx.herokuapp.com
SESSION_DRIVER:           database
SESSION_LIFETIME:         120
VITE_APP_NAME:            ${APP_NAME}

关键配置修正 #

419错误通常和CSRF令牌验证失败有关，结合InertiaJS和Heroku的环境特性，需调整以下核心环境变量：

• APP_ENV: 将local改为production
  生产环境下Laravel的安全策略更严格，local环境的调试设置会导致CSRF验证逻辑在Heroku上失效。

• SANCTUM_STATEFUL_DOMAINS: 将.xxx.herokuapp.com改为xxx.herokuapp.com
  Sanctum的状态域无需前缀点，直接使用完整域名（不含协议）即可，需与APP_URL中的域名完全匹配。

• SESSION_DOMAIN: 将.xxx.herokuapp.com改为xxx.herokuapp.com
  单域名场景下无需前缀点，直接设置为Heroku应用域名，保证会话Cookie能正确绑定到当前域名。

• APP_DEBUG: 生产环境建议改为false
  虽然不是直接导致419的原因，但开启DEBUG在生产环境存在安全风险，建议关闭。

修正后的核心环境变量示例：

APP_ENV:                  production
APP_DEBUG:                false
SANCTUM_STATEFUL_DOMAINS: xxx.herokuapp.com
SESSION_DOMAIN:           xxx.herokuapp.com

额外注意事项 #

1. 执行数据库迁移：
   在Heroku CLI中运行命令：heroku run php artisan migrate
   由于设置了SESSION_DRIVER: database，需确保会话表已创建。

2. 清除Heroku缓存：
   执行命令：heroku run php artisan config:clear 和 heroku run php artisan cache:clear
   确保新的环境变量配置生效。

3. 验证InertiaJS的CSRF自动携带：
   确认React组件中使用了Inertia的useForm钩子，它会自动处理CSRF令牌的携带，无需手动配置。

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