Hexo + Butterfly 博客从零搭建到 Vercel 上线全记录(含踩坑)
前言
作为一名计本大二学生。在不知某种机缘巧合之下,刷到了别人博客、听到了一些建议。于是乎我也想要搭建一个博客,用来沉淀平时的技术学习、项目实战以及算法题解。这个博客不仅是记录,更希望它作为一个核心个人项目,未来能写进简历。
经过一番折腾,终于成功上线。本文记录从零搭建 Hexo + Butterfly 主题,到部署至 Vercel 的完整流程,以及在这个过程中踩过的坑,希望能帮到后来的同学。
一、 技术选型
- 框架:Hexo(基于 Node.js 的静态博客框架,轻量、极速、支持 Markdown)
- 主题:Butterfly(GitHub 上非常火的极客风格主题,配置丰富,生态好)
- 代码托管:GitHub(同时同步 Gitee 保持绿格子活跃)
- 部署平台:Vercel(免费、支持绑定自定义域名、推送代码自动构建部署)
二、 环境准备与本地跑通
统一账号信息:先更新本地 Git 和 Gitee 的邮箱保持一致,防止后续提交项目代码时不记录“绿格子”(与博客搭建无关)。
基础环境:注册 GitHub,安装 Node.js(使用 fnm 进行版本管理,附带 npm)。
本地初始化:使用终端命令跑通 Hexo 基础框架。
1
2
3
4
5npm install -g hexo-cli
hexo init myblog
cd myblog
npm install
hexo s更换主题:将 Butterfly 主题克隆到 themes 目录,并在
_config.yml中修改theme: butterfly。随后根据官方文档配置了菜单导航、分类、标签以及侧边栏卡片。创作第一篇:使用
hexo new "文章名"生成 Markdown 文件,用 VSCode 进行编写。
三、 部署上线与 Vercel 踩坑
1. 推送到 GitHub
在 GitHub 新建仓库,本地执行 git init 并配置 .gitignore(忽略 node_modules 和 public 等巨型文件夹),然后将代码推送到远程 main 分支。
2. Vercel 部署(核心踩坑)
登录 Vercel 导入 GitHub 仓库进行自动构建,遇到了两个棘手问题:
坑一:仓库被误判为“多服务项目”
- 现象:部署时,Vercel 识别提示需要配置多服务,甚至生成了 Agent 提示词让我进行干预。
- 排查:我怀疑是因为主题目录下包含了一些非 Hexo 的其他配置文件(例如 Jekyll 相关),导致 Vercel 框架探测机制混淆。
- 解决:对于普通的 Hexo 博客,本质就是纯静态站点。我最终清理了容易干扰识别的多余配置文件,并明确了构建命令(
npm run build)和输出目录(public),问题得以解决。
坑二:Vercel 账号风控拦截
- 现象:注册 Vercel 时一直触发风控拦截。经过排查,发现同一个 Google 账户下,新旧(名称) Gmail 被识别成了两个独立账户,新改名的账户触发了安全机制。
- 排查与总结:原因可能是叠加了“使用了 VPN”、“新账户刚改名”以及“短时间重复尝试登录”几个因素。
- 解决:停止短时间内的频繁重试,换个纯净的网络节点或等待风控解除后,使用一致的老账号重新授权成功。
四、 下一步计划
目前代码已经成功上线 Vercel,公网可访问。接下来:
- 等待阿里云购买的域名审核通过。
- 绑定自定义域名并开启 SSL。
- 正式开始日更(可能…),把项目总结和每日算法题写进来。
结语
搭建博客的过程虽然踩了不少坑,但也锻炼了看文档、使用工具、排查问题的能力。希望我的经历可以帮助后来的大家,如果有想一同学习的同学,欢迎通过我的邮箱联系我。当然,无论出于什么原因,都欢迎大家通过邮箱与我联系!点击这里给我发邮件