从零搭建个人独立博客：Hexo + GitHub Pages 极速建站与踩坑实录

引言作为一名爱折腾的开发者刚解决完一个极其棘手的 WebGL 3D 网页滚动陷阱 Bug最爽的事情莫过于把这份血汗经验写成文章分享出来这篇文章将为你带来一份实战教程完整记录我是如何使用Hexo配合GitHub Pages建站并解决 “图床存储” 和 “Markdown 渲染冲突” 的踩坑全过程。板块一本地环境极速初始化搭建静态博客的第一步是在自己的电脑上打好地基。打开你的终端Terminal 或 cmd找一个风水宝地比如E:\博客文件夹 我们直接敲击键盘开始施法步骤 1初始化你的博客项目在终端输入以下命令hexo init my-tech-blog(命令敲下后Hexo 会自动从云端拉取脚手架终端会提示INFO Start blogging with Hexo!)步骤 2进入目录并安装依赖cd my-tech-blog npm install(这里 npm 会自动帮你安装数百个必需的依赖包看到added xxx packages就稳了 )步骤 3启动本地预览服务器见证奇迹hexo server执行完毕后终端会跳出一行激动人心的绿字INFO Hexo is running at http://localhost:4000/。 预期效果立刻打开浏览器访问http://localhost:4000/你会看到 Hexo 官方为你生成的第一个基础版博客页面里面静静地躺着一篇《Hello World》 板块二在 GitHub 安家本地地基打好了接下来我们要去 GitHub 上给博客搞一个免费的公网“海景房”。步骤 1新建仓库登录 GitHub点击右上角加号或访问github.com/new创建新仓库New repository 。步骤 2仓库命名的“生死法则”在Repository name仓库名称那一栏必须严格按照你的用户名.github.io的格式填写。比如我的用户名是Qiushi0919那么这里一个字母都不能错必须写Qiushi0919.github.io。只要名字起对GitHub 就会秒懂你要建静态网站 。步骤 3千万管住手核心避坑绝对不要勾选底下的Add README file和Add .gitignore保持一个纯粹的空仓库非常重要否则一会儿我们用 Hexo 往上推代码时绝对会爆出冲突报错。直接点击最绿的那个Create repository按钮即可 。板块三写下你的第一篇 Markdown 文章核心房子建好了现在我们要把写好的干货搬进去。在 Hexo 中写博客你不需要去文件夹里手动右键新建文件一切都可以用极客的方式解决。步骤 1用命令生成新文章保持终端在你博客的根目录下敲下这行命令新建一篇文章hexo new 告别网页3D滚动陷阱步骤 2找到你的 Markdown 文件打开你的博客文件夹依次进入source-_posts目录 。你会发现里面多了一个叫告别网页3D滚动陷阱.md的文件。步骤 3保留“头部”粘贴正文用你的 Typora 或其他编辑器打开这个.md文件。你会看到文件最上方有两行被---包围的内容这叫 Front-matter用来设置网页标题和发布时间等 。⚠️ 避坑提醒千万保留这两条虚线和里面的内容在你只需把光标移到下方把你在这篇 Typora 里写好的所有排版精美的 Markdown 源码直接一股脑粘贴进去然后按下Ctrl S保存 。板块四配置与一键部署 (Deploy)空房子建好了现在我们要把本地精美的博客装修“发射”上天。步骤 1修改灵魂配置文件用编辑器强烈推荐 Typora 或 VS Code打开你博客根目录下的_config.yml文件。直接拉到最最底部找到# Deployment区域 。步骤 2配置部署地址严格按照以下格式修改注意 YAML 格式极其严格冒号后面必须有一个英文空格deploy: type: git repo: https://github.com/Qiushi0919/Qiushi0919.github.io.git branch: main步骤 3一键发射连招回到终端敲下这行最帅的终极连招清缓存 - 生成静态网页 - 部署上云hexo clean hexo g hexo d 预期效果看着终端里代码疯狂滚动压缩、打包……直到最后一行跳出尊贵的绿色字体INFO Deploy done: git 这四个字意味着大功告成现在所有人都可以通过https://Qiushi0919.github.io访问你的杰作了板块五白嫖 GitHub Issues 做零成本图床我的文章里要放几个演示动图GIF。但把几十兆的 GIF 塞进代码仓库里不仅会让后续上传慢如蜗牛还会撑爆本地空间。这里我问了一下Gemini学到了一个“神级偷懒操作”。步骤 1召唤输入框回到你刚刚建好的 GitHub 仓库点击顶部的Issues标签新建一个 Issue标题随便起比如叫blog1 。步骤 2暴力拖拽上传把我精心录制好的展示 WebGL 交互的2 张 GIF 和 1 张 PNG 演示图直接用鼠标暴力拖拽进这个多行文本输入框里 步骤 3获取永久直链稍微等几秒钟输入框里会自动生成类似这样的 Markdown 代码。 把这些链接复制下来直接粘贴到我本地的 Typora 文章源码里。Issue 可以提交也可以关闭只要链接生成图片就已经永久白嫖存放在 GitHub 的全球 CDN 加速节点上了加载极其丝滑这里我上传了3张图片包含2个GIF和一个PNG。板块六填坑指南 - Markdown 渲染方言差异就在我以为一切完美跑到网页上验收时却迎头撞上了一个经典名场面“本地 Typora 岁月静好一发到网上原形毕露”。 翻车现场在我的文章里有一段加粗的重点词汇***滚动陷阱(Scroll Trap)***。在 Typora 里看是完美的粗体字但部署到网页上后它不仅没加粗那几颗星号反而像乱码一样原样暴露在页面上。 破案分析这根本不是写错了而是撞上了臭名昭著的“Markdown 解析器方言差异”Hexo 默认携带的解析器hexo-renderer-marked是一位古板的老顽固它对中文标点符号和全角字符边界极其敏感。星号一旦紧贴着中文它就直接罢工不认了。️ 终极解决方案一劳永逸不要向它妥协去敲难看的空格直接在终端里把这个默认解析器“炒鱿鱼”换上对中文排版极度友好、和 Typora 内核高度一致的顶级引擎markdown-it执行以下神仙救火指令# 1. 卸载笨蛋老解析器 npm uninstall hexo-renderer-marked ​ # 2. 安装聪明的下一代解析器 npm install hexo-renderer-markdown-it --save ​ # 3. 重新清空缓存并推上云端 hexo clean hexo g hexo d 预期效果等待 1 分钟后强制刷新网页Ctrl F5那些刺眼的星号终于乖乖消失变成了极其舒适、优雅的加粗黑体字图片完美显示整个技术博客的交互质感瞬间拉满 。总结踩完这些坑看着最终丝滑运行的独立博客那种全权掌控自己代码和内容的成就感是无与伦比的。从今天起这里就是我的主场后续我也会持续在这里分享关于前端交互、WebGL 以及更多踩坑实录。如果你也厌倦了受限的内容平台不如趁今天去搭一个专属于你自己的数字基地吧