子主题开发手记：看板娘、换肤与 Pio 智能大脑

摘要

WordPress 博客（Sakurairo 主题）的颜值担当：Live2D 看板娘 Pio、深浅色切换、18 套换装、智能大脑（访客记忆、阅读进度陪伴、戳一戳有反应）。这些全是子主题（sakurairo-child）里实现的。这篇记录子主题的开发手记：目录结构、看板娘的选型与自托管、换肤按钮的移除与重做、换装系统的实现、智能大脑的交互设计。核心原则：父主题一个字不改，所有定制进子主题，升级无忧。

目录

• 一、子主题的目录结构
• 二、铁律：父主题一个字不改
• 三、看板娘 Pio：选型与自托管
• 四、换肤：移除旧按钮，重做深浅切换
• 五、换装系统：18 套服装
• 六、Pio 智能大脑：交互设计
• 七、手机端：迷你 Pio
• 八、部署与缓存：OPcache 是第一嫌疑人
• 九、总结

一、子主题的目录结构

sakurairo-child/
├── style.css          # 子主题声明（Template: sakurairo）
├── functions.php      # 入口：加载父主题 + 自己的资源
├── custom.css         # 全部自定义样式（按节编号，如 21 节、22.4 节）
├── custom.js          # 全部自定义脚本
├── live2d/            # 看板娘：JS/CSS/模型全自托管
│   ├── waifu-tips.json    # 模型路径 + 文案
│   ├── waifu-brain.js     # 智能大脑
│   └── autoload.js        # 按序加载
└── Pio 模型/          # 18 套服装的纹理与 index-*.json

custom.css 按"节"编号管理（第 21 节、第 22.4 节……），改样式时先找节号，不迷路。看板娘的全部资源放 live2d/ 目录，JS/CSS/模型全自托管，不依赖任何外部 CDN——外部依赖清零，和速度优化那篇的思路一致。

二、铁律：父主题一个字不改

WordPress 主题升级会覆盖父主题的全部文件，直接改父主题等于每次升级重做一遍。所以铁律：父主题一个字不改，所有定制进子主题。

子主题的机制：style.css 头声明 Template: sakurairo，WordPress 就知道它是 Sakurairo 的子主题；functions.php 里先加载父主题的样式和脚本，再加载自己的 custom.css/custom.js（优先级更高，覆盖父主题）。要改的功能，在子主题里用"覆盖模板文件"或"hook"实现。

这次的速度优化里，父主题 theme-plus.php 的改动教训已经吃过一次：直接改父主题，升级就没。现在所有定制都在 sakurairo-child 里，父主题随便升。

三、看板娘 Pio：选型与自托管

看板娘选了 stevenjoezhang/live2d-widget（约 1.1 万 star），眼睛跟随鼠标、可拖动、可换装、有聊天气泡。模型用 Pio（粉色魔女），120 个文件全自托管。

选型的考虑：star 数代表维护活跃度，自托管代表不依赖外部（速度优化的要求）。中文互动文案重写了一遍，原版的文案是英文/机翻腔，配不上"折腾 · 记录 · 分享"的气质。

浏览器实机验收：左下角正常渲染、中文气泡、一言/换装/拍照/关闭都可用。验收标准还是"看真实效果"，截图确认。

四、换肤：移除旧按钮，重做深浅切换

Sakurairo 原来自带一个右下角的 changskin 控制面板，功能杂、样式旧。处理：custom.js 运行时删除 + CSS 隐藏，双保险。然后在右上角导航栏新增太阳/月亮切换按钮：

• 点一下切换 body.dark 类，深浅色即时切换；
• localStorage 持久化，下次打开记住选择；
• Hero 标语卡片做了深浅两套配色（亮色深梅子字 + 粉边柔光，暗色夜樱深紫玻璃卡 + 月白字），之前粉底白字看不清的 bug 在这次重做里修了。

深浅切换的验收：浏览器实机点两下，浅/暗两套都截图确认。localStorage 持久化要清缓存测一遍，确保记住选择。

五、换装系统：18 套服装

Pio 的 87 张纹理里精选了 18 套服装（樱花和服、女仆装、粉色旗袍、振袖和服、圣诞装、奶油蛋糕、小动物装等），每套独立 index-*.json，waifu-tips.json 的 models.paths 接入 18 个 URL，换装按钮循环切换。

换装有个"魔法特效"：waifu-brain.js 里的 costumeMagic()，缩放旋转 + 16 粒星光粒子 + 气泡报服装名。waifu.css 给 Pio 加了立体投影（drop-shadow）。桌面端实测 5 套外观切换正常。

换装系统的本质是"换纹理包"：模型骨骼不变，只换贴图。所以 18 套的增量成本很小，主要是纹理文件的体积。单套服装加载约 812KB，手机端也扛得住。

六、Pio 智能大脑：交互设计

waifu-brain.js 是看板娘的"大脑"，让 Pio 从"摆件"变成"有反应的伙伴"。交互设计按"场景"划分：

气泡样式也重做了：樱粉渐变 + 小尾巴 + 弹跳动画，深色模式自动切紫。waifu-tips.json 的选择器与文案同步丰富化。

设计的原则：有趣，但不扰民。气泡有展示间隔，连续触发会排队，不会满屏刷。看板娘是点缀，不是弹窗广告。

七、手机端：迷你 Pio

手机端原来是直接 display:none 藏掉看板娘，现在改成迷你版：Pio 缩到 160px Q 版，气泡 185px 适配，工具栏缩小。单套服装 812KB，手机加载无压力。

移动端适配的思路：不是"藏起来"，是"变小"。看板娘是博客的标识，手机上也应该在，只是别挡内容。待用户真机验证。

八、部署与缓存：OPcache 是第一嫌疑人

子主题部署后，页面还是旧的，排查顺序：

1. systemctl reload php-fpm-82 清 OPcache（第一嫌疑人）；
2. 清页面缓存（wp-content/cache/all/）；
3. 浏览器硬刷新（Ctrl+Shift+R）。

这次开发里，OPcache 坑踩了不止一次：custom.css 改了没效果、custom.js 新功能不出，第一反应都应该是 reload php-fpm。记住这个顺序，能省一半排查时间。

组件库：auto-toc、时间线与 callout

博客后来还上了一套文章组件库，随文章部署进子主题，写技术文章时直接用：

这 20 篇技术文章用的就是这套组件：目录是 auto-toc 的思路（手写锚点版），踩坑用 callout，命令用 cmd-table。组件库的价值：写文章时不用重复造轮子，读者看着也统一。

开发工作流：改→传→清缓存→验收

子主题的开流程固定四步：

1. 改：本地改 custom.css/custom.js，按节编号找位置；
2. 传：传到服务器的子主题目录（经 SSH/rsync）；
3. 清缓存：systemctl reload php-fpm-82 清 OPcache，再清页面缓存；
4. 验收：浏览器实机看效果，桌面端 + 手机端都点一点。

第四步别省：CSS 改完只在桌面端看，手机端可能崩版。看板娘、换肤、换装，每个功能上线都是这么验过来的。工作流固定了，改东西才不慌。

主题定制的审美：克制

子主题能改的东西太多，多到容易"过度定制"。看板娘、换肤、换装、智能大脑、组件库……每个都好玩，加起来可能就是灾难。主题定制的审美，核心是克制。

克制一：功能克制。 每个新功能上线前，问三个问题：有人用吗？不用会怎样？维护成本多高？看板娘有人看（门面），换肤有人点（深浅偏好），换装有人玩（好玩），智能大脑有人互动（有趣）。四个都通过了，才上的。如果只是"我觉得酷"，不上。博客是给人看的，不是给自己炫技的。

克制二：视觉克制。 樱粉是主色，但不是所有东西都刷成粉色。主色、辅色、点缀色，三色原则。看板娘是粉的，代码高亮就别也是粉的；按钮是粉的，警告框就用橙的。色彩有分工，页面才有层次。Sakurairo 本身的设计语言是"淡雅"，定制要顺着它的气质走，别把它改成夜店风。

克制三：性能克制。 每个 JS、每张图，都是加载时间。看板娘 120 个文件自托管，单套服装 812KB，这是算过的：812KB 换"门面"，值。智能大脑的交互，事件监听是节流的，不是一股脑全加上。性能预算是定制的紧箍咒：加功能前，先看加多少体积，超预算就优化或放弃。速度优化那篇的成果，不能被定制吃回去。

克制的反面不是"不做"，是"做少而精"。这套博客的定制，每一个拿出来都能讲 10 分钟，但合在一起不乱、不卡、不丑，就是克制的功劳。定制如做菜，调料是提味的，不是当饭吃的。

从使用者到开发者：主题定制的学习路径

这套子主题的定制，是从"改颜色"开始，一路做到"智能大脑"的。学习路径复盘一下，给想入坑的人参考。

第一阶段：改样式（1-2 周）。 custom.css 里改颜色、字体、间距。工具：浏览器开发者工具，点到哪改到哪。这是"所见即所得"的阶段，成就感最高，适合建立信心。Sakurairo 的文档和社区，能解决 80% 的样式问题。

第二阶段：加功能（1 个月）。 custom.js 里加小功能：回到顶部、代码复制、深浅切换。工具：jQuery（主题自带）、原生 JS。这是"从样式到逻辑"的跨越，开始理解"主题是怎么工作的"。看板娘的接入，就是这个阶段的项目：照着文档，把 live2d-widget 接进来，再改中文文案。

第三阶段：做系统（持续）。 换装系统、智能大脑、组件库，是"系统级"的定制：多个文件配合，有数据（JSON）、有逻辑（JS）、有样式（CSS）。这个阶段，开始写"自己的代码"，而不是"改别人的代码"。标志是：你有了自己的文件结构（live2d/ 目录），自己的命名规范，自己的更新节奏。

贯穿始终的：版本控制（改之前备份，custom.css 按节编号）、实机验收（改完浏览器看，手机也看）、文档（改了什么，记一笔）。三个习惯，比技术本身更重要。技术会过时，习惯不会。

从使用者到开发者，没有分水岭，只有"改得越来越多"。改第一行 CSS 时，你就是开发者了。

子主题的更新：父主题升级后检查什么

Sakurairo 父主题升级，子主题一般不用动，但要检查三件事：一是父主题有没有改模板结构（子主题覆盖的模板文件，对照一下）；二是父主题的 CSS 类名变没变（custom.css 里引用的类，抽查几个）；三是前台点一遍（首页、文章页、看板娘、换肤）。三项过，升级闭环。子主题的价值就在这里：父主题随便升，定制都在，检查 10 分钟，安心。

九、总结

子主题开发的三条经验：父主题一个字不改（升级无忧）、资源全自托管（不依赖外部）、部署后先查 OPcache（第一嫌疑人）。看板娘 Pio 从"能看"做到"好玩"：选型（1.1 万 star 的 live2d-widget）→ 自托管 → 换肤重做 → 18 套换装 → 智能大脑 → 手机端迷你版，每一步都经浏览器实机验收。博客的颜值是生产力，看板娘是门面，门面值得用心。

相关阅读：《WordPress 极致速度优化全记录》。