博客搭建配置

本文最后更新于：2025年4月29日 下午

Hexo

安装前提

安装 Hexo 相当简单，只需要先安装下列应用程序即可：

  • Node.js (Node.js 版本需不低于 10.13，建议使用 Node.js 12.0 及以上版本)
  • Git

如果您的电脑中已经安装上述必备程序，那么恭喜您！你可以直接前往 安装 Hexo 步骤。

如果您的电脑中尚未安装所需要的程序，请根据以下安装指示完成安装。

安装 Git

  • Windows：下载并安装 git.
  • Mac：使用 Homebrew, MacPorts 或者下载 安装程序。
  • Linux (Ubuntu, Debian)：sudo apt-get install git-core
  • Linux (Fedora, Red Hat, CentOS)：sudo yum install git-core

Mac 用户

如果在编译时可能会遇到问题，请先到 App Store 安装 Xcode，Xcode 完成后，启动并进入 Preferences -> Download -> Command Line Tools -> Install 安装命令行工具。

Windows 用户

对于中国大陆地区用户，可以前往 淘宝 Git for Windows 镜像 下载 git 安装包。

安装 Node.js

Node.js 为大多数平台提供了官方的 安装程序。对于中国大陆地区用户，可以前往 淘宝 Node.js 镜像 下载。

其它的安装方法：

  • Windows：通过 nvm 安装。
  • Mac：使用 Homebrew 或 MacPorts 安装。
  • Linux（DEB/RPM-based）：从 NodeSource 安装。
  • 其它：使用相应的软件包管理器进行安装，可以参考由 Node.js 提供的 指导。

对于 Mac 和 Linux 同样建议使用 nvm，以避免可能会出现的权限问题。

Windows 用户

使用 Node.js 官方安装程序时，请确保勾选 Add to PATH 选项（默认已勾选）

For Mac / Linux 用户

如果在尝试安装 Hexo 的过程中出现 EACCES 权限错误，请遵循 由 npmjs 发布的指导 修复该问题。强烈建议 不要 使用 root、sudo 等方法覆盖权限

Linux

如果您使用 Snap 来安装 Node.js，在 初始化 博客时您可能需要手动在目标文件夹中执行 npm install。

安装 Hexo

所有必备的应用程序安装完成后，即可使用 npm 安装 Hexo。

$ npm install -g hexo-cli

初始化 Hexo 项目

$ hexo init blog(项目名)
cd blog-demo  //进入blog-demo文件夹
npm i		 // 安装依赖

初始化项目后，blog有如下结构：

【node_modules】：依赖包
【scaffolds】：生成文章的一些模板
【source】：用来存放你的文章
【themes】：主题
【.npmignore】：发布时忽略的文件（可忽略）
【_config.landscape.yml】：主题的配置文件
【config.yml】：博客的配置文件
【package.json】：项目名称、描述、版本、运行和开发等信息

启动项目

hexo server或者hexo s

$ hexo s
================================
INFO  Validating config
INFO  Start processing
INFO  Hexo is running at http://localhost:4000 . Press Ctrl+C to stop.

挂载到GitHub Pages

安装 hexo-deployer-git

npm install hexo-deployer-git --save

修改 _config.yml 文件

修改最后一行的配置，将repository修改为你自己的github项目地址即可，还有分支要改为main代表主分支（注意缩进）。

deploy:
  type: git
  repository: git@github.com:Fomalhaut-Blog/Fomalhaut-Blog.github.io.git
  branch: main

修改好配置后，运行如下命令，将代码部署到 GitHub

hexo clean && hexo generate && hexo deploy  // Git BASH终端
hexo clean; hexo generate; hexo deploy  // VSCODE终端
  • hexo clean：删除之前生成的文件，若未生成过静态文件，可忽略此命令。
  • hexo generate：生成静态文章，可以用hexo g缩写
  • hexo deploy：部署文章，可以用hexo d缩写

如果出现Deploy done，则说明部署成功了。

image-20231025094812948

新建页面或分栏

新建页面

hexo new [layout] <title>

layout 是文章的布局，默认为post，可以先不写。[post(默认)、draft、page]
title 是文章的标题，也是文件的名字，存储在source/_posts下

新建分栏

hexo new page <title>

博客配置

官方文档

Butterfly - A Simple and Card UI Design theme for Hexo

安装butterfly主题

在你的博客根目录打开Git BASH命令窗口执行npm i hexo-theme-butterfly

npm i hexo-theme-butterfly

安装成功后可在【blog/node_modules】文件夹下找到hexo-theme-butterfly文件夹

升级方法：在博客根目录下，运行 npm update hexo-theme-butterfly。
升级前请将hexo-theme-butterfly文件夹备份，npm更新会直接覆盖成新的包。

应用主题

  1. 修改站点配置文件_config.yml，把主题改为butterfly

    theme: butterfly

  2. 如果你没有pug以及stylus的渲染器，请下载安装，这两个渲染器是Butterfly生成基础页面所需的依赖包：

    npm install hexo-renderer-pug hexo-renderer-stylus --save

  3. 为了减少升级主题后带来的不便，请使用以下方法（建议，可以不做，高度魔改的一般都不会升级主题了，不然魔改的会被覆盖掉）
    把主题文件夹中的 _config.yml 复制到 Hexo 根目录里（，同时重新命名为 _config.butterfly.yml。以后只需要在 _config.butterfly.yml进行配置即可生效。Hexo会自动合併主题中的_config.yml和 _config.butterfly.yml里的配置，如果存在同名配置，会使用_config.butterfly.yml的配置，其优先度较高。

Front-matter

Front-matter 是 markdown 文件最上方以---分隔的区域，用于指定个别档案的变数。

  • Page Front-matter 用于页面配置
  • Post Front-matter 用于文章页配置

Page Front-matter：

---
title:
date:
updated:
type:
comments:
description:
keywords:
top_img:
mathjax:
katex:
aside:
aplayer:
highlight_shrink:
---
写法 解释
title 【必需】页面标题
date 【必需】页面创建日期
type 【必需】标籤、分类和友情链接三个页面需要配置
updated 【可选】页面更新日期
description 【可选】页面描述
keywords 【可选】页面关键字
comments 【可选】显示页面评论模块(默认 true)
top_img 【可选】页面顶部图片
mathjax 【可选】显示mathjax(当设置mathjax的per_page: false时，才需要配置，默认 false)
kates 【可选】显示katex(当设置katex的per_page: false时，才需要配置，默认 false)
aside 【可选】显示侧边栏 (默认 true)
aplayer 【可选】在需要的页面加载aplayer的js和css,请参考文章下面的音乐 配置
highlight_shrink 【可选】配置代码框是否展开(true/false)(默认为设置中highlight_shrink的配置)

Post Front-matter：

---
title:
date:
updated:
tags:
categories:
keywords:
description:
top_img:
comments:
cover:
toc:
toc_number:
toc_style_simple:
copyright:
copyright_author:
copyright_author_href:
copyright_url:
copyright_info:
mathjax:
katex:
aplayer:
highlight_shrink:
aside:
---
写法 解释
title 【必需】文章标题
date 【必需】文章创建日期
updated 【可选】文章更新日期
tags 【可选】文章标籤
categories 【可选】文章分类
keywords 【可选】文章关键字
description 【可选】文章描述
top_img 【可选】文章顶部图片
cover 【可选】文章缩略图(如果没有设置top_img,文章页顶部将显示缩略图，可设为false/图片地址/留空)
comments 【可选】显示文章评论模块(默认 true)
toc 【可选】显示文章TOC(默认为设置中toc的enable配置)
toc_number 【可选】显示toc_number(默认为设置中toc的number配置)
toc_style_simple 【可选】显示 toc 简洁模式
copyright 【可选】显示文章版权模块(默认为设置中post_copyright的enable配置)
copyright_author 【可选】文章版权模块的文章作者
copyright_author_href 【可选】文章版权模块的文章作者链接
copyright_url 【可选】文章版权模块的文章连结链接
copyright_info 【可选】文章版权模块的版权声明文字
mathjax 【可选】显示mathjax(当设置mathjax的per_page: false时，才需要配置，默认 false)
katex 【可选】显示katex(当设置katex的per_page: false时，才需要配置，默认 false)
aplayer 【可选】在需要的页面加载aplayer的js和css,请参考文章下面的音乐 配置
highlight_shrink 【可选】配置代码框是否展开(true/false)(默认为设置中highlight_shrink的配置)
aside 【可选】显示侧边栏 (默认 true)

标签页

前往你的Hexo博客根目录，打开Git Bash执行如下命令：

hexo new page tags

在\source\会生成一个含有index.md文件的tags文件夹。

修改\source\tags\index.md，添加type: "tags"。

---
title: tags
date: 2022-10-28 12:00:00
type: "tags"
---

友情链接

前往你的Hexo博客根目录，打开cmd命令窗口执行如下命令：

hexo new page link

在[BlogRoot]\source\会生成一个含有index.md文件的link文件夹

修改[BlogRoot]\source\link\index.md，添加type: "link"

---
title: link
date: 2022-10-28 12:00:00
type: "link"
---

前往[BlogRoot]\source\_data创建一个link.yml文件（如果沒有 _data 文件夹，请自行创建），并写入如下信息（根据你的需要写）：

- class_name: 1.技术支持
  class_desc: 本网站的搭建由以下开源作者提供技术支持
  link_list: 
    - name: Hexo 
      link: https://hexo.io/zh-cn/
      avatar: https://d33wubrfki0l68.cloudfront.net/6657ba50e702d84afb32fe846bed54fba1a77add/827ae/logo.svg
      descr: 快速、简单且强大的网志框架
      siteshot: https://source.fomal.cc/siteshot/hexo.io.jpg
      
- class_name: 2.友情链接
  class_desc: 一些好朋友~~
  link_list:
    - name: Fomalhaut🥝
      link: https://fomal.cc/
      avatar: /assets/head.jpg
      descr: Future is now 🍭🍭🍭
      siteshot: https://source.fomal.cc/siteshot/www.fomal.cn.jpg

class_name和class_desc支持 html 格式，如不需要，也可以留空。

404页面

主題內置了一个简单的404页面，可在设置中开放。

如需本地预览，请访问 http://localhost:4000/404.html

# A simple 404 page
error_404:
  enable: true
  subtitle: "页面沒有找到"
  background:

博客网站配置

git

# 清除缓存，生成静态文件，部署到github 
hexo cl && hexo g && hexo d # git bash
hexo cl; hexo g; hexo d # vscode

Markdown语法与外挂标签写法汇总
https://www.fomal.cc/posts/5389e93f.html

{% note simple %}默认 提示块标签{% endnote %}

{% note default simple %}default 提示块标签{% endnote %}

{% note primary simple %}primary 提示块标签{% endnote %}

{% note success simple %}success 提示块标签{% endnote %}

{% note info simple %}info 提示块标签{% endnote %}

{% note warning simple %}warning 提示块标签{% endnote %}

{% note danger simple %}danger 提示块标签{% endnote %}
需要复制的 需要删除的
_config.yml：站点配置文件 .git：无论是在站点根目录下，还是主题目录下的.git文件，都可以删掉
_config.butterfly.yml：主题配置文件，为了方便主题升级剥离出来的配置文件 node_modules：npm install会根据package.json生成
package.json：说明使用哪些依赖包 public：hexo g会重新编译生成
scaffolds：文章的模板 .deploy_git：在使用hexo d时也会重新生成
source：自己写的博客源码 db.json文件：hexo s快速启动所需的数据库
themes：主题文件夹（魔改都在里面啦） package-lock.json：记录依赖之间的内部依赖关系，可以根据package.json重新生成
.gitignore：说明在提交时哪些文件可以忽略

嵌入B站视频

<div align=center class="aspect-ratio">
    <iframe src="https://player.bilibili.com/player.html?aid=247609487&bvid=BV1vv41177jq&cid=324439110&page=1&high_quality=1&danmaku=0" 
    scrolling="no" 
    border="0" 
    frameborder="no" 
    framespacing="0" 
    high_quality=1
    danmaku=1 
    allowfullscreen="true"> 
    </iframe>
</div>
视频质量 弹幕（0为默认关闭）
&high_quality=1 &danmaku=0

Aplayer歌单引入

必要的参数

data-id =>音乐页面链接上的id号

data-server => 平台名称。netease：网易；tencent：腾讯；xiami：虾米；kugou：酷狗；baidu：百度

data-type=>类型。playlist：歌单；song：单曲；专辑：album；关键词：search；歌手：artist

data-id data-server data-type
3778678 netease playlist
热歌榜 网易 歌单

GIThub工作流

在根目录创建.github，在里面新建文件夹workflows，新建dependblog.yml

name: publish site
on: # 在什么时候触发工作流
  push: # 在从本地main分支被push到GitHub仓库时
    branches:
      - main
  pull_request: # 在main分支合并别人提的pr时
    branches:
      - main
jobs: # 工作流的具体内容
  deploy:
    runs-on: ubuntu-latest # 创建一个新的云端虚拟机 使用最新Ubuntu系统
    steps:
      - uses: actions/checkout@v2 # 先checkout到main分支
      - uses: actions/setup-python@v2 # 再安装Python3和相关环境
        with:
          python-version: 3.x
      - run: pip install mkdocs-material # 使用pip包管理工具安装mkdocs-material
      - run: mkdocs gh-deploy --force # 使用mkdocs-material部署gh-pages分支

Algolia搜索写入索引

hexo algolia

Anzhiyu主题

写法 解释
title 【必需】文章标题
date 【必需】文章创建日期
updated 【可选】文章更新日期
tags 【可选】文章标签
categories 【可选】文章分类
keywords 【可选】文章关键字
description 【可选】文章描述
top_img 【可选】文章顶部图片
cover 【可选】文章缩略图(如果没有设置 top_img,文章页顶部将显示缩略图，可设为 false/图片地址/留空)
comments 【可选】显示文章评论模块(默认 true)
toc 【可选】显示文章 TOC(默认为设置中 toc 的 enable 配置)
toc_number 【可选】显示 toc_number(默认为设置中 toc 的 number 配置)
toc_style_simple 【可选】显示 toc 简洁模式
copyright 【可选】显示文章版权模块(默认为设置中 post_copyright 的 enable 配置)
copyright_author 【可选】文章版权模块的文章作者
copyright_author_href 【可选】文章版权模块的文章作者链接
copyright_url 【可选】文章版权模块的文章链接链接
copyright_info 【可选】文章版权模块的版权声明文字
mathjax 【可选】显示 mathjax(当设置 mathjax 的 per_page: false 时，才需要配置，默认 false)
katex 【可选】显示 katex(当设置 katex 的 per_page: false 时，才需要配置，默认 false)
aplayer 【可选】在需要的页面加载 aplayer 的 js 和 css,请参考文章下面的音乐 配置
highlight_shrink 【可选】配置代码框是否展开(true/false)(默认为设置中 highlight_shrink 的配置)
aside 【可选】显示侧边栏 (默认 true)
swiper_index 【可选】首页轮播图配置 index 索引，数字越小越靠前
top_group_index 【可选】首页右侧卡片组配置, 数字越小越靠前
background 【可选】文章背景可配置为 16 进制颜色值
  1. 首页轮播图配置: swiper_index, 数字越小越靠前
  2. 首页卡片配置: top_group_index, 数字越小越靠前
  3. page 中background, 可配置为 16 进制颜色值

Qexo

Hexo的管理界面

博客
#主题
博客搭建配置
https://junyyds.top/2023/05/17/博客搭建配置/
作者
Phils
发布于
2023年5月17日
更新于
2025年4月29日
许可协议