Heroku上Laravel启动失败因artisan命令未缓存及环境变量未加载，需在composer.json中配置post-install-cmd执行optimize:clear、config:cache等；数据库须通过DATABASE_URL解析；静态资源需确保heroku-postbuild触发npm run production；APP_KEY等环境变量必须用heroku config:set手动注入。
Heroku上Laravel启动失败：artisan命令找不到
常见现象是部署后访问返回 Application error，或者日志里看到 bash: artisan: command not found。根本原因不是没装 Laravel，而是 Heroku 默认不执行 php artisan optimize 或 php artisan config:cache，且 public/index.php 依赖的 bootstrap/app.php 在未加载环境变量时会直接报错退出。
必须在 composer.json 的 scripts 里补全生产启动链：
"scripts": {
"post-install-cmd": [
"Illuminate\Foundation\ComposerScripts::postInstall",
"@php artisan optimize:clear",
"@php artisan config:cache",
"@php artisan route:cache",
"@php artisan view:cache"
]
}
-
optimize:clear是必须的——Heroku 构建缓存可能残留旧 bootstrap 文件 - 所有
:cache命令必须加@php前缀，否则 Heroku 的 Composer 环境里找不到artisan可执行文件 - 别在
Procfile里手动写php artisan serve，Heroku PHP buildpack 自带 web server，只认public/目录
数据库配置在Heroku上始终连不上
错误典型是 SQLSTATE[HY000] [2002] Connection refused 或 Connection refused to host "127.0.0.1"。Heroku 的 PostgreSQL 是通过 DATABASE_URL 环境变量注入的，Laravel 默认不读这个，也不会自动拆解成 DB_HOST、DB_NAME 等。
解决方案只有两个有效路径：
- 用
laravel/framework9.2+ 自带的database_url解析能力：在.env里写DATABASE_URL=postgres://user:pass@host:5432/dbname，然后在config/database.php的pgsql配置块中，把'url' => env('DATABASE_URL')这行取消注释（默认被注释） - 降级兼容方案：在
bootstrap/app.php开头加几行手动解析逻辑，用parse_url(getenv('DATABASE_URL'))覆盖env()返回值（注意要放在Application实例创建前） - 绝对不要在
.env里硬编码DB_HOST=127.0.0.1—— Heroku 不允许本地连接，且每次 dyno 启动 IP 都不同
静态资源（CSS/JS）404 或未生效
表现是页面 HTML 正常渲染，但样式空白、控制台报 Failed to load resource: the server responded with a status of 404 ()。核心问题在于 Laravel Mix 编译产物默认输出到 public/mix-manifest.json，而 Heroku 的构建流程中，如果 npm install 和 npm run production 没触发，或触发时机不对，manifest 文件就为空或缺失。
关键动作只有三步：
- 确保
package.json中"heroku-postbuild"脚本存在："heroku-postbuild": "npm run production"
- 确认
webpack.mix.js里没有写死.setPublicPath('dist')类路径——Heroku 只认public/为 Web 根目录 - 清掉本地
node_modules和public/mix-manifest.json，重新npm install && npm run production再提交，避免 Git 忽略了 manifest 文件
环境变量丢失导致 APP_KEY 为空或 JWT 失效
现象包括登录后无法保持 session、API 返回 TokenMismatchException、或 APP_KEY 报 The only supported ciphers are AES-128-CBC and AES-256-CBC。Heroku 不会自动从 .env 加载变量，且 .env 本身不该进 Git，所以必须手动注入。
正确做法是用 Heroku CLI 一次性设全：
heroku config:set APP_KEY=$(php -r "echo base64_encode(random_bytes(32));") APP_DEBUG=false APP_ENV=production LOG_CHANNEL=errorlog
-
APP_KEY必须用random_bytes()生成，不能手敲字符串或复用本地值——不同环境 key 必须独立 - 设完立刻验证：
heroku config:get APP_KEY，确认长度是 44 字符（base64 编码后的 32 字节） - JWT、session、encrypt 等所有依赖
APP_KEY的功能，只要 key 变过，旧 token/session 全失效，这是预期行为，不是 bug
最常被跳过的一步是忘记关 APP_DEBUG——开启状态下 Heroku 会暴露完整堆栈，且某些中间件行为异常。
