引言
作为一名爱折腾的开发者，刚解决完一个极其棘手的 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 以及更多踩坑实录。如果你也厌倦了受限的内容平台，不如趁今天，去搭一个专属于你自己的数字基地吧！
