rzx.me 主题架构评估与 Fork 迁移实录

日期：2026-10-11

操作：arkclaw 云端（pro-ba4023）

站点：rzx.me（阿里云 39.97.241.49，SSH 端口 22333）

一、背景与问题

rzx.me 当前使用 WordPress 官方 Twenty Twenty-Five 主题。用户基于该主题做了大量自定义：添加页面、添加大量 CSS。用户纠结是否要把主题独立出来，做一套自有命名与 CSS 体系，还是继续沿用”官方主题 + 标准修改 + 额外 CSS”的形式。

二、实地分析结论

2.1 现状三层结构

主题层（文件）：twentytwentyfive 官方原版，零改动

• style.css / theme.json / functions.php 时间戳全为安装时 2026-05-22 00:54，md5 与官方一致
• 无 git、无子主题、无任何文件级修改

全局样式层（数据库）：真正的”大量 CSS”所在

• wp_global_styles 自定义样式 11KB，绑定主题 twentytwentyfive（post_name: wp-global-styles-twentytwentyfive）
• 内容：
  • 手写 CSS 6549 字符，含 49 个 !important（”全局终极清理”强制移除链接下划线/框/阴影、去 focus outline、全站粉红 hover 等）
  • typography 定制：platypi / ysabeau-office 字体族、标题行高 1.2、列表 1.3、button 大写 + 字距 1.44px
  • 按 block 定制 10 项（pullquote/quote/site-title/code/heading/list/loginout/post-terms/navigation-link/navigation）
  • elements 定制 4 项（button/heading/h6/h5）

模板层（数据库）：20 个自定义模板/部件

• 12 个 wp_template：404、page、single、home、front-page、archive、search、ray-storyboard、wp-custom-template、wp-custom-template-ray、wp-custom-template-ray-2、ray-gemini-show
• 8 个 wp_template_part：footer、header、ray、ray-2、ray-3、test、footer-columns、ray-gemini-siderbar
• 大量页面/文章引用自定义模板（STORYBOARD/Photography/sketch/3D 用 ray-storyboard，BLOG 用 wp-custom-template-ray，HMXY 等文章用 wp-custom-template）

2.2 核心问题诊断

2.3 评估结论：值得独立（Fork 而非重写）

收益：命名自主、CSS 收编、升级可控、数据随主题走（一目录迁移）

成本：一次性迁移约半天（已由脚本自动化 90%）

注意：wp-block-* / wp-elements-* 是 Gutenberg 运行时生成，fork 与否都逃不掉

三、执行规划

阶段 1：备份（已完成 ✅）

• mysqldump 全库 → /root/rzx-fork-backup-20261011-055222/rzx-full.sql（33MB）
• 官方主题完整副本 → twentytwentyfive-orig（8.9MB）
• themes 目录 tgz → wp-content-themes.tgz（28MB）

阶段 2：创建 Fork 主题（已完成 ✅）

1. 复制 twentytwentyfive → rzx-2025
2. 改 style.css 头部：Theme Name → RZX 2025 (fork)、Text Domain → rzx-2025
3. 全局样式迁移：
   • 手写 CSS（6549 字符）→ rzx-custom.css → 并入 style.css（绕开 WP Optimize 合并选择问题）
   • 结构化定制（blocks/elements/typography）→ 深度合并进 theme.json
4. 重写 functions.php：
   • 全部 twentytwentyfive_ → rzx_2025_
   • 样式 handle twentytwentyfive-style → rzx-2025-style
   • 文本域/pattern 命名空间 → rzx-2025
   • get_parent_theme_file_uri → get_theme_file_uri（子主题模式 → 独立主题模式）
   • 追加 rzx-2025-custom enqueue
5. 模板落盘：12 模板 → templates/，8 部件 → parts/，内部 "theme":"twentytwentyfive" → "theme":"rzx-2025"
6. theme.json 注册 5 个 customTemplates

阶段 3：切换与验证（已完成 ✅）

1. UPDATE wp_options SET option_value='rzx-2025' WHERE option_name IN ('stylesheet','template')
2. 清缓存：WP Super Cache + WP Optimize minify + Redis Object Cache + opcache
3. 验证：
   • 首页 / blog / storyboard / photography / about-the-site 全部 HTTP 200 + rzx-2025 主题
   • 手写 CSS 特征（全局终极清理、粉红 hover #e05be5）出现在渲染 CSS 中 ✅
   • STORYBOARD 页 ray-storyboard 模板渲染正常（73 处 query/post 块）✅
   • 单篇文章（HMXY，wp-custom-template）正常 ✅
4. 数据库模板 post 的 theme 引用同步更新为 rzx-2025（残留 0）

阶段 4：发布报告（本文）

• 发布到 rzx.me WordPress，分类 Geek，标签 wordpress

四、执行过程关键记录

4.1 踩坑记录

4.2 关键技术决策

为什么不删数据库模板 post：数据库里 12 模板 + 8 部件 + 2 全局样式 post 保留为完整备份。WP 切换主题后，theme=旧主题 的模板 post 不再被加载，前端自动用 rzx-2025 文件模板（已验证）。数据库 post 的 theme 引用已改为 rzx-2025，编辑器一致。

为什么 CSS 并入 style.css 而非独立文件：WP Optimize 的 CSS 合并（enable_merging_of_css:1 + 30 天缓存生命周期）不会可靠地把新 handle 合并进 wpo-minify。并入主题主样式文件最稳妥。

五、最终成果

/www/wwwroot/rzx.me/wp-content/themes/rzx-2025/
├── style.css          (官方 + 手写自定义 CSS，310 行)
├── style.min.css      (官方占位)
├── rzx-custom.css     (迁移的手写 CSS 备份副本)
├── functions.php      (rzx_2025_ 前缀 + custom enqueue)
├── theme.json         (官方 + 全局样式定制 + 5 个 customTemplates)
├── templates/         (12 个模板文件，含 5 个自定义)
└── parts/             (8 个模板部件文件)

迁移后站点状态：

• ✅ 主题：rzx-2025（独立主题，不再依赖官方更新）
• ✅ 全局样式：theme.json 结构化 + style.css 手写 CSS
• ✅ 模板：文件系统管理，脱离数据库
• ✅ 全部页面 200，样式特征验证通过
• ✅ 备份完整可回滚（/root/rzx-fork-backup-20261011-055222/）

六、后续建议

1. 上 git：给 rzx-2025 建 git 仓库，每次改动可回滚
2. 清理命名：逐步把 ray- 前缀统一为 rzx-，消除测试模板（ray-3/test 是空的）
3. 官方更新 cherry-pick：官方出新版时 diff 合并有用修复
4. 长期：页面内联 wp-elements-* 哈希是编辑器生成的，保持不动

报告由 arkclaw 云端生成并发布