现象
把博客从 TypeCho 1.1 升级到 1.2 之后,前台文章照常打开,只要访问 /admin 登录页或点进后台首页,浏览器立刻返回 HTTP 500,页面全白。PHP 错误日志里写着 Call to undefined function add_filter(),也有的站点报 Class Typecho\Db not found。
原因
常见原因有四个。升级包只覆盖了一部分目录,usr/plugins 与 usr/themes 还是 1.1 的旧文件,旧插件调用了 1.2 已改名或移入命名空间的函数;运行环境仍是 PHP 7.2,而 1.2 要求 7.4 以上;config.inc.php 没跟着升级;opcache 缓存着旧字节码,文件换了也不生效。
解决步骤
第一步,先确认报错的文件和行号。打开 PHP 错误日志,用 grep 定位调用位置,顺便确认命令行与 FPM 用的是同一个 PHP 版本。
tail -n 60 /www/wwwlogs/php_error.log
grep -rn "add_filter" /www/wwwroot/blog/usr/plugins
php -v && php-fpm -v
第二步,强制停用全部插件再进后台。把 usr/plugins 临时改名,或者在 config.inc.php 里把 plugins 一项置空。如果能进后台,说明是插件不兼容,再把目录改回逐个放行,找到报错的那个换成 1.2 对应版本。
第三步,补齐文件并刷新缓存。用官方完整包覆盖全部文件,只保留 usr/uploads 与 config.inc.php,清空缓存并重启 PHP-FPM。若仍报类找不到,检查主题目录是否残留旧文件。
验证
再次打开后台,登录页正常渲染,能进设置页并保存成功,error_log 里不再出现 Fatal error 与 500 记录。
小结
升级白屏多半不是程序本身的问题,而是旧插件与旧缓存混在里面。先看日志锁定文件和行号,再停插件、补文件、清缓存,比直接回滚整站更省时间。
