从零搭建博客和踩坑记录

耗费了整整三天，终于成功搭建好了自己的个人技术博客。从零基础环境配置、主题安装美化，到最终部署上线到 GitHub Pages，遇到了新手大概率会遇到的各类问题。

这篇博客记录了自己亲自的搭建经历以及踩过的坑。

一、搭建前的准备

搭建 Hexo 博客只要提前装好两个核心环境，绝大多数启动报错都是环境缺失、版本不匹配导致的。

1. 必须安装的软件

  • Node.js：Hexo 运行核心环境，最好安装 LTS 稳定版，最新测试版容易出现兼容报错
    官网链接：https://nodejs.org/

  • Git：用于本地博客初始化、远程仓库部署
    官网链接：https://git-scm.com/

安装完成后，要重新打开新的终端窗口，输入一下命令，验证环境是否配置成功：

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

能正常输出版本号即为安装成功，若提示“不是内部或外部命令”，大概率是环境变量未配置。

二、Hexo 基础搭建流程

前期环境配置无误后就可以开始初始化博客。

1. 全局安装 Hexo

1
npm install -g hexo-cli

如果下载很慢，可以切换国内镜像：

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

2. 初始化博客文件夹

1
2
hexo init blog
cd blog

blog 就是我们的博客根目录，路径不要带空格和中文，否则可能出现命令报错或构建异常。

3. 安装依赖包

1
npm install

4. 本地启动测试

1
hexo s

终端启动成功后，浏览器打开 localhost:4000，即可看到 Hexo 默认初始页面，代表基础博客搭建完成。

按 Ctrl + C 可以停止本地服务。

三、主题安装与配置

Hexo 默认主题样式简陋，我选择了热门主题 Butterfly。

1. 下载主题到根目录

执行：

1
git clone https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly

2. 启用主题

打开博客根目录的 _config.yml 全局配置文件，找到 theme 配置项，修改为：

1
theme: butterfly

YAML 语法严格，冒号后面必须加空格，不能用中文标点，否则会报错。

3. 主题依赖安装

Butterfly 主题需要额外依赖，很多新手跳过这一步，导致页面空白、功能失效。在根目录执行：

1
npm install hexo-renderer-pug hexo-renderer-stylus --save

本地预览测试：

1
hexo clean && hexo s

四、我踩过的坑

以下所有问题均为我搭建过程中亲身遇到、逐一排查解决的真实报错。

1. 环境安装成功，终端依然提示命令不存在

问题原因：软件安装时未勾选自动配置环境变量，或手动配置路径错误，系统无法识别 hexo、node 等命令。

解决方案：重新安装 Node.js 和 Git，务必勾选自动配置环境变量；若已安装，手动找到软件安装路径，添加到系统环境变量后，重启终端再测试。

2. hexo s 启动失败，终端报错、页面无法访问

问题原因：博客文件夹依赖缺失、npm 缓存冲突、初始化文件残缺。

解决方案：依次执行清理、重装依赖、重启服务命令：

1
2
3
hexo clean
npm install
hexo s

3. 更换 Butterfly 主题后，网站样式错乱、纯白空白

问题原因：99% 是未安装主题专属渲染依赖，这是新手最容易遗漏的步骤，默认主题无需这些依赖，Butterfly 必须单独安装。

解决方案：执行上文的 pug、stylus 渲染依赖安装命令，清理缓存后重启服务即可恢复正常样式。

4. 配置文件修改后不生效，改了白改

问题原因：两个核心误区：一是混淆全局配置和主题配置文件，二是修改配置后未清理缓存、未重启服务。

核心区分：

  • 根目录 _config.yml：全局配置（网站标题、描述、部署仓库）
  • themes/butterfly/_config.yml：主题配置（侧边栏、图标、美化样式）

解决方案：修改任意配置后，固定执行 hexo clean && hexo s，确保新配置生效。

5. Markdown 文章无法渲染、图片不显示

问题原因：文章命名不规范、图片路径错误、特殊符号冲突。

解决方案：文章文件名尽量只用英文、数字、下划线，避免中文和空格；图片使用正确路径，存放到规范文件夹，避免路径识别失败。

6. 部署 GitHub Pages 失败，网页加载空白

这个放到 GitHub 部署部分详细讲解。

五、GitHub Pages 部署 Hexo 博客

作用：把本地博客上传到 GitHub，生成公开网址，任何人都能访问你的博客。

前置准备：

  1. 注册 GitHub 账号：https://github.com/
  2. 记住你的 GitHub 用户名（username，区分大小写）
  3. 已经安装 Git，并且配置 Git 用户名和邮箱（和 GitHub 账号保持一致）

1. 本地配置 Git

打开终端，任意位置执行：

1
2
git config --global user.name "你的GitHub用户名"
git config --global user.email "你的GitHub注册邮箱"

2. GitHub 创建仓库

  1. 登录 GitHub 主页，右上角点击 New 新建仓库

  2. 仓库名称：部署到个人主页时必须是 你的用户名.github.io；部署到项目页时仓库名可以自定义

    例：如果你的 GitHub 用户名是 zhonghai2006，部署到个人主页时仓库名就填 zhonghai2006.github.io

    仓库名或发布分支设置错误，都可能导致网页无法访问

  3. Description 描述随便写

  4. 勾选 Public（公开仓库，免费）

  5. 不要勾选 Add README file，直接点 Create repository 创建仓库

3. 安装 hexo-deployer-git 部署插件（博客根目录执行）

进入你的 blog 博客根目录，终端运行：

1
npm install hexo-deployer-git --save

这个插件就是一键自动推送博客静态文件到 GitHub 仓库。

4. 修改 Hexo 根目录 _config.yml 的部署配置

打开根目录的 _config.yml，拉到最底部，找到 deploy 配置，改成下面内容：

1
2
3
4
deploy:
  type: git
  repo: https://github.com/你的用户名/你的仓库名.git
  branch: main

示例：

1
2
3
4
deploy:
  type: git
  repo: https://github.com/zhonghai2006/boke-github.io.git
  branch: main

注意：冒号后面必须有空格，YAML 语法严格，中文标点会直接部署失败！

如果部署的是项目页，还需要同步修改根目录 _config.yml 的 url 和 root，否则页面样式和链接会 404。例如仓库名为 boke-github.io 时：

1
2
url: https://zhonghai2006.github.io/boke-github.io
root: /boke-github.io/

5. 生成静态文件 + 一键部署（每次更新博客都要执行这三步）

在博客根目录终端依次执行：

1
2
3
4
5
6
7
8
# 清理旧缓存文件
hexo clean

# 生成静态网页文件，输出到 public 文件夹
hexo g

# 部署上传到 GitHub
hexo d
  • hexo g = hexo generate，生成网页
  • hexo d = hexo deploy，部署推送

第一次执行 hexo d 前需要先配置好 GitHub 凭据：用 SSH 密钥推送（repo 写成 git@github.com:用户名/仓库名.git），或在 HTTPS 地址下使用 Personal Access Token 登录。

6. 访问你的博客

等待 1 至 3 分钟（GitHub 需要时间构建页面）：

  • 部署到个人主页：https://你的用户名.github.io
  • 部署到项目页：https://你的用户名.github.io/你的仓库名/

我在 GitHub Pages 部署时踩过的坑

1. 仓库名字写错，网站打不开

  • 部署到个人主页时，仓库名必须是 用户名.github.io，大小写严格匹配
  • 部署到项目页时，仓库名可自定义，但访问路径要带上仓库名

2. hexo d 报错，提示权限不足

  1. 确认 repo 地址是否正确，是否多复制了空格
  2. SSH 方式：确认已生成 SSH 密钥并添加到 GitHub 账号
  3. HTTPS 方式：使用 Personal Access Token 代替账号密码登录

3. 部署成功，但打开网页 404

  1. 查仓库发布分支是不是 main
  2. 项目页还要检查 url 和 root 是否和仓库名一致
  3. 等待几分钟再刷新
  4. 确认 hexo g 生成了 public 文件夹

4. 每次更新文章，网页不变

每次写完文章，必须执行 hexo clean && hexo g && hexo d，清理缓存再重新生成 + 部署

搭建复盘

这次从零搭建 Hexo 博客，看似是简单的工具部署，实则让我收获很多。所有报错和 bug，基本都源于细节遗漏、配置混淆、文件存放不规范，而非操作难度过高。

踩坑的过程，也是快速学习、积累经验的过程，不仅熟练掌握了 Hexo 博客的搭建、配置、排错方法，也对前端静态网站、Git 部署、环境配置有了更清晰的认知。

参考资料