搭建实录：从零到上线踩过的坑

坑一：Git 代理导致 clone 失败#

现象

1
git clone https://gitee.com/xxx/yyy.git
2
fatal: unable to access '...': Failed to connect to gitee.com:443
3
over proxy 127.0.0.1 after 2036 ms

定位

代理残留在了 Git 全局配置里，但本地那个端口根本没服务在跑：

1
git config --global --get https.proxy
2
# http://127.0.0.1:10808
3

4
netstat -ano | grep 10808
5
# 无输出 = 端口没有监听

解决

1
git config --global --unset http.proxy
2
git config --global --unset https.proxy

坑二：Gitee Pages 下架#

网上教程清一色教你”仓库 → 服务 → Gitee Pages → 启动”，但 2025 年 10 月 11 日这个功能已经下架（官方 issue #ID1EVM 确认）。

替代方案实测

坑三：Hexo 改完主题没生效#

Hexo 有缓存。改完配置必须：

1
hexo clean && hexo generate && hexo server

少了 clean，一半的改动都不会生效。

坑四：换主题迁移（Hexo → Firefly）#

用 Hexo + Butterfly 跑了三天，还是换成了 Firefly（Astro 主题）。迁移本身不难，但有三个坑：

1. Node 版本要够

Firefly 要求 Node ≥ 22.23，本机的 22.22 差一个小版本。engines 字段默认只警告不拦截，构建照样能过，但遇到诡异报错先核对版本再排查。

2. pnpm 是硬依赖

Firefly 用 pnpm 管依赖，package.json 里有 preinstall: npx only-allow pnpm，用 npm 装会被直接拒绝。更坑的是本机的 corepack 坏了（路径拼接错乱），最后绕过 pnpm 直接用 node_modules/.bin 里的本地二进制跑构建链。

3. front-matter 字段名不一样

字段名写错不会报错，文章会直接”消失”——因为校验不过被丢弃了。迁移后先看文章总数对不对。

心得#

遇到问题先看报错信息本身，它通常已经把原因说清楚了。别急着搜，先读懂。