Laravel部署引入autoload.php报致命错误如何排查解决

问题背景 #

项目入口文件为index.php，部署采用的目录结构如下：

root -> public_html -> laravel [存放除public目录外的所有Laravel项目文件]
                    -> public -> index.php
                              -> 公共静态资源文件

部署时持续触发致命错误，当前index.php中注册自动加载器的代码如下：

/*
|--------------------------------------------------------------------------
| Register The Auto Loader
|--------------------------------------------------------------------------
|
| Composer provides a convenient, automatically generated class loader for
| this application. We just need to utilize it! We'll simply require it
| into the script here so we don't need to manually load our classes.
|
*/

require __DIR__.'/laravel/vendor/autoload.php';

触发的报错信息：

Warning: require(/usr/www/users/pdffoeddae/laravel/vendor/composer/../psy/psysh/src/functions.php): Failed to open stream: No such file or directory in /usr/www/users/pdffoeddae/laravel/vendor/composer/autoload_real.php on line 55 Fatal error: Uncaught Error: Failed opening required '/usr/www/users/pdffoeddae/laravel/vendor/composer/../psy/psysh/src/functions.php' (include_path='.:/usr/share/php') in /usr/www/users/pdffoeddae/laravel/vendor/composer/autoload_real.php on line 55 Stack trace: #0 /usr/www/users/pdffoeddae/laravel/vendor/composer/autoload_real.php(38): composerRequire11021545d8de1bcd9cc99ffff97d671b('801c31d8ed748cf...', '/usr/www/users/...') #1 /usr/www/users/pdffoeddae/laravel/vendor/autoload.php(12): ComposerAutoloaderInit11021545d8de1bcd9cc99ffff97d671b::getLoader() #2 /usr/www/users/pdffoeddae/index.php(37): require('/usr/www/users/...') #3 {main} thrown in /usr/www/users/pdffoeddae/laravel/vendor/composer/autoload_real.php on line 55

故障根因 #

从报错栈可以确认，当前自动加载路径已经能正常读取laravel/vendor目录下的Composer核心文件，报错的核心原因是上传到服务器的vendor目录不完整，psy/psysh（Laravel默认依赖的命令行调试包）的对应文件缺失，导致Composer自动加载流程中断。
另外注意：描述的目录结构中index.php存放在public子目录，但报错栈显示实际运行的index.php位于public_html根目录，二者位置不匹配也会引发路径错误。

修复步骤 #

• 修正入口文件路径配置
  如果你实际把index.php放在public_html/public目录下，原有自动加载路径写法错误，需要修改为：

  require __DIR__.'/../laravel/vendor/autoload.php';
  

  同文件中后续引入Laravel应用实例的代码也要同步修改路径：

  $app = require_once __DIR__.'/../laravel/bootstrap/app.php';
  

  如果index.php实际放在public_html根目录，保持现有自动加载路径即可。
• 补全完整项目依赖
  二选一操作即可：
  • 本地方案：在本地开发环境的项目根目录执行composer install --no-dev --optimize-autoloader，生成生产环境可用的优化后依赖包，将整个vendor目录打包为压缩包上传到服务器，在服务器端解压覆盖原有laravel/vendor目录，避免零散FTP传输导致的文件漏传。
  • 服务器方案：如果主机支持SSH登录，直接进入服务器上的laravel目录执行composer install --no-dev --optimize-autoloader，直接在服务器端拉取所有依赖，完全规避文件传输问题。
• 配置运行权限
  依赖安装完成后，递归设置laravel/storage、laravel/bootstrap/cache目录权限为755，保证Web服务进程对这两个目录有读写权限，避免后续运行出现权限类报错。

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