安装新模块后，前台和后台同时显示 500，最重要的是先保留第一条异常，而不是连续执行清缓存、编译和重启，把原始错误覆盖掉。下面按“先恢复访问，再修模块”的顺序处理。

先确认 500 来自 PHP 还是 Web Server

curl -sk -D- -o /tmp/magento500.html https://www.example.com/
tail -n 100 var/log/exception.log
tail -n 100 var/log/system.log
tail -n 100 /var/log/nginx/error.log
journalctl -u php-fpm --since '10 minutes ago'

PHP Fatal error、类不存在和构造参数错误通常在 Magento/PHP 日志；Nginx 的 upstream timed out、Primary script unknown 则属于回源或路径问题。记录异常类、文件和部署时间。

模块是否真的被启用

bin/magento module:status Vendor_Module
composer show vendor/module-name
grep -n "Vendor_Module" app/etc/config.php

代码目录存在但 Composer 包未完整安装，或 config.php 已启用模块而 vendor 缺依赖，都会直接 500。不要从另一台服务器随手复制一个 vendor 子目录；应使用同一 composer.lock 重建完整产物。

在维护模式下重新跑安装步骤

bin/magento maintenance:enable
bin/magento setup:upgrade --keep-generated
bin/magento setup:di:compile
bin/magento cache:clean

每条命令单独执行，第一条失败就停止。setup:upgrade 报数据库补丁错误时，不要继续 compile；compile 报 preference、接口或构造参数错误时，回到模块的 di.xml 和 PHP 类型声明处理。

快速判断是不是新模块导致

如果模块没有执行不可逆数据迁移，可在维护窗口禁用它做隔离：

bin/magento module:disable Vendor_Module
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:clean

恢复后说明故障与该模块有关，但这不是最终修复。模块若创建了订单字段、队列表或数据补丁，禁用前应阅读卸载说明并备份数据库，不能直接删除代码。

常见 Fatal error 对应处理

  • Class ... does not exist：检查 Composer autoload、类名大小写和 registration.php；
  • Cannot instantiate interface：检查 area 对应 di.xml 是否缺 preference；
  • Too few arguments：模块版本可能不兼容当前 Magento/PHP；
  • Permission denied：检查 var、generated、pub/static 的运行用户权限；
  • Allowed memory size exhausted：先定位循环依赖或异常集合，不能只无限加内存。

恢复上线前的验证

bin/magento maintenance:disable
curl -fsS https://www.example.com/health_check.php
bin/magento cron:run
bin/magento indexer:status

测试首页、商品页、购物车、结账、后台登录和模块自己的功能。还要确认 Cron 与 Consumer 使用的新 release，否则 Web 恢复了，后台任务仍可能加载旧模块代码。