The following is the Chinese translation of the update notes. Seehttps://github.com/next-theme/hexo-theme-next/releases https://theme-next.js.org/docs/troubleshooting.html#Quick-Debug-Instructions
以下是对 NexT 使用过程中常见问题的说明。
NexT 主题会尽可能保证配置文件向下兼容，使得用户能够平滑升级。但在 NexT 主题不断发展和完善的过程中，难免会出现配置和使用方式的变化。因此，在每次更新主题前，请务必阅读更新说明 ，特别是Breaking Change部分（这涉及到了一些重大更新，可能影响先前的用户配置或自定义）。
为了避免操作失误导致配置文件冲突或源码丢失，我们建议使用 Git 等工具对博客源码做好版本管理和备份。这样做有很多好处，比如你可以使用 GitHub Actions 来自动进行博客部署，也可以随时回退到历史版本。
NexT 一贯以「开箱即用」为目标，尽量将简洁易懂的配置提供给用户。不过，虽然 _config.yml 配置文件中对很多配置选项都提供了注释，但一些选项的细节并没有完全展现。为了避免出现问题，请在进行配置和使用前阅读网站 https://theme-next.js.org 上对应的文档。对于文档中描述不清楚的地方，欢迎提出改进建议 😊
此外，通过搜索引擎可以找到许多 NexT 热心用户创作的教程文章。不过，在过去的数年时间里，NexT 新增了大量的 Feature，有部分内容是常见的教程没有涵盖的。后文中摘录了部分 NexT v7 版本的新功能及使用说明，供参考。
问题反馈方式
使用 NexT 时遇到了问题？不用担心！有许多种方法可以与 NexT 主题开发/维护者团队（下称「NexT 团队」）或其他用户取得联系，共同解决问题：
Discord Server（中文/英文）: https://discord.gg/qmkgkY3jaG
Gitter（英文）: https://app.gitter.im/#/room/#next:gitter.im
Telegram 群（中文）：https://t.me/theme_next_cn
使用 GitHub Discussions 功能发帖：https://github.com/next-theme/hexo-theme-next/discussions
环境
我们通过 GitHub Actions 进行自动化测试，确保 NexT 可以在 Windows，macOS 以及 Linux 上正常使用： https://github.com/next-theme/hexo-theme-next/actions?query=workflow%3ATester
Hexo 支持直接在 Windows 上运行，安装 Node.js 即可。使用 WSL 安装也是可以的。不推荐使用 mingw 环境。
如果可能，请始终使用最新版本的 Hexo 和 NexT。新版本 Hexo 带来的渲染性能的提升非常显著。
NexT 仓库
NexT 一共有三个不同的仓库：
一些网络教程可能使用了旧仓库的链接。为了避免安装过时的 NexT 版本，请务必按照本仓库 README 中提供的几种安装方式进行操作，安装最新的 v8 版本的主题。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 _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
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 生成的 html 中输出了 NexT 模版源码，说明你正在使用旧版本的 NexT，请重新安装或升级 NexT。
v7.6.0 auto_excerpt
自 7.6.0 版本开始，auto_excerpt 功能被移除，因为按照字数截断文章，必须先移除其中的 HTML 标签，这将导致图片、代码块显示错误，不符合 NexT 的设计原则。我们推荐通过 <!-- more --> 来精确控制 Read More 的位置。当然，也可以自行安装第三方插件：
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 https://web.archive.org/web/20210805113249/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
v8.1.0 移除 Valine
Valine 使用 Leancloud 作为后端，是一个深受静态博客用户喜爱的评论系统。然而 Valine 暴露出了一些令人担忧的问题：
Valine 自 1.4 版本起不再开源，发布的打包版本中存在未告知用户的百度统计代码；
2020 年 11 月下旬出现了针对 Valine 的垃圾评论攻击；
CVE-2021-34801
考虑到这些问题已经严重影响到 NexT 用户的数据安全，我们决定将其移除，需要继续使用的用户请安装插件： https://github.com/next-theme/hexo-next-valine appid 和 appkey 改为 appId 和 appKey）任何 问题，请在这里反馈： https://github.com/xCss/Valine/issues 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 出现问题的插件或服务
参考文章：busuanzi 访问量统计与 live2d 插件同时使用导致 busuanzi 不显示的根本原因以及解决方法 - ouuan's blog
其它常见问题
在 Hexo 的 _config.yml 中有一些选项可以修改页面的永久链接形式（permalink）。而 NexT 所集成的评论系统可能需要通过页面的 URL 加载对应的数据。如非必要，请不要修改有关设置，以免评论数据丢失。
如果自定义了部分元素的 opacity，那么这会创建新的层叠上下文，进而影响其它元素的 z-index 表现，例如导致搜索框显示不正常（本地搜索框被覆盖 theme-next/hexo-theme-next#914
Group Picture 推荐与 FancyBox 插件一同使用。如果在一行中包含宽高比不同的图片，MediumZoom 可能会在放大时错误地计算图片尺寸。(images in a row with hardcoded height, look bad when zoomed in francoischalifour/medium-zoom#147 (comment)
不蒜子计数依赖于浏览器请求中的 Referer 信息来获取页面的访问量数据。如果你使用的浏览器具有阻止跨站追踪功能（例如 Safari），那么浏览器可能会忽略网站设定而使用最严格的 Referrer-Policy，导致加载的访问量数据不准确。另见 https://caniuse.com/referrer-policy
Issue 和 Pull Request 规范
提交 Issue
为了更快地解决问题，在使用 NexT 主题遇到 Bug 时，可以先自行按照以下方法排查（因为问题可能并非来自 NexT 主题本身）： https://theme-next.js.org/docs/troubleshooting.html#Quick-Debug-Instructions
如果对主题进行过自定义，那么请移除全部的自定义文件，检查 Bug 是否仍然存在。
如果是在升级 Hexo 或 Hexo 插件后遇到的问题，请尝试：
将全部 Hexo 插件都升级到最新版本（以避免 Hexo 版本兼容性问题），可以使用 npm-check 等工具辅助；
如果报错信息来自第三方插件，可以卸载插件或将 Hexo 退回旧版本，一些插件可能由于长时间未更新，与新版 Hexo 不兼容；
按照本「更新说明」的指导，在清楚更新内容的情况下，升级 NexT 主题至最新版本。
关于 Pull Request
我们非常欢迎通过 Pull Request 来加入新功能或修复 Bug。在修改主题的样式时，请注意考虑 NexT 主题四个 Scheme 之间的差异。这可能要求额外的代码来确保样式的一致性，并避免改动对于其它 Scheme 的破坏。此外，配色方案的设计也需要考虑暗色模式的支持。
欢迎加入 Telegram 群聊或参与 GitHub 上的讨论，许多关键的改动都会通过投票的方式征求意见。
感谢各位对 NexT 主题及 NexT 团队的支持。祝使用愉快！
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.
以下是对 NexT 使用过程中常见问题的说明。
NexT 主题会尽可能保证配置文件向下兼容，使得用户能够平滑升级。但在 NexT 主题不断发展和完善的过程中，难免会出现配置和使用方式的变化。因此，在每次更新主题前，请务必阅读更新说明，特别是
Breaking Change部分（这涉及到了一些重大更新，可能影响先前的用户配置或自定义）。为了避免操作失误导致配置文件冲突或源码丢失，我们建议使用 Git 等工具对博客源码做好版本管理和备份。这样做有很多好处，比如你可以使用 GitHub Actions 来自动进行博客部署，也可以随时回退到历史版本。
NexT 一贯以「开箱即用」为目标，尽量将简洁易懂的配置提供给用户。不过，虽然
_config.yml配置文件中对很多配置选项都提供了注释，但一些选项的细节并没有完全展现。为了避免出现问题，请在进行配置和使用前阅读网站 https://theme-next.js.org 上对应的文档。对于文档中描述不清楚的地方，欢迎提出改进建议 😊此外，通过搜索引擎可以找到许多 NexT 热心用户创作的教程文章。不过，在过去的数年时间里，NexT 新增了大量的 Feature，有部分内容是常见的教程没有涵盖的。后文中摘录了部分 NexT v7 版本的新功能及使用说明，供参考。
问题反馈方式
使用 NexT 时遇到了问题？不用担心！有许多种方法可以与 NexT 主题开发/维护者团队（下称「NexT 团队」）或其他用户取得联系，共同解决问题：
环境
我们通过 GitHub Actions 进行自动化测试，确保 NexT 可以在 Windows，macOS 以及 Linux 上正常使用： https://github.com/next-theme/hexo-theme-next/actions?query=workflow%3ATester
Hexo 支持直接在 Windows 上运行，安装 Node.js 即可。使用 WSL 安装也是可以的。不推荐使用 mingw 环境。
如果可能，请始终使用最新版本的 Hexo 和 NexT。新版本 Hexo 带来的渲染性能的提升非常显著。
NexT 仓库
NexT 一共有三个不同的仓库：
一些网络教程可能使用了旧仓库的链接。为了避免安装过时的 NexT 版本，请务必按照本仓库 README 中提供的几种安装方式进行操作，安装最新的 v8 版本的主题。
跨版本的升级可能并不顺滑（例如由 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.htmlCustom 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.htmlHexo 5.0 版本移除了对于 swig 模版的支持。如果你发现 Hexo 生成的 html 中输出了 NexT 模版源码，说明你正在使用旧版本的 NexT，请重新安装或升级 NexT。
v7.6.0
auto_excerpt自 7.6.0 版本开始，
auto_excerpt功能被移除，因为按照字数截断文章，必须先移除其中的 HTML 标签，这将导致图片、代码块显示错误，不符合 NexT 的设计原则。我们推荐通过<!-- more -->来精确控制 Read More 的位置。当然，也可以自行安装第三方插件：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://web.archive.org/web/20210805113249/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 用户的数据安全，我们决定将其移除，需要继续使用的用户请安装插件： 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 出现问题的插件或服务
参考文章：busuanzi 访问量统计与 live2d 插件同时使用导致 busuanzi 不显示的根本原因以及解决方法 - ouuan's blog
其它常见问题
_config.yml中有一些选项可以修改页面的永久链接形式（permalink）。而 NexT 所集成的评论系统可能需要通过页面的 URL 加载对应的数据。如非必要，请不要修改有关设置，以免评论数据丢失。opacity，那么这会创建新的层叠上下文，进而影响其它元素的z-index表现，例如导致搜索框显示不正常（本地搜索框被覆盖 theme-next/hexo-theme-next#914）Issue 和 Pull Request 规范
提交 Issue
为了更快地解决问题，在使用 NexT 主题遇到 Bug 时，可以先自行按照以下方法排查（因为问题可能并非来自 NexT 主题本身）： https://theme-next.js.org/docs/troubleshooting.html#Quick-Debug-Instructions
如果对主题进行过自定义，那么请移除全部的自定义文件，检查 Bug 是否仍然存在。
如果是在升级 Hexo 或 Hexo 插件后遇到的问题，请尝试：
关于 Pull Request
我们非常欢迎通过 Pull Request 来加入新功能或修复 Bug。在修改主题的样式时，请注意考虑 NexT 主题四个 Scheme 之间的差异。这可能要求额外的代码来确保样式的一致性，并避免改动对于其它 Scheme 的破坏。此外，配色方案的设计也需要考虑暗色模式的支持。
欢迎加入 Telegram 群聊或参与 GitHub 上的讨论，许多关键的改动都会通过投票的方式征求意见。
感谢各位对 NexT 主题及 NexT 团队的支持。祝使用愉快！