The following is the Chinese translation of the update notes. See
https://github.com/next-theme/hexo-theme-next/releases
and
https://theme-next.js.org/docs/troubleshooting.html#Quick-Debug-Instructions
for the English version.
以下是常见问题的说明,烦请过目。
在每次更新主题前,请务必阅读以下更新说明,特别是Breaking Change
部分(这涉及到了一些重大更新,可能影响先前的用户配置或自定义)。
https://github.com/next-theme/hexo-theme-next/releases
为了避免操作失误导致配置文件冲突或源码丢失,我们建议使用 Git 等工具对博客源码做好版本管理和备份。这样做有很多好处,比如你可以使用 GitHub Actions 来自动进行博客部署。
NexT 一贯以「开箱即用」为目标,尽量隐藏复杂的实现,将简洁易懂的配置提供给用户。不过,虽然 _config.yml
中对很多配置选项都提供了注释,但一些选项的细节并没有完全展现。为了避免出现问题,请在进行配置和使用前阅读网站 https://theme-next.js.org 上对应的文档。对于文档中描述不清楚的地方,欢迎提出改进建议 😊
此外,通过搜索引擎可以找到许多 NexT 热心用户创作的教程文章。不过,在过去的数年时间里,NexT 新增了大量的 Feature,有部分内容是常见的教程没有涵盖的。后文中摘录了部分 NexT v7 版本的新功能及使用说明,供参考。
问题反馈方式
使用 NexT 时遇到了问题?不用担心!有许多种方法可以与 NexT 主题开发/维护者团队(下称「NexT 团队」)或其他用户取得联系,共同解决问题:
- 欢迎加入 Telegram 群,讨论问题更方便
- 使用 GitHub Discussions 功能发帖:https://github.com/next-theme/hexo-theme-next/discussions
- 提交 Issue。我们主要将 Issue 结合 Milestone 用于追踪 Bug Report 和 Feature Request,以明确阶段性的开发目标,每月发布一个新版本。
环境
操作系统
我们通过 GitHub Actions 进行自动化测试,确保 NexT 可以在 Windows,macOS 以及 Linux 上正常使用: https://github.com/next-theme/hexo-theme-next/actions?query=workflow%3ATester
Hexo 支持直接在 Windows 上运行,无需使用 mingw 等环境。
Hexo 与 NexT 兼容性
版本 |
Hexo 3.0.0-beta.4 或更低 |
Hexo 3.0.0-rc.1 ~ 3.9 |
Hexo 4.0 ~ 4.2.1 |
Hexo 5.0 ~ 5.2.0 |
Hexo 5.3.0 或更高 |
NexT v0.4.5.1 或更低 |
✅ |
✅ |
❌ 图标显示问题 |
❌ 图标显示问题 |
❌ 图标显示问题 |
NexT v0.4.5.2 ~ v7.4.1 |
⚠️ 不支持 Data Files |
✅ |
❌ 图标显示问题 |
❌ 图标显示问题 |
❌ 图标显示问题 |
NexT v7.4.2 ~ v8.1.0 |
⚠️ 不支持 Data Files |
✅ |
✅ |
✅ |
✅ |
NexT v8.2.0 ~ v8.3.0 |
⚠️ 需安装 Renderer |
⚠️ 需安装 Renderer |
⚠️ 需安装 Renderer |
✅ |
✅ |
NexT v8.4.0 ~ v8.5.0 |
⚠️ 需安装 Renderer |
⚠️ 需安装 Renderer |
⚠️ 需安装 Renderer |
❌ 不支持escape_html |
✅ |
NexT v8.6.0 或更高 |
⚠️ 需安装 Renderer |
⚠️ 需安装 Renderer |
⚠️ 需安装 Renderer |
✅ |
✅ |
如果可能,请始终使用最新版本的 Hexo 和 NexT。对于用户而言,新版本 Hexo 带来的渲染性能的提升非常显著。
NexT 仓库
NexT 一共有三个不同的仓库:
一些网络教程可能使用了旧仓库的链接。为了避免安装过时的 NexT 版本,请务必按照本仓库 README 中提供的几种安装方式进行操作。
跨版本的升级可能并不顺滑(例如由 v5.1.4 或 v7.8.0 升级至 v8.0.0),请备份配置文件及修改过的文件(例如自定义模板文件)后,重新安装新的主题。具体操作请阅读文档: https://theme-next.js.org/docs/getting-started/upgrade.html
NexT 自定义
NexT 支持在不修改主题仓库内文件的情况下进行配置和自定义,因此无论是使用 Git 还是 npm 安装的主题都能顺利更新。
_config.next.yml
配置文件
为了避免更新出现冲突,推荐使用 Alternate Theme Config 存储配置:https://theme-next.js.org/docs/getting-started/configuration.html
注:在升级到 Hexo 5.0 版本后,请留意配置方式上的改变,使用 Hexo 支持的 _config.next.yml
代替 source/_data/next.yml
。旧的 next.yml
配置方式诞生于 2015 年(iissnan/hexo-theme-next#328),已经完成其历史使命,于 NexT v8.1.0 版本后停止支持。
v7.3.0 Custom Files 用法
PR theme-next/hexo-theme-next#868 调整了自定义布局或样式的方式,取消原本主题目录下的自定义文件(例如 _custom/custom.styl
),只保留在配置文件中指定自定义文件的方式。 自定义文件与主题文件分离是个好的实践,这样可以在不修改任何主题原始代码的情况下加入自定义内容;可以避免由于 git merge
产生冲突,同时也允许在通过 npm
安装主题时方便地进行自定义。
你可以将所有自定义布局或样式放在一个位置特定位置(比如:hexo-site/source/_data
),然后取消注释主题配置文件中 custom_file_path
部分下对应的内容(注意文件名与路径要一致),即可完成对于主题的自定义。这个页面提供了几个使用 Custom Files 的例子,例如加载看板娘、修改页面宽度、隐藏 cheers
等等: https://theme-next.js.org/docs/advanced-settings/custom-files.html
Custom Files 在向页面中增加内容时非常方便。如果要在不修改主题源码的情况下修改或删除内容,请使用插件 https://github.com/jiangtj/hexo-extend-theme
NexT 插件
除了 custom_file_path,我们还提供了更加灵活的自定义方式(theme_inject
),可以阅读文档: https://theme-next.js.org/docs/advanced-settings/injects.html
这一特性使得 NexT 主题拥有了一套不同于 Hexo 的插件系统。不妨看看这个仓库: https://github.com/next-theme/awesome-next
如果有新颖的想法,或着撰写了关于 NexT 主题的教程,抑或是希望将自己的博客作为 NexT 主题演示站,欢迎在这里提交 Pull Request!
v7.4.2 Nunjucks 引擎
鉴于 swig 缺乏维护,NexT 自 7.4.2 版本开始,使用 Nunjucks 代替 swig 作为模版引擎。如果此前根据 swig 的语法写过自定义内容,请在更新前确认它们是与 Nunjucks 兼容的,否则会报错,且生成的页面为空白。例如, Nunjucks 只支持 and
运算符,需要替换掉 swig 中的 &&
。见 http://mozilla.github.io/nunjucks/getting-started.html
Hexo 5.0 版本移除了对于 swig 模版的支持,改为独立的 hexo-renderer-swig 插件。如果你发现 Hexo 生成的 html 中输出了 NexT 模版源码,说明你正在使用旧版本的 NexT,请重新安装或升级 NexT。
v7.6.0 auto_excerpt
自 7.6.0 版本开始,auto_excerpt
功能被移除,因为按照字数截断文章,必须先移除其中的 HTML 标签,这将导致图片、代码块显示错误;并且,它也并不属于 Hexo 主题应当负责的内容。我们推荐通过 <!-- more -->
来精确控制 Read More 的位置;或者设置 excerpt_description
然后为每篇文章指定 description
。当然,也可以自行安装第三方插件:
https://github.com/chekun/hexo-excerpt
https://github.com/ashisherc/hexo-auto-excerpt
作出以上改动后,请执行 hexo clean
。
v7.6.0 访问量统计
如果开启了访问量统计功能,请确保 Hexo 配置文件中的url
正确设置为了你的网站域名,否则统计不会生效(这是为了屏蔽来自 http://localhost:4000
的流量);如果使用 GitHub pages 和自定义域名,请将 url
设置为自定义域名而不是 *.github.io
;如果同时使用了带有 www 和不带 www 的域名,请进行 301 重定向。
v7.7.2 升级 MathJax
7.7.2 版本中,NexT 主题升级了内置的 MathJax 的版本。旧版本的 NexT 文档中建议使用 MathJax 的用户安装 hexo-renderer-kramed,但由于这一插件已经停止维护,在这次 MathJax 升级后将不再被 NexT 支持,请使用 hexo-renderer-pandoc 代替(需要先安装 pandoc)。此外,如果在 vendors
中设置了 CDN 链接,请更新或移除它们以使用默认的 CDN 配置,否则会加载失败。
NexT 除内置的 MathJax 和 KaTeX 引擎外,还提供了 hexo-filter-mathjax 插件用于后端渲染,无需加载前端脚本,欢迎使用。
v7.7.2 Dark Mode
7.7.2 版本中,NexT 主题加入了对暗色模式的支持。在配置文件中设置 darkmode: true
,并在启用了暗色模式的操作系统中,使用支持 prefers-color-scheme
属性的浏览器即可体验。
见 https://caniuse.com/prefers-color-scheme
v8.0.0-rc.1 自定义图标
NexT 主题自 8.0.0 版本开始,将自带的 Font Awesome 图标库由 4.7.0 版本升级为了 5.13.0 版本。此次升级并不向下兼容,请修改配置文件中与 Font Awesome 相关的内容,否则图标可能无法正常显示。
全部可选图标在此: https://fontawesome.com/icons
如果要使用 Font Awesome 没有收录的图标,请看这篇文章: https://blog.dlzhang.com/posts/32/
v8.0.0-rc.5 动画效果
鉴于 Velocity.js 缺乏维护,NexT 使用 Animate.css 代替之。两者的动画效果几乎完全一致,除了动画名称略有不同。如果在配置文件中设置了旧的名称(例如 slideDownIn
),请将其移除或根据此网页选择新的动画效果:
https://theme-next.js.org/animate/
v8.0.0 CDN 设置
NexT 已支持一键切换 CDN 服务商,而不需要为每个插件单独设置 CDN 地址。见 https://theme-next.js.org/docs/advanced-settings/vendors.html
手动设置 CDN 地址会增加管理成本,并且可能错误地加载不兼容的脚本。我们不建议用户继续使用这一方式。
v8.1.0 移除 Valine
Valine 使用 Leancloud 作为后端,是一个深受静态博客用户喜爱的评论系统。然而 Valine 暴露出了一些令人担忧的问题:
- NexT 团队曾多次收到关于 Valine 评论系统存在隐私数据泄露的反馈;
- Valine 自 1.4 版本起不再开源,发布的打包版本中存在未告知用户的百度统计代码;
- 2020 年 11 月下旬出现了针对 Valine 的垃圾评论攻击;
- CVE-2021-34801
考虑到这些问题已经严重影响到 NexT 用户的数据安全,我们决定将其移除,需要继续使用的用户请安装插件: https://github.com/next-theme/hexo-next-valine
(插件的配置项使用驼峰命名,与 Valine 本身一致,需要注意将 appid
和 appkey
改为 appId
和 appKey
)
由于 Valine 不再开源,NexT 团队无法对其 Debug。如果在使用时出现任何问题,请在这里反馈: https://github.com/xCss/Valine/issues
从 Valine 迁移到 Disqus: https://github.com/YunYouJun/valine-to-disqus
v8.10.0 Highlight.js 兼容性
NexT 为了支持 highlight.js 提供的近百个代码高亮主题,使用正则表达式从 css 中提取代码块的前景、背景色。虽然这样做可能无法完全支持 css 的语义信息,但对现有的绝大多数 highlight.js 主题都适用。highlight.js 11.0 版本后发布的 css 经过了压缩,导致原有的正则表达式失效,因此向 stylus 引擎传递了空值。这一问题在 NexT 的 8.10.0 版本中被修复。NexT 此前默认的暗色代码高亮主题 tomorrow-night
同样跟随 Highlight.js 更新,请手动将其更改为 base16/tomorrow-night
。
可能导致 Hexo 或 NexT 出现问题的插件或服务
其它常见问题
- 在 Hexo 的
_config.yml
中有一些选项可以修改页面的永久链接形式(permalink
)。而 NexT 所集成的评论系统可能需要通过页面的 URL 加载对应的数据。如非必要,请不要修改有关设置,以免评论数据丢失。
- 如果自定义了部分元素的
opacity
,那么这会创建新的层叠上下文,进而影响其它元素的 z-index
表现,例如导致搜索框显示不正常(theme-next/hexo-theme-next#914)
- Group Picture 推荐与 FancyBox 插件一同使用。如果在一行中包含宽高比不同的图片,MediumZoom 可能会在放大时错误地计算图片尺寸。(francoischalifour/medium-zoom#147 (comment))
- 不蒜子计数依赖于浏览器请求中的 Referer 信息来获取页面的访问量数据。如果你使用的浏览器具有阻止跨站追踪功能(例如 Safari),那么浏览器可能会忽略网站设定而使用最严格的 Referrer-Policy,导致加载的访问量数据不准确。另见 https://caniuse.com/referrer-policy
![](https://user-images.githubusercontent.com/16272760/101658476-05a73080-3a80-11eb-8d6a-1a24fc718178.png)
Issue 和 Pull Request 规范
-
NexT 主题会尽可能保证配置文件向下兼容,使得用户能够平滑升级。但在 NexT 主题不断发展和完善的过程中,难免会出现配置和使用方式的变化。因此,在更新主题前一定要先阅读对应的 Release Notes,切勿在不了解更新内容的情况下进行更新。
-
NexT 团队仅对使用最新版本 NexT 主题的用户提供技术支持,并将拒绝解答使用旧版本 NexT 出现的任何问题。 如果使用版本号为 5.x 至 7.x 的主题出现问题,请到对应的旧的仓库中提交 Issue。
2.1 如果使用 npm
安装主题,那么默认是本仓库的最新版本,不用担心。
2.2 如果使用 git
安装主题,请务必检查主题的 package.json
中 version
字段版本号是否正确。
-
也请各位遵守 AGPL 协议,这包括对于修改 NexT 主题后开放源代码的要求,以及 NexT 团队对由使用 NexT 主题造成的任何问题免责。
提交 Issue
如果在使用中遇到问题,欢迎提交 Issue。在提交 Issue 前,可以先在已有的 Issue 中搜索一下,或许就能找到相似的问题;尽量不要重复提交。
提交 Issue 时,请务必根据模版,提供网站的链接、源码仓库和有关截图。 需要这些信息的原因是:
- 有时一些 bug 需要在特定的条件下才能够复现(例如,安装了某个 Hexo 插件,或者使用了某个特定的浏览器),提供尽可能多的信息,能够使 NexT 团队更快地定位问题
- 在未来,可能有其他遇到了相同问题的用户,如果 Issue 中只提供了网站链接,而链接发生变化,那么这个 Issue 就无法参考了。
关于 Bug
为了更快地解决问题,在使用 NexT 主题遇到 Bug 时,可以先自行按照以下方法排查(因为问题可能并非来自 NexT 主题本身): https://theme-next.js.org/docs/troubleshooting.html#Quick-Debug-Instructions
如果对主题进行过自定义,那么请移除全部的自定义文件,检查 Bug 是否仍然存在。
如果是在升级 Hexo 或 Hexo 插件后遇到的问题,请尝试:
- 将全部 Hexo 插件都升级到最新版本(以避免 Hexo 版本兼容性问题),可以使用 npm-check 等工具辅助;
- 如果报错信息来自第三方插件,可以卸载插件或将 Hexo 退回旧版本,一些插件可能由于长时间未更新,与新版 Hexo 不兼容;
- 按照本「更新说明」的指导,在清楚更新内容的情况下,升级 NexT 主题至最新版本。
如果这并非一个来自于 NexT 主题的 bug,可以尝试向 Hexo 团队寻求帮助:https://github.com/hexojs/hexo/issues
另见: https://github.com/next-theme/hexo-theme-next/blob/master/docs/zh-CN/CONTRIBUTING.md#你需要了解的
关于 Feature Request
使用前文介绍的 custom_file_path
,可以轻松地将自定义的 HTML,JavaScript 和 CSS 插入到页面中。因此,对于一些简单且小众的功能,我们建议用户自行实现,并通过 Awesome NexT 进行推广。例如,想要在页面中隐藏一个组件,往往用一行 CSS 就可以实现。这时我们一般不会考虑专门为此在配置文件中增加新的选项。
关于 Pull Request
我们非常欢迎通过 Pull Request 来加入新功能或修复 Bug。在修改主题的样式时,请注意考虑 NexT 主题四个 Scheme 之间的差异。这可能要求额外的代码来确保样式的一致性,并避免改动对于其它 Scheme 的破坏。此外,配色方案的设计也需要考虑暗色模式的支持。
写在最后:如果你希望 NexT 主题变得更好,那么请加入 Telegram 群聊或参与 GitHub 上的讨论,因为许多关键的改动都会通过投票的方式征求意见。我们非常希望用户的反馈能够产生积极、正面的效果。对 NexT 社区做出贡献的方法有很多,如果你是开发者,那么提交代码是最直接的方式;而对于广大用户而言,及时地将使用体验反馈给 NexT 团队同样是非常重要的。
感谢各位对 NexT 主题及 NexT 团队的支持。祝使用愉快!