常见问题

本文档汇总了使用 ModernDuang 主题过程中的常见问题及解决方案。如果你遇到的问题未在此列出，欢迎在 GitHub Issues 中提出。

1. 如何更新主题？

ModernDuang 通过 npm 安装，因此可以使用 npm 命令直接更新：

npm update hexo-theme-modernduang --save

更新后，建议执行以下操作：

# 清理 Hexo 缓存与生成文件
hexo clean

# 重新生成站点
hexo generate

注意： 更新前请查看主题的 Changelog，了解是否存在破坏性变更。如果你已经自定义了主题源文件，更新可能会覆盖这些修改。建议始终通过 _config.modernduang.yml 和 source/ 目录进行自定义，避免直接修改主题文件。

2. 暗色模式不生效？

如果暗色模式无法正常工作，请逐步排查以下问题：

检查配置

确认 _config.modernduang.yml 中已启用暗色模式：

dark_mode:
  enable: true       # 必须为 true
  default: light     # 或 dark

清除 localStorage

暗色模式的用户偏好会存储在浏览器的 localStorage 中。如果切换状态异常，请清除该数据：

打开浏览器开发者工具（F12）
进入 Application（应用程序）面板
在左侧选择 Local Storage -> 你的站点域名
找到 theme 键并删除
刷新页面

或者直接在控制台执行：

localStorage.removeItem('theme');
location.reload();

检查浏览器支持

暗色模式依赖 CSS 的 prefers-color-scheme 媒体查询。如果你的浏览器版本较旧（如 IE），可能不支持该特性。请使用最新版本的 Chrome、Firefox、Safari 或 Edge。

检查 CSS 冲突

如果你在 source/css/main.css 中添加了自定义样式，确保没有覆盖暗色模式的 CSS 变量。检查是否有选择器优先级高于 [data-theme="dark"] 的情况。

3. 如何设置 Twikoo 评论？

ModernDuang 使用 Twikoo 作为评论系统。以下是完整的设置步骤：

第一步：获取 envId

Twikoo 支持多种部署方式，推荐使用腾讯云 CloudBase：

访问腾讯云 CloudBase 控制台
创建一个云开发环境（选择按量计费即可，有免费额度）
进入环境 -> 「环境设置」->「登录授权」，开启「匿名登录」
进入环境 -> 「云函数」，点击「新建云函数」
函数名称随意填写，在「函数代码」中上传 Twikoo 的云函数代码包（从 Twikoo 发布页下载 twikoo-cloudbase-*.zip）
部署完成后，在云函数详情页获取「触发路径」，即为你的 envId

其他部署方式（Vercel、Docker、Railway）请参考 Twikoo 文档。

第二步：配置主题

将获取到的 envId 填入 _config.modernduang.yml：

comments:
  twikoo:
    envId: https://your-env-id.ap-shanghai.tcb.qcloud.la/twikoo  # 你的完整触发路径
    region: ap-shanghai

提示： region 需与你 CloudBase 环境的地域一致。国内用户通常选 ap-shanghai 或 ap-guangzhou。

第三步：验证

重新生成站点并访问任意文章页面，页面底部应出现 Twikoo 评论框。首次加载可能需要几秒钟初始化。

禁用单篇文章的评论

在文章的 Front Matter 中添加：

---
title: 我的文章
comment: false
---

4. 如何添加 Google Analytics 等统计代码？

有几种方式可以添加统计代码：

方法一：通过页脚 custom HTML（推荐）

在 _config.modernduang.yml 的 footer.custom 中注入脚本：

footer:
  custom: |
    <!-- Google Analytics -->
    <script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'G-XXXXXXXXXX');
    </script>

方法二：通过 layout 注入

如果需要将脚本放在 <head> 中，可以编辑 layout/partials/header.ejs，在 <head> 标签内添加脚本。不过此方法需要直接修改主题文件，更新主题时可能会被覆盖。

支持的统计服务

以下统计服务均可通过相同方式集成：

统计服务	代码注入位置
Google Analytics (GA4)	`footer.custom` 或 `<head>`
百度统计	`footer.custom`
不蒜子	`footer.custom`
CNZZ（友盟）	`footer.custom`
Microsoft Clarity	`footer.custom` 或 `<head>`

5. 友链为什么不显示？

如果友链页面无法正常显示，请检查以下方面：

检查 group 名称匹配

友链项中的 group 字段必须与 friendGroups 中定义的键名完全一致（区分大小写）：

# 正确示例
friendGroups:
  技术伙伴: 🌟
  朋友们: 🤝

friends:
  - name: 示例博客
    url: https://example.com
    desc: 一个很棒的博客
    avatar: https://example.com/avatar.png
    group: 技术伙伴        # 必须与 friendGroups 的键完全一致

常见错误：

group 值与 friendGroups 键名大小写不匹配
使用了 friendGroups 中未定义的分组名称
friendGroups 为空（{}）但友链项中指定了 group

检查 YAML 缩进

YAML 对缩进非常敏感。确保 friends 数组和 friendGroups 的缩进正确：

# 正确缩进
friendGroups:
  朋友们: 🤝

friends:
  - name: 示例博客      # 注意：连字符后有一个空格
    url: https://example.com   # 属性缩进对齐
    desc: 一个很棒的博客
    avatar: https://example.com/avatar.png
    group: 朋友们

验证友链页面已生成

确认 Hexo 已正确生成友链页面：

hexo clean && hexo generate

检查 public/links/index.html 是否已生成。

6. 如何绑定自定义域名？

第一步：配置 CNAME

在 Hexo 站点的 source/ 目录下创建 CNAME 文件（注意无扩展名、全大写）：

echo "yourdomain.com" > source/CNAME

注意： CNAME 文件必须放在 source/ 目录下，这样每次 hexo generate 时它会自动复制到 public/ 目录的根位置。

第二步：配置 DNS

在你的域名 DNS 管理面板中添加记录：

如果使用 GitHub Pages：

记录类型	主机记录	记录值
CNAME	@	`yourusername.github.io`
CNAME	www	`yourusername.github.io`

如果使用 Vercel / Netlify：

请参考对应平台的文档，通常需要在平台控制台中添加自定义域名，并按提示配置 DNS。

第三步：验证

DNS 解析生效可能需要几分钟到 48 小时。生效后访问你的自定义域名即可看到博客。

7. 如何更改主题色？

ModernDuang 的主题色通过 CSS 变量 --primary 控制。编辑 source/css/main.css，覆盖该变量：

:root {
  --primary: #E8A0BF;        /* 粉色主题 */
  --primary-light: #F2C4D5;
  --primary-dark: #C97A9A;
}

/* 暗色模式下的主题色 */
[data-theme="dark"] {
  --primary: #F2C4D5;
  --primary-light: #FFD4E5;
  --primary-dark: #E8A0BF;
}

常见配色方案参考

风格	--primary	--primary-dark
经典蓝（默认）	`#6C9BCF`	`#4A7BB7`
樱花粉	`#E8A0BF`	`#C97A9A`
薄荷绿	`#7EC8A0`	`#5AA37A`
暖橙色	`#F0A060`	`#D08040`
薰衣草紫	`#A78BFA`	`#7C5CE7`

更改其他颜色元素

你可以同时覆盖更多 CSS 变量来全面定制配色：

:root {
  --primary: #7EC8A0;
  --primary-light: #A8E6C3;
  --primary-dark: #5AA37A;
  --bg-primary: #F7FCF9;     /* 调整背景色 */
  --shadow-sm: 0 2px 8px rgba(126, 200, 160, 0.15);  /* 带主题色的阴影 */
}

8. Mermaid 图表不渲染？

如果 Mermaid 图表在页面上显示为原始代码而非图表，请按以下步骤排查：

检查 Front Matter

确保文章头部设置了 mermaid: true：

---
title: 我的流程图文章
date: 2024-01-01
mermaid: true
---

如果没有设置 mermaid: true，主题不会在页面中加载 Mermaid 渲染脚本。

检查代码块语法

Mermaid 代码块必须使用正确的标记语言标识：

```mermaid
graph TD
    A[开始] --> B{判断}
    B -->|是| C[执行]
    B -->|否| D[结束]
```

确保代码块的语言标识是 mermaid（全部小写）。

查看浏览器控制台

打开开发者工具（F12）的 Console 面板，查看是否有 Mermaid 相关的错误信息：

mermaid is not defined — Mermaid 脚本未能加载，检查网络请求是否被拦截
语法错误 — 检查 Mermaid 图表语法是否正确
渲染错误 — 可能是 Mermaid 版本与语法不兼容

检查 CDN 访问

Mermaid 脚本从 CDN 加载。如果你是国内用户，CDN 可能被墙或加载缓慢。可以尝试在 source/js/main.js 中手动引入国内 CDN 镜像：

// 使用国内 CDN 镜像加载 Mermaid
if (document.querySelector('.mermaid')) {
  var script = document.createElement('script');
  script.src = 'https://cdn.bootcdn.net/ajax/libs/mermaid/10.6.1/mermaid.min.js';
  script.onload = function() {
    mermaid.initialize({ startOnLoad: true, theme: 'default' });
  };
  document.body.appendChild(script);
}

9. 如何从其他主题迁移？

从其他 Hexo 主题迁移到 ModernDuang 的步骤如下：

第一步：备份现有配置

在迁移之前，务必备份你的 Hexo 站点：

cp -r your-hexo-site your-hexo-site-backup

第二步：安装 ModernDuang

cd your-hexo-site
npm install hexo-theme-modernduang --save

第三步：切换主题

编辑 Hexo 站点根目录的 _config.yml：

theme: modernduang

第四步：创建主题配置文件

cp themes/modernduang/_config.yml _config.modernduang.yml

第五步：迁移设置

根据你之前的主题配置，逐一将相应设置迁移到 _config.modernduang.yml：

需迁移的设置	ModernDuang 对应配置
导航菜单	`menu`
社交媒体链接	`profile.social`
评论系统	`comments.twikoo`
友链数据	`friends` 和 `friendGroups`
页脚信息	`footer`
Google Analytics 等脚本	`footer.custom`
头像和座右铭	`profile.avatar` 和 `profile.motto`

第六步：清理并生成

hexo clean
hexo generate
hexo server

需要注意的兼容性问题

ModernDuang 使用 EJS 模板引擎。如果你之前的主题使用了其他模板引擎（如 Pug、Swiq 等），自定义的模板代码无法直接复用。
评论系统仅支持 Twikoo。如果你之前使用 Valine、Gitalk 等，需要迁移到 Twikoo 或通过自定义脚本集成。
文章和页面的 Markdown 内容是通用的，不受主题切换影响。

10. 如何添加新页面？

第一步：创建页面

使用 Hexo 命令创建新页面：

hexo new page about

这会在 source/about/index.md 创建一个新页面。

第二步：编写页面内容

编辑 source/about/index.md，添加页面内容：

---
title: 关于我
date: 2024-01-01
type: page
---

## 关于我

你好！我是...

这是我的个人博客，主要分享...

### 联系方式

- GitHub: [@yourname](https://github.com/yourname)
- Email: [email protected]

第三步：添加到导航菜单

在 _config.modernduang.yml 的 menu 中添加链接：

menu:
  首页: /
  归档: /archives
  标签: /tags
  分类: /categories
  友链: /links
  关于: /about        # 添加新页面链接

第四步：生成与查看

hexo clean && hexo generate && hexo server

提示： 如果你创建的是独立页面（非文章），建议在 Front Matter 中设置 type: page 和 comment: false，以便主题正确处理。

11. 国内字体加载不了？

Google Fonts 在国内可能无法直接访问，导致字体加载失败或页面加载缓慢。

解决方法一：使用 Google Fonts 镜像

在 _config.modernduang.yml 中修改 font.host：

font:
  enable: true
  host: https://fonts.googleapis.cn   # 使用国内镜像
  global:
    external: true
    families:
      - Inter:wght@300;400;500;600
      - JetBrains+Mono:wght@400;500

常用的 Google Fonts 镜像站：

镜像站	地址
官方	`https://fonts.googleapis.com`
国内镜像 1	`https://fonts.googleapis.cn`
国内镜像 2	`https://fonts.loli.net`
国内镜像 3	`https://gstatic.loli.net`

解决方法二：使用国内字体 CDN

可以完全替换为国内字体服务。编辑 source/css/main.css：

@import url('https://fonts.googleapis.cn/css2?family=Inter:wght@300;400;500;600&display=swap');
@import url('https://fonts.googleapis.cn/css2?family=JetBrains+Mono:wght@400;500&display=swap');

同时将 font.enable 设为 false 以避免主题重复加载字体：

font:
  enable: false

解决方法三：使用本地字体

将字体文件下载到 source/fonts/ 目录，通过 @font-face 引入（参见自定义字体）。

12. 头像不显示？

头像显示异常通常由以下几个原因导致：

检查 URL 格式

确保头像 URL 是完整的绝对路径：

# 正确
profile:
  avatar: https://example.com/avatar.png

# 正确（使用 CDN）
profile:
  avatar: https://cdn.jsdelivr.net/gh/yourname/avatar.png

# 错误（相对路径可能无法正确解析）
profile:
  avatar: /images/avatar.png

如果使用本地图片，建议先将图片上传到图床或 CDN，然后使用绝对 URL。如果一定要使用本地图片，请使用相对于站点根目录的路径：

profile:
  avatar: /img/avatar.png   # 图片需放在 source/img/avatar.png

检查图片是否存在

确认图片 URL 可访问——直接在浏览器中打开该 URL，查看是否能正常加载。

检查 HTTPS 混用

如果你的站点使用 HTTPS，但头像 URL 使用 HTTP，浏览器可能会阻止加载。请始终使用 https:// 开头的 URL。

检查图片格式

确保图片格式为常见的 Web 格式（PNG、JPG、WebP、SVG）。某些特殊格式或损坏的图片文件可能无法显示。

检查 CDN 访问

如果你将图片托管在境外 CDN（如 GitHub 的 raw 链接），国内用户可能无法访问。建议使用国内可访问的图床或 CDN 服务。

仍有问题？

如果你遇到的问题未在本页提及，可以通过以下方式获取帮助：

GitHub Issues： 提交 Issue
查看源码： 阅读主题源码了解具体实现细节
参考 Hexo 官方文档： Hexo 文档涵盖了与主题无关的通用问题

提交 Issue 时请提供： 你的 _config.modernduang.yml 配置（隐去敏感信息）、浏览器控制台错误信息、Hexo 版本和 Node.js 版本。

#常见问题

#1. 如何更新主题？

#2. 暗色模式不生效？

#检查配置

#清除 localStorage

#检查浏览器支持

#检查 CSS 冲突

#3. 如何设置 Twikoo 评论？

#第一步：获取 envId

#第二步：配置主题

#第三步：验证

#禁用单篇文章的评论

#4. 如何添加 Google Analytics 等统计代码？

#方法一：通过页脚 custom HTML（推荐）

#方法二：通过 layout 注入

#支持的统计服务

#5. 友链为什么不显示？

#检查 group 名称匹配

#检查 YAML 缩进

#验证友链页面已生成

#6. 如何绑定自定义域名？

#第一步：配置 CNAME

#第二步：配置 DNS

#第三步：验证

#7. 如何更改主题色？

#常见配色方案参考

#更改其他颜色元素

#8. Mermaid 图表不渲染？

#检查 Front Matter

#检查代码块语法

#查看浏览器控制台

#检查 CDN 访问

#9. 如何从其他主题迁移？

#第一步：备份现有配置

#第二步：安装 ModernDuang

#第三步：切换主题

#第四步：创建主题配置文件

#第五步：迁移设置

#第六步：清理并生成

#需要注意的兼容性问题

#10. 如何添加新页面？

#第一步：创建页面

#第二步：编写页面内容

#第三步：添加到导航菜单

#第四步：生成与查看

#11. 国内字体加载不了？

#解决方法一：使用 Google Fonts 镜像

#解决方法二：使用国内字体 CDN

#解决方法三：使用本地字体

#12. 头像不显示？

#检查 URL 格式

#检查图片是否存在

#检查 HTTPS 混用

#检查图片格式

#检查 CDN 访问

#仍有问题？

#相关页面

常见问题

1. 如何更新主题？

2. 暗色模式不生效？

检查配置

清除 localStorage

检查浏览器支持

检查 CSS 冲突

3. 如何设置 Twikoo 评论？

第一步：获取 envId

第二步：配置主题

第三步：验证

禁用单篇文章的评论

4. 如何添加 Google Analytics 等统计代码？

方法一：通过页脚 custom HTML（推荐）

方法二：通过 layout 注入

支持的统计服务

5. 友链为什么不显示？

检查 group 名称匹配

检查 YAML 缩进

验证友链页面已生成

6. 如何绑定自定义域名？

第一步：配置 CNAME

第二步：配置 DNS

第三步：验证

7. 如何更改主题色？

常见配色方案参考

更改其他颜色元素

8. Mermaid 图表不渲染？

检查 Front Matter

检查代码块语法

查看浏览器控制台

检查 CDN 访问

9. 如何从其他主题迁移？

第一步：备份现有配置

第二步：安装 ModernDuang

第三步：切换主题

第四步：创建主题配置文件

第五步：迁移设置

第六步：清理并生成

需要注意的兼容性问题

10. 如何添加新页面？

第一步：创建页面

第二步：编写页面内容

第三步：添加到导航菜单

第四步：生成与查看

11. 国内字体加载不了？

解决方法一：使用 Google Fonts 镜像

解决方法二：使用国内字体 CDN

解决方法三：使用本地字体

12. 头像不显示？

检查 URL 格式

检查图片是否存在

检查 HTTPS 混用

检查图片格式

检查 CDN 访问

仍有问题？

相关页面