PHP框架项目上线报错主因是部署环节环境不一致、依赖未装全或配置未生效；须依次验证PHP版本与扩展（php -v、php -m）、Composer autoload映射（dump-autoload -o）、.env配置与密钥生成及缓存刷新、SQL与模板路径日志、目录权限及全量错误报告启用。
PHP框架项目一上线就报错，不是代码写错了，而是部署环节漏掉了关键前提——环境不一致、依赖没装全、配置没生效，三者任缺其一就会让整个应用卡在启动前。
确认PHP版本与扩展是否匹配
先运行php -v和php -m | grep -E "(pdo|mysqli|openssl|mbstring)"，看实际运行的PHP版本和核心扩展是否加载成功。
如果日志里出现PHP Warning: PHP Startup: Unable to load dynamic library 'redis.so'，说明扩展ABI与当前PHP不兼容——【不能直接复用旧服务器上的.so文件】，必须用对应PHP版本重新编译或通过pecl安装。
使用Docker时，FROM镜像必须明确指定小版本号，例如php:8.2-apache比php:8-apache更可靠，后者可能随时间自动升级到8.3，导致扩展失效。
立即学习“PHP免费学习笔记（深入）”；
强制刷新Composer自动加载映射
修改了命名空间或类路径后，ThinkPHP/Laravel仍报Class not found，不是文件丢了，是PSR-4映射缓存没更新。
方法一：运行composer dump-autoload -o生成优化后的类映射表，这一步必须执行，仅清缓存或重启服务无效。
方法二：若报Class not found且确认路径/命名空间/大小写全部正确，检查composer.json中"autoload": {"psr-4": {"app\": "app/"}}末尾反斜杠是否为双反斜杠，Windows下少一个会导致Linux部署失败。
注意：Linux区分Index.php和index.php，开发机改名后未提交，上线就会触发autoload失败。
验证.env配置与密钥是否生效
第一步：确认.env文件存在且权限为600，不能是.env.example重命名后残留BOM头或换行符异常。
第二步：运行php artisan key:generate（Laravel）或php think optimize:config（ThinkPHP），确保APP_KEY写入.env并被框架读取。
第三步：执行php artisan config:cache或php think clear，否则框架仍读取旧配置缓存——【未执行此步，.env修改等于没改】。
第四步：用php -r "echo getenv('APP_KEY');"验证环境变量是否真实加载，避免Web服务器未继承shell环境变量。
查看真实SQL与模板路径定位问题
Db::table()->find()返回null但数据存在？开启log.sql = true（ThinkPHP）或DB_LOG=true（Laravel），直接看日志里执行的WHERE条件，90%是主键字段名不匹配。
$this->fetch('index')报模板不存在？日志里搜Template not exists:，它会打印出ThinkPHP真正尝试加载的绝对路径，比如/var/www/html/app/view/index/index.html——你放错目录层级或后缀名不匹配（如文件是index.php却没配view_suffix）都会静默失败。
public/目录权限必须755，storage/和runtime/必须775，否则日志写不进、缓存生成失败，错误堆栈反而被屏蔽。
一键启用全量错误报告
在入口文件public/index.php顶部插入：
ini_set('display_errors', 1);
ini_set('display_startup_errors', 1);
error_reporting(E_ALL);
生产环境切勿长期保留，但首次部署调试阶段必须加——【不打开这个，90%的致命错误会被静默吞掉】。
同时检查php.ini中log_errors = On和error_log = /var/log/php-error.log是否生效，确保错误不只显示在页面上。
