Typecho 的主题为什么装上去就白屏

给博客换了个主题，装完一刷新——白屏。改回来，又白屏。最后发现是三个互相独立的问题叠在一起，每一个单拎出来都是 Typecho 主题安装的常见坑。

坑一：GitHub 上的 master 是半成品

从仓库下载的 zip，解开后 css/ 目录里只有 mix.css，但页面引用的是 mix.min.css——构建产物没进仓库。

很多主题仓库只放源码，压缩合并后的 CSS/JS 要靠构建工具生成，或者发布在 npm、Releases 里。直接 clone master 装上，页面就是裸 HTML 无样式，运气差点直接 PHP 报错。

对策：看 README 有没有写安装方式。写"下载 Releases"就去 Releases 下载；只写了 clone，就检查有没有对应的 npm 包或构建说明。我这个主题最后是源码包 + npm 构建产物合并才凑齐的。

坑二：主题配置的存储格式

样式文件补齐了，页面还是乱的。查下来是配置问题：主题的 CDN 选项读不到值，拼出来的资源路径少了目录前缀，全部 404。

根因是 Typecho 存主题配置的方式：一行 JSON 存在 theme:主题名 这个键里，不是逐项存。主题第一次启用时这行还不存在，代码里又没写默认值兜底，于是配置为空 → 路径拼错 → 全站样式丢失。

对策：换主题后第一件事不是看效果，是进「设置外观」把每个选项过一遍、点一次保存。保存动作会把完整配置写进数据库，大部分"装上就坏"的问题在这一步就消了。

坑三：1.3 的兼容断层

Typecho 1.3 把内部类从 Typecho_xxx 改成了命名空间写法 \Typecho\xxx。部分旧类保留了别名兼容，但不是全部。

具体到这个站：主题的表单类有兼容层，没事；但有个插件实现的接口 Typecho_Plugin_Interface 没有别名，加载直接报"接口不存在"，整个插件失效。

对策：装老主题老插件前，搜一下代码里的 Typecho_ 开头类名，对照 1.3 的源码确认有兼容别名。这个检查两分钟，能省掉两小时的白屏排查。

通用检查清单

主题装上之后按这个顺序过一遍：

1. 后台能打开吗？          → 不能：PHP 致命错误，看日志
2. 前台有样式吗？          → 没有：构建产物缺失或路径错
3. 设置页能保存吗？        → 保存后配置才完整写入
4. 404 页正常吗？          → 主题的冷门页面常藏着兼容问题
5. 各类型页面都点开看看    → 首页/列表/文章/独立页/404

第四步是我这次差点漏的：正常页面都好好的，唯独 404 页会触发一条 PHP 报错——主题里一行无条件调用的代码，在没有"当前文章"的页面上拿不到数据。平时根本访问不到，只有真的 404 时才炸。

一句话总结

Typecho 主题安装不是"传上去、点启用"两步，而是传文件、补构建、存配置、查兼容、验页面五步。每一步炸的方式都不一样，但日志里都有答案。