PHP 报错信息像摩斯电码？我整理了份「异常翻译手册」和条件反射排查法

昨晚帮朋友看一个 Laravel 项目，页面就一行白底黑字：Undefined variable: config。他盯着看了十分钟，跟我说"这变量我明明定义了啊"。结果我让他往上滚三行——use Config; 写成了小写，IDE 都没标红，因为那是他自己起的别名。

这事让我想，咱们天天跟 Exception 打交道，其实可以训练一套肌肉记忆。不是背文档，是看到报错前缀就能条件反射地往哪捅。

一、Class 'XXX' not found：别急着 composer dump，先看三个地方

这报错最贼的地方在于，它不一定真是类不存在。

上周我踩的坑：文件名叫 UserService.php，里面写的 class UserServices，多打了个 s。autoload 映射能找到文件，但类名对不上，照样抛这个错。还有 namespace 前面漏了反斜杠、use 语句写在了命名空间上面、或者 PSR-4 路径里某个文件夹首字母大写被 git 忽略大小写了——Windows 开发上传到 Linux，这种破事我遇过两回。

现在我的排查顺序：① 类名和文件名逐字符比对 ② composer dump-autoload -o ③ 看 git 是不是把大小写变更吞了。

二、SQLSTATE[HY000] [2002]：MySQL 连接失败的"替身文学"

这个错误代码像俄罗斯套娃。2002 后面跟 Connection refused 是端口或进程问题；跟 No such file or directory 是 socket 路径对不上——宝塔和 Homestead 的 socket 位置经常打架。

最阴的一次：.env 里 DB_HOST=127.0.0.1，但 MySQL 只绑了 localhost 的 socket，没开 TCP。改成 DB_HOST=localhost 或者显式指定 socket 路径才通。现在我看到 2002 先 netstat -tlnp | grep 3306，确认是走网卡还是走文件。

三、Trying to access array offset on value of type null：PHP 7.4 送的"惊喜"

以前返回 null 还能假装数组用，7.4 开始直接炸。这报错通常出现在链式调用里：$user->profile->avatar，中间某个环节查出来是 null。

我现在的习惯是，任何从数据库或接口来的数据，先 $data['key'] ?? null 或者 $user?->profile?->avatar（PHP 8）。但老项目升级时，这种报错能刷满一屏，我的做法是临时在公共方法里包一层安全取值，再逐个替换。

四、Maximum execution time exceeded：别只改 max_execution_time

新手看到这就去 php.ini 改时间，结果 30 秒改 300 秒，服务器卡死。我排查会先看是 CPU 跑满还是 IO 阻塞：top 看负载，然后 show processlist 抓慢 SQL。

上个月有个导出功能超时，最后发现是嵌套循环里每次都 new Model() 查关联，N+1 到天上去了。改成 with 预加载，30 秒变 2 秒。超时只是症状，病灶在别处。

五、TokenMismatchException 和 419 Page Expired：缓存和时钟的合谋

Laravel 的 CSRF token 存在 session 里，session 存在 Redis/文件/Memcached 里。如果 session 驱动配的是 Redis，但缓存前缀和另一个项目撞了，或者服务器时间差了五分钟（token 有过期时间），就会莫名其妙 419。

我现在的 checklist：① date 看系统时间 ② php artisan cache:clear 只是清缓存，session 要单独清 ③ 多项目共用 Redis 时前缀必须隔离。

最后说个邪门的

有次生产环境报 Allowed memory size exhausted，128M 改 512M 还炸。最后发现是日志文件被删了但进程没释放句柄，磁盘没满但 inode 满了，PHP 写不了日志就疯狂重试，内存蹭蹭涨。lsof | grep deleted 看到这个的时候，我沉默了很久。

你们有没有遇到过"报错信息完全误导方向"的情况？说出来让我平衡一下。