Start Blogging Here:浅谈 Hexo 搭建个人博客

· · 科技·工程

目录

开始之前

:::info[关于终端]{open} 在本文中,可在所有平台使用的命令使用 > 开头:

> Command

仅在 macOS 或 Linux 下的命令用 $ 开头:

$ Command

在 Windows 下,终端指 命令提示符Powershell,这样打开:

按下 Win-R,输入 cmd,打开 Command Line

在 macOS 下,终端 App 在您的启动台中,在启动台中搜索 终端 以启动

在大部分 Linux 发行版下,终端Terminal App 一般在应用程序视图中,点击来打开 :::

在开始建站之前,请确保你的依赖已经安装:

名称 用途
Node.js 运行环境
Git 版本管理
Hexo 建站工具

安装 Node.js

Node.js 是一个 JavaScript 运行环境,很多命令行工具都需要使用它,点击下面的按钮进入官网:

Node.js

验证安装:

> node --version

注意:文中所有终端命令均不含提示符,开头的 > 仅用作提醒,无需输入

安装 Git

Git 是版本管理工具,不仅需要使用 Git 来安装插件,网站部署也需要使用,点击下面的按钮来下载:

Git Download

验证安装:

> git --version

特殊:对于 macOS

macOS 的官方包已在 3 年前停止维护,如要下载,请使用 Homebrew:

在终端中,输入以下命令

$ curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh"

然后

$ brew install git

安装 Hexo

打开终端,输入:

> npm install hexo-cli

:::info[关于安装错误]{open} 如果遇到安装错误,请先执行:

npm install

:::

验证安装:

> hexo -v

GitHub 仓库

如果你没有账号,去 GitHub 注册一个。

点击右上角 + 号,选择 New repository

Repository name 中填写:你的 GitHub 用户名.github.io。 属性选择 Public(公开)。

:::info[关于默认分支]{open} GitHub 的默认分支是 main,而 Git 的默认分支是 master,推荐将 Git 的默认分支改为 main 方便后续使用

> git checkout master
> git branch -m main

:::

:::warning[注意启用双因素身份验证(2FA)]{open} GitHub 最近开启了强制 2FA,如果您有条件,可以使用 Authy (手机) 或 Authenticator (Chromium 扩展) 来验证,一定要复制恢复密钥,否则一旦丢失验证器应用,你将丢失你的 GitHub 仓库 :::

配置 GitHub 的 SSH

打开终端,输入以下命令:

ssh-keygen -t rsa -C "GitHub 注册的邮箱地址"

按下回车,按四次(如果你需要每次提交输入密码,如机房等公用环境,那么在中间提示设定密码时设定),直到出现一个奇怪的图(“SSH Key Finderpoint”)时,则完成。每次生成的图会不同,属于正常现象。

接着打开用户目录下的 .ssh 目录(可能隐藏),打开 id-rsa.pub,复制内容

进入 GitHub ,登录自己的账号,点击右上角头像 -> Settings

然后点击左侧的 SSH and GPG keys

点击 New SSH key

标题随便写,内容粘贴刚才的密钥,点击确定,密钥就配置完成啦!

初始化 Hexo

打开终端(Windows 下的 cmd 或其他系统下的 Terminal),输入:

> hexo init blog

这会在当前目录下创建一个网站模板,当你看到 Start blogging...,就成功啦!

预览你的网站:

> hexo s

这会打开一个服务器,按下 ^C (Ctrl + C) 停止服务

:::success [网站预览]{open} 如果前面的操作没有异常,你应该会在网站中看见一个带有 Hexo 标题的页面,以及一篇文章 Hello World! :::

写文章

在终端中输入:

> hexo new 文章名

然后打开 source/_posts/文章名.md,编辑内容,模板如下:

---
title: 标题
categories: 分类(可选)
tag: 
  - 标签 1(可选)
  - 标签 2(可选)
---

正文

Markdown 语法参见 洛谷 Markdown 格式手册

安装主题和基础配置

我推荐 Anzhiyu 主题,可自定义程度高,兼容很多插件

预览站点:我的 Blog

官方配置文档,需要进阶配置的在这里:安知鱼主题官方文档 | 一个简洁、美丽的静态hexo主题

安装

> npm install hexo-theme-anzhiyu

将主题目录(安装 anzhiyu 的地方)里面的 _config.yml 复制到博客根目录,重命名成 _config.anzhiyu.yml

配置中文和主题

打开 _config.yml(以下简称为全局配置或 GC),改变以下行:

--- _config.yml
+++ _config.yml
- lang: en
+ lang: zh-CN

...

- theme: landscape
+ theme: anzhiyu

分类页面

> hexo new page categories

创建一个分类页,请在此页的源文件(source/categories/index.md)中输入以下代码:

---
title: Categories
...
type: "categories"
---

注意:分类页本身不能含有分类

在其他文章中,这样设置分类:

---
title: xxx
...
category: abcabc
---

此时回到首页,会发现无法进入分类,这样配置菜单栏:

在 TC 中写入以下内容:

menu:
  文章:
    分类: /categories/ || anzhiyu-icon-shapes
    随便逛逛: javascript:toRandomPost()
  友链:
    johnCh 的博客: https://johnch.us.ci
    # 添加其他想要显示在顶部菜单栏中的内容

:::info[生成静态文件来刷新]{open} 注意,GC 和 TC 的更改需要关闭服务器再开启才能生效

点击 Ctrl-C 来关闭服务器,输入 hexo g 来重新生成,然后重新开启服务器 :::

此时的菜单栏应该会出现两个按钮

标签页面

类似分类页面,我们也需要为标签创建一个独立的页面。

> hexo new page tags

在生成的 source/tags/index.md 文件中,添加 type: "tags" 到 Front-matter:

---
title: Tags
date: xxxx-xx-xx xx:xx:xx
type: "tags"
---

这样标签页面就会以特殊的标签云布局显示所有标签。

在文章 Front-matter 中,你可以这样设置标签:

---
title: 我的文章
tags:
  - 技术
  - 生活
---

或者使用行内写法:tags: [技术, 生活]

为了让菜单中出现标签页的链接,在 TC 的 menu 中添加一项,例如:

menu:
  我的博客:
    归档: /archives/ || anzhiyu-icon-box-archive
    分类: /categories/ || anzhiyu-icon-shapes
    标签: /tags/ || anzhiyu-icon-tags

添加后重新生成,菜单中就会出现标签入口。

配置个人信息和网站信息

AnZhiyu 主题提供了丰富的个人信息展示区域,主要包括头像、站点图标、作者卡片、社交链接等。以下配置均在 TC(_config.anzhiyu.yml)中完成。

站点图标(Favicon)

在 TC 中找到 favicon 字段,设置你的图标路径:

favicon: /img/favicon.png

建议将图标放在 source 目录下(如 source/img/favicon.png),然后路径以 / 开头。

头像

头像用于侧边栏作者卡片和部分界面元素:

avatar:
  img: /img/avatar.webp
  effect: true   # 是否开启头像旋转等特效

站点描述

在 GC(_config.yml)中,可以设置站点描述,它会出现在页面元数据中:

description: 这是我的个人博客,记录技术、生活和思考。

作者卡片

侧边栏的作者卡片显示头像、名称、简介等。在 TC 中:

aside:
  card_author:
    enable: true
    description: 后端开发 / 开源爱好者 / 生活记录者
    name_link: /about/   # 点击名字跳转的链接,通常指向关于页

如果你希望在作者卡片中展示更多状态(如技能、当前状态),可以启用 author_status

author_status:
  enable: true
  statusImg: "https://cdn.luogu.com.cn/upload/usericon/1366636.png"
  skills:
    - Python 工程
    - OI
    - HTML/Electron 开发

社交链接

在 TC 中配置 social,支持显示在页脚或其他位置:

social:
  GitHub: https://github.com/你的用户名 || anzhiyu-icon-github
  邮箱: mailto:[email protected] || anzhiyu-icon-envelope
  哔哩哔哩: https://space.bilibili.com/你的UID || anzhiyu-icon-bilibili
  微博: https://weibo.com/你的微博 || anzhiyu-icon-weibo

格式为 名称: 链接 || 图标类。图标类可以从主题自带的图标库(AnZhiYu 图标)或 Font Awesome 中选择。

配置颜色主题

AnZhiYu 主题支持两种颜色主题配置方式:手动设置固定颜色,或自动从文章封面提取主色调。

手动设置主题色

在 TC 中找到 theme_color 字段,可以自定义各种场景下的颜色:

theme_color:
  enable: true
  main: "#425AEF"               # 主色调
  dark_main: "#3fe0f0"          # 深色模式主色调
  paginator: "#425AEF"          # 分页器颜色
  button_hover: "#ff6f61"        # 按钮悬停颜色
  text_selection: "#ffd6d6"      # 文本选中背景色
  link_color: "#425AEF"          # 链接颜色
  meta_color: "#858585"          # 元信息文字颜色
  hr_color: "#A5D6F9"            # 分隔线颜色
  code_foreground: "#F47466"     # 代码前景色
  code_background: "#FFF4F2"     # 代码背景色

所有颜色值需要用双引号包裹。

自动提取主色调(从封面图)

主题还可以根据文章的封面图自动提取主色调,用于页面标题装饰等。启用 mainTone

mainTone:
  enable: true
  mode: api                 # 可选 colorthief / cdn / api / both
  api: https://img2color-go.vercel.app/api?img=
  cover_change: true        # 切换文章时是否更新颜色

如果你希望手动为某篇文章指定主色调,可以在文章 Front-matter 中添加 main_color: #ff0000

配置关于页、友链页、留言板页

这些独立页面通常需要先创建页面文件,然后在菜单中添加链接,最后配置对应的主题布局(如果有的话)。

关于页

> hexo new page about

source/about/index.md 中编写你的个人介绍。主题可能会对 about 页面应用特殊样式,无需额外设置 type

友链页

友链页通常需要特定的布局来展示友链卡片。创建页面:

> hexo new page link

source/link/index.md 的 Front-matter 中添加:

---
title: 友人帐
type: "link"
---

然后在同目录下创建 data 文件夹,里面放置 link.ymllink.json 来定义友链数据。例如 source/link/data/link.yml

- class_name: 友情链接
  link_list:
    - name: JohnCh
      link: https://johnch.us.ci
      avatar: https://johnch.us.ci/img/avatar.webp
      descr: 博客作者
- class_name: 小伙伴们
  link_list:
    - name: 示例博客
      link: https://example.com
      avatar: https://example.com/avatar.jpg
      descr: 一个示例站点

留言板页

> hexo new page comments

source/comments/index.md 中写入留言板内容,通常包含评论系统。如果需要启用评论区,确保页面中已经包含评论模块(主题自动根据 comments.use 加载)。

添加到菜单

在 TC 的 menu 中添加这些页面的链接:

menu:
  关于:
    关于本人: /about/ || anzhiyu-icon-paper-plane
  友链和留言:
    友人帐: /link/ || anzhiyu-icon-link
    留言板: /comments/ || anzhiyu-icon-envelope

配置左上角菜单和“开往”链接

左上角菜单

在 TC 中,menu 字段定义了导航栏的菜单项,支持二级菜单。你可以根据需要组织菜单结构。

示例:

menu:
  我的博客:
    归档: /archives/ || anzhiyu-icon-box-archive
    分类: /categories/ || anzhiyu-icon-shapes
    标签: /tags/ || anzhiyu-icon-tags
  关于:
    关于本人: /about/ || anzhiyu-icon-paper-plane
    留言板: /comments/ || anzhiyu-icon-envelope
    友人帐: /link/ || anzhiyu-icon-link

菜单项后的 || 后面是图标类(来自主题图标库或 Font Awesome)。

“开往”链接

“开往”是一个友链接力项目,加入后你的博客会在右下角显示一个“开往”按钮,点击随机跳转到其他成员博客。

要添加“开往”链接,通常在主题的右下角按钮配置中,增加一个自定义按钮。在 TC 中查找 rightside_item_order 或直接添加一个菜单项指向开往的随机链接。也可以通过在 menu 中添加一个外部链接来实现。

更简单的做法:在页脚或右下角加入开往图标。例如在 footersocialBar 中添加:

socialBar:
  enable: true
  left:
    - title: 开往
      link: https://www.travellings.cn/go.html
      icon: anzhiyu-icon-train

或者如果你希望它出现在右下角按钮区域,可以自定义 rightside_item_order 添加一项,但需要主题支持自定义按钮。

另外,你可以在 nav(顶部导航栏)中增加一个链接:

nav:
  enable: true
  menu:
    - title: 开往
      item:
        - name: 随机前往
          link: https://www.travellings.cn/go.html
          icon: anzhiyu-icon-train

这样左上角(或顶部导航)就会出现“开往”的入口。

进阶配置

以上配置已经可以搭建一个功能完整的博客。但 AnZhiYu 主题还提供了大量进阶功能,让你可以进一步定制博客的外观和体验。以下是一些常用进阶配置的简介,详细配置项请参考主题官方文档或 MANUAL.md。

评论系统

主题支持多种评论系统:Twikoo、Giscus、Waline、Artalk 等。在 TC 中通过 comments.use 选择,并填写对应服务的配置。

例如配置 Giscus(基于 GitHub Discussions):

comments:
  use: giscus
  text: true
  lazyload: true
  count: true

giscus:
  repo: 你的用户名/你的仓库名
  repo_id: 你的 repo_id
  category: Announcements
  category_id: 你的 category_id
  mapping: pathname
  strict: 0
  reactions_enabled: 1
  emit_metadata: 0
  lang: zh-CN

搜索功能

主题支持 Algolia、Docsearch 和本地搜索。

文章增强

美化与特效

侧边栏卡片

侧边栏可以灵活配置各种卡片,如公告、最近文章、分类、标签、归档、站点信息等。在 TC 的 aside 下控制:

aside:
  card_announcement:
    enable: true
    content: 欢迎来到我的博客!
  card_recent_post:
    enable: true
    limit: 5
  card_categories:
    enable: true
    limit: 8
  card_tags:
    enable: true
    limit: 40
  card_archives:
    enable: true
    type: monthly
    format: MMMM YYYY
    limit: 8
  card_webinfo:
    enable: true
    post_count: true
    last_push_date: false

右下角工具

右下角悬浮按钮支持多种工具:阅读模式、简繁转换、深色模式切换、中控台等。可以在 TC 中分别控制:

readmode: true
translate:
  enable: true
  default: 繁
darkmode:
  enable: true
  button: true
  autoChangeMode: 1   # 1 跟随系统,2 定时
centerConsole:
  enable: true
  card_tags:
    enable: true
    limit: 40
  card_archives:
    enable: true
    type: monthly
    limit: 8

PWA 支持

将博客配置为渐进式 Web 应用(PWA),允许用户将网站安装到桌面。在 TC 中启用:

pwa:
  enable: true
  startup_image_enable: true
  manifest: /manifest.json
  theme_color: var(--anzhiyu-main)
  apple_touch_icon: /apple-touch-icon.png
  favicon_32_32: /favicon-32x32.png
  favicon_16_16: /favicon-16x16.png
  mask_icon: /safari-pinned-tab.svg

你需要生成相应的图标并放在 source 目录下,并创建 manifest.json

自定义代码注入

如果你需要引入额外的 CSS 或 JS,可以使用 inject 字段:

inject:
  head:
    - <link rel="stylesheet" href="/css/custom.css">
  bottom:
    - <script src="/js/custom.js"></script>

这些代码会被注入到 HTML 的 </head> 前和 </body> 前。

CDN 加速

主题允许自定义资源 CDN 提供商,提升加载速度。在 TC 的 CDN 字段配置:

CDN:
  internal_provider: local        # 内部资源:local / jsdelivr / unpkg
  third_party_provider: cbd       # 第三方资源:cbd / elemecdn / jsdelivr
  version: true                   # 是否在链接后附加版本号
  custom_format: https://npm.elemecdn.com/${name}@latest/${file}
  option:                         # 可单独覆盖某个资源的链接
    # main_css: https://xxx.com/main.css

部署你的网站

推送到 GitHub

首先,将你的博客源码初始化为 Git 仓库并推送到 GitHub。

如果你还没有在本地将博客目录初始化为 Git 仓库,执行:

> git init
> git add .
> git commit -m "Initial commit"

然后,在 GitHub 上创建仓库(参考前面的步骤),复制仓库地址(例如 [email protected]:用户名/仓库名.git 或 HTTPS 地址)。

添加远程仓库并推送:

> git remote add origin 你的仓库地址
> git branch -M main
> git push -u origin main

现在你的博客源码已经托管在 GitHub 上,后续可以通过部署服务自动构建和发布。

部署到 Cloudflare Pages

  1. 登录 Cloudflare 控制台

    访问 Cloudflare ,登录账号。

  2. 进入 Pages 管理页面

    点击左侧菜单栏的 Compute (Workers) -> 选择 Pages (旧版界面可能显示为 Workers & Pages

  3. 创建 Pages 项目

    点击 Create application -> Pages -> Connect to Git

    授权访问你的 GitHub 仓库,选择博客源码仓库。

  4. 配置构建参数

    Build settings 选项卡中填写:

    • Build command: hexo g

    • Build output directory: public

  5. 开始部署

    其他选项保持默认,点击 Save and Deploy

    点击 Build and Deploy,等待进度跑完,不要立即打开页面,因为 DNS 服务需要时间

    大概 2 分钟后就可以访问了,完成后默认域名为 <项目名>.pages.dev

当你看到熟悉的页面时,恭喜!

之后更新文章时,仅需推送代码到 GitHub 仓库(main 分支),Cloudflare Pages 会自动触发重新构建和部署。

部署到 Netlify

  1. 登录 Netlify 控制台

    访问 Netlify,使用 GitHub 账号登录(或注册)。

  2. 导入 Git 仓库

    点击 Add new site -> Import an existing project,选择 GitHub 并授权 Netlify 访问你的仓库。

    选择你的博客源码仓库。

  3. 配置构建选项

    在构建设置中填写:

    • Build command: hexo g (或如果你在 package.json 中定义了 build 脚本,可以填写 npm run build
    • Publish directory: public
  4. 开始部署

    点击 Deploy site,等待构建完成。部署完成后,Netlify 会分配一个随机子域名(例如 random-name.netlify.app)。

  5. (可选)自定义域名

    在 Netlify 的域名设置中,你可以添加自定义域名并配置 DNS。

之后,每次推送代码到 GitHub 仓库(main 分支),Netlify 都会自动触发重新构建和部署。

关于添加自定义域名、配置 DNS 等进阶操作,可以参考 这篇文章。

发布以后

恭喜!你的博客已经成功部署到公网,可以访问了。但这只是开始,一个优秀的博客需要持续的维护和优化。本章将介绍发布后的一些常见任务和建议,帮助你更好地运营博客。

日常维护

更新文章

写文章是博客的核心。你可以随时在本地编写新文章,使用 hexo new "文章标题" 创建,编辑后通过 hexo g 生成并预览,确认无误后推送到 GitHub 仓库,触发自动部署(如果你配置了 Cloudflare Pages 或 Netlify 等 CI/CD 服务)。如果没有自动部署,可以手动执行 hexo d 部署(需配置 Git 部署)。

建议定期备份博客源文件(包括主题配置、文章、图片等),可以使用 Git 仓库作为备份,也可以额外备份到云盘。

升级 Hexo 和主题

Hexo 和主题会不定期更新,修复 bug、增加新功能。你可以关注 Hexo 和 AnZhiYu 主题的 Release 页面,适时升级。

升级 Hexo 核心:

> npm update hexo

升级主题(如果通过 npm 安装):

> npm update hexo-theme-anzhiyu

如果是通过 Git 克隆的主题,进入主题目录拉取最新代码即可。

注意:升级前最好备份配置文件,以防配置变更导致问题。

检查评论系统

如果你配置了评论系统(如 Twikoo、Giscus),定期检查评论是否正常显示,是否有垃圾评论需要处理。Twikoo 提供了管理后台,Giscus 的评论存储在 GitHub Discussions 中,可以在仓库的 Discussions 板块管理。

优化

SEO 优化

为了让搜索引擎更好地收录你的博客,可以进行以下优化:

性能优化

访问统计

了解博客的访问情况有助于调整内容和运营策略。你可以使用:

安全与稳定性

内容丰富

添加新页面

除了默认的归档、分类、标签页,你可以创建更多自定义页面:

这些页面可能需要配合主题的特定布局或标签外挂,请参考 AnZhiYu 主题文档。

使用标签外挂

AnZhiYu 主题支持丰富的标签外挂(Tag Plugins),可以在 Markdown 中插入复杂元素,如提示块、按钮、选项卡、时间轴、Mermaid 图表等。例如:

{% note info %}
这是一个提示块
{% endnote %}

{% mermaid %}
graph TD;
  A-->B;
  A-->C;
  B-->D;
  C-->D;
{% endmermaid %}

这些外挂能大大丰富文章的呈现形式。

集成更多服务

互动与社区

评论管理

友链

社交媒体推广

持续迭代

博客不是一成不变的,你可以:

最后,保持写作的热情和耐心。技术博客不仅是对外分享,也是自我成长的记录。祝你在博客的世界里找到乐趣和成就!