从零搭建个人独立博客：Hexo + GitHub Pages 极速建站与踩坑实录
作为一名爱折腾的开发者，刚解决完一个极其棘手的 WebGL 3D 网页滚动陷阱 Bug，最爽的事情莫过于把这份血汗经验写成文章分享出来！
这篇文章将为你带来一份实战教程，完整记录我是如何使用 Hexo 配合 GitHub Pages 建站，并解决 “图床存储” 和 “Markdown 渲染冲突” 的踩坑全过程。
板块一：本地环境极速初始化
搭建静态博客的第一步，是在自己的电脑上打好地基。打开你的终端（Terminal 或 cmd），找一个风水宝地（比如 E:\博客 文件夹 ），我们直接敲击键盘开始施法：
步骤 1：初始化你的博客项目
在终端输入以下命令：
1 | hexo init my-tech-blog |
(命令敲下后，Hexo 会自动从云端拉取脚手架，终端会提示 INFO Start blogging with Hexo! )
步骤 2：进入目录并安装依赖
1 | cd my-tech-blog |
(这里 npm 会自动帮你安装数百个必需的依赖包，看到 added xxx packages 就稳了 )
步骤 3：启动本地预览服务器（见证奇迹）
1 | 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：用命令生成新文章
保持终端在你博客的根目录下，敲下这行命令新建一篇文章：
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 格式极其严格，冒号后面必须有一个英文空格）：
1 | deploy: |
步骤 3：一键发射连招！
回到终端，敲下这行最帅的终极连招（清缓存 -> 生成静态网页 -> 部署上云）：
1 | 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 | # 1. 卸载笨蛋老解析器 |
🎉 预期效果： 等待 1 分钟后强制刷新网页（Ctrl + F5），那些刺眼的星号终于乖乖消失，变成了极其舒适、优雅的加粗黑体字 ！图片完美显示，整个技术博客的交互质感瞬间拉满 。
总结
踩完这些坑，看着最终丝滑运行的独立博客，那种全权掌控自己代码和内容的成就感是无与伦比的。
从今天起，这里就是我的主场！后续我也会持续在这里分享关于前端交互、WebGL 以及更多踩坑实录。如果你也厌倦了受限的内容平台，不如趁今天，去搭一个专属于你自己的数字基地吧！