轻松搭建个性化博客，最全Hexo部署教程来袭！

发表于 2023-04-10 分类于博客部署本文字数： 4.4k 阅读时长 ≈ 16 分钟

当今社交媒体的兴起让个人网站逐渐失去了其往日的荣耀，但对于一些喜欢写作、分享的人来说，拥有一个独立的博客仍然是非常有吸引力的。Hexo 是一个基于 Node.js 的静态博客生成器，它可以轻松地将你的Markdown格式文章转换成 HTML 文件，并部署到 GitHub Pages 或其他静态托管服务上。

接下来我们会先建毛胚房（基础框架），再精装修（优化完善），在搭建过程中一步步学习，并探索自己喜欢的风格，最终建造一座美观舒适的“小房子”。

Hexo的基本搭建

安装前提

安装Hexo前，需要有一个GitHub账号，电脑（此教程是在Windows环境下）需已有以下应用程序：

如果你的电脑已安装上述应用，可以直接进行下一步。

如果未安装，可以到官方网站选择下载与你电脑操作系统相对应的安装包，安装步骤很简单，一路下一步就可以了。

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

此教程安装使用的版本：

Node.js 18.15.0
Git 2.40.0

安装Hexo

确保上述应用安装完毕后，打开cmd命令行终端。

点击查看cmd命令行终端介绍

“cmd”是Windows系统中的命令行终端程序，可以用于执行各种系统命令和批处理脚本。在Windows系统中，打开cmd命令行终端的方法如下：

按下Win+R键组合，打开“运行”对话框。
在“运行”对话框中输入“cmd”，按下Enter键或者点击“确定”按钮。
或者在Windows资源管理器中，打开任意一个目录，并在地址栏中输入“cmd”命令，按下Enter键即可打开命令行终端并自动切换到当前目录。

在cmd命令行终端中，用户可以输入各种系统命令和参数，进行文件管理、网络操作、进程控制等功能。例如，可以使用dir命令查看当前目录下的所有文件和子目录，使用netstat命令查看网络连接状态，使用tasklist命令查看正在运行的进程列表等等。

使用npm全局安装Hexo，执行命令：

1	npm install -g hexo-cli

初始化Hexo

新建空文件夹mybolg
在地址栏中输入cmd，回车打开命令行终端
在命令行终端执行初始化命令：
1
hexo init
等待执行完成后，继续执行：
1
npm install
点击查看”npm install”命令介绍

“npm install”是npm（Node Package Manager）命令中的一种，用于安装当前项目所需要的依赖关系（即所需的各种npm包）。具体含义如下：
- “npm”表示使用npm命令。
- “install”表示安装依赖关系。
在执行”npm install”命令时，npm会自动从npm仓库下载所需的npm包，并将它们安装到当前项目目录下的node_modules文件夹中。可以在项目根目录下找到一个名为package.json的文件，其中记录了项目需要的所有依赖包及其版本号。如果该文件存在，则npm会根据其中的定义自动安装所有的依赖包；如果不存在，则npm只会安装必要的依赖包以满足当前项目的基本运行需求。

需要注意的是，使用”npm install”命令时，可以添加不同的参数来指定安装方式和操作方式。例如，可以使用”–save”参数将安装的依赖包信息保存到package.json文件中，方便其他开发人员或机器使用。可以使用”-g”参数进行全局安装，以供任何项目使用。也可以使用”–production”参数仅安装生产环境需要的依赖包，而忽略开发环境需要的依赖包。

上述流程完成后，会看到myblog文件夹中有如下文件：

myblog文件夹

简单介绍一下每个文件的用处：

node_modules：整个项目的环境依赖。
source：新建的markdown 文章都保存在这个目录下的_post文件夹下。
scaffolds：模版文件夹。模板是指在新建文章hexo new post 'title'，文件中默认填充scaffold/post.md中的Front-matter内容。
themes：主题目录
_config.yml：全局配置文件，很多信息都是在这个文件中配置的，比如网站的名字、副标题、网站描述信息、作者等。
package.json：应用程序的信息。

到这里一个毛胚房（最原始的博客模板）其实就搭建好了，在命令行终端中执行命令：

hexo s

执行命令：hexo s

在浏览器中打开http://localhost:4000/，就能看到毛胚房的样子了：

毛胚房

是不是很简单？三行命令就能搭建博客！

写一个简单的博客

在命令行终端中执行命令：
1
hexo new 'demo'
可以看到在D:\blog\mybolg\source\_posts路径下，生成了demo.md文件，“demo”是文件名，同时也是文章的标题，你可以来自己定义。

文件名（也就是title）不要重复

当然也可以直接在该路径下新建markdown文件，不过直接新建的markdown文件是空白的，需要自己配置yaml，使用命令创建的文件是根据scaffolds文件夹下的post.md模板生成的。
打开demo.md文件，输入你要编辑的内容

在命令行终端中执行命令：
1
hexo s
在浏览器中打开http://localhost:4000/，查看新写的文章：

新建页面

新建关于页面

1	hexo new page "about"

执行命令后，mybolg\source\about路径下会生成一个index.md文件，你可以在里面填写自己的一些自我介绍。

新建标签页面

1	hexo new page "tags"

执行命令后，mybolg\source\tags路径下会生成一个index.md文件，不用填写内容，会有插件自动生成。

文件内容：

1
2
3

title: 标签
date: 2023-04-12 09:39:44
type: "tags"

新建分类页面

1	hexo new page "categories"

执行命令后，mybolg\source\categories路径下会生成一个index.md文件，不用填写内容，会有插件自动生成。

文件内容：

1
2
3

title: 分类
date: 2023-04-12 09:39:56
type: "categories"

基础配置

打开myblog文件夹下的_config.yml文件进行配置：

站点信息

# Site

#网站标题
title: 与或非's Blog
#网站副标题
subtitle: ''
#网站描述
description: 个人成长记录与分享
keywords:
#作者
author: 与或非
#语言
language: zh-CN
#网站时区
timezone: Asia/Shanghai

URL信息

# URL
## Set your site url here. For example, if you use GitHub Page, set url as 'https://username.github.io/project'
url: https://andornot.top
permalink: ':category/:hash.html'
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

url：后续会使用GitHub Pages部署，因此url配置：

https://你的GitHub用户名.github.io

比如我的GitHub用户名是andornottop，url配置https://andornottop.github.io/

如果自己有域名可以配置自己的域名。
permalink：文章的永久链接格式，默认值:year/:month/:day/:title/，我这里改为:category/:hash.html。
因为原来的格式分级太多，且用了:title，当:title为中文时不太方便。:category可以在category_map做中英文映射处理，:hash为文件名（与 :title 相同）和日期的 SHA1 哈希值（12位16进制数）。

category_map映射配置例子：
1
2
3
4
5
6
7
8
# Category & Tag
default_category: uncategorized
category_map:
随笔杂记: note
计算机基础知识: base
Java相关知识: java
Java开发框架: framework
数据库: database

是不是感觉已经可以写博客了？当然到这里还没结束，毛胚房怎么能住人呢？接下来我们选择NexT的主题来进行一步一步装修。

配置NexT主题

NexT 是一款非常流行的 Hexo 主题，具有许多令人印象深刻的功能，其中一些包括：

支持多种语言和代码高亮
自适应布局和响应式设计
支持多种社交媒体链接和评论系统
可自定义的导航菜单和侧边栏
基于 Pjax 技术的无刷新页面加载
可配置的归档、分类和标签页面
可自定义的关键词和描述标签
支持 Google Analytics 和站点地图等 SEO 工具

NexT Schemes——四种风格可选

下载主题

进入到themes文件夹下，在命令行终端执行：

1	git clone https://github.com/next-theme/hexo-theme-next next

启用主题

在myblog文件夹下打开_config.yml，将theme的值改为next。

验证主题

在命令行终端中执行命令：

hexo s

此时即可使用浏览器访问 http://localhost:4000，检查站点是否正确运行。

NexT 主题

配置主题插件

在mybolg\themes\next文件夹找到_config.yml配置文件，复制一份重命名为_config.next.yml，然后将_config.next.yml移动到mybolg文件夹下，NexT主题相关配置就在_config.next.yml修改。

不建议在mybolg\themes\next文件夹下的文件中直接修改内容，因为修改后日后更新主题可能会把已修改的文件覆盖。

Hexo 在合并主题配置时，Hexo 配置文件中的 theme_config 的优先级最高，其次是 _config.[theme].yml 文件，最后是位于主题目录下的 _config.yml 文件。

Scheme Settings

NexT主题有四种Scheme可以选择，也可以开启暗黑模式：

# ---------------------------------------------------------------
# Scheme Settings
# ---------------------------------------------------------------

# Schemes
#scheme: Muse
scheme: Mist
#scheme: Pisces
#scheme: Gemini

# Dark Mode
darkmode: false

Site Information Settings

设置图标

可以将图标文件放到mybolg\source\images文件夹下

favicon:
  small: /images/logo_non1200.png
  medium: /images/logo_non1200.png
  apple_touch_icon: /images/logo_non1200.png
  safari_pinned_tab: /images/logo_and.svg
  #android_manifest: /manifest.json

设置许可

# Creative Commons 4.0 International License.
# See: https://creativecommons.org/about/cclicenses/
creative_commons:
  # Available values: by | by-nc | by-nc-nd | by-nc-sa | by-nd | by-sa | cc-zero
  license: by-nc-sa
  # Available values: big | small
  size: small
  sidebar: true
  post: true
  # You can set a language value if you prefer a translated version of CC license, e.g. deed.zh
  # CC licenses are available in 39 languages, you can find the specific and correct abbreviation you need on https://creativecommons.org
  language:

设置菜单

# Usage: `Key: /link/ || icon`
# Key is the name of menu item. If the translation for this item is available, the translated text will be loaded, otherwise the Key name will be used. Key is case-sensitive.
# Value before `||` delimiter is the target link, value after `||` delimiter is the name of Font Awesome icon.
# External url should start with http:// or https://
menu:
  home: / || fa fa-home
  about: /about/ || fa fa-user
  tags: /tags/ || fa fa-tags
  categories: /categories/ || fa fa-th
  archives: /archives/ || fa fa-archive
  #schedule: /schedule/ || fa fa-calendar
  #sitemap: /sitemap.xml || fa fa-sitemap
  #commonweal: /404/ || fa fa-heartbeat

# Enable / Disable menu icons / item badges.
menu_settings:
  icons: true
  badges: false

另外也支持次级菜单，配置参考Theme Settings | NexT (theme-next.js.org)

配置头像

# Sidebar Avatar
avatar:
  # Replace the default image and set the url here.
  url: #/images/avatar.gif
  # If true, the avatar will be displayed in circle.
  rounded: false
  # If true, the avatar will be rotated with the cursor.
  rotated: false

侧边栏社交链接

# Social Links
# Usage: `Key: permalink || icon`
# Key is the link label showing to end users.
# Value before `||` delimiter is the target permalink, value after `||` delimiter is the name of Font Awesome icon.
social:
  GitHub: https://github.com/andornottop || fab fa-github
  E-Mail: mailto:andornottop@163.com || fa fa-envelope
  #Weibo: https://weibo.com/yourname || fab fa-weibo
  #Twitter: https://twitter.com/yourname || fab fa-twitter
  #FB Page: https://www.facebook.com/yourname || fab fa-facebook
  #StackOverflow: https://stackoverflow.com/yourname || fab fa-stack-overflow
  #YouTube: https://youtube.com/yourname || fab fa-youtube
  #Instagram: https://instagram.com/yourname || fab fa-instagram
  #Skype: skype:yourname?call|chat || fab fa-skype

social_icons:
  enable: true
  icons_only: false
  transition: false

以上是一些我个人的配置，仅供参考，更加详细的配置的文档请参考Theme Settings | NexT (theme-next.js.org)

部署

注意事项

本节主要介绍讲博客部署到GitHub Pages，由于某些原因，GitHub 访问会不太稳定，可能需要科学地上网。

我这里部署的流程是先在GitHub建立两个空仓库：

一个私有仓库存储博客源代码
一个公有仓库存储Hexo生成的页面，因为部署GitHub Pages的仓库，免费账号必须权限公有

官方教程使用的是一个公有仓库部署到GitHub Pages，源代码在主分支，生成的静态页面文件在会放在储存库中的 gh-pages 分支，这样源代码免费账号必须设置权限公有，但是部署操作会简单。如果你想按这种方式部署，可以参考官方文档在 GitHub Pages 上部署 Hexo | Hexo。

部署流程

下面介绍我的部署流程：

登录GitHub账号，点击右上角 “+” ，选择 “New repository”。
输入仓库名 “myblog”，因为这个仓库是要存储博客的源代码，建议设置私有权限，其他的选项不用处理，点击下面的 ”create repository“。
回到本地 myblog文件夹下，打开命令行终端，执行命令初始化本地 Git 仓库：
1
git init

添加文件并提交更改：

1 2	git add . git commit -m "Initial commit"

将当前 Git 仓库的默认分支从原来的分支名（通常为 master）更改为 main：
1
git branch -M main
与远程 Git 仓库关联，要换成你自己的仓库地址：
1
git remote add origin <remote_repo_url>
将本地 Git 仓库中的代码推送到远程 Git 仓库中：
1
git push -u origin main
登录你的GitHub账户，打开myblog仓库会看到本地仓库的文件已经推送到了你的远程GitHub仓库里面。
按照第1、2步再创建一个仓库：
- 仓库权限：Public
- 仓库命名格式：<你的 GitHub 用户名>.github.io
打开命令行终端，生成SSH 密钥对：

输入命令：

1	ssh-keygen -t rsa -b 4096 -C "blog_deploy_key"

需要多次回车。

打开C盘用户文件夹，找到.shh文件夹，里面id_rsa 是私钥，id_rsa_pub是公钥，可以用记事本打开查看。

请注意，私钥应始终保持机密，并妥善保管。
将公钥（id_rsa_pub里的全部内容）复制，打开GitHub仓库<你的 GitHub 用户名>.github.io：
- 找到Settings页面，并选择“Deploy keys”或“SSH keys”选项卡。
- 单击“Add deploy key”按钮，然后将公钥的内容粘贴到Key文本框中。
- Title填写：blog_deploy_key
- 勾选Allow write access
将私钥（id_rsa里的全部内容）复制，打开GitHub仓库myblog：
- 找到Settings页面，并选择“Secrets and variables”下的“Actions”选项卡。
- 单击“New repository secret”按钮，然后将私钥的内容粘贴到Secret文本框中。
- Name填写：ACTIONS_DEPLOY_KEY
点击Actions，去创建一个pages.yml文件：

接着将以下内容复制进去，并按要求改动内容：

文件名称改为pages.yml
external_repository改为你自己的用户名/仓库名：

<你的 GitHub 用户名>/<你的 GitHub 用户名>.github.io
安装主题时保留主题目录中的 .git 文件夹以方便更新，GitHub Actions 对子模块的处理有点问题。所以需要在 Workflow 文件中用 with 标注出你使用的子模块。

在部署时这里踩了大坑，官方文档中未提及子模块的问题，导致生成的静态文件是空白的，无意间看到这位老哥的博客使用 GitHub Actions 部署 Hexo 博客 - 智子酱 - 博客园 (cnblogs.com)帮了大忙

name: Pages

on:
  push:
    branches:
      - main # default branch

jobs:
  pages:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v3

          # 主题文件夹
      - name: Checkout theme repo
        uses: actions/checkout@v3
        with:
          repository: next-theme/hexo-theme-next
          ref: master
          path: themes/next

      - name: Use Node.js 18.15.0
        uses: actions/setup-node@v3
        with:
          node-version: "18.15.0"
      - name: Cache NPM dependencies
        uses: actions/cache@v3
        with:
          path: ~/.npm
          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-node-

      - run: npm ci
      - name: Build
        run: npm run build
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
          external_repository: andornottop/andornottop.github.io
          publish_branch: main  # default: gh-pages
          publish_dir: ./public

点击Start commit，进行Commit new file。
在<你的 GitHub 用户名>.github.io仓库中找到Settings页面的Pages选项，选择main分支后保存，网站的 URL 将在 GitHub Pages 页面中显示。

后续每次在自己电脑上写完博客后，只需将新写的Markdown文件推送到myblog仓库就能自动部署了：

提交并推送更改到Git存储库的命令如下：

先使用 git pull 命令拉取远程仓库的更改。示例：git pull origin main
再使用 git add 命令将更改添加到暂存区。示例：git add .
然后使用 git commit 命令将更改提交到本地存储库。示例：git commit -m "Commit message"
最后，使用 git push 命令将更改推送到远程存储库。示例：git push origin main

优化

Tag Plugins

详细配置介绍Tag Plugins | NexT (theme-next.js.org)

Note

引导标识插件配置：

# Note tag (bootstrap callout)
note:
  # Note tag style values:
  #  - simple    bootstrap callout old alert style. Default.
  #  - modern    bootstrap callout new (v2-v3) alert style.
  #  - flat      flat callout style with background, like on Mozilla or StackOverflow.
  #  - disabled  disable all CSS styles import of note tag.
  style: flat
  icons: true
  # Offset lighter of background in % for modern and flat styles (modern: -12 | 12; flat: -18 | 6).
  # Offset also applied to label tag variables. This option can work with disabled note tag.
  light_bg_offset: 0

示例：

{% note danger %}

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

{% endnote %}

自定义域名

在mybolg\source文件夹下，新建CNAME文件，注意不要有后缀，打开将你的域名填进去即可。

CNAME

参考链接

Hexo官方文档：https://hexo.io/zh-cn/docs/
NexT官方文档：https://theme-next.js.org/docs/
GitHub Pages action：https://github.com/marketplace/actions/github-pages-action