个人博客搭建全流程指南（完整版）

cwz0528

249人浏览 · 2026-08-13 15:13:15

cwz0528 · 2026-08-13 15:13:15 发布

从0开始保姆级手把手带你搭建个人博客

前言

本文内容面向新手小白，记录主包第一次动手搭建博客的
我跟着教程用 Hexo 搭了一个个人博客,部署在 GitHub Pages,主题是 Butterfly,整体做成了水墨风。本文记录我从零到上线、再到用 Claude 帮忙优化的完整流程。重点讲技术细节,踩过的坑。

一、效果展示

博客主页

项目	选择
博客框架	Hexo(静态站点生成器)
主题	Butterfly 5.7.0
托管	GitHub Pages
个性化定制	Claude Code(自定义 CSS/JS、特效调试)

二、搭建流程

1. 初始化项目

先安装 Node.js 和 Git,然后:

npm install hexo-cli -g
hexo init my_blog
cd my_blog
npm install
hexo s   # 本地预览,打开 http://localhost:4000

常用命令:

hexo g —— 生成静态文件到 public/
hexo clean —— 清理缓存
hexo d -g —— 生成并部署
hexo s —— 本地预览

2. 安装 Butterfly 主题

# 下载主题到 themes/butterfly
git clone https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly
# 安装主题需要的渲染插件
npm install hexo-renderer-pug hexo-renderer-stylus
# 复制主题配置到站点根目录(重点:主题配置不写在 themes 里)
cp themes/butterfly/_config.yml _config.butterfly.yml

在站点根目录的 _config.yml 中启用主题:

theme: butterfly

Butterfly 的核心配置都在 _config.butterfly.yml:导航菜单、首页 banner、自定义代码注入(inject)、评论系统、访问统计等。

3. 部署到 GitHub Pages

先创建一个仓库 你的用户名/你的用户名.github.io,然后:

npm install hexo-deployer-git --save

在 _config.yml 中配置部署信息:

deploy:
  type: git
  repo: git@github.com:你的用户名/你的用户名.github.io.git
  branch: main

配置好 SSH key 后,一条命令上线:hexo d -g。

三、用 Claude 做个性化优化（重点）

网站本身跑起来很容易,真正花时间的是让它"像自己的"。下面这些功能都是我和 Claude Code 一起完成的。

1. 水墨风改造

主包搜寻了网上很多教程及美化方案，发现大多为二刺螈风格，而主包对水墨侠客风较为喜欢，下面是个性化改造

整体视觉方向是"水墨":

全局背景用墨色山水图(#web_bg),搭配半透明磨砂卡片,贴合水墨配色
首页做打字机效果
自定义样式统一放在 source/css/custom.css,通过主题配置注入:

inject:
  head:
    - <link rel="stylesheet" href="/css/custom.css">

2. 自定义页面

在 source/ 下建页面目录,用 front-matter 指定类型和 banner:

---
title: 关于
type: about
top_img: /img/girl.jpg
---

页面内容

我加了关于、项目、友链等页面;分类、标签、归档页用 hexo new page 生成。导航菜单在 _config.butterfly.yml 里配置。

3. 图片优化

首页 banner 原图 3.1MB,压到 576KB(JPEG q90、渐进式编码、subsampling=0),体积降了八成,加载明显变快。链接页、分类页的 banner 也做了同样的压缩处理。

4. 页脚水墨远山

用 Python 脚本生成 SVG:三层山峦叠影加燕子剪影,再配 CSS 渐变,做出"淡墨远山"的页脚效果。

5. 下雪特效 + 开关

用 Canvas 实现全站下雪,右下角有个开关按钮可以关闭,选择结果用 localStorage 记住:

雪花是圆形柔边(径向渐变),颗粒小、速度慢,不干扰内容阅读
通过 inject.bottom 注入:<script src="/js/snow.js?v=8">
每次改 JS 都要换 ?v= 版本号,避免浏览器走缓存

6. 音乐播放器

用 APlayer + Meting 加了一个固定在页面右侧的播放器,直接播放歌单。

7. 评论系统 giscus

基于 GitHub Discussions,在主题配置里填好 repo_id 就能用,评论数据都存在自己的仓库里。

8. 访问统计 busuanzi

页脚显示"访客 / 浏览"两个数字,由 busuanzi 提供。这里踩过一个坑,见下文。

四、踩过的坑(最终结论)

hexo server 是内存缓存。改了代码 hexo g 之后,必须重启本地服务,浏览器还要强刷(Ctrl+F5),否则看到的一直是旧页面。
自定义 JS 要加版本号。不换 ?v= 浏览器会命中缓存,改了代码却看不到效果。
busuanzi 翻页计数虚增。busuanzi 脚本带了 data-pjax 标记,每次切换分页都会重新执行、重新计数,导致"浏览"数字翻一页加 1。修复:去掉脚本上的 data-pjax,让它只在真正刷新页面时计数;翻页时用本地缓存恢复显示的数字。
主题文件别乱改。themes/butterfly 下的 .pug 文件在主题升级时会被覆盖。能用 inject + 自定义 CSS/JS 解决的,就不要动主题文件。
CSS 的 !important 会压过页面设置。custom.css 里带 !important 的规则会覆盖页面单独配置的 top_img,排查 banner 不生效时先查这里。
特效"看不见"先证明它真的在跑。下雪特效有段时间怎么调都显示不出来,最后是通过给脚本加一个显示帧数的调试角标,再用独立测试页验证,才定位到真正的 bug(雪花数组没有初始化)。排查视觉效果,要验证浏览器里实际渲染的结果,而不是只看服务返回的 HTML。