Hexo博客搭建完整指南

发表于 更新于 分类于 ， 阅读次数： 本文字数： 4.2k 阅读时长 ≈ 4 分钟
一份全面的 Hexo 博客搭建指南，包含环境配置、主题安装、写作发布以及常见问题解决方法。

Hexo博客搭建完整指南

个人博客网站: https://znza.top

项目介绍

这是一个基于 Hexo 框架构建的个人博客网站，使用 NexT 主题的 Gemini 风格。主要关注 AI、计算机视觉和机器学习等技术领域。

环境配置

前提条件

  • Node.js (推荐使用 v10.0 以上版本)
  • Git

安装步骤

  1. 安装 Hexo 命令行工具

    1
    npm install -g hexo-cli

  2. 初始化项目（在空目录中）

    1
    2
    3
    4
    5
    # 如果你是在全新环境中设置
    mkdir blog-folder
    cd blog-folder
    hexo init .
    npm install

  3. 如果使用当前仓库

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    # 克隆仓库
    git clone git://github.com/wangqiqi/wangqiqi.github.io.git
    cd wangqiqi.github.io

    # 安装依赖 (确保你已经有 package.json 文件)
    npm install

    # 如果没有 package.json 文件，需要初始化一个新的 Hexo 项目并迁移内容
    # 1. 在别处创建一个新的 Hexo 项目
    mkdir temp_hexo
    cd temp_hexo
    hexo init .
    npm install

    # 2. 复制必要的配置文件到原项目
    # 将 package.json, package-lock.json, _config.yml, scaffolds/ 和 themes/ 等复制到原项目

主题安装

  1. 安装 NexT 主题

    1
    2
    3
    4
    5
    6
    7
    8
    # 方法一：使用 git clone (可能会遇到网络问题)
    git clone https://github.com/theme-next/hexo-theme-next themes/next

    # 方法二：使用 npm 安装 (推荐)
    npm install hexo-theme-next --save

    # 方法三：如果使用 npm 安装但主题不生效，需要复制到 themes 目录
    xcopy /E /I /Y node_modules\hexo-theme-next themes\next

  2. 启用主题（在 _config.yml 中修改）

    1
    theme: next

  3. 安装必要的插件

    1
    2
    3
    npm install hexo-generator-searchdb --save  # 搜索功能
    npm install hexo-generator-feed --save      # RSS 订阅
    npm install hexo-deployer-git --save        # Git 部署

本地开发

启动本地服务器

1
2
3
hexo server
# 或简写为
hexo s

启动后可通过 http://localhost:4000 访问本地预览。

排查本地预览问题

如果出现 “No layout” 警告或者页面样式不正确：

  1. 确认主题是否正确安装到 themes/next 目录

    1
    dir themes\next

  2. 清除缓存并重新生成

    1
    hexo clean && hexo g && hexo s

  3. 检查 _config.yml 中主题设置是否正确

    1
    theme: next  # 必须与 themes 目录下的主题文件夹名称一致

创建新文章

1
2
# 创建名为 "article-title" 的新文章
hexo new post "article-title"

这将在 source/_posts 目录下创建一个名为 article-title.md 的新文件。

文章格式

文章头部使用 YAML front-matter 配置文章属性：

1
2
3
4
5
6
7
8
9
10
11
12
---
title: 文章标题
date: 2023-01-01 12:00:00
categories:
  - 分类名称
tags:
  - 标签1
  - 标签2
description: 文章描述
---

这里是文章内容...

构建与部署

配置部署

编辑 _config.yml，配置部署信息：

1
2
3
4
deploy:
  type: git
  repo: https://github.com/wangqiqi/wangqiqi.github.io
  branch: master

生成静态文件

1
2
3
hexo generate
# 或简写为
hexo g

部署到 GitHub Pages

1
2
3
hexo deploy
# 或简写为
hexo d

也可以生成并部署一步完成：

1
2
3
hexo generate --deploy
# 或简写为
hexo g -d

部署问题排查

如果遇到部署问题：

  1. 确认 hexo-deployer-git 插件已安装

    1
    npm install hexo-deployer-git --save

  2. 检查 GitHub 仓库配置是否正确

  3. 检查 Git 用户凭证是否正确设置

主题定制

当前使用的是 NexT 主题的 Gemini 风格，主题配置文件位于根目录的 _config.yml 和主题目录的 _config.yml（或使用根目录的 _config.next.yml）。

更换主题风格

NexT 主题提供了几种不同的风格：

  • Muse - 默认方案，黑白主调
  • Mist - Muse 的紧凑版本
  • Pisces - 双栏布局
  • Gemini - Pisces 的增强版，现在使用的风格

可在主题配置文件中修改：

1
2
# Schemes
scheme: Gemini

推荐自定义部分

  1. 网站图标：替换 source/images/ 目录下的图标文件
  2. 代码高亮风格：调整 _config.yml 中的 highlight 部分
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    highlight:
      enable: true
      line_number: true
      auto_detect: false
      tab_replace: ''
      wrap: true
      hljs: true
    prismjs:
      enable: false
      preprocess: true
      line_number: true
      tab_replace: ''
  3. 添加自定义页面：
    1
    2
    3
    hexo new page "about"
    hexo new page "categories"
    hexo new page "tags"
  4. 集成第三方服务：如 Valine 评论系统、百度/谷歌统计等

写作风格建议

  1. 使用 Markdown：熟悉 Markdown 语法，高效编写文章

  2. 图文结合：适当添加图片、代码示例增加可读性

    1
    2
    3
    4
    5
    6
    ![图片描述](/images/example.jpg)

    代码示例：
    ```python
    def hello_world():
        print("Hello, World!")

  3. 段落结构：注意段落划分，使用标题层级组织内容

  4. 代码展示：使用代码块标注语言类型以获得语法高亮

常见问题

主题配置无效

确保你的主题配置文件正确：

  • 使用独立主题配置文件：将主题目录下的 _config.yml 复制到站点根目录，并重命名为 _config.next.yml
  • 使用根目录和主题目录的配置文件配合

文章不显示

检查文章 front-matter 是否正确，特别是日期格式。

更新主题

更新 NexT 主题：

1
2
cd themes/next
git pull

清除缓存

遇到异常情况，可尝试清除缓存：

1
hexo clean

Windows 特有问题

  1. 路径问题：Windows 使用反斜杠 \，但配置中应使用正斜杠 /
  2. 编码问题：确保所有文件使用 UTF-8 编码，避免中文显示乱码
  3. 权限问题：某些操作可能需要管理员权限

图片资源管理

开启文章资源文件夹功能后，可以为每篇文章创建同名资源文件夹：

  1. 确保 _config.yml 中设置了 post_asset_folder: true
  2. 创建文章时会自动生成同名文件夹：hexo new post "my-post"
  3. 在文章中引用图片：![描述](image.jpg) 或使用 {% asset_img image.jpg 描述 %}

参考资源

  • Hexo 文档
  • NexT 主题文档
  • Markdown 基本语法
  • Hexo 部署到 GitHub Pages
  • NexT 主题配置

日常工作流程

目录结构说明

博客项目的核心是 source 目录，它包含了所有需要维护的内容：

1
2
3
4
5
6
7
8
9
10
11
source/
├── _posts/           # 博客文章
│   ├── 文章1.md
│   └── 文章2/        # 文章资源文件夹（如果有图片等资源）
├── images/           # 全局图片资源
│   ├── person.jpg    # 个人头像
│   └── wechat.jpg    # 微信二维码等
├── about/            # "关于"页面
├── tags/            # 标签页面
├── categories/      # 分类页面
└── CNAME            # 域名配置

写作和更新流程

  1. 写新文章：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    # 1. 创建新文章
    hexo new post "文章标题"

    # 2. 编辑文章（在 source/_posts/文章标题.md）

    # 3. 如果文章包含图片等资源：
    # - 创建同名文件夹：source/_posts/文章标题/
    # - 将图片等资源放入该文件夹
    # - 在文章中使用相对路径引用：![图片说明](文章标题/图片.jpg)

  2. 添加全局图片：

    • 将图片放入 source/images/ 目录
    • 在文章中使用绝对路径引用：![图片说明](/images/图片.jpg)

  3. 修改页面：

    • 关于页面：编辑 source/about/index.md
    • 标签页面：编辑 source/tags/index.md
    • 分类页面：编辑 source/categories/index.md

  4. 本地预览：

    1
    2
    3
    4
    5
    6
    7
    8
    # 清理缓存并重新生成
    hexo clean

    # 生成静态文件
    hexo g

    # 启动本地服务器
    hexo s

    访问 http://localhost:4000 预览效果

  5. 部署网站：

    1
    2
    3
    4
    5
    # 部署到 GitHub Pages
    hexo d

    # 或者一键生成并部署
    hexo g -d

维护建议

  1. 定期备份：

    • 定期提交到 Git 仓库
    • 备份 source 目录最重要，它包含所有原始内容

  2. 图片管理：

    • 文章配图放在文章同名文件夹中
    • 全局图片（如头像）放在 source/images/ 中
    • 压缩图片以优化加载速度

  3. 定期清理：

    • 可以安全删除的临时文件：
      • .deploy_git/（部署缓存）
      • public/（生成的静态文件）
      • db.json（数据库缓存）
    • 这些文件会在需要时自动重新生成

  4. 版本控制：

    • 主要关注 source 目录的变更
    • 可以忽略的文件已在 .gitignore 中配置

常见问题解决

  1. 部署失败：

    • 检查网络连接
    • 确认 GitHub 仓库设置正确
    • 验证 Git 凭证是否有效

  2. 图片显示问题：

    • 检查图片路径是否正确
    • 区分相对路径和绝对路径的使用场景
    • 确保图片已经提交到正确的目录

  3. 预览异常：

    • 使用 hexo clean 清理缓存
    • 重新生成静态文件
    • 检查主题配置是否正确