Hexo主题功能测试-布局与页面篇

本文既是 matery 主题布局与页面功能的完整使用教程，也是 自动化测试靶场。覆盖：文章布局特性、侧边栏组件、响应式断点、相册、搜索、评论、暗色模式、加密、RSS/站点地图、PWA。自动化测试（tools/tests/release-test.sh）会断言下方标注的渲染标记。

1. 文章布局特性

1.1 上下篇导航（上一篇/下一篇）

用途：文章底部展示上一篇/下一篇卡片，引导读者连续阅读。

配置（主题 _config.yml）：

# 文章底部上下篇导航（自动按时间排序相邻文章）
prenext:
  enable: true

实现效果：文章末尾左右两张卡片，显示相邻文章标题 + 缩略图，hover 有渐变背景。

测试断言：文章页含 #prenext-posts 容器。

1.2 版权声明

用途：文章底部展示版权/许可协议，注明作者与转载规则。

配置（主题 _config.yml）：

post:
  copyright: true          # 显示版权声明
  license: 本文采用 CC BY-NC-SA 4.0 许可协议

实现效果：文章底部灰色版权卡片，含作者、链接、许可协议三行。

测试断言：文章页含版权声明容器（#copyright 或 .post-copyright）。

1.3 文章时效提示

用途：对过期文章显示"内容可能已过时"提示，按天数分级（警告/错误样式）。

配置（主题 _config.yml）：

post:
  outdate:
    enable: true
    warning_day: 365      # 超过 365 天显示警告样式 note
    error_day: 3650       # 超过 3650 天显示错误样式 note

实现效果：文章开头显示过期提示 note，天数越长样式越醒目。

测试断言：文章页含时效提示元素（outdate 相关 class）。

1.4 TOC 目录

用途：右侧（或侧边栏）显示文章章节导航，点击跳转对应标题，滚动高亮当前章节。

配置（主题 _config.yml）：

# TOC 目录
toc:
  enable: true
  # 锚点偏移（配合固定导航栏）
  anchor_offset: 60

实现效果：桌面端右侧悬浮目录树，随滚动高亮当前标题；移动端折叠进侧边栏。

测试断言：文章页含 #toc-content 目录容器。

1.5 广告位

用途：TOC 下方预留广告位（卡片形式）。

配置：广告卡片由 _partial/widget/advertisement.ejs 渲染，内容在模板中维护（2026-09-08 目录重构后位置）。

实现效果：侧边栏 TOC 下方展示广告卡片（.tgCard）。

测试断言：文章页含 .tgCard 广告容器。

2. 侧边栏组件（widgets）

2.1 分类雷达图

用途：/categories/ 页面用 canvas 雷达图展示各分类文章数量分布。

实现效果：分类页顶部 canvas 雷达图，每个分类一个维度。

测试断言：/categories/ 含 <canvas> 元素。

2.2 标签云

用途：/tags/ 页面以 chip 样式展示全部标签，点击跳转对应标签页。

实现效果：标签页彩色圆角 chip，hover 高亮。

测试断言：/tags/ 含 .tag-chips .chip。

2.3 词云

用途：/tags/ 页面 ECharts 词云（2026-09-05 自写螺旋 → echarts-wordcloud@2，修复 30s 超时），标签大小/颜色按权重分布。

实现效果：标签页 ECharts 词云（字号连续 sizeRange [14,56] ∝ 文章数；容器高度自适应 max(theme.wordcloud.minHeight=500, n×theme.wordcloud.heightPerWord=2.2)——用户零配置自动计算；标题 标签词云 i18n；明暗走 Matery.echarts.init 自动切换）。

测试断言：/tags/ 含 #tag-wordcloud 容器 + echarts 已加载且仅 1 份 + 明暗切换 dispose→reinit（tools/tests/wordcloud.test.js L2g）。

2.4 归档时间线

用途：/archives/ 页面按年/月时间线归档全部文章。

实现效果：垂直时间线，圆点 + 年份折叠。

测试断言：/archives/ 含 #cd-timeline。

2.5 关于页统计（postCharts）

用途：/about/ 页面用三张 ECharts 图表展示站点统计（文章趋势/分类分布/标签分布）。

实现效果：关于页三组 canvas 图表（#posts-chart / #categories-chart / #tags-chart），明暗自适应。

测试断言：/about/ 含 #postCharts 容器 + 多个 <canvas> 元素。

2.6 ArtiTalk 说说

用途：在"关于"页嵌入 ArtiTalk 说说组件（基于 LeanCloud 的个人说说墙），可发布短动态。

配置（主题 _config.yml）：

artitalk:
  enable: false    # 默认禁用
  appId: # LeanCloud App ID
  appKey: # LeanCloud App Key

实现效果：/about/ 页面渲染说说列表，需 LeanCloud 后端支持。默认禁用，启用需填写 appId/appKey。

测试断言：默认状态下不渲染。

2.7 我的项目（myProjects）

用途：/about/ 页面展示个人项目卡片列表（项目名/图标/简介/链接）。

配置（主题 _config.yml）：

myProjects:
  enable: true
  data:
    项目名:
      icon: fab fa-linux
      iconBackground: 'linear-gradient(...)'
      url: https://example.com
      desc: 项目简介

实现效果：关于页三列项目卡片，带图标 + 渐变背景色 + 标题 + 描述。

测试断言：/about/ 含 .my-projects 容器。

2.8 我的技能（mySkills）

用途：/about/ 页面展示技能进度条（技能名/百分比/颜色渐变）。

配置（主题 _config.yml）：

mySkills:
  enable: true
  data:
    C语言:
      background: 'linear-gradient(to right, #2196F3 0%, #42A5F5 100%)'
      percent: 90%

实现效果：关于页两列技能条，彩色渐变背景 + 百分比数字。

测试断言：/about/ 含 .my-skills 容器。

2.9 归档日历（postCalendar）

用途：/archives/ 页面以日历热力图展示每月文章发布数量。

配置（主题 _config.yml）：

postCalendar: true    # 在归档页显示文章日历控件

实现效果：归档页日历组件（#post-calendar），颜色深浅表示文章数量。

测试断言：/archives/ 含 #post-calendar 容器。

2.10 侧边栏广告（advertisement）

用途：文章页 TOC 下方展示广告卡片（文字/图片/链接）。

配置（主题 _config.yml）：

post:
  advertisements:
    - id: "ad-1"
      text: "广告文案"
      link: "https://example.com"
      background: "#ff6666"
      background_dark: "#8b3a3a"
      enable: true

实现效果：TOC 下方渲染 .tgCard 广告卡片，支持暗色模式双色值。无启用广告时输出空。

测试断言：文章页含 .tgCard 广告容器。

3. 响应式断点

配置（themes/matery/source/css/_variables/base.styl）

$breakpoint-sm: 368px   // 超小屏（手机竖屏）
$breakpoint-md: 768px   // 平板/手机横屏
$breakpoint-lg: 992px   // 桌面
$breakpoint-fun: 1400px // 特效启用阈值（大屏）

各断点布局

实现效果

Bootstrap/Materialize 栅格自适应，侧边栏在窄屏自动隐藏，TOC 移动端折叠。

测试断言：<768px 导航折叠；>992px 桌面三栏；>1400px 特效启用。

4. 内容宽度统一（2026-09-07 新增）

设计原则

“比例 + 上限”：内容区 width: 90%（相对屏幕）+ max-width 阶梯（可读性上限）。不要纯 90%——4K 下 90% = 3456px 不可读。

宽度阶梯（_variables/base.styl）

选型规则（mixin content-container(wide)）

• 单栏（内容无侧栏）：content-container() → 标准宽度
• 多栏（内容 + 侧栏/TOC）：content-container(true) → 宽宽度
• 禁止 layout 手写 max-width（统一走 mixin）

实现效果

wiki（多栏）4K 内容列 899px → 1500px（+67%）；与 post-container 同宽阶梯。

自动化测试

tools/tests/content-width.test.js（L2m）覆盖：W1 4K wiki==post-container / W3 FHD / W4 2K / W5 单栏封顶 1525px。

5. 多语言与回落机制（2026-09-08 新增，2026-09-10 修订）

语言配置（preference 段）

• default_lang：默认语言（无前缀路径），所有组件共用
• fallback_lang：回落中间层——请求语言不存在时先回落此语言
• lang_meta：语言能力表（9 语言）+ enabled 开关（未启用不生成多语言页/不出现在下拉）

回落链（三层）

请求语言存在？ → 用它
→ 不存在 → fallback_lang 存在？ → 回落 fallback_lang
→ 不存在 → default_lang 存在？ → 回落 default_lang
→ 不存在 → 任意可用语言

真实翻译映射（post / wiki）

翻译文件与默认语言同名，放在语言子目录：

中英关联双模式：有 abbrlink 插件 → 相同 abbrlink 关联；无插件 → 同名文件关联（带文件系统兜底检查）。有真实翻译 → 生成 /{lang}/posts/{abbrlink}/ 真实内容页；无翻译 → 回落链生成。

注：hexo 原生只认 source/_posts/（en/_posts/ 会被忽略），文章翻译由主题 i18n-post-generator.js 生成。

各页面类型行为（2026-09-10 修订）

独立页（含 gallery 子页与 pages 集合中 layout:'post' 的历史页如 dash）由 standalone-page-generator.js 按排除法生成（layout ∉ {wiki, tags, categories, 404} 即生成，新增独立页自动覆盖，无需登记清单）。

客户端语言策略（方案 A 全站跟随，2026-09-10）

语言前缀规则（url_for_lang）

资源（css/js/libs/medias/images/fonts 等）与静态文件（xml/txt/json 等）不加语言前缀；其余内容路径一律加前缀。豁免规则单一来源 scripts/utils/url-lang-blacklist.js。独立页导航因此带上 /en/ 前缀指向对应语言版。

标题 i18n（page_title_i18n，2026-09-10）

<title> 与封面大标题（bg-cover-content.ejs）共用 scripts/helpers/page-title.js 的 page_title_i18n：tags/categories/about 按 title、其余按 layout 映射 i18n key；返回 null 时调用方回退原 title——多语言页面标题随语言切换。

实现效果

访问 /de/docs/setup/（de 已启用无翻译）：有 en 翻译 → 内容用 en + 提示条"de 不存在，显示 en"；无 en → 内容用 zh-cn + 提示条。独立页 /en/musics/ 显示英文界面文案；浏览器语言为 en 的访客首访时被询问是否切换到英文版。

自动化测试

• tools/tests/lang-fallback.test.js（L13）覆盖回落链 4 级 + 配置兼容/过滤/校验（13 断言）
• tools/tests/release-test.sh L2x 覆盖 MATERY_LANG 注入 / 回落页 / 9 个独立页多语言（含 gallery 子页与 dash）200 / 聚合页多语言
• tools/tests/unit-standalone.test.js（L13，22 断言）覆盖独立页排除法判定 + 语言前缀豁免
• tools/tests/lang-client-strategy.test.js（L11，7 断言）覆盖客户端语言策略（全站跟随 / 爬虫跳过 / 面板回显）

6. Wiki 多语言（docs/api/tutorial 子站，2026-09-10 修订）

用途

Wiki 文档子站（docs/api/tutorial）三栏布局 + 中英双语 + 回落机制，与博客文章共用同一套多语言体系。

核心约定（front-matter 必填）

---
layout: wiki        # 必填，否则不渲染三栏布局
wiki: tutorial       # 必填，子站名（docs/api/tutorial）
---

目录结构

回落机制

无英文版 → /en/... 回落显示中文 + 顶部提示条（“no en version”）+ noindex。

侧栏（source/_data/{wiki}-sidebar.yml）

# source/_data/docs-sidebar.yml
docs:
  - key: guide
    children:
      - key: writing
        title: 写作指南

• 条目 key 英文 snake_case，显示文本走 languages/*.yml 翻译
• wiki 整体加密：侧栏顶部配置 encrypt_password（统一 encrypt_ 前缀：message/placeholder/button_text 可选）→ 该 wiki 全部页面加密，输入密码解密渲染；解密后派生密钥（dk）存 localStorage（wiki.<wiki名>，TTL 1 天），同 wiki 其他页面自动解密免重输；encrypt_ 前缀配置键在侧栏渲染时跳过（不显示为目录项）

内部链接

绝对路径 + .html（/tutorial/guide/writing.html），多语言自动加前缀。

段落编号

手写编号的 wiki 页必须 closeAutoTocNum: true（与博客一致，防 CSS 自动编号双重编号）。

新增 wiki 页流程

1. 写中文 source/{wiki}/xxx.md（front-matter layout: wiki + wiki: <子站>）
2. 补英文 source/en/{wiki}/xxx.md
3. 更新 source/_data/{wiki}-sidebar.yml
4. 9 语言翻译 key（languages/*.yml）
5. hexo clean 重建

自动化测试

tools/tests/release-test.sh L2b：en 页面 200 + 回落提示条 + 评论 path 归一化 + 默认语言无前缀；L2y：wiki 加密页解密 + 侧栏无 encrypt_ 垃圾标题。

7. 相册功能

数据源（source/_data/galleries.yml）

相册名:
  photos: 单张图对象 | 字符串路径 | 目录路径  # 三种形式
  cover: 封面图
  description: 描述

页面结构

• /galleries/ — 相册列表页（卡片 + 封面）
• /galleries/<名称>/ — 单个相册页（灯箱 + caption）
• 加密相册：front-matter 加 password，进入需解密

实现效果

列表卡片 + 内页 lightGallery 灯箱浏览，加密相册解密后显示。

测试断言：

• /galleries/ 相册列表
• /galleries/2020/ 灯箱 + caption
• /galleries/private/ 加密解密 UI

8. 搜索功能

配置（根 _config.yml 的 search 块）

三引擎：local（本地 search.json）+ algolia（Algolia API）+ pagefind（Pagefind 索引）。

交互

• 弹窗：点击/聚焦导航栏搜索框打开；Ctrl+K（Mac ⌘+K）快捷键打开
• 引擎切换：弹窗内下拉在 local / Algolia / Pagefind 三引擎间切换
• 多语言过滤：按语言前缀过滤 + 回落去重（applyLangFilter）
• 高亮统一：三引擎继承同一基类，共用 _highlight/_escapeHtml（结果高亮一致）

实现效果

• 导航栏搜索框（#searchInput）
• 搜索弹窗实时结果
• /search.json 为本地搜索数据源

测试断言：页面含 #searchInput；/search.json 可访问；弹窗可打开。

9. 评论系统

配置（根 _config.yml）

comment: waline    # 评论引擎
waline:
  serverURL: https://waline.17lai.site
  ...

页面 front-matter 控制：comment: waline（文章/留言/友链/说说页）。

已废弃：Valine（valine.enable: false）已停用，实际评论引擎为 Waline。

实现效果

Waline 评论框（Markdown/Emoji/点赞/后台管理）。

测试断言：文章/msg/friends/bb 页含 #comments；waline 初始化脚本存在。

10. 暗色模式

配置（主题 _config.yml）

dark_mode:
  enable: true
  default: auto   # auto | light | dark

• auto：优先 prefers-color-scheme，其次本地时间 18:00–6:00 自动暗色
• 切换按钮：手动切换后覆盖默认模式

实现效果

[data-user-color-scheme="dark"] 属性驱动全套 CSS 变量切换，图片/图表自适应。

测试断言：CSS 含 [data-user-color-scheme="dark"] 规则；切换按钮可切换明暗。

11. 加密文章

配置（根 _config.yml）

encrypt:
  tags:
    - 私密    # 按标签加密
  default_abstract: 本文已加密
  ...

文章只需打上加密标签，阅读时需输入密码。

实现效果

文章页显示解密 UI（#hbePass），输入正确密码后渲染正文。

测试断言：tag 加密文章含 #hbePass 解密 UI。

解密后统一刷新（2026-09-09 新增）

加密内容解密后，正文中的组件需重新初始化（解密前是密文，DOM 无这些元素）：

统一触发点：hbe-bundle onSuccess（所有加密场景：文章/相册/wiki/片段共用）。各监听器只保留特有处理：

• post：tocbot reinit（文章目录）
• wiki：TOC 加密态移除 + tocbot reinit
• 相册：initGallery()

幂等保护：codeWidget data-code-processed、mermaid data-processed、articleInit destroy 旧实例重建——重复调用不产生重复元素。

测试断言：解密后 .code-toolbar 数量 = .code-area 数量；图片包装 .img-item + 容器 lg-uid 属性存在。

12. RSS / 站点地图

配置（根 _config.yml）

feed:            # hexo-feed 生成
  type: atom
  path: atom.xml
sitemap:         # hexo-generator-sitemap
  path: sitemap.xml

产物

• /rss.xml、/atom.xml、/feed.json — 订阅源
• /sitemap.xml、/baidusitemap.xml — 搜索引擎抓取

测试断言：/rss.xml、/atom.xml、/feed.json、/sitemap.xml 均可访问。

13. PWA

配置（根 _config.yml + userConfig/sw.tmp.js）

pwa:
  enable: true
  manifest: ...   # 名称/图标/主题色

sw.tmp.js 是 Service Worker 模板，CI 时注入离线缓存版本号 17lai-cache-{时间戳} 生成 source/sw.js。

实现效果

• 可安装（manifest）
• 离线缓存静态资源
• 版本更新自动刷新

测试断言：/sw.js 可访问，SW 注册正常（localhost 豁免）。

SW 版本对比自动刷新

CI 注入的缓存键 17lai-cache-{时间戳} 变化即视为新版本。注册 SW 时监听 updatefound（新 SW installed）与 controllerchange，对比新旧 cacheStorageKey：变化则自动刷新一次（不弹窗，用户无需手动刷新）。sw.tmp.js 安装时 skipWaiting + 激活后 clients.claim() 接管，并清理旧 17lai-cache-* 缓存。

14. SEO 结构化数据（JSON-LD + Open Graph）

用途

为搜索引擎与社交平台提供结构化元数据：JSON-LD 富结果 + Open Graph / Twitter Card 分享预览。

配置（layout/_partial/common/structured-data.ejs + head.ejs）

无独立开关，随 head.ejs 输出：

• JSON-LD @graph 单 script：WebSite（含 SearchAction 搜索框）+ Person（作者）+ Organization（站点），文章页附加 BlogPosting
• @id 互相引用（publisher/author 指向 #organization/#person），描述经 strip_html + 210 字符截断
• OG/Twitter：og:type/title/url/site_name/description/image + twitter:card=summary_large_image

实现效果

• 页面含 <script type="application/ld+json"> 富结果数据
• 分享到社交平台显示标题/描述/封面图预览

测试断言：页面含 application/ld+json；文章页含 BlogPosting；含 og:type / twitter:card 标记。

15. 设计令牌与 CSS 变量架构

用途

统一设计令牌（圆角/阴影/过渡/间距/字号），经三层传递链落到 CSS 自定义属性供全站引用，避免硬编码。

配置（主题 _config.yml 的 design 段）

design:
  radius_sm: 3px          # 按钮/小标签
  radius_md: 8px          # 卡片/便签
  radius_lg: 12px         # 弹窗
  shadow_md: "0 2px 5px 0 rgba(0,0,0,0.16)"
  shadow_lg: "0 5px 11px 0 rgba(0,0,0,0.18)"
  transition_fast: 0.2s
  space_1: 4px            # 4px 基准递增
  font_size_md: 1.125rem  # rem 制，随 --font-scale 缩放

三层传递链

_config.yml design.* → theme-config() → Stylus 变量 → :root CSS 自定义属性 → 组件 var(--*)

• 方案层：source/css/_schemes/matery.styl（对齐 NexT _schemes/ 机制，未来可新增方案）
• 字号：根字号 calc(var(--font-size-base) * var(--font-scale))，偏好面板调 --font-scale 全站 rem 等比缩放

实现效果

组件统一引用令牌（圆角/阴影/间距一致），改 design 段一处即全站生效。

测试断言：CSS 含 --font-scale 规则与根字号 calc(... * var(--font-scale))。

⚠️ 已知坑

坑 1：标题编号双重叠加

现象：标题渲染为「1. 1. 概述」（两个编号）。

原因：主题 CSS 自动给 h2–h6 加编号（默认开启），手写编号（如 ## 1. 概述）会叠加。

正确做法：手写编号的页面在 front-matter 加 closeAutoTocNum: true；不手写编号的页面不要加该字段。

本文已正确设置 closeAutoTocNum: true（front-matter 第 19 行）。

坑 2：加密 ↔ TOC 冲突

现象：wiki 整体加密时 TOC 按设计不显示。

原因：加密模式下 TOC 组件被跳过（设计如此）。

正确做法：相关测试断言勿写死「TOC 必须存在」。加密 wiki 页面不显示 TOC 是正常行为，不是 bug。

坑 3：Wiki 英文页漏 lang: en

现象：侧栏链接指向 /docs/ 而非 /en/docs/。

原因：wiki_sidebar 使用 page.lang || default_lang，省略 lang: en 则回落到默认语言路径。

正确做法：所有 source/en/tutorial/ 下的页面必须写 lang: en。验证：for f in source/en/tutorial/**/*.md; do grep -L 'lang: en' "$f"; done。

坑 4：_config.tmp.yml 注释行保留

现象：尝试删除注释行瘦身，被用户否决并 100% 回滚。

原因：用户明确声明注释行是有用储备（未来可能恢复）。

正确做法：永远不要删除或修改 userConfig/_config.tmp.yml 中的注释行。

坑 5：改配置后必须 clean 构建

现象：改了配置但页面不变。

原因：Hexo 缓存机制不会自动检测配置变更。

正确做法：改配置或 source/_data/* 后必须 npm run clean && npm run build。构建日志中出现 INFO Deleted database. 和 INFO Deleted public folder. 表示 clean 成功执行。

坑 6：source/_data/* 增量缓存误判

现象：修改 source/_data/friends.yml 等数据文件后，页面空白或数据不更新。

原因：Hexo 增量缓存误判「已缓存未变化」（Cache 哈希更新但 Data model 未写入）。

正确做法：

• 本地：rm -f db.json && npm run build
• 容器：tools/cicd.sh -d（内置 clean + generate + 配置注入）
• 容器内 pm2 restart 不够：pm2 内存缓存 db.json 旧 content

附：布局页面功能速查表