常见问题

安装与兼容

>= 16.0.0。这是 package.json 的 engines 字段声明的下限。低于此版本会在安装或构建阶段报错。

支持。主题的脚本加载器（scripts/*.js）做了自执行兼容处理——Hexo 7/8 不会回调 module.exports，因此主题在脚本作用域内直接调用初始化函数，同时用 hexo.__XFM_* 标记防止重复注册。

需要注意 Hexo 8 起核心不再内置渲染器与部分生成器，需自行安装（见安装与部署）。

不需要。 搜索索引、站点地图、robots.txt、404 页、内容增强全部由主题内置的生成器与过滤器提供。

唯一需要按需安装的是 hexo-generator-feed——只在你需要 RSS 订阅时。

常见组合验证过：

插件 说明
hexo-generator-feed 无冲突，正常使用
hexo-generator-sitemap 建议卸载，与主题内置的 sitemap 生成器会产出两份
hexo-generator-search 建议卸载，索引格式与主题前端不一致
hexo-deployer-git 无冲突，部署用

模式选择

该选哪个模式？

一句话判断：

  • 主要是写文章、给人看 → blog
  • 持续积累零散知识 → notes
  • 结构稳定、面向使用者的手册 → docs

三者可以共存：站点选一个默认模式，个别内容用 front-matter 的 mode 覆盖。

可以。站点设 mode: blog，给文档页的 front-matter 加 mode: docs：

YAML
1
2
3
4
---
title: 用户手册
mode: docs
---

这样这篇会以三栏文档布局呈现。但要注意：只要站内存在 mode: docs 的页面，就需要维护 source/_data/docs.yml，否则那些页面的左栏会退化为扁平列表。

notes docs
树怎么来 按分类 / 日期自动分组 手工在 docs.yml 定义
层级 两级 任意层级
上下篇 无 有（按树顺序）

内容会持续零散增加 → notes；结构需要精心编排 → docs。

大部分内容可以。注意两件事：

  1. 标签插件语法不同。其它主题的 {% note %} 参数顺序可能不一样，需要对照标签插件总览调整。
  2. _config.yml 完全不同。主题配置项是针对 XFM 设计的，不能直接复用旧主题的配置。

性能

主题的静态产物很轻：

资源 说明
CSS 7 个文件，按 variables → base → layout → components → post → plugins → adaptive 分层
JS 4 个文件（adaptive / core / toc / search），无框架、无 polyfill
图标 内联 SVG sprite，零外部请求
图片 内置资源全为 SVG

没有引入任何前端框架，运行时全部是原生 JS。

索引体积由 search.content_length 决定（每条记录的正文保留前 N 字符）。参考量级：

  • 100 篇中等长度文档，content_length: 3000 → 约 300–600 KB
  • 静态托管普遍开启 gzip，实际传输约 1/3
  • 且搜索面板打开时才拉取，不参与首屏

需要更小就调低 content_length，或关闭 index_content。

不会。 档位探测脚本位于 <head> 最前，是内联同步脚本，在浏览器渲染 <body> 之前就已写入 data-tier。所以第一帧画出来就是正确档位。

不会阻塞首屏。Mermaid 使用动态 import()，数学库使用 defer 加载。只有在页面上确实存在对应内容时才有意义——如果你的站点完全不用公式或图表，建议直接关掉：

YAML
1
2
3
vendors:
  math: none
  mermaid: false

定制

我改了配置但没生效

按顺序排查：

  1. hexo clean 执行了吗？——adaptive 相关的样式是构建期生成的，必须清缓存
  2. 改的是主题的 _config.yml 还是站点的？站点 theme_config 优先级更高
  3. YAML 语法对吗？——布尔值加了引号会被当成非空字符串（仍为真）
  4. 颜色值加引号了吗？——primary: "#4f6bed"
场景 建议
单人维护、不常升级 直接改 themes/xfm/_config.yml，改动集中好找
跟随上游升级 用站点 _config.yml 的 theme_config 覆盖

唯一绝对不要做的：改 themes/xfm/ 下的模板和 CSS 文件。升级时整个目录会被替换。

Hexo 层面的做法：在站点 layout/ 下放一个 EJS 文件，名字对应 page.layout。

YAML
1
2
3
4
---
title: 我的自定义页
layout: my-page
---

然后在站点 layout/my-page.ejs 里写模板。Hexo 的模板查找顺序是站点 layout/ 优先于主题 layout/，所以这不会污染主题目录。

模板里可以直接用主题的全部辅助函数（xfm_icon() 等）。

优先考虑是否能用配置达成：

  • 加菜单项 → menu
  • 换图标 → menu.<项>.icon
  • 隐藏标题 → appearance.site_title: false
  • 隐藏整个导航 → navbar.enable: false
  • 隐藏搜索 / RSS / 切换按钮 → 各自的开关

都不满足时，覆盖 layout/_partials/header.ejs（放在站点 layout/_partials/ 下）。

部署

站点 _config.yml：

YAML
1
2
url: https://example.com/docs
root: /docs/

主题内部所有链接都走 Hexo 的 url_for()，会自动带上 root 前缀。搜索索引与 sitemap 的 URL 也会自动适配，不需要额外配置。

部署到子目录后务必本地验证一遍：hexo clean && hexo g && hexo s --root /docs/。

文档是独立页面（page），会被收录。若缺失，检查：

  1. 站点 url 是否已配置？——未配置 url 时生成器直接返回 null，不产出 sitemap
  2. 该页面是否有 title？
  3. 是否被 sitemap.exclude 的规则命中？——匹配方式是子串包含

静态托管 + 浏览器缓存。两种处理：

  1. 每次发布时给 CSS/JS 加版本查询串（需要自定义模板，成本较高）
  2. 配置托管平台的缓存策略，让 HTML 不缓存、带 hash 的资源长缓存

对多数文档站，在发布后主动刷新一次 CDN 缓存已经够用。

还没解决？

到 故障排查 看看常见报错的具体处置方式，或在仓库提 issue：

提交 Issue