我要改首页那句签名。
第一反应是去模板里找,改掉那句日文示例。手已经放上去了,又收回来——这个主题 888 个文件、21 MB,下次升级会整体替换,改了等于没改。
于是走"正规"路径:不进主题目录,所有改动都落在数据库。选项、额外 CSS、菜单,全部如此。改完数了一下,光主题选项这一个 option,就有 307 个键。
当时以为事情到这里就结束了。后来发现,"不会被升级覆盖"和"改得对"是两个完全不同的命题,而我当时只解决了前者。
一、先画一张图
把这次动到的东西按"活多久"排一下,是四层,不是两层:
| 层 | 存在哪 | 升级后 | 能改什么 |
|---|---|---|---|
| 主题目录文件 | 文件系统 | 整体覆盖 | 任何东西,但一次性的 |
| 子主题 | 独立目录 | 保留 | 理论上只覆盖模板与样式 |
| 数据库选项 | wp_options 单行 | 保留 | 值、开关、文案 |
| 额外 CSS | wp_posts 一条 | 保留 | 选择器与样式 |
层数越往下越安全,但能碰的东西越少。真正的麻烦都发生在"以为自己在第三层、其实需要第一层能力"的时候。
二、第一层:改主题文件,一定会丢
这一层没什么可争的。888 个文件、21 MB,升级就是整个目录替换,你改的每一行都会消失。
但它值得单独说一句,因为主题源码里确实存在"只对上游开发者有意义"的东西。比如高亮模块里有这么一行:
$theme_color = ($image_url) ? get_image_theme_color($image_url) : 'false';
error_log('计算结果为' . $theme_color);
update_post_meta($post_id, 'post_theme_color_meta', [
'theme_color' => $theme_color,
]);
从上下文看,这是取封面图主色、写进文章 meta 的钩子。中间那句 error_log 是开发期的调试输出,忘了删,一直留到了正式版。
它不致命:error_log 在 FPM 下写进日志文件,访客看不到。但它有一个我没想到的副作用——在命令行下跑脚本时,PHP 的 error_log 默认走 stderr,而我把 stderr 也并进了输出,于是每次执行都能看到一句"计算结果为false"夹在中间。
这句 false 本身也值得看一眼。三元表达式的另一支是字符串 'false',不是布尔值,所以取不到封面图时,写进 meta 的是一个非空字符串。下游如果用 if ($color) 判断,这个字符串永远为真。
这类东西你改不改?
改,就是动主题文件,下次升级丢失。不改,就得永远在日志里过滤它。没有第三个选项——子主题解决不了,下一节会说为什么。
三、第二层:子主题,这个主题上不成立
WordPress 的通行建议是"要改主题就建子主题"。这条建议在多数主题上成立,在这个主题上不成立,而且不成立的方式很干净,可以用两个数字说明:
grep -rn "require|include" --include=*.php . | grep -c "get_template_directory"
# 21
grep -rn "require|include" --include=*.php . | grep -c "get_stylesheet_directory"
# 0
21 处 require 全部用 get_template_directory(),指向父主题目录;用 get_stylesheet_directory() 的,0 处。
这两者的区别是:get_stylesheet_directory() 在有子主题时返回子主题目录,是子主题唯一能"接管"文件的路径。主题作者用它,意味着把这些文件开放给子主题替换;用 get_template_directory(),意味着写死指向自己。
而 WordPress 的模板层级——single.php、header.php、footer.php 这些——是核心在找文件,会先查子主题。所以子主题确实能覆盖模板。
但 functions.php 里这一行不会被子主题影响:
require get_template_directory() . '/opt/option-framework.php';
以及紧随其后的:
$GLOBALS['iro_options'] = get_option('iro_options');
子主题自己的 functions.php 是先于父主题加载的,加载完之后父主题的 functions.php 照样执行,照样用绝对路径 require 它自己的文件。没有过滤器、没有 hook、没有接管点。
结论是:子主题在这个主题上能改的是外观和模板,改不了任何 PHP 逻辑。想改选项的读写行为、想删那句 error_log、想调整某个 require 的条件——都只能动主题目录。
四、第三层:数据库选项,不丢,但代价换了地方
这一层是"正确答案"所在。主题选项存在 wp_options 表的一个键里,升级主题不碰数据库,改动一定保留。
代价不在"会不会丢",而在它怎么存、怎么读。
4.1 307 个键是同一行
先看它有多大:
iro_options 键数:307
序列化后:18,398 字节
autoload:off
307 个配置项,序列化成一串 18 KB 的文本,躺在 wp_options 的一行里。
这意味着不存在"只改一个字段"的操作。主题自己的更新函数长这样:
function iro_opt_update($option = '', $value = null)
{
$options = get_option('iro_options');
if ($options) {
$options[$option] = $value;
} else {
$options = array($option => $value);
}
update_option('iro_options', $options);
}
取出全部 307 项、改其中一个、把 307 项整体写回。Customizer 保存走的是另一条路径,但结局一样:
$theme_mod_options = array_merge($iro_options, $theme_mod_options);
update_option('iro_options', $theme_mod_options);
也是全量替换。
所以每一次"保存设置",都是一次对 307 个键的整体覆盖。两个标签页同时打开设置页、各自保存,后写的那个会带走先写的全部改动——不是覆盖某一个字段,是整个配置。
autoload 是 off,说明作者知道这串东西大,不想让每个请求都预加载。但紧接着 functions.php 第 29 行又无条件地读了一次,塞进全局变量。等于绕过了自己设的开关。
4.2 在同一个请求里,你改完读不到
这是我这次踩到的最实在的一个坑。
主题把选项读进一个 PHP 全局变量,只在文件加载时读一次:
$GLOBALS['iro_options'] = get_option('iro_options');
function iro_opt($option = '', $default = null)
{
return $GLOBALS['iro_options'][$option] ?? $default;
}
之后所有对 iro_opt() 的调用,都从这个全局变量取值,不再碰数据库。
我一开始以为这是 WordPress 的对象缓存问题,所以写了个探针,改完值先 wp_cache_flush() 再读。结果:
【1】iro_opt 读到的值:愿你保持不变 保持己见 充满热血
【2】get_option 直读:愿你保持不变 保持己见 充满热血
【3】update_option 之后,get_option 直读:__PROBE_TMP__
【4】update_option 之后,iro_opt 读到:愿你保持不变 保持己见 充满热血
【5】已还原:愿你保持不变 保持己见 充满热血
第 3 行是新的,第 4 行还是旧的。清了对象缓存也没用——因为拦住它的不是对象缓存,是一个普通的 PHP 全局变量,作用域就是这一次请求。
实际后果:任何"改完选项立刻渲染"的脚本,看到的都是旧配置。想验证改动是否生效,必须另起一个请求。
我这次没有栽在它上面,纯粹是操作习惯恰好避开了:脚本只负责写,写完退出,另一次调用再去读,天然是两个进程。但如果哪天想写一个"改完配置立刻预览效果"的工具,第一版一定会在这里返工——而且会以为是写入失败。
4.3 预览模式是另一条读取路径
同一个 iro_opt(),在 Customizer 预览状态下走的是另一个分支:
if (is_customize_preview()) {
$theme_mod = get_theme_mod('iro_options', []);
if (isset($theme_mod[$option])) {
return $theme_mod[$option];
} else {
return $GLOBALS['iro_options'][$option] ?? $default;
}
}
预览时优先查 theme_mod,非预览时只查全局变量。两条路径,两套数据源,两套兜底顺序。
这不是缺陷,是 Customizer 预览机制的必然代价——预览要能显示"还没保存的值"。但它带来一个使用上的不确定性:你在 Customizer 里看到的效果,和保存之后前台的样貌,走的不是同一份数据。调试时如果两边表现不一致,第一件该确认的事是"我看的是哪个分支"。
五、第四层:主题不给你改的地方
到这里,"改在数据库里"的解法已经用尽了。但还有一类问题,四层都覆盖不到——主题的排版假设。
这次遇到的是文章目录(TOC)的宽度。原样是这样的:
.toc-container {
width: 190px;
right: -15vw;
top: 240px;
position: absolute;
}
.toc {
width: fit-content;
position: sticky;
top: 12%;
max-height: 80vh;
overflow-y: auto;
}
容器 190px、绝对定位、向右偏移 15% 视口宽度;里面的目录块用 fit-content 决定宽度。
fit-content 对英文是合理的。英文按单词断行,内容自然撑开到一个合适的宽度。但对中文,每一个汉字都是合法的断行点,浏览器把宽度收缩到"最小可用宽度"时,会一路缩到底——结果是目录里每个条目被压成每行三四个字。
这个主题有 languages/ 目录,也有 Text Domain 声明,界面文案走多语言。但排版层没有针对中文做任何适配。这是一个系统性的偏差:它支持你的语言,但不支持你的字形。
修它只能加额外 CSS。而这件事我调了三次:
| 尝试 | 结果 |
|---|---|
.toc { width: 100% } | 无效。100% 是相对容器算的,而容器整体被 right:-15vw 右移,面板有一截落在视口之外。加宽加在了被裁掉的那一侧,看起来没变化 |
.toc 与容器都给 220px,右偏移改 -8vw | 面板完整了,宽度也够,但左缘压到正文 |
两者给 210px,右偏移 -16vw | 通过。1440 / 1280 / 1920 三个视口分别截图确认,均不与正文重叠、也不被右边缘裁切;其中 1280 时余量最小 |
值得说的是第一次失败。我以为改宽度就够了,实际不行——宽度是相对的,而决定你看见多少的是父元素的定位偏移。改的是子元素,掌控可见性的是父元素。
这就是这一层的代价:不是在配置,是在逆向主题的布局假设。它没有给你一个 .toc 该多宽的选项,因为它默认你不需要——默认你写的是英文。
我回头核了一遍,307 个键里带 css 字样的,0 个。主题根本没打算让你写 CSS,所以只能借 WordPress 自己的口子:Customizer 的额外 CSS。
而这个口子存的位置,跟主题选项完全不同:
post_type = custom_css
post_name = sakurairo ← 主题目录名的小写形式
post_status = publish
post_content 长度 = 526 字节
它是一条普通的 wp_posts 记录,post_name 就是当前主题的目录名小写。
这带来一个容易被忽略的边界:额外 CSS 活得过升级,活不过换主题。换主题之后,wp_get_custom_css() 会去找新主题名对应的那条记录,找不到就新建一条空的——你原来那 526 字节还躺在表里,但不会再被加载,也不会有人提示你。
两个存储位置,两种存活条件:
| 存哪 | 活过升级 | 活过换主题 | |
|---|---|---|---|
| 主题选项 | wp_options 一行 | 是 | 视情况(换了主题,这些键没人读了) |
| 额外 CSS | wp_posts 一条 | 是 | 否,与主题名绑定 |
所以"全都放数据库就安全了"这句话,还得再补一个限定:数据库活得比主题长,但数据库里的东西不一定。
六、如果一定要动这 307 个键
全量写入意味着改坏就是全丢,而这个主题没有导出/导入功能——我搜过 export_settings、import_settings 一类关键字,0 命中。所以操作顺序比操作内容重要。
三条,都是这次实际用上的:
改前先 dump。
file_put_contents(
$backup,
json_encode(get_option('iro_options'), JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT)
);
18 KB 的 JSON,出问题能整体还原。省掉这一步,等于在一个没有撤销键的编辑器里同时编辑 307 个字段。
写入必须是"读—改—写",不能"改—写"。
因为 update_option 不合并。这一句:
update_option('iro_options', ['signature_text' => 'xxx']);
不会更新签名、保留其余 306 项,而是把整个 option 换成一个只有一项的数组。307 项变 1 项,而且不会有任何报错。
验证必须另起一个进程。
因为 $GLOBALS 的存在,同一个进程里看不到自己刚写进去的值——上一节的探针已经证明了这点。脚本负责写,另一次调用负责读,中间不做任何"应该已经生效了"的假设。
改完我核对的是键数:
改前 307,改后 307
数目对得上,才说明"读—改—写"这条链没断。这是唯一能立刻拿到、成本又足够低的完整性信号。
七、还有一类:没被测试过的组合
主题的 header 里写着:
Version: 3.0.10
Tested up to: 6.8
站点跑的是 WordPress 7.1.4。
中间隔着 7.0 和 7.1 两代。这不代表一定有问题,但它意味着这个组合从未被作者验证过。当某个功能表现异常时,你会多一层排查负担:是配置错了,还是版本不匹配,还是主题的假设在这套环境里不成立。
这类风险是慢性的,平时不显形,出问题时不给你任何提示。
八、所以该怎么判断
把这次的经历收成三条,判断依据是"这处改动在下一个版本里还成立吗"。
改的是值——颜色、文案、开关、开关组合。放数据库,升级安全。这是主题选项该干的事,307 个键的价值就在这里。
改的是布局或尺寸——宽度、间距、偏移、响应式断点。用额外 CSS,但要预期它会在下次升级时失效。因为你依赖的不是选择器名字,是主题的整套定位模型(容器宽度、偏移单位、定位方式)。模型一变,覆盖就错位。
改的是逻辑——PHP 行为、加载顺序、某个函数怎么算。只能在没别的办法时动主题文件,而且动手前记下来改了哪个文件的第几行,升级前 diff 一遍。没有子主题兜底,这是这个主题的现状。
还有一个更前置的问题,比上面三条都重要:
这处改动,主题作者是不是本来就不打算让你改?
想改中文排版宽度,本质是想要一个主题没提供的选项。这类需求不会因为你换了存储位置就变得安全——它一直站在"你在跟主题对抗"这一侧。区别只是对抗的代价是"下次被覆盖"还是"下次重调一遍"。
我最后留在数据库里的,是一份 18 KB 的序列化数组、一段额外 CSS、一个菜单结构。它们确实扛住了下一次升级。但真正让这个站点看起来像自己的,是那三次调整目录宽度里学到的、关于这套布局怎么运转的东西——那个东西不在数据库里,在脑子里。
而它也有个好处:主题换掉,它还在。
Comments NOTHING