Hexo博客搭建完整指南

发表于 更新于 分类于 阅读次数：

为什么选择Hexo?

Hexo 是一个快速、简洁且高效的博客框架，具有以下优势：

  • 极速生成：Node.js驱动，每秒可生成数十个页面
  • 丰富插件：支持SEO、评论、统计等数百种插件
  • 多平台部署：一键部署到GitHub Pages、Netlify等平台
  • 主题生态：数百款精美主题，高度可定制

环境准备

系统要求

环境 最低要求 推荐配置
Node.js v10.13.0 v16.0.0+
Git v2.0.0 v2.30.0+
操作系统 Windows/macOS/Linux 任意现代系统

安装步骤

使用标签页功能需要先安装插件：npm install hexo-tag-tabs --save

    验证安装：

    node -v  # 应显示v16+版本
git --version  # 应显示v2.30+版本
npm -v  # 应显示v7+版本
    1. 安装 Hexo 命令行工具
    npm install -g hexo-cli
    1. 初始化项目（在空目录中）
    # 如果你是在全新环境中设置
mkdir blog-folder
cd blog-folder
hexo init .
npm install
    1. 如果使用当前仓库
    # 克隆仓库
git clone https://github.com/wangqiqi/wangqiqi.github.io
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 主题
    # 方法一：使用 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
    1. 启用主题（在 _config.yml 中修改）
    theme: next
    1. 安装必要的插件
    npm install hexo-generator-searchdb --save  # 搜索功能
npm install hexo-generator-feed --save      # RSS 订阅
npm install hexo-deployer-git --save        # Git 部署

    本地开发

    启动本地服务器

    hexo server
# 或简写为
hexo s

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

    排查本地预览问题

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

    1. 确认主题是否正确安装到 themes/next 目录
    dir themes\next
    1. 清除缓存并重新生成
    hexo clean && hexo g && hexo s
    1. 检查 _config.yml 中主题设置是否正确
    theme: next  # 必须与 themes 目录下的主题文件夹名称一致

    创建新文章

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

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

    文章格式

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

    ---
title: 文章标题
date: 2023-01-01 12:00:00
categories:
  - 分类名称
tags:
  - 标签1
  - 标签2
description: 文章描述
---

这里是文章内容...

    构建与部署

    配置部署

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

    deploy:
  type: git
  repo: https://github.com/nxu-game/wangqiqi.github.io
  branch: master

    生成静态文件

    hexo generate
# 或简写为
hexo g

    部署到 GitHub Pages

    hexo deploy
# 或简写为
hexo d

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

    hexo generate --deploy
# 或简写为
hexo g -d

    部署问题排查

    如果遇到部署问题：

    1. 确认 hexo-deployer-git 插件已安装
    npm install hexo-deployer-git --save
    1. 检查 GitHub 仓库配置是否正确
    2. 检查 Git 用户凭证是否正确设置

    主题定制

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

    更换主题风格

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

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

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

    # Schemes
scheme: Gemini

    推荐自定义部分

    1. 网站图标：替换 source/images/ 目录下的图标文件
    2. 代码高亮风格：调整 _config.yml 中的 highlight 部分
    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: ''
    1. 添加自定义页面：
    hexo new page "about"
hexo new page "categories"
hexo new page "tags"
    1. 集成第三方服务：如 Valine 评论系统、百度/谷歌统计等

    写作风格建议

    1. 使用 Markdown：熟悉 Markdown 语法，高效编写文章
    2. 图文结合：适当添加图片、代码示例增加可读性
    ![图片描述](/images/example.jpg)

代码示例：
```python
def hello_world():
    print("Hello, World!")
    1. 段落结构：注意段落划分，使用标题层级组织内容
    2. 代码展示：使用代码块标注语言类型以获得语法高亮

    常见问题

    主题配置无效

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

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

    文章不显示

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

    更新主题

    更新 NexT 主题：

    cd themes/next
git pull

    清除缓存

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

    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 目录，它包含了所有需要维护的内容：

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

    写作和更新流程

    1. 写新文章：

      # 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. 本地预览：

      # 清理缓存并重新生成
hexo clean

# 生成静态文件
hexo g

# 启动本地服务器
hexo s

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

    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 清理缓存
      • 重新生成静态文件
      • 检查主题配置是否正确

    高级配置技巧

    _config.yml核心配置

    site:
  title: 我的技术博客
  subtitle: '分享AI与计算机视觉技术'
  description: '专注于AI、机器学习和计算机视觉领域的技术博客'
  keywords: AI, 机器学习, 计算机视觉, 技术分享
  author: 王七七
  language: zh-CN
  timezone: 'Asia/Shanghai'

# URL配置
url: https://znza.top
root: /
permalink: :year/:month/:day/:title/
permalink_defaults:
  lang: zh-CN

# 分页设置
per_page: 10
pagination_dir: page

# 主题配置
theme: next

    Next主题个性化

      内容创作指南

      Markdown高级语法

      数学公式

      使用Hexo渲染数学公式需安装插件：

      npm install hexo-filter-mathjax --save

      在文章中使用LaTeX语法：

      $$E=mc^2$$

\(a^2 + b^2 = c^2\)

      流程图

      ```mermaid
graph TD
    A[开始] --> B{条件A}
    B -->|是| C[结果A]
    B -->|否| D[结果B]
    C --> E[结束]
    D --> E

      
### SEO优化策略

1. **标题优化**
   - 包含核心关键词
   - 控制在50-60个字符
   - 使用吸引人的表述

2. **内容优化**
   - 首段包含关键词
   - 合理使用小标题（h2-h4）
   - 关键词密度控制在2%-5%

3. **Meta标签**
   ```yaml
   # 在文章Front-matter中添加
   keywords: Hexo, SEO, 博客优化
   description: 详细介绍Hexo博客的SEO优化方法

      部署与维护

      多环境部署方案

        博客维护 checklist

        • [ ] 定期备份 _config.yml和文章内容
        • [ ] 使用 hexo clean清理缓存
        • [ ] 更新Hexo和插件到最新版本
        • [ ] 检查死链接和图片引用
        • [ ] 优化大型图片和资源

        常见问题解决

        部署后样式丢失

        # 检查站点URL配置
hexo config url

# 确保配置正确后重新部署
hexo clean && hexo deploy

        本地预览与线上差异

        # 生成静态文件并本地预览
hexo generate && hexo server -s

        插件冲突解决

        # 查看已安装插件
npm list --depth=0

# 卸载冲突插件
npm uninstall hexo-plugin-name

        推荐资源

        优质插件

        • hexo-generator-searchdb: 站内搜索功能
        • hexo-filter-nofollow: 添加nofollow属性
        • hexo-autoprefixer: CSS自动前缀
        • hexo-related-popular-posts: 相关文章推荐

        学习资源

        • Hexo官方文档
        • Next主题文档
        • Hexo插件大全