Hexo建设个人网站系列教程 目录

  1. 第一章：初识Hexo——开启博客新时代
  2. 第二章：环境搭建与 Hexo 安装——从零开始的准备工作
  3. 第三章：创建你的第一个 Hexo 博客项目——动手实践篇
  4. 第四章：主题选择与定制——让你的博客个性十足
  5. 第五章：撰写精彩内容——文章编辑与管理技巧
  6. 第六章：插件加持——提升博客功能与用户体验
  7. 第七章：博客部署与上线——一步步教你搞定

第三章：创建你的第一个 Hexo 博客项目——动手实践篇

Hexo 是一款基于 Node.js 的静态博客生成器，其简单高效、扩展性强的特点吸引了众多开发者和博客爱好者。无论你是新手还是有一定经验的开发者，这一章节都将详细介绍如何利用 Hexo 命令行工具创建并管理一个全新的博客项目，带你一步步动手实践。
本文内容共分为如下几个部分：

  • 环境准备与 Hexo 简介
  • 安装 Hexo CLI 工具
  • 初始化博客项目
  • 项目目录结构解析
  • 各主要文件与目录详细说明
  • 实例演示：创建你的第一篇博客文章
  • 启动 Hexo 服务器并预览效果
  • 后续更新与部署提示
  • 常见问题及解决方案
  • 小结

下面我们将逐步展开介绍。

环境准备与 Hexo 简介

在开始创建博客之前，首先需要确认你的开发环境已经满足 Hexo 的运行要求。Hexo 是基于 Node.js 构建的，因此需要安装 Node.js 和 npm（Node 包管理器）。另外，建议在开发过程中安装 Git 以便于项目管理和后续部署。

环境要求

  • Node.js： 建议使用 LTS 版本（长期支持版本），例如 Node.js 14.x 或 16.x。你可以从 Node.js 官网 下载并安装。
  • npm： Node.js 自带 npm，确保 npm 版本在 6.x 及以上。
  • Git： 用于版本控制和代码管理，建议提前安装 Git。

在终端中执行以下命令检查版本信息，确认安装成功：

1
2
3
node -v
npm -v
git --version

如果上述命令均返回正确的版本号，说明环境已准备就绪。接下来，我们将安装 Hexo 命令行工具。

安装 Hexo CLI 工具

Hexo 提供了全局命令行工具 hexo-cli，它可以帮助你快速创建、更新和部署博客项目。全局安装 Hexo CLI 非常简单，只需使用 npm 命令即可。
在终端中执行如下命令：

1
npm install -g hexo-cli

这条命令会将 hexo-cli 安装到全局环境中，确保你在任何目录下都可以使用 hexo 命令。如果安装过程中出现权限问题，可以尝试在命令前加上 sudo（针对 Linux/Mac 系统）或者以管理员身份运行命令提示符（针对 Windows 系统）。
安装成功后，在终端输入：

1
hexo -v

你将会看到 Hexo 的版本信息及相关依赖包版本，确认安装无误。

初始化博客项目

有了 Hexo CLI 后，接下来就可以开始创建一个全新的博客项目。Hexo 提供了简单易用的初始化命令，帮助你快速搭建项目骨架。

新建博客项目

在你希望存放博客项目的目录中打开终端，然后执行以下命令：

1
hexo init my-blog

这里的 my-blog 是你的博客项目文件夹名称，你可以根据需要自行命名。执行该命令后，Hexo 将会自动在该目录下生成博客的基本目录结构和必要的配置文件。

初始化步骤解析

执行 hexo init 后，Hexo 会完成以下几步操作：
创建目录与文件： Hexo 会在 my-blog 目录下生成以下文件与文件夹：

  • _config.yml：博客全局配置文件。
  • package.json：项目依赖描述文件，记录 Hexo 及相关插件版本信息。
  • scaffolds：存放文章、页面等模板文件的目录，用于创建新文章时自动引用默认模板。
  • source：博客内容目录，其中包含文章、页面、资源文件等。
  • themes：存放博客主题的目录，你可以在这里切换或自定义主题。
    初始化 npm 项目： 执行完 hexo init 后，系统会自动生成 package.json 文件，描述了项目所依赖的各种 npm 包。
    安装依赖： 完成项目初始化后，建议立即执行 npm install 命令以安装所有依赖包，确保后续命令能正常运行。

安装依赖

在 my-blog 目录下，执行以下命令安装依赖包：

1
2
cd my-blog
npm install

这一步会根据 package.json 文件中的依赖列表下载所有必要的 npm 包到 node_modules 目录。安装完成后，你就可以使用 Hexo 提供的各项命令进行后续操作了。

项目目录结构解析

成功初始化项目后，整个博客项目的目录结构大致如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
my-blog/
├── _config.yml
├── package.json
├── scaffolds/
│   ├── draft.md
│   ├── page.md
│   └── post.md
├── source/
│   ├── _data/
│   ├── _drafts/
│   ├── _posts/
│   └── images/...
├── themes/
│   └── <你的主题文件夹>
└── node_modules/

下面我们对这些文件和目录进行详细说明。

根目录文件

  • _config.yml：
    这是 Hexo 的全局配置文件，你可以在这里设置博客的基本信息（如站点标题、作者、语言、链接格式等）以及插件、部署信息。此文件采用 YAML 格式，非常直观易读。
  • package.json：
    记录了当前项目所依赖的 npm 包以及一些基本信息。通过该文件，可以方便地管理和更新项目依赖，同时也包含一些脚本命令的配置。

scaffolds 目录

该目录存放 Hexo 文章和页面的模板文件。默认情况下，Hexo 提供了三种模板：

  • post.md： 新建文章时默认使用的模板，其中包含文章标题、日期、标签等元数据。
  • page.md： 用于新建页面时的模板，如“关于我”、“联系”等静态页面。
  • draft.md： 用于创建草稿文章的模板，便于未完成文章的保存与编辑。

你可以根据需要修改或自定义这些模板内容，确保新生成的文件符合你的风格。

source 目录

source 目录是博客内容的主要存放位置，主要包括：

  • _posts/： 存放已经发布的博客文章。每篇文章都是一个 Markdown 文件，文件名格式通常为“YYYY-MM-DD-文章标题.md”。
  • _drafts/： 存放博客草稿，未发布的文章可以放在这里，等内容完善后再移至 _posts 文件夹。
  • _data/： 存放数据文件，比如个人信息、菜单配置等。数据文件一般采用 JSON、YAML 等格式。
  • images/ 或其他静态资源目录： 用于存放博客中引用的图片、视频、附件等文件。

themes 目录

themes 目录用于存放博客的主题文件。Hexo 支持多种主题，你可以在主题市场中选择喜欢的主题并安装到该目录。安装好主题后，需要在 _config.yml 中进行主题切换。
例如，如果你安装了 landscape 主题，可以在 _config.yml 文件中找到如下配置项，并将其修改为：

1
theme: landscape

主题文件夹中包含了页面模板、样式文件、脚本和图片等资源，是决定博客外观和交互的重要部分。

node_modules 目录

该目录存放所有通过 npm 安装的依赖包，不建议手动修改其中内容。它由 package.json 文件控制，随时可以通过 npm install 重新生成。

各主要文件与目录详细说明

在了解了项目结构之后，下面我们逐一介绍各个关键文件与目录的详细作用及常见配置，帮助你更好地理解 Hexo 的工作机制。

_config.yml —— 博客全局配置

全局配置文件 _config.yml 是整个博客项目的核心，里面包含了博客标题、作者、语言、文章链接格式、主题配置以及插件设置等内容。以下是一个简单的示例及注释说明：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 站点信息
title: 我的 Hexo 博客  # 博客标题
subtitle: "追寻技术与生活的交汇点"  # 博客副标题
description: "记录技术心得，分享生活点滴" # 博客描述
author: "张三"# 作者名称
language: zh-CN   # 语言设置
timezone: "Asia/Shanghai" # 时区设置
# 文章设置
permalink: :year/:month/:day/:title/  # 文章链接格式
source_dir: source/_posts  # 文章存放目录
new_post_name: :year-:month-:day-:title.md  # 新文章默认文件名格式
# 路径设置
root: /   # 博客部署的根目录，通常用于部署到二级目录时设置
# 服务器配置
port: 4000# 本地预览服务器端口
# 其他配置
theme: landscape  # 使用的主题名称

在此文件中，你可以根据需要进行多处自定义配置，比如启用评论、集成第三方统计、设置插件参数等。修改配置文件后，保存并重启 Hexo 服务即可生效。

package.json —— 项目依赖与脚本

package.json 文件中包含了当前项目依赖的 Hexo 核心库及相关插件信息，同时也记录了项目名称、版本号和一些自定义脚本。示例内容如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "name": "my-blog",
  "version": "1.0.0",
  "private": true,
  "scripts": {
"clean": "hexo clean",
"generate": "hexo generate",
"server": "hexo server",
"deploy": "hexo deploy"
  },
  "dependencies": {
"hexo": "^5.4.0",
"hexo-cli": "^4.2.0"
  }
}

你可以通过运行 npm install 命令来安装其中列出的所有依赖。如果将来需要安装其他插件，比如评论系统、搜索插件等，也可以通过 npm 方式添加到依赖中，并在配置文件中进行相应设置。

scaffolds —— 文章与页面模板

scaffolds 目录下的模板文件决定了新建文章和页面时默认的元数据格式。以 post.md 为例，内容可能如下：

1
2
3
4
title: {{ title }}
date: {{ date }}
tags:
---

当你执行 hexo new “我的第一篇文章” 时，Hexo 会根据该模板生成一个包含默认字段的 Markdown 文件，方便你直接在文件中编辑文章内容。你可以根据个人习惯修改模板内容，比如添加摘要、分类等字段。

source —— 博客内容存放地

source 目录是你博客内容的仓库，通常分为以下几个部分：

  • _posts： 存放已发布的文章，文件格式通常为 Markdown。每个文件的头部均为 YAML Front-matter，记录了文章标题、日期、标签、分类等信息。
  • _drafts： 用于保存草稿文章，便于在未完成时保持编辑状态，不会在生成时显示。
  • _data： 可以存放一些结构化数据，比如站点菜单、友情链接、作者信息等，这些数据可通过模板引擎调用，灵活展示在前端页面中。
  • images、assets 等目录： 用于存放博客所需的静态资源，如图片、视频和其它附件。你可以在文章中通过相对路径引用这些资源。

themes —— 主题文件夹

Hexo 的魅力之一在于其主题系统，通过更换主题可以迅速改变博客外观。themes 目录下存放的是各个主题的完整文件集，通常包括：

  • 布局文件（layout）： 用于定义博客页面的整体结构和模块划分。
  • 静态资源（public、source）： 包括 CSS、JS、图片等，用于呈现页面样式和动态效果。
  • 配置文件： 部分主题会提供自己的配置文件，允许你自定义主题颜色、菜单、侧边栏内容等。
    安装主题的方法有很多，比如直接从 GitHub 克隆主题仓库到 themes 文件夹，然后在 _config.yml 中指定使用该主题。

实例演示：创建你的第一篇博客文章

在完成项目初始化和基本配置后，我们可以尝试创建并发布你的第一篇博客文章。

使用 Hexo 新建文章命令

Hexo 提供了 hexo new 命令，用于新建文章或页面。以创建新文章为例，在项目根目录下执行：
hexo new “我的第一篇文章”
该命令会在 source/_posts/ 目录下生成一个新的 Markdown 文件，文件名格式会依据 _config.yml 中 new_post_name 的配置自动生成，例如 2025-03-14-我的第一篇文章.md。

编辑文章内容

打开新生成的 Markdown 文件，文件内容大致如下：

1
2
3
4
5
6
7
8
title: 我的第一篇文章
date: 2025-03-14 10:00:00
tags:
---
这里开始书写你的文章内容……
可以添加代码块，例如：
```javascript
console.log("Hello, Hexo!");

你可以按照自己的需求编辑文章内容，添加段落、代码、图片等。由于 Hexo 支持 Markdown 语法，因此编写起来既简洁又直观。

添加草稿与定时发布

如果文章尚未完成，不想立即发布，可以将其保存至 source/_drafts/ 目录中，方法如下：

1
hexo new draft "未完成的文章"

待文章内容完善后，将文件移动到 _posts 目录，并修改文件头部日期等信息，然后生成静态页面发布。

启动 Hexo 服务器并预览效果

当你完成文章撰写后，可以通过 Hexo 内置的服务器预览博客效果。
在项目根目录下执行：

1
hexo server -p 4000

该命令会启动一个本地服务器，并在浏览器中访问 http://localhost:4000。每当你更新文章或修改主题后，只需刷新浏览器页面即可看到最新效果。开发过程中，Hexo 会监控文件变化并自动重新生成页面，极大提升了开发效率。
如果你想查看生成后的静态文件，可以在终端执行：

1
hexo generate

该命令会将所有 Markdown 文件转换为 HTML 页面，并将结果输出到 public 目录中。你可以将 public 目录下的内容上传到静态网站托管平台，如 GitHub Pages、Netlify 或 Vercel，完成博客部署。

后续更新与部署提示

成功创建项目并预览后，接下来你可能需要不断更新内容和主题。以下是一些常见的更新与部署提示：

更新 Hexo 及插件

随着 Hexo 社区的发展，新的插件和功能不断推出。你可以通过以下命令检查更新：

1
npm update

同时，建议定期关注 Hexo 的官方文档和社区动态，了解最新最佳实践和插件推荐。

自定义主题与样式

虽然 Hexo 提供了多种主题供选择，但你也可以根据需要自定义主题。修改 themes/<你的主题>/ 目录下的模板文件和 CSS 样式，即可实现个性化定制。部分主题还支持配置文件，你可以在主题目录下找到相关说明文件，按照文档修改配置项。

部署到远程服务器或 GitHub Pages

完成本地测试后，可以将博客部署到线上环境。常见的部署方式包括：
GitHub Pages： 修改 _config.yml 中的 deploy 配置，安装 hexo-deployer-git 插件，然后执行 hexo deploy 命令即可将生成的静态文件推送到 GitHub 仓库，启用 GitHub Pages 服务。
Netlify/Vercel： 这些平台支持直接从 Git 仓库自动构建和部署 Hexo 博客，配置简单、速度快。
例如，部署到 GitHub Pages 的配置示例：

1
2
3
4
deploy:
  type: git
  repo: https://github.com/your_username/your_blog_repo.git
  branch: gh-pages

安装部署插件：

1
npm install hexo-deployer-git --save

配置完成后，运行：

1
hexo deploy

部署成功后，你可以通过浏览器访问你的博客网址，检查线上效果。

常见问题及解决方案

在实际操作过程中，可能会遇到各种问题。下面总结了一些常见问题及其解决方案，供你参考。

npm 安装依赖失败

问题描述： 在执行 npm install 时遇到网络或权限问题。
解决方案：
检查网络连接，必要时切换国内镜像（如淘宝镜像）。
Linux 或 Mac 系统上，可尝试使用 sudo npm install，或者配置 npm 的权限。
清除 npm 缓存：npm cache clean –force，然后重新安装。

Hexo 命令报错或无效

问题描述： 运行 hexo new、hexo generate 或 hexo server 等命令时提示命令不存在或报错。
解决方案：
确认 Hexo CLI 是否全局安装，检查 hexo -v 是否能正常显示版本信息。
如仍报错，可尝试重新安装 Hexo CLI：npm uninstall -g hexo-cli，然后再安装一次。
检查 Node.js 版本是否兼容，建议使用 LTS 版本。

主题显示异常或页面布局混乱

问题描述： 更换主题后出现页面布局错乱或部分功能失效。
解决方案：
检查主题目录中是否存在缺失或错误的文件。
参照主题官方文档检查配置文件设置，确保 _config.yml 中的 theme 字段与主题名称一致。
清除缓存：执行 hexo clean 后重新生成页面，确保缓存不会导致显示问题。

部署后页面打不开或资源加载错误

问题描述： 部署至线上后，浏览器显示 404 或部分图片、CSS 无法加载。
解决方案：
检查 _config.yml 中的 root 配置项，确保其与部署的实际路径匹配。
如果部署到二级目录，需要将 root 修改为 /your-repo-name/。
确认部署命令执行无误，建议本地生成静态文件后手动检查 public 目录结构。

小结

通过本章节的详细讲解，我们已经成功利用 Hexo 命令行工具完成了博客项目的初始化与搭建。具体来说，你已经了解了：
环境准备与 Hexo 安装： 确保 Node.js、npm 和 Git 环境配置完备，并全局安装 Hexo CLI。
项目初始化与依赖安装： 通过 hexo init my-blog 命令生成项目骨架，并使用 npm install 安装所有依赖。
项目目录结构解析： 深入认识 _config.yml、package.json、scaffolds、source、themes 等关键目录与文件的作用。
实例演示与内容创建： 使用 hexo new 命令创建新文章，编辑 Markdown 文件，掌握 YAML Front-matter 的基本格式。
本地预览与部署： 利用 hexo server 命令启动本地预览服务器，通过 hexo generate 生成静态页面，并部署至线上平台。
常见问题排查： 针对安装、运行、主题、部署等常见问题提供了解决思路和具体方案。
掌握以上知识后，你已经具备了从零开始创建、维护并更新 Hexo 博客项目的能力。实践过程中，你可以不断扩展 Hexo 的功能，安装各类插件，或者根据实际需求修改主题样式，使你的博客既具备技术优势又兼具个性化风格。
在后续的博客教程中，我们还将探讨如何优化 Hexo 的性能、如何集成第三方服务（如评论、搜索、社交分享等），以及如何通过 CI/CD 实现自动化部署。希望你在实践中不断探索、总结经验，打造出一个既美观又高效的个人博客。