Heroku部署Laravel项目出现返回类型兼容错误导致部署失败

DevOps 小满

2026-8-26

问题现象

Heroku部署Laravel应用时推送被拒，composer依赖安装阶段报错终止，应用在本地环境可正常运行，已在Procfile中配置启动规则：
web: vendor/bin/heroku-php-apache2 public/

部署阶段核心报错日志如下：

> Illuminate\Foundation\ComposerScripts::postAutoloadDump
remote:        Deprecation Notice: Return type ofIlluminate\Container\Container::offsetExists($key) should either be compatible with ArrayAccess::offsetExists(mixed $offset): bool, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice in /tmp/build_275de9ef/vendor/laravel/framework/src/Illuminate/Container/Container.php:1231
remote:        Deprecation Notice: Return type of Illuminate\Container\Container::offsetGet($key) should either be compatible with ArrayAccess::offsetGet(mixed $offset): mixed, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice in /tmp/build_275de9ef/vendor/laravel/framework/src/Illuminate/Container/Container.php:1242
remote:        Deprecation Notice: Return type of Illuminate\Container\Container::offsetSet($key, $value) should either be compatible with ArrayAccess::offsetSet(mixed $offset, mixed $value): void, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice in /tmp/build_275de9ef/vendor/laravel/framework/src/Illuminate/Container/Container.php:1254
remote:        Deprecation Notice: Return type of Illuminate\Container\Container::offsetUnset($key) should either be compatible with ArrayAccess::offsetUnset(mixed $offset): void, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice in /tmp/build_275de9ef/vendor/laravel/framework/src/Illuminate/Container/Container.php:1267
remote:        > @php artisan package:discover --ansi
remote:        PHP Deprecated:  Return type of Illuminate\Container\Container::offsetExists($key) should either be compatible with ArrayAccess::offsetExists(mixed $offset): bool, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice in /tmp/build_275de9ef/vendor/laravel/framework/src/Illuminate/Container/Container.php on line 1231
remote:        PHP Deprecated:  Return type of Illuminate\Container\Container::offsetGet($key) should either be compatible with ArrayAccess::offsetGet(mixed $offset): mixed, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice in /tmp/build_275de9ef/vendor/laravel/framework/src/Illuminate/Container/Container.php on line 1242
remote:        PHP Deprecated:  Return type of Illuminate\Container\Container::offsetSet($key, $value) should either be compatible with ArrayAccess::offsetSet(mixed $offset, mixed $value): void, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice in /tmp/build_275de9ef/vendor/laravel/framework/src/Illuminate/Container/Container.php on line 1254
remote:        PHP Deprecated:  Return type of Illuminate\Container\Container::offsetUnset($key) should either be compatible with ArrayAccess::offsetUnset(mixed $offset): void, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice in /tmp/build_275de9ef/vendor/laravel/framework/src/Illuminate/Container/Container.php on line 1267
remote:        PHP Deprecated:  Return type of Illuminate\Config\Repository::offsetExists($key) should either be compatible with ArrayAccess::offsetExists(mixed $offset): bool, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice in /tmp/build_275de9ef/vendor/laravel/framework/src/Illuminate/Config/Repository.php on line 141
remote:        PHP Deprecated:  Return type of Illuminate\Config\Repository::offsetGet($key) should either be compatible with ArrayAccess::offsetGet(mixed $offset): mixed, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice in /tmp/build_275de9ef/vendor/laravel/framework/src/Illuminate/Config/Repository.php on line 152
remote:        PHP Deprecated:  Return type of Illuminate\Config\Repository::offsetSet($key, $value) should either be compatible with ArrayAccess::offsetSet(mixed $offset, mixed $value): void, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice in /tmp/build_275de9ef/vendor/laravel/framework/src/Illuminate/Config/Repository.php on line 164
remote:        PHP Deprecated:  Return type of Illuminate\Config\Repository::offsetUnset($key) should either be compatible with ArrayAccess::offsetUnset(mixed $offset): void, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice in /tmp/build_275de9ef/vendor/laravel/framework/src/Illuminate/Config/Repository.php on line 175
remote:        PHP Fatal error:  During inheritance of ArrayAccess: Uncaught ErrorException: Return type of Illuminate\Support\Collection::offsetExists($key) should either be compatible with ArrayAccess::offsetExists(mixed $offset): bool, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice in /tmp/build_275de9ef/vendor/laravel/framework/src/Illuminate/Support/Collection.php:1277
remote:        Stack trace:
remote:        #0 /tmp/build_275de9ef/vendor/laravel/framework/src/Illuminate/Support/Collection.php(11): Illuminate\Foundation\Bootstrap\HandleExceptions->handleError()
remote:        #1 /tmp/build_275de9ef/vendor/composer/ClassLoader.php(571): include('...')
remote:        #2 /tmp/build_275de9ef/vendor/composer/ClassLoader.php(428): Composer\Autoload\includeFile()
remote:        #3 /tmp/build_275de9ef/vendor/laravel/framework/src/Illuminate/Support/helpers.php(109): Composer\Autoload\ClassLoader->loadClass()
remote:        #4 /tmp/build_275de9ef/vendor/laravel/framework/src/Illuminate/Foundation/PackageManifest.php(130): collect()
remote:        #5 /tmp/build_275de9ef/vendor/laravel/framework/src/Illuminate/Foundation/PackageManifest.php(106): Illuminate\Foundation\PackageManifest->build()
remote:        #6 /tmp/build_275de9ef/vendor/laravel/framework/src/Illuminate/Foundation/PackageManifest.php(89): Illuminate\Foundation\PackageManifest->getManifest()
remote:        #7 /tmp/build_275de9ef/vendor/laravel/framework/src/Illuminate/Foundation/PackageManifest.php(78): Illuminate\Foundation\PackageManifest->config()
remote:        #8 /tmp/build_275de9ef/vendor/laravel/framework/src/Illuminate/Foundation/Bootstrap/RegisterFacades.php(26): Illuminate\Foundation\PackageManifest->aliases()
remote:        #9 /tmp/build_275de9ef/vendor/laravel/framework/src/Illuminate/Foundation/Application.php(219): Illuminate\Foundation\Bootstrap\RegisterFacades->bootstrap()
remote:        #10 /tmp/build_275de9ef/vendor/laravel/framework/src/Illuminate/Foundation/Console/Kernel.php(320): Illuminate\Foundation\Application->bootstrapWith()
remote:        #11 /tmp/build_275de9ef/vendor/laravel/framework/src/Illuminate/Foundation/Console/Kernel.php(129): Illuminate\Foundation\Console\Kernel->bootstrap()
remote:        #12 /tmp/build_275de9ef/artisan(37): Illuminate\Foundation\Console\Kernel->handle()
remote:        #13 {main} in /tmp/build_275de9ef/vendor/laravel/framework/src/Illuminate/Support/Collection.php on line 11
remote:        Script @php artisan package:discover --ansi handling the post-autoload-dump event returned with error code 255
remote:  !     WARNING: A post-autoload-dump script terminated with an error
remote: 
remote:  !     ERROR: Dependency installation failed!
remote:  !     Push rejected, failed to compile PHP app.
remote: 
remote: !       Push rejected to qutesapp.
 ! [remote rejected]   master -> master (pre-receive hook declined)
error: failed to push some refs to 'https://git.heroku.com/qutesapp.git'

日志显示部署阶段composer依赖安装失败，post-autoload-dump脚本执行异常，大量Illuminate核心类出现ArrayAccess接口返回类型不兼容提示，最终触发PHP致命错误，代码推送被拒绝。

故障原因

PHP版本与Laravel版本不兼容：当前使用的Laravel版本为8.83.0以下，或Laravel 6/7等旧版本，未适配PHP 8.1及以上版本的ArrayAccess接口返回类型规则。Heroku构建时默认拉取最新的PHP 8.1+版本运行composer脚本，旧版Laravel的类方法返回值签名与新版PHP内置接口要求不匹配，直接触发致命错误。本地可正常运行是因为本地PHP版本低于8.1，不存在该兼容问题。

解决方案

二选一即可修复：

方案1：锁定Heroku构建PHP版本，与本地版本对齐
在项目根目录composer.json的config节点下添加platform配置，值填写本地实际运行的PHP版本号，例如本地使用PHP 7.4时配置如下：
```
"config": {
    "platform": {
        "php": "7.4.33"
    }
}
```
原有config下的其他配置项保留即可，配置完成后本地执行composer update --lock更新锁文件，提交composer.json和composer.lock到代码仓库，重新推送至Heroku即可。
方案2：升级Laravel版本适配高版本PHP
将Laravel升级至8.83.0及以上版本，或直接升级到Laravel 9/10长期支持版本，这类版本已原生适配PHP 8.1+的接口返回类型要求，升级完成后提交依赖配置文件和锁文件重新部署即可。

注意：后续开发需要保证本地运行的PHP版本、composer依赖版本与线上构建环境版本一致，避免出现本地正常、线上报错的环境差异问题。

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