博客踩坑录 · 第 01 篇
记录这个博客从 0 到上线过程中真实踩到的坑。每篇都写清楚:现象 → 原因 → 修法。
本系列持续更新,按「坑的类型」组织,方便以后回查。


一台 99 块钱的服务器,一个 Hexo 博客,两天时间。
这篇文章记录我踩的 12 个坑——每个都有现象、原因和修法。


一、缓存类:改了没反应(3 个)

这是最难查的一类,因为代码是对的,浏览器不给你看。

坑 1:样式改了一整天,看到的一直是旧版

现象:改 CSS、重新部署、刷新页面,一模一样。

查错过程:以为构建失败 → 以为文件没传上去 → 以为浏览器缓存 → 清了缓存还是不行。

原因:Nginx 给静态资源设了 30 天强缓存:

1
2
3
location ~* \.(js|css|png|jpg|svg)$ {
expires 30d;
}

而 HTML 里引用的地址是 /css/whale-girl.css——地址没变,浏览器凭什么重新下载?

修法:所有静态资源地址带版本号。

1
2
3
inject:
head:
- <link rel="stylesheet" href="/css/whale-girl.css?v=20261031i">

改一次代码,换一个版本号。

教训:强缓存 + 不带版本号 = 你自己永远看不到新代码。线上环境和本地预览完全是两个世界。

坑 2:HTML 本身也被缓存

现象:版本号改了,但页面里引用的还是旧版本号。

原因:HTML 响应没有 Cache-Control,浏览器按启发式规则自己猜,可能缓存很久。

修法:

1
2
3
4
location / {
add_header Cache-Control "no-cache"; # 每次回源校验,走 304,开销很小
try_files $uri $uri/ =404;
}

教训:no-cache 不是”不缓存”,是”每次都要问一下服务器”。对 HTML 来说这是最合适的策略。

坑 3:搜索索引搜不到新文章

现象:新发的文章,站内搜索搜不到;过几天又能搜到。

原因:search.xml 没有缓存策略,浏览器缓存时长不确定。

修法:

1
2
3
location = /search.xml {
add_header Cache-Control "public, max-age=300";
}

5 分钟内更新,又不至于每次都重新下载 35KB。


二、配置类:写对了但不生效(3 个)

坑 4:Giscus 评论框死活不出现

现象:配置了 Giscus,评论区一片空白,控制台也没报错。

原因:Butterfly 5.x 要求 giscus 写在顶层,不是 comments 下面:

1
2
3
4
5
6
7
8
# 错
comments:
giscus:
repo: xxx

# 对
giscus:
repo: xxx

写错了不会报错,只是静默失效——这是最坑的地方。

教训:主题配置找不到效果时,先去主题源码里搜这个键名到底往哪读。

坑 5:404 页面一片空白

现象:访问不存在的路径,页面全白,但返回 200。

原因:

1
2
3
4
5
# 错
type: 404 # YAML 解析成数字 404

# 对
type: '404' # 字符串

主题判断 page.type === '404',数字永远不相等。

坑 6:定时发布不生效

现象:给文章设了未来日期,结果一部署就全出来了。

原因:_config.yml 里默认 future: true——未来日期的文章也会渲染。

修法:

1
future: false

于是 hexo generate 会自动跳过日期还没到的文章。配合计划任务每天重新构建,就实现了”每天自动发一篇”。


三、样式类:看起来像 bug 的设计(3 个)

坑 7:所有动画突然静止

现象:看板娘的呼吸、摆尾全部不动了,像一张贴图。

原因:我写过这段,本意是”尊重系统的减少动效设置”:

1
2
3
@media (prefers-reduced-motion: reduce) {
.wg * { animation: none !important; }
}

结果发现很多 Windows 用户默认关闭了”动画效果”——而看板娘唯一的功能就是动。

修法:删掉这段。

教训:可访问性很重要,但对一个纯装饰物来说,”能用”优先级更高。静止的看板娘不是”简化版”,是”坏掉了”。

坑 8:弹幕被截断成一张纸条

现象:长弹幕显示成”这个 bug 又出现了…”,后面全被省略号吃掉。

原因:.dm-item { max-width: 80vw; text-overflow: ellipsis; }

修法:去掉宽度限制和省略号,长内容自动换行 + 缩小字号。

坑 9:海底生物一滚动就重新排列

现象:页面上的小鱼小虾,每次滚动都乱跳,很像卡顿。

原因:用 position: fixed + 每次滚动随机重算位置。

修法:改成 position: absolute + 固定随机种子(20261031),一次性算好位置,之后不响应滚动。

教训:装饰元素要跟文档流一起走,否则滚动时它会”活过来”,非常干扰阅读。


四、工具链类:我自己的脚本坑(3 个)

坑 10:hexo clean 报 EBUSY

现象:

1
Error: EBUSY: resource busy or locked, rmdir 'public'

原因:有两个进程攥着 public 目录——

  • VS Code 的文件监视器
  • 我之前起的 python -m http.server --directory public

修法:把构建目录改成 public-build,彻底绕开被锁的 public。

1
public_dir: public-build

教训:Windows 上删不掉的目录,八成有进程拿它当工作目录。用 Get-CimInstance Win32_Process 查命令行里带路径的进程,比乱猜快得多。

坑 11:Nginx 报 invalid parameter "max-age=2592000"

现象:改完配置 nginx -t 直接报错。

原因:我用 PowerShell 往配置文件里写:

1
add_header Cache-Control "public, max-age=2592000";

PowerShell 把双引号吃掉了,Nginx 收到的是裸的 max-age=2592000。

修法:用 expires 30d; 代替手写 header;或者改配置一律用脚本文件 + 单引号。

坑 12:部署脚本被我自己改坏

现象:deploy.ps1 突然报 The string is missing the terminator。

原因:我用 PowerShell 的 .Replace() 往脚本里插了一行带双引号的中文提示,引号嵌套直接破坏了语法。

修法:整个脚本重写,并且存成 UTF-8 with BOM——PowerShell 5.1 读无 BOM 的中文文件会乱码。

教训:不要在 shell 里用字符串替换去改脚本。用编辑器写完整文件,或者用 Python 处理文本。


五、还有两个”不是 bug 的 bug”

坑 13:搜索点了没反应

现象:点搜索按钮,有时候弹层不出来。

排查:我在服务器上放了一个探测页,让它模拟点击并把结果回传。数据是这样:

1
2
btf=object  span=true  dlg0=none  dlg1=block
err=[TypeError: Cannot read properties of null (reading 'nextElementSibling')]

原因:我为了让搜索更快,把 preload 改成了 true。这会提前触发索引加载,把「数据加载中」的占位元素删掉;等真正的 search:loaded 事件触发时:

1
2
const $loadDataItem = document.getElementById('loading-database')
$loadDataItem.nextElementSibling.style.visibility = 'visible' // null 了

修法:preload 改回 false,另写一个 search-warm.js 在页面加载后后台预取搜索脚本和索引,用缓存换速度。

坑 14:控制台一条红字,不是我的锅

现象:

1
2
Uncaught (in promise) Error: A listener indicated an asynchronous response
by returning true, but the message channel closed before a response was received

原因:这是浏览器扩展的消息通道错误(广告拦截、翻译插件常见),跟站点代码无关。

验证方法:开无痕窗口(扩展禁用),如果没有这条报错,就实锤是扩展。

教训:控制台的错误不一定都是你的。先判断它来自页面还是扩展/第三方脚本。


六、我的排查顺序

踩完这 14 个坑,现在的排查流程固定成这样:

1
2
3
4
5
6
7
8
9
10
11
1. 先怀疑缓存
Ctrl + F5 / 无痕窗口 / F12 勾 Disable cache
↓
2. 再看控制台
红字是什么类型?TypeError?扩展报错?跨域?
↓
3. 再看 Network
文件是不是 200?是不是 304?内容对不对?
↓
4. 最后才看代码
前面三步排除了,才是真的写错了

一句话总结这一天的收获:

调试的时候,先怀疑缓存,再怀疑自己。


附:这个博客最终的技术栈

层 用什么
生成 Hexo 8 + Butterfly 5.7
服务器 阿里云 ECS 2C2G / 3Mbps / Ubuntu 22.04
Web Nginx(8080 端口,备案中)
数据 Python 标准库 HTTP + SQLite(留言/弹幕 API)
自定义 手绘 SVG 看板娘、弹幕、海底生物、背景切换

这个系列的后续

「博客踩坑录」会按主题继续写下去,目前排队的题目:

编号 主题 大概内容
02 域名、备案与 HTTPS 解析怎么配、备案要等多久、证书怎么自动化
03 一个 2C2G 的服务器能扛什么 内存、带宽、缓存的真实数字
04 手搓一个留言与弹幕后端 Python 标准库 + SQLite,为什么不用框架
05 看板娘是怎么画出来的 手绘 SVG、状态机、体积控制

如果你也在搭自己的站,欢迎在下面留言说说你踩过什么坑——好的题目我会收进这个系列。