【Hexo】Hexo基本使用

Hexo官网：https://hexo.io/

Hexo Github: https://github.com/hexojs/hexo

Hexo Awesome: https://github.com/hexojs/awesome-hexo

1、初始化

需要node 环境，不再赘述node安装过程

推荐使用cnpm进行安装

npm install -g cnpm --registry=https://registry.npm.taobao.org

安装好后需要配置下环境变量，将 node_global目录添加到path环境变量

使用 cnpm -v 查看cnpm版本并验证是否安装配置成功

以下npm 命令可替换为 cnpm 命令

# 安装hexo脚手架
npm install hexo-cli -g

# 初始化 会自动创建一个blog目录
hexo init blog

# 切换到blog目录
cd blog

# 安装依赖
npm install

# 运行服务 可简写为 hexo s
hexo server

hexo 默认端口为4000，如果一切顺利的话，此时访问 localhost:4000 或者 127.0.0.1：4000 即可访问

初始化的项目会有篇Hello World的文章，文章源文件可以到 blog\source\_posts 目录内查看

2、常用命令

init

hexo init [folder]

新建一个网站。如果没有设置 folder ，Hexo 默认在目前的文件夹建立网站。

本命令相当于执行了以下几步：

Git clone hexo-starter 和 hexo-theme-landscape 主题到当前目录或指定目录。
使用 Yarn 1、pnpm 或 npm 包管理器下载依赖（如有已安装多个，则列在前面的优先）。npm 默认随 Node.js 安装。

new

hexo new [layout] <title>

新建一篇文章。如果没有设置 layout 的话，默认使用 _config.yml 中的 default_layout 参数代替。如果标题包含空格的话，请使用引号括起来。

hexo new "post title with whitespace"

参数	描述
`-p`, `--path`	自定义新文章的路径
`-r`, `--replace`	如果存在同名文章，将其替换
`-s`, `--slug`	文章的 Slug，作为新文章的文件名和发布后的 URL

默认情况下，Hexo 会使用文章的标题来决定文章文件的路径。对于独立页面来说，Hexo 会创建一个以标题为名字的目录，并在目录中放置一个 index.md 文件。你可以使用 --path 参数来覆盖上述行为、自行决定文件的目录：

hexo new page --path about/me "About me"

以上命令会创建一个 source/about/me.md 文件，同时 Front Matter 中的 title 为 "About me"

注意！title 是必须指定的！如果你这么做并不能达到你的目的：

hexo new page --path about/me

此时 Hexo 会创建 source/_posts/about/me.md，同时 me.md 的 Front Matter 中的 title 为 "page"。这是因为在上述命令中，hexo-cli 将 page 视为指定文章的标题、并采用默认的 layout。

generate

hexo generate

生成静态文件。

选项	描述
`-d`, `--deploy`	文件生成后立即部署网站
`-w`, `--watch`	监视文件变动
`-b`, `--bail`	生成过程中如果发生任何未处理的异常则抛出异常
`-f`, `--force`	强制重新生成文件 Hexo 引入了差分机制，如果 `public` 目录存在，那么 `hexo g` 只会重新生成改动的文件。使用该参数的效果接近 `hexo clean && hexo generate`
`-c`, `--concurrency`	最大同时生成文件的数量，默认无限制

该命令可以简写为

hexo g

publish

hexo publish [layout] <filename>

发表草稿。

server

hexo server

启动服务器。默认情况下，访问网址为： http://localhost:4000/。

选项	描述
`-p`, `--port`	重设端口
`-s`, `--static`	只使用静态文件
`-l`, `--log`	启动日记记录，使用覆盖记录格式

deploy

hexo deploy

部署网站。

参数	描述
`-g`, `--generate`	部署之前预先生成静态文件

该命令可以简写为：

 hexo d

clean

hexo clean

清除缓存文件 (db.json) 和已生成的静态文件 (public)。

在某些情况（尤其是更换主题后），如果发现您对站点的更改无论如何也不生效，您可能需要运行该命令。

list

hexo list <type>

列出网站数据。

version

 hexo version

显示 Hexo 版本。

3、提交到GitHub

3.1 创建仓库

在Github上新创建一个仓库，仓库名只能为 xxx.github.io

将xxx替换为github登录名，因为一会要用到Github pages服务

复制仓库地址

在_config.yml文件中添加仓库信息

deploy:
  type: git
  repo: https://github.com/xiangyangdev/xiangyangdev.github.io.git
  branch: master

注意 branch 默认主分支是 master 或者main

3.2 生成SSH并关联Github

首先需要配置一下Git的user.name和user.email信息

git config user.name "your github account"
git config user.email "your email"

这里的user.name输入你的GitHub用户名，user.email输入你GitHub的邮箱。这样GitHub才能知道你是不是对应它的账户,配置之后可以使用以下命令查看配置的用户信息

git config user.name
git config user.email

然后执行下面的命令创建SSH

ssh-keygen -t rsa -C "your email"

输入命令之后会提示输入密码，不用管直接一路回车，直到出现如下界面

然后可以在你的计算机用户（如WIndows为C:/Users/xxx/）下面看到自动生成了一个.ssh文件夹，可以看到.ssh文件下面有两个个文件id_rsa和id_rsa.pub

ssh，简单来讲，就是一个秘钥，其中，id_rsa是你这台电脑的私人秘钥，不能给别人看的，id_rsa.pub是公共秘钥，可以随便给别人看。把这个公钥放在GitHub上，这样当你连接自己的GitHub账户时，它就会根据公钥匹配你的私钥，当能够相互匹配时，才能够顺利的通过git上传你的文件到GitHub上。

到Github => 点击头像 => settings => SSH and GPG keys => new SSH key

Title可随意填写，把id_rsa.pub里面的内容复制到Key里面，然后点击Add SSH Key就可以了

输入下面的命令可以查看配置是否成功

ssh -T git@github.com

3.3 一键部署

安装 hexo-deployer-git 用于一键部署

npm install hexo-deployer-git --save

安装好后生成下静态文件

hexo generate  # 或者  hexo g

一键部署

hexo deploy # 或者 hexo d

若出现 ERROR Deployer not found: git 错误则表明hexo-deployer-git插件未安装成功，重新安装一下即可

当看到命令窗口打印INFO Deploy done:git就说明部署成功了，可以到github查看提交的代码

部署完成后稍等片刻你便可以访问 https://your_github_name.github.io/ 来预览你的博客了

3.2 跳过渲染 `README.md` 文件

通常情况下每个项目下都应该有一个 README.md 的项目介绍文件，但由于hexo仅保留 public 目录下的源码文件，如果我们想要保留 README.md文件，则需要在 source根目录创建该文件

然后修改_config.yml 下的skip_render 内容，跳过指定文件的渲染，添加需要忽略的文件或目录

修改完成之后需要重新清理缓存生成动态文件，你可以使用以下命令

hexo clean && hexo g && hexo d

然后在github上就能看到 README.md 文件了

3.3 绑定自定义域名

首先添加一条CNAME 记录，目标地址为github博客域名，即 your_github_name.github.io

然后在 source 目录下创建一个 CNAME 文件，注意不带后缀名

目录结构如下

把CNAME 文件添加到 skip_render ，跳过该文件的渲染

在github => settings => pages => Custom domain 关联我们的域名

开启强制HTTPS

如果不能开启需要检查DNS解析是否正常，CNAME记录不要开启小云朵，一般更换域名后一个小时左右再刷新该页面即可开启强制HTTPS

保存成功后就可以用我们关联的域名进行访问了

4、博客美化

4.1 更换主题

Hexo官网上面有非常多好看的主题，你可以选择自己喜欢的主题下载下来放到 themes文件夹下面

比较好看的主题有 Butterfly、Fluid、Indigo、Matery等，这里以更换为Matery主题为例。

首先点击官方下载地址下载 master 分支的最新稳定版的代码，解压缩后，将 hexo-theme-matery 的文件夹复制到你 Hexo 的 themes 文件夹中即可。

当然你也可以使用 git clone 命令来下载，例如下载Butterfly主题

cd blog
git clone -b master https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly

然后修改 Hexo 根目录下的 _config.yml 的 theme 的值：theme: butterfly

4.2 _config.yml配置说明

网站

参数	描述
`title`	网站标题
`subtitle`	网站副标题
`description`	网站描述
`keywords`	网站的关键词。支持多个关键词，多个用逗号分隔。
`author`	您的名字
`language`	网站使用的语言。对于简体中文用户来说，使用不同的主题可能需要设置成不同的值，请参考你的主题的文档自行设置，常见的有 `zh-Hans`和 `zh-CN`。
`timezone`	网站时区。Hexo 默认使用您电脑的时区。请参考时区列表进行设置，如 `America/New_York`, `Japan`, 和 `UTC` 。一般的，对于中国大陆地区可以使用 `Asia/Shanghai`。

其中，description 主要用于SEO，告诉搜索引擎一个关于您站点的简单描述，通常建议在其中包含您网站的关键词。author 参数用于主题显示文章的作者。

示例：

title: 時光
subtitle: '時光的博客园子'
description: '時光的博客园子'
keywords: '博客,時光,時光的博客,時光博客园子,实用博客,开源,共享'
author: 時光
language: zh-CN
timezone: 'Asia/Shanghai'

网址

参数	描述	默认值
`url`	网址, 必须以 `http://` 或 `https://` 开头
`root`	网站根目录	`url's pathname`
`permalink`	文章的永久链接格式	`:year/:month/:day/:title/`
`permalink_defaults`	永久链接中各部分的默认值
`pretty_urls`	改写 `permalink` 的值来美化 URL
`pretty_urls.trailing_index`	是否在永久链接中保留尾部的 `index.html`，设置为 `false` 时去除	`true`
`pretty_urls.trailing_html`	是否在永久链接中保留尾部的 `.html`, 设置为 `false` 时去除 (对尾部的 `index.html`无效)	`true`

网站存放在子目录

如果您的网站存放在子目录中，例如 http://example.com/blog，则请将您的 url 设为 http://example.com/blog 并把 root 设为 /blog/。

例如：

# 比如，一个页面的永久链接是 http://example.com/foo/bar/index.html
pretty_urls:
  trailing_index: false
# 此时页面的永久链接会变为 http://example.com/foo/bar/

示例：

# URL
## Set your site url here. For example, if you use GitHub Page, set url as 'https://username.github.io/project'
url: https://blog.shiguangdev.eu.org
permalink: :year/:month/:day/:hash/
permalink_defaults:
pretty_urls:
  trailing_index: true # Set to false to remove trailing 'index.html' from permalinks
  trailing_html: true # Set to false to remove trailing '.html' from permalinks

参数	描述	默认值
`source_dir`	资源文件夹，这个文件夹用来存放内容。	`source`
`public_dir`	公共文件夹，这个文件夹用于存放生成的站点文件。	`public`
`tag_dir`	标签文件夹	`tags`
`archive_dir`	归档文件夹	`archives`
`category_dir`	分类文件夹	`categories`
`code_dir`	Include code 文件夹，`source_dir` 下的子目录	`downloads/code`
`i18n_dir`	国际化（i18n）文件夹	`:lang`
`skip_render`	跳过指定文件的渲染。匹配到的文件将会被不做改动地复制到 `public` 目录中。您可使用 glob 表达式来匹配路径。

例如：

skip_render: "mypage/**/*"
# 将会直接将 `source/mypage/index.html` 和 `source/mypage/code.js` 不做改动地输出到 'public' 目录
# 你也可以用这种方法来跳过对指定文章文件的渲染
skip_render: "_posts/test-post.md"
# 这将会忽略对 'test-post.md' 的渲染

提示

如果您刚刚开始接触 Hexo，通常没有必要修改这一部分的值。

示例：

# Directory
source_dir: source
public_dir: public
tag_dir: tags
archive_dir: archives
category_dir: categories
code_dir: downloads/code
i18n_dir: :lang
skip_render: 
 - "README.md"
 - "CNAME"

文章

参数	描述	默认值
`new_post_name`	新文章的文件名称	`:title.md`
`default_layout`	预设布局	`post`
`auto_spacing`	在中文和英文之间加入空格	`false`
`titlecase`	把标题转换为 title case	`false`
`external_link`	在新标签中打开链接	`true`
`external_link.enable`	在新标签中打开链接	`true`
`external_link.field`	对整个网站（`site`）生效或仅对文章（`post`）生效	`site`
`external_link.exclude`	需要排除的域名。主域名和子域名如 `www` 需分别配置	`[]`
`filename_case`	把文件名称转换为 (1) 小写或 (2) 大写	`0`
`render_drafts`	显示草稿	`false`
`post_asset_folder`	启用资源文件夹	`false`
`relative_link`	把链接改为与根目录的相对位址	`false`
`future`	显示未来的文章	`true`
`highlight`	代码块的设置, 请参考 Highlight.js 进行设置
`prismjs`	代码块的设置, 请参考 PrismJS 进行设置

相对地址

默认情况下，Hexo 生成的超链接都是绝对地址。例如，如果您的网站域名为 example.com，您有一篇文章名为 hello，那么绝对链接可能像这样：http://example.com/hello.html，它是绝对于域名的。相对链接像这样：/hello.html，也就是说，无论用什么域名访问该站点，都没有关系，这在进行反向代理时可能用到。通常情况下，建议使用绝对地址。

分类 & 标签

参数	描述	默认值
`default_category`	默认分类	`uncategorized`
`category_map`	分类别名
`tag_map`	标签别名

日期 / 时间格式

Hexo 使用 Moment.js 来解析和显示时间。

参数	描述	默认值
`date_format`	日期格式	`YYYY-MM-DD`
`time_format`	时间格式	`HH:mm:ss`
`updated_option`	当 Front Matter 中没有指定 `updated` 时 `updated` 的取值	`mtime`

updated_option

updated_option 控制了当 Front Matter 中没有指定 updated 时，updated 如何取值：

mtime: 使用文件的最后修改时间。这是从 Hexo 3.0.0 开始的默认行为。
date: 使用 date 作为 updated 的值。可被用于 Git 工作流之中，因为使用 Git 管理站点时，文件的最后修改日期常常会发生改变
empty: 直接删除 updated。使用这一选项可能会导致大部分主题和插件无法正常工作。

use_date_for_updated 选项已经在 v7.0.0+ 中被移除。请改为使用 updated_option: 'date'。

分页

参数	描述	默认值
`per_page`	每页显示的文章量 (0 = 关闭分页功能)	`10`
`pagination_dir`	分页目录	`page`

例如：

pagination_dir: 'page'
# http://example.com/page/2

pagination_dir: 'awesome-page'
# http://example.com/awesome-page/2

扩展

参数	描述
`theme`	当前主题名称。值为`false`时禁用主题
`theme_config`	主题的配置文件。在这里放置的配置会覆盖主题目录下的 `_config.yml` 中的配置
`deploy`	部署部分的设置
`meta_generator`	Meta generator 标签。值为 `false` 时 Hexo 不会在头部插入该标签

示例：

## Themes
theme: butterfly

# Deployment
deploy:
  type: git
  repo: https://github.com/xxxxxxxxx/xxxxxxxxx.github.io.git
  branch: master

包括或不包括目录和文件

在 Hexo 配置文件中，通过设置 include/exclude 可以让 Hexo 进行处理或忽略某些目录和文件夹。你可以使用 glob 表达式对目录和文件进行匹配。

include 和 exclude 选项只会应用到 source/ ，而 ignore 选项会应用到所有文件夹.

参数	描述
`include`	Hexo 默认会不包括 `source/` 下的文件和文件夹（包括名称以下划线和 `.` 开头的文件和文件夹，Hexo 的 `_posts` 和 `_data` 等目录除外）。通过设置此字段将使 Hexo 处理他们并将它们复制到 `source` 目录下。
`exclude`	Hexo 不包括 `source/` 下的这些文件和目录
`ignore`	Hexo 会忽略整个 Hexo 项目下的这些文件夹或文件

例如：

# 处理或不处理目录或文件
include:
  - ".nojekyll"
  # 处理 'source/css/_typing.css'
  - "css/_typing.css"
  # 处理 'source/_css/' 中的任何文件，但不包括子目录及其其中的文件。
  - "_css/*"
  # 处理 'source/_css/' 中的任何文件和子目录下的任何文件
  - "_css/**/*"

exclude:
  # 不处理 'source/js/test.js'
  - "js/test.js"
  # 不处理 'source/js/' 中的文件、但包括子目录下的所有目录和文件
  - "js/*"
  # 不处理 'source/js/' 中的文件和子目录下的任何文件
  - "js/**/*"
  # 不处理 'source/js/' 目录下的所有文件名以 'test' 开头的文件，但包括其它文件和子目录下的单文件
  - "js/test*"
  # 不处理 'source/js/' 及其子目录中任何以 'test' 开头的文件
  - "js/**/test*"
  # 不要用 exclude 来忽略 'source/_posts/' 中的文件。你应该使用 'skip_render'，或者在要忽略的文件的文件名之前加一个下划线 '_'
  # 在这里配置一个 - "_posts/hello-world.md" 是没有用的。

ignore:
  # 忽略任何一个名叫 'foo' 的文件夹
  - "**/foo"
  # 只忽略 'themes/' 下的 'foo' 文件夹
  - "**/themes/*/foo"
  # 对 'themes/' 目录下的每个文件夹中忽略名叫 'foo' 的子文件夹
  - "**/themes/**/foo"

列表中的每一项都必须用单引号或双引号包裹起来。

include 和 exclude 并不适用于 themes/ 目录下的文件。如果需要忽略 themes/ 目录下的部分文件或文件夹，可以使用 ignore 或在文件名之前添加下划线 _。

source/_posts 文件夹是一个例外，但该文件夹下任何名称以 _ 开头的文件或文件夹仍会被忽略。不建议在该文件夹中使用 include 规则。

使用代替配置文件

可以在 hexo-cli 中使用 --config 参数来指定自定义配置文件的路径。你可以使用一个 YAML 或 JSON 文件的路径，也可以使用逗号分隔（无空格）的多个 YAML 或 JSON 文件的路径。例如：

# 用 'custom.yml' 代替 '_config.yml'
$ hexo server --config custom.yml

# 使用 'custom.yml' 和 'custom2.json'，优先使用 'custom3.yml'，然后是 'custom2.json'
$ hexo generate --config custom.yml,custom2.json,custom3.yml

当你指定了多个配置文件以后，Hexo 会按顺序将这部分配置文件合并成一个 _multiconfig.yml。如果遇到重复的配置，排在后面的文件的配置会覆盖排在前面的文件的配置。这个原则适用于任意数量、任意深度的 YAML 和 JSON 文件。

例如，使用 --config 指定了两个自定义配置文件：

hexo generate --config custom.yml,custom2.json

如果 custom.yml 中指定了 foo: bar，在 custom2.json 中指定了 "foo": "dinosaur"，那么在 _multiconfig.yml 中你会得到 foo: dinosaur。

使用代替主题配置文件

通常情况下，Hexo 主题是一个独立的项目，并拥有一个独立的 _config.yml 配置文件。

除了自行维护独立的主题配置文件，你也可以在其它地方对主题进行配置。

配置文件中的 theme_config

该特性自 Hexo 2.8.2 起提供

# _config.yml
theme: "my-theme"
theme_config:
  bio: "My awesome bio"
  foo:
    bar: 'a'
# themes/my-theme/_config.yml
bio: "Some generic bio"
logo: "a-cool-image.png"
  foo:
    baz: 'b'

最终主题配置的输出是：

{
  bio: "My awesome bio",
  logo: "a-cool-image.png",
  foo: {
    bar: "a",
    baz: "b"
  }
}

独立的 _config.[theme].yml 文件

该特性自 Hexo 5.0.0 起提供

独立的主题配置文件应放置于站点根目录下，支持 yml 或 json 格式。需要配置站点 _config.yml 文件中的 theme 以供 Hexo 寻找 _config.[theme].yml 文件。

# _config.yml
theme: "my-theme"
# _config.my-theme.yml
bio: "My awesome bio"
foo:
  bar: 'a'
# themes/my-theme/_config.yml
bio: "Some generic bio"
logo: "a-cool-image.png"
  foo:
    baz: 'b'

最终主题配置的输出是：

{
  bio: "My awesome bio",
  logo: "a-cool-image.png",
  foo: {
    bar: "a",
    baz: "b"
  }
}

我们强烈建议你将所有的主题配置集中在一处。如果你不得不在多处配置你的主题，那么这些信息对你将会非常有用：Hexo 在合并主题配置时，Hexo 配置文件中的 theme_config 的优先级最高，其次是 _config.[theme].yml 文件，最后是位于主题目录下的 _config.yml 文件。

5、数据备份与迁移

可参考文章

Hexo 自动备份
Hexo 自动部署
批量备份迁移 Markdown 文件中的图片解决方案
蓝空图床数据迁移

6、其他设置

6.1、文章置顶

修改 Front-Matter信息，添加sticky属性 sticky 值越大，置顶越靠前。

---
title: xxxxx
tags:
  - xxxxx
sticky: 10
date: 2024-05-11 20:05:11
---

常见错误

2.1 `Cannot find module 'esprima'`

手动安装一下即可

npm install esprima

2.2 `Asset render failed: css/style.css`

由于无法加载css，访问服务如下所示

升级一下 hexo版本即可

查看hexo 版本

hexo version

升级命令如下：

npm i hexo-cli -g
npm update

参考

hexo 版本升级

Butterfly

使用Hexo免费搭建个人博客教程

hexo域名解析的两种方法