Heroku上Laravel启动失败主因是artisan未缓存、DATABASE_URL未解析、APP_KEY未注入；需在composer.json中配置post-install-cmd执行optimize:clear、config:cache等，数据库通过DATABASE_URL解析，APP_KEY须用heroku config:set手动注入。
Heroku 上 Laravel 启动失败，90% 是因为 artisan 命令没缓存、DATABASE_URL 没解析、APP_KEY 没注入——不是代码写错了，是部署链漏了关键环节。
artisan 命令找不到或 config:cache 失败
现象是访问返回 Application error，日志里出现 bash: artisan: command not found 或 Class 'App\Providers\AppServiceProvider' not found。根本原因：Heroku 的 Composer 构建阶段默认不执行 Laravel 生产优化命令，且 public/index.php 在未加载环境变量时就尝试启动容器，直接报错退出。
- 必须在
composer.json的"scripts"里补全post-install-cmd链，且所有 artisan 命令都要加@php前缀（否则 Heroku 的 shell 找不到可执行文件） -
optimize:clear必须放在第一条——Heroku 构建缓存可能残留旧的bootstrap/cache/*.php，导致后续 cache 命令加载失败 - 不要在
Procfile里写web: php artisan serve，Heroku PHP buildpack 只认public/目录，且自带 Apache/Nginx
示例 composer.json 片段：
"scripts": {
"post-install-cmd": [
"Illuminate\Foundation\ComposerScripts::postInstall",
"@php artisan optimize:clear",
"@php artisan config:cache",
"@php artisan route:cache",
"@php artisan view:cache"
]
}
DATABASE_URL 解析失败，连不上 PostgreSQL
错误典型是 SQLSTATE[HY000] [2002] Connection refused 或连到 127.0.0.1。Heroku 的数据库地址只通过 DATABASE_URL 环境变量注入，Laravel 默认配置完全忽略它。
- Laravel 9.2+ 用户：取消
config/database.php中pgsql配置块里'url' => env('DATABASE_URL')这行的注释，并确保.env里有DATABASE_URL=postgres://... - Laravel 8 及更早用户：不能依赖 url 字段，必须在
bootstrap/app.php开头（new Application之前）手动解析：$url = parse_url(getenv('DATABASE_URL'));，然后用putenv()或$_ENV覆盖DB_HOST、DB_DATABASE等 - 绝对不要在
.env里写DB_HOST=127.0.0.1—— Heroku dyno 每次重启 IP 都不同，且禁止本地连接
静态资源 404 或未生效
页面 HTML 渲染正常，但 CSS/JS 控制台报 404，或样式空白。这是因为 Heroku 默认不触发前端构建，npm run production 没执行，public/mix-manifest.json 不存在或路径错乱。
- 确保
composer.json的scripts里有heroku-postbuild钩子："heroku-postbuild": "npm install && npm run production" - 确认
package.json里scripts.production真正输出到public/下（比如mix --production），而不是dist/或其他目录 - 如果用了多 buildpack（如 Node.js + PHP），顺序必须是
nodejs在前、php在后，否则 PHP buildpack 构建时 node_modules 还没装好
APP_KEY 和环境变量没生效
常见表现是登录失败、session 丢失、加密异常，日志里出现 Missing application key。Heroku 不读取 .env 文件，所有敏感配置必须用 heroku config:set 注入。
-
APP_KEY必须手动设置：heroku config:set APP_KEY=$(php artisan key:generate --show)（注意加--show，否则命令不输出） - 不要用
APP_ENV=production，Heroku 会自动设为production；但APP_DEBUG=false必须显式设，否则可能暴露敏感信息 - 如果项目依赖自定义变量（如
API_TOKEN），也得一个个heroku config:set，别指望.env上传生效
最关键的细节是：所有缓存命令（config:cache 等）都依赖环境变量已加载，而环境变量又依赖 APP_KEY 存在——所以 APP_KEY 必须在第一次 git push heroku main 前就设好，否则构建会卡在 config:cache 报错。
