利用 Hexo 与 GitHub Pages 搭建个人博客指南

1. 前期准备与环境配置

开始之前，你需要准备好以下工具和账户，这是搭建博客的基础。

1.1 所需工具与账户

  • GitHub 账户: 如果你还没有，请先去 GitHub 官网 注册一个。
  • Node.js: Hexo 基于 Node.js，请从官网下载 LTS（长期支持版本）。安装后，在终端或命令行中输入 node -v 和 npm -v 来检查是否安装成功。
  • Git: 用于版本控制和部署。同样从官网下载并安装。安装后，可通过 git --version 验证。

1.2 优化安装体验（可选）

国内用户可以通过更换 npm 的镜像源来提升安装包的速度和稳定性：

1
npm config set registry https://registry.npmmirror.com

2. 安装并初始化 Hexo

环境准备好后，我们就可以安装并创建你的博客项目了。

  1. 安装 Hexo CLI (命令行工具):

    1
    npm install -g hexo-cli

  2. 创建博客项目:
    选择一个你喜欢的目录，然后执行以下命令来初始化你的博客。<folder> 替换为你想要的博客文件夹名称，例如 my-blog。

    1
    2
    3
    hexo init <folder>
    cd <folder>
    npm install

  3. 本地预览:
    完成初始化后，可以立即在本地启动服务器查看默认博客的样子：

    1
    hexo server # 或简写为 hexo s

    在浏览器中访问 http://localhost:4000，你应该能看到默认的 Hexo 博客页面。

3. 创建 GitHub 仓库并配置

让你的博客能在互联网上访问的关键是 GitHub Pages。

  1. 创建仓库:

    • 登录 GitHub，点击右上角的 “+” -> “New repository”。
    • 选择仓库为 Public（公开）。
    • 建议勾选 “Initialize this repository with a README”。

  2. 配置 SSH 密钥（推荐）:
    使用 SSH 密钥可以与 GitHub 建立安全的连接，无需每次部署都输入密码。

    • 生成密钥（在任意目录下打开 Git Bash 或终端执行）:

      1
      ssh-keygen -t ed25519 -C "your_email@example.com"
      • 按回车接受默认保存路径。
      • 设置一个安全的密码（可直接回车留空，但不推荐）。

    • 添加公钥到 GitHub:

      • 复制公钥内容（默认位于 ~/.ssh/id_ed25519.pub 文件内）。
      • 进入 GitHub Settings -> SSH and GPG keys -> New SSH key。
      • 标题任意，将公钥内容粘贴到 “Key” 框中并保存。

  3. 测试 SSH 连接:

    1
    ssh -T git@github.com

    看到 “You’ve successfully authenticated” 之类的欢迎信息即表示成功。

4. 配置 Hexo 部署设置

接下来，我们需要告诉 Hexo 如何将博客部署到刚才创建的 GitHub 仓库。

  1. 安装部署插件:
    在你的博客根目录下执行：

    1
    npm install hexo-deployer-git --save

  2. 修改博客配置文件:
    用文本编辑器（切勿使用 Windows 记事本，推荐 VSCode、Sublime Text、Notepad++ 等）打开博客根目录下的 _config.yml 文件。滚动到文件最底部，找到 deploy 部分，并按如下格式修改（注意每个冒号后面的空格必不可少）：

    1
    2
    3
    4
    5
    # 部署配置
    deploy:
      type: git
      repo: <你的 SSH 仓库地址> # 替换为你的 SSH 仓库地址
      branch: main # 或 master，根据你的仓库默认主分支名称决定

搭建项目网站的注意事项

在利用 Hexo 和 GitHub Pages 搭建个人博客时，你可以选择自定义一个仓库名称，例如 hexo-demo，但这会影响到你的博客访问地址。在发布后，你的博客网址是 https://<username>.github.io/hexo-demo。

此时，你需要修改 Hexo 配置文件 _config.yml 中的 url 和 root 参数，以确保正确的页面链接和资源加载。

_config.yml 修改示例：

1
2
3
4
# URL
## If your site is hosted at https://<username>.github.io/hexo-demo
url: https://<username>.github.io
root: /hexo-demo/
  • url: 设置为主域名 https://username.github.io。
  • root: 设置为仓库名称 /hexo-demo/。

5. 写作与部署

现在一切就绪，可以开始写你的第一篇博客并把它发布到网上！

  1. 创建新文章:

    1
    hexo new "我的第一篇文章"

    这条命令会在 source/_posts 目录下生成一个 Markdown 文件（例如 我的第一篇文章.md），用编辑器打开它就可以开始写作了。

    Markdown 文件顶部有一块 Front-matter，用于设置文章属性：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    ---
    title: 我的第一篇文章
    date: 2025-09-01 14:00:00
    categories: [日常]
    tags: [Hexo, 博客]
    ---

    这里是文章的摘要部分...
    <!--more-->
    这里是文章的正文内容，你可以使用 **Markdown** 语法进行写作。

  2. 生成并部署:
    当你写完文章后，通过以下命令将博客部署到 GitHub Pages：

    1
    hexo clean && hexo deploy -g
    • hexo clean: 清理缓存和旧文件。
    • hexo generate (hexo g): 生成静态网页文件。
    • hexo deploy (hexo d): 部署到远程仓库。

    你也可以使用组合命令 hexo g -d 来一次性完成生成和部署。

  3. 访问你的博客:
    部署完成后，等待一两分钟（GitHub 需要一点时间处理），然后在浏览器中访问 https://你的用户名.github.io，你就能看到在线博客了！🎉

6. 基本命令速查表

为了方便记忆，这里汇总了 Hexo 的常用命令：

命令 说明
hexo new "文章标题" 创建一篇新文章
hexo new page "页面名" 创建一个新页面（如关于页）
hexo generate (hexo g) 生成静态网站文件
hexo server (hexo s) 启动本地服务器，用于预览
hexo deploy (hexo d) 部署到远程仓库（如 GitHub Pages）
hexo clean 清除缓存文件和已生成的静态文件

7. 进阶提示与常见问题

  • 关于主题: 默认主题可能比较简洁。你可以在Hexo 主题官网探索大量第三方主题，安装通常只需 git clone 主题到 themes 目录，然后在 _config.yml 中修改 theme 字段即可。
  • 自定义域名: 如果你有自己的域名，可以在仓库根目录创建一个名为 CNAME 的文件（无后缀），里面写上你的域名（例如 blog.yourname.com），并在你的域名注册商处配置 DNS 解析即可。
  • 资源加载问题: 如果部署后发现样式、图片没加载出来，请首先检查 _config.yml 中的 url 和 root 设置是否正确，部署到子目录时 root 需要修改为 /<repository-name>/。
  • 保持更新: 建议将你的 Hexo 博客源文件（整个文件夹）也 push 到一个单独的私有 GitHub 仓库，这样既方便备份，也便于在多台设备上写作和同步。

更换主题的操作步骤

这里以fluid主题为例进行说明：

第一步：下载主题

1
git clone https://github.com/fluid-dev/hexo-theme-fluid.git themes/fluid

或者

1
git clone git@github.com:fluid-dev/hexo-theme-fluid.git  # 可能快一些

这会将 Fluid 主题下载并保存到 themes/fluid 文件夹下。如果你想使用其他主题，只需替换命令中的 URL 和文件夹名称即可。

第二步：配置主题

下载完成后，你需要告诉 Hexo 使用这个新主题。

打开你博客根目录下的主配置文件 _config.yml（注意：是博客根目录的，不是主题文件夹里的）。找到 theme 字段，将它的值改为你新下载的主题文件夹的名称。

1
2
3
4
# Extensions
## Plugins: https://hexo.io/plugins/
## Themes: https://hexo.io/themes/
theme: fluid  # 将这里的 landscape 改成 fluid

第三步：部署博客

本地测试：

1
hexo server

部署到Github Pages：

1
hexo clean && hexo deploy -g

希望这份指南能帮助你顺利搭建起自己的博客！如果遇到问题，Hexo 的官方文档和社区通常是寻找答案的好地方。享受写作和分享的乐趣吧！

with the help of Deepseek and Gemini

#Hexo #Github Pages #博客
利用 Hexo 与 GitHub Pages 搭建个人博客指南
https://younotknowwho.github.io/2025/09/01/利用-Hexo-与-GitHub-Pages-搭建个人博客指南/
Author
You Know Who
Posted on
September 1, 2025
Licensed under