博客迁移与部署指南（mkdocs to hexo）

在个人只是管理的初期，MkDocs以其极致的简洁和对Markdown的原生支持，成为我构建文档站点的首选。它足够轻快，能够快速部署。但是使用了一段时间发现，MkDocs的主题生态相对单一、插件不够丰富。

我尝试使用Hexo框架，它是一个基于Node.js的静态博客框架，生态和可定制型较好。

基础准备

迁移的第一步，就是在本地构建一个功能完备的Hexo工作环境。Hexo依赖于Node.js。

可以参考这个博客使用Hexo搭建静态博客并部署到Github Pages

初始化与核心迁移

环境就绪后，我们开始创建博客项目并迁移内容。

1. 初始化Hexo项目

1
2

hexo init Blog(自己定义)
cd Blog

进入新创建的目录，会看到Hexo的标准项目结构。

2. 安装项目依赖
   不要忽视的是，hexo init仅仅创建了骨架，真正的功能模块需要通过npm install来安装。

1

npm install 

如果跳过这一步直接执行，会遇到一个仅仅显示init，缺乏一些项目依赖。

3. 迁移Markdown内容

将原生Mkdocs项目的docs/目录下的所有.md文档复制到Hexo项目的source/_posts/目录下。

在文章的头部加入一个Front-matter——一个YAML格式区域，用于定义文章的元数据。

1
2
3
4
5
6
7
8
9
10
11

---
title: 文章题目
date: 2025-7-9 19:00:00
tags:
  - Hexo
  - 博客搭建
  - Nginx
categories:
  - 安装
---
(正文)

美化与配置

Hexo的灵魂在于其丰富的主题。我选择了很多主题

cactus, icarus, matery, next
cactus的github地址：https://github.com/probberechts/hexo-theme-cactus.git
可以在github下载，并且放到themes路径下。同时配置_config.yml，修改theme字段：

1

theme: matery

在配置过程中需要仔细越多所选主题的官方文档，并且对主题配置文件进行修改，如配置导航菜单、社交链接、个人头像等等。

部署上线

我们将本地生成的静态网站部署到服务器。

1. 生成静态文件
   在本地博客的根目录下，执行命令

1

hexo generate # 简写：hexo g

所有的网站文件将被生成并存放在public/目录中。

2. 上传到服务器
   使用rsync是高效、可靠的方式，它能增量同步文件，仅上传有变动的部分：

1
2
3
4

# 将 public/ 目录下的所有内容同步到服务器的 /var/www/my-hexo-site 目录
rsync -avz public/ user@your_server_ip:/var/www/my-hexo-site
# 我的命令如下
rsync -avz public /var/www/hexo-site

3. 配置Nginx
   编辑域名的Nginx配置文件，核心是修改root指令，使其指向新的网站目录

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

server {
    listen 80;
    server_name your-domain.com; # 你的域名

    # 核心修改：将 root 指向 Hexo 生成的静态文件目录
    root /var/www/my-hexo-site;
    index index.html index.htm;

    location / {
        try_files $uri $uri/ =404;
    }
    
    # 如果有 SSL, listen 443 等配置也应在此处
    # ...
}

4. 重载Nginx配置

1
2

sudo nginx -t           # 检查配置语法是否有问题
sudo nginx -s reload    # 使新配置重新生效

写文章并更新

Hexo教程

之后在使用过程中，如果需要发布新博客，直接

1

hexo new "你的文章标题"

在整个文章编写好之后，静态部署并且迭代更新到nginx路径下，也就是使用

1
2

hexo g
rsync -avz public /var/www/hexo-site