hesu-JT/docs/THEME-AUDIT-2026-08-17.md

# HESU 主题综合审计报告与优化方案

- 日期：2026-08-17
- 对象：`hesu-theme/hesu/`（v2 同步版，commit 48b6a3a）+ 测试站实测（WP 7.0.4 / CF7 6.1.6 / PHP 8.2）
- 方法：三路并行审计（性能/SEO、安全/兼容/运维、代码遗留/编辑器 UX/可访问性），实测验证（curl/Playwright/DB 查询/无害表单提交），交叉去重后综合

---

## 一、总体结论

**架构层健康**：条件资产加载、三层结构锁定、转义纪律（v2 新增输出零违规）、幂等 seed、CF7 降级路径、编辑器加固实测全部成立。**真正的问题集中在四条线**：

1. **图片管线是性能瓶颈**——首页总传输 ~5.8MB（图片占 95%），手写 `<img>` 无 srcset、首屏下方大图无 lazy、LCP 走 CSS 背景最差模式、24 个 >500KB 未压缩图；测试库还有 123MB reseed 重复侧载尸体。
2. **SEO 三缺**——OG/Twitter 卡片全站缺失（外贸 B2B 分享场景直接损失）、single-news 双 H1 / about-us 无 H1、96 个附件 alt 全空。
3. **两处"文档/文案与事实不符"**——HESU Tools 页声称"编辑过的页面不受影响"（实际 reseed 会删并重建）；readme 声称 15 篇新闻/有 Mega Menu 文案设置（实际 4 篇/已删）。
4. **公网表单滥用面**——无反垃圾，实测可脚本无限灌表（运维配置项，非代码缺陷）。

另有一批 **v1 遗留死代码**（v2 同步后 11 项可安全删除）与若干编辑器 UX 打磨点。

---

## 二、发现明细（去重后按严重度）

### 🔴 高

| # | 发现 | 证据 | 影响 |
|---|---|---|---|
| H1 | 手写 `<img>` 全部无 srcset/sizes | hero/business-intro/media-card/large-image/news hero 的 render.php 直出 `<img src>`（对照：news-grid 用 `the_post_thumbnail` 有 srcset ✓） | 手机端下载全尺寸大图，多耗 2.5-3MB |
| H2 | LCP 走 CSS 背景图（最差模式） | `style.css:367` hero-bg 引用 banner.jpg 908KB，CSS 背景无 preload/fetchpriority；WP 把 fetchpriority=high 给了页面底部新闻图 | 4G 移动端 LCP 预计 >4s |
| H3 | 首屏下方大图无懒加载 | global-map.png（1.4MB）/introfuction2.png（953KB）/media-card 卡图均无 `loading="lazy"` | 首屏外 ~2MB 提前下载 |
| H4 | 24 个图片 >500KB 未压缩 | global-map.png 1.4MB、home-bgs.png 1.2MB、banner.jpg 908KB 等；统一压缩+WebP 可 -70% | 全站每次访问多传 ~4MB |
| H5 | OG/Twitter 卡片全站缺失 | 4 页实测 `og:`/`twitter:` = 0 | 社交分享无标题无图 |
| H6 | 标题结构硬伤 | single-news 双 H1（"NEWS" + 文章标题）；about-us 全页 0 个 H1 | 搜索引擎语义混乱 |
| H7 | 表单可被脚本无限提交 | 实测 REST 直发全字段通过校验到发信阶段；无蜜罐/reCAPTCHA/频率限制 | 公网垃圾灌箱、SMTP 配额耗尽 |
| H8 | **HESU Tools 文案误导**（`settings-page.php:47`） | 称"手动新建/编辑过的页面与文章不受影响"——实际 reseed 按 slug/meta 删除重建 seed 页面与新闻，后台修改会被覆盖 | 真实数据丢失事故诱因 |
| H9 | **readme.txt 与事实不符** | 称"15 篇示例新闻"（实际 4）；称自定义项含"Mega Menu 文案"（v2 已删） | 交付即误导 |

### 🟡 中

| # | 发现 | 证据 | 影响 |
|---|---|---|---|
| M1 | 96/96 附件 alt 全空；mediaPicker 无 alt 编辑 | DB 查询 with_alt=0；helpers.js onSelect 不含 alt 控件 | 图片搜索流量丢失；编辑 alt 需媒体库往返 |
| M2 | v1 死代码 11 项（可安全删除清单见附录 A） | section-heading 整块、stat bp 变体+4 SVG、hero showScroll/bgAlt、cap svgIcon、feature-card ae-marker+13 SVG、product-card 5 SVG+icon 枚举、banner-cell kicker、css/style.css 双胞胎等 | 维护面虚胖；inserter 噪音 |
| M3 | 结构化数据为零 | 无 Organization/Article/BreadcrumbList JSON-LD | 无富摘要资格 |
| M4 | reseed 无备份/导出机制 | cleanup 直接删（含用户修改），仅 JS confirm；无 dry-run/版本化 | 高危操作无兜底 |
| M5 | DEPLOYMENT.md 缺"升级主题→内容更新语义"章节 | `hesu_seeded` 守卫使 zip 升级不动 DB 内容；管理员不知道何时该 reseed | 升级后内容不同步的困惑 |
| M6 | 业务 JS 粗粒度加载 + CF7 全站加载 | 任一业务区块→4 个业务 JS（~6.3KB 冗余）；CF7 css/js ~26KB 全站；wp-emoji 未移除 | ~30KB 冗余请求/页 |
| M7 | WP/CF7 升级回归点 5 处 | lock.js WP7 类名、Registry::get_instance（WP6 fatal）、canLockBlocks 键、apiVersion 3、CF7 6.x DOM 桥接 | 大版本升级需回归 |
| M8 | 无 screenshot.png / Theme URI 占位 / 37 区块 0 description | Theme Check REQUIRED 级瑕疵；inserter 33 区块无图标难辨认 | 合规与编辑体验 |
| M9 | 整页缓存与 news-grid 冲突 | 服务端 WP_Query，缓存下发新文章首页不刷新 | 上缓存插件时需配失效 |

### 🟢 低 / 记录在案

- 字体无 preload（建议 2 个展示 weight）；sitemap 含 users-1.xml（建议关作者归档）；archive 分页 meta 未验证（4 篇无第 2 页）；首页 H1 纯品牌词（静态设计使然）
- phControl 暴露原始 CSS 类名给编辑者（au-gps ~15 个字段）；presence 区块排序异常（注册元数据）；GP 全屏无 prefers-reduced-motion 退出（与静态一致，超基线建议）；DateTime::createFromFormat 无守卫；style.css 注释 mojibake
- 设计取舍（**明确不改**）：mega 菜单键盘不可主动展开（与静态逐字节一致）；菜单渲染绕过 wp_nav_menu（Polylang 菜单切换器等不生效）；无子主题路径（按"直接改"交付）；多语言未验证（范围外）；index.js 剩余重复维持现状（YAGNI）

---

## 三、优化方案（分级）

### P0 必改（上线前，~1 天工作量）

| # | 动作 | 改动点 | 收益 |
|---|---|---|---|
| P0-1 | 修复 H8/H9：settings-page 文案改为如实描述（"将删除并重建全部预置页面/新闻/菜单，后台修改会被覆盖，执行前请导出备份"）；readme 更正 4 篇新闻、删除 Mega Menu 文案描述 | 2 个文件 | 消除数据丢失诱因 |
| P0-2 | 修复 H6：single-news 的 hero H1 降为 `<p>`（视觉不变）；about-us 的 au-title 升 H1 | 2 个模板各 1 行 | 语义硬伤 |
| P0-3 | 补 OG/Twitter 卡片：`wp_head` 输出 og:title/description/image（featured 或 hero bg）/url/type + twitter:card（~30 行，含 esc） | inc/setup.php 或新 inc/seo.php | 社交分享立即有卡 |
| P0-4 | 懒加载补齐：large-image/media-card/hub-card/presence map/business-intro 图加 `loading="lazy" decoding="async"`（hero 除外） | 各 render.php | 首屏外 -2MB |
| P0-5 | hero LCP：输出 `<link rel="preload" as="image" href=banner>` + hero bg img 加 `fetchpriority="high" decoding="async"`（保持 CSS 背景视觉不变，img 藏 aria-hidden 或改 preload 方案按改动最小者） | header.php wp_head / render | LCP 显著改善 |
| P0-6 | 图片压缩（构建步骤）：24 个 >500KB 图批量压（jpg q78 / png→webp 1920px），重建 zip；测试库清空 uploads 后重新 seed（消 123MB 尸体） | image/ + 重播种 | 全站 -70% 传输 |
| P0-7 | 部署文档补"升级语义"章节 + 上线检查单加：CF7 reCAPTCHA/蜜罐 + Flamingo + SMTP + 真实收件箱 + xmlrpc 关闭/REST users 收口 | DEPLOYMENT.md | 运维防线 |

### P1 建议（上线后一周内，~1-2 天）

| # | 动作 | 收益 |
|---|---|---|
| P1-1 | 手写 img 补 srcset：区块图片属性已有 imgId，render 改走 `wp_get_attachment_image()`（带 srcset/sizes/loading 一并解决） | 移动端 -2.5MB |
| P1-2 | mediaPicker 加 alt TextControl（helpers.js ~10 行）+ seed 侧载时写 `_wp_attachment_image_alt`（标题现成） | 图片 SEO + 编辑体验 |
| P1-3 | 死代码清理：按附录 A 清单删 11 项（注意 feature-card/product-card 的模板耦合同步删） | 维护面收缩 |
| P1-4 | Organization + news Article JSON-LD | 富摘要资格 |
| P1-5 | reseed 安全化：执行前自动导出 seed 页面+新闻为 WXML 文件存 wp-content/uploads（或至少 post_content 序列化存 option），页面文案如实警示 | 高危操作兜底 |
| P1-6 | CF7 资产仅 contact 页加载；业务 JS 按页面精确映射（或合并单文件）；移除 wp-emoji | -30KB/页 |
| P1-7 | screenshot.png（1200×900 首页截图）+ Theme URI 改真实域名 + 37 区块补 description 字段 | 合规 + 编辑器辨识 |

### P2 可选（按需）

- 字体 preload ×2；sitemap 关 users 归档；phControl 收进 Advanced 折叠组；presence 注册元数据清理；GP `prefers-reduced-motion` 退出劫持；DateTime 守卫；mojibake 清理；缓存插件配套（news 发布失效首页缓存）

### 附录 A：可安全删除清单（P1-3）

1. `blocks/section-heading/` 整目录（seed 零使用）
2. stat bp 分支 + 4 SVG、stats-bar bp 分支、business-intro `slot:'stats'`（成对遗骸，打包删）
3. hero `showScroll`（render+block.json+index.js 三处）+ `bgAlt` 属性
4. cap `svgIcon` + 4 SVG 映射（iconAlt 保留）
5. feature-card `ae-marker` 变体 + x/y/dir/hub 属性 + 13 内置 SVG（**必须连 feature-cards/index.js 模板 icon 预置一起删**——唯一耦合项）
6. feature-cards as-region 模板的 `flag:'CN/AE/GH'`（属性未注册，静默丢弃的死字节）
7. product-card 5 内置 SVG + `icon` 枚举（连 product-cards 模板一起删）
8. banner-cell `kicker` 三处
9. `css/style.css`（先把 editor-style.css 的 @import 改指根 `style.css`，消除双胞胎漂移）