博客踩坑录 01|折腾一个博客,我踩了 14 个坑
博客踩坑录 · 第 01 篇
记录这个博客从 0 到上线过程中真实踩到的坑。每篇都写清楚:现象 → 原因 → 修法。
本系列持续更新,按「坑的类型」组织,方便以后回查。
一台 99 块钱的服务器,一个 Hexo 博客,两天时间。
这篇文章记录我踩的 12 个坑——每个都有现象、原因和修法。
一、缓存类:改了没反应(3 个)
这是最难查的一类,因为代码是对的,浏览器不给你看。
坑 1:样式改了一整天,看到的一直是旧版
现象:改 CSS、重新部署、刷新页面,一模一样。
查错过程:以为构建失败 → 以为文件没传上去 → 以为浏览器缓存 → 清了缓存还是不行。
原因:Nginx 给静态资源设了 30 天强缓存:
1 | location ~* \.(js|css|png|jpg|svg)$ { |
而 HTML 里引用的地址是 /css/whale-girl.css——地址没变,浏览器凭什么重新下载?
修法:所有静态资源地址带版本号。
1 | inject: |
改一次代码,换一个版本号。
教训:强缓存 + 不带版本号 = 你自己永远看不到新代码。线上环境和本地预览完全是两个世界。
坑 2:HTML 本身也被缓存
现象:版本号改了,但页面里引用的还是旧版本号。
原因:HTML 响应没有 Cache-Control,浏览器按启发式规则自己猜,可能缓存很久。
修法:
1 | location / { |
教训:no-cache 不是”不缓存”,是”每次都要问一下服务器”。对 HTML 来说这是最合适的策略。
坑 3:搜索索引搜不到新文章
现象:新发的文章,站内搜索搜不到;过几天又能搜到。
原因:search.xml 没有缓存策略,浏览器缓存时长不确定。
修法:
1 | location = /search.xml { |
5 分钟内更新,又不至于每次都重新下载 35KB。
二、配置类:写对了但不生效(3 个)
坑 4:Giscus 评论框死活不出现
现象:配置了 Giscus,评论区一片空白,控制台也没报错。
原因:Butterfly 5.x 要求 giscus 写在顶层,不是 comments 下面:
1 | # 错 |
写错了不会报错,只是静默失效——这是最坑的地方。
教训:主题配置找不到效果时,先去主题源码里搜这个键名到底往哪读。
坑 5:404 页面一片空白
现象:访问不存在的路径,页面全白,但返回 200。
原因:
1 | # 错 |
主题判断 page.type === '404',数字永远不相等。
坑 6:定时发布不生效
现象:给文章设了未来日期,结果一部署就全出来了。
原因:_config.yml 里默认 future: true——未来日期的文章也会渲染。
修法:
1 | future: false |
于是 hexo generate 会自动跳过日期还没到的文章。配合计划任务每天重新构建,就实现了”每天自动发一篇”。
三、样式类:看起来像 bug 的设计(3 个)
坑 7:所有动画突然静止
现象:看板娘的呼吸、摆尾全部不动了,像一张贴图。
原因:我写过这段,本意是”尊重系统的减少动效设置”:
1 | @media (prefers-reduced-motion: reduce) { |
结果发现很多 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 | btf=object span=true dlg0=none dlg1=block |
原因:我为了让搜索更快,把 preload 改成了 true。这会提前触发索引加载,把「数据加载中」的占位元素删掉;等真正的 search:loaded 事件触发时:
1 | const $loadDataItem = document.getElementById('loading-database') |
修法:preload 改回 false,另写一个 search-warm.js 在页面加载后后台预取搜索脚本和索引,用缓存换速度。
坑 14:控制台一条红字,不是我的锅
现象:
1 | Uncaught (in promise) Error: A listener indicated an asynchronous response |
原因:这是浏览器扩展的消息通道错误(广告拦截、翻译插件常见),跟站点代码无关。
验证方法:开无痕窗口(扩展禁用),如果没有这条报错,就实锤是扩展。
教训:控制台的错误不一定都是你的。先判断它来自页面还是扩展/第三方脚本。
六、我的排查顺序
踩完这 14 个坑,现在的排查流程固定成这样:
1 | 1. 先怀疑缓存 |
一句话总结这一天的收获:
调试的时候,先怀疑缓存,再怀疑自己。
附:这个博客最终的技术栈
| 层 | 用什么 |
|---|---|
| 生成 | 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、状态机、体积控制 |
如果你也在搭自己的站,欢迎在下面留言说说你踩过什么坑——好的题目我会收进这个系列。