这篇文章只干一件事:把昨晚到今早踩的坑,一条条记下来。

不是教程,是病历。能复现的坑才有价值,所以每条都写清楚:现象、原因、修法。

坑 1:f-string 中间插了个表达式,整段 Python 语法错

现象:每天自动发布都失败,「构建发布」永远是红叉。

日志:

1
2
3
File "<stdin>", line 11
f'title: "{title}"\n'
SyntaxError: invalid syntax

原因:拼 front-matter 时,我在字符串里插了一个条件表达式:

1
2
3
4
5
6
front = (
'---\n'
f'title: "{title}"\n'
('tags:\n - ' + topic + '\n' if topic else '') # ← 这里
f'categories:\n' # ← 变成孤立字面量
)

Python 里相邻字符串会自动拼接,但中间夹了一个非字符串表达式,后面那个 f'...' 就成了没有操作符的独立语句。

修法:不要玩隐式拼接,用列表 + join:

1
2
3
4
parts = ['---\n', f'title: "{title}"\n']
if topic:
parts.append('tags:\n - ' + topic + '\n')
front = ''.join(parts)

坑 2:rsync --delete 让首页闪 404

见另一篇《把发布做成原子操作》,这里只记结论:原地覆盖一定有窗口期,要么先同步再 mv,要么上 releases + 软链。

坑 3:claim_named 把文件名拆成了字符集

现象:控制台点「发布这篇」,接口返回 done: [],什么都没发生。

原因:

1
2
names = set(names)          # "20261101-012023.md" → {'2','0','6',...}
if payload['name'] in names: # 永远 False

传字符串进来,set() 会按字符拆。

修法:

1
names = {names} if isinstance(names, str) else set(names)

教训:函数参数写 names(复数)但单个值也合法时,一定要处理字符串这种情况。

坑 4:控制台按钮走的是旧脚本,界面永远不动

现象:点「把队列里的写出来」,流水线四个阶段一动不动。

原因:按钮执行 flush.sh,而 flush.sh 直接调 rewrite.py,绕过了 svc-control。阶段状态是 core 记的,所以永远不变。

修法:所有动作改走 core 的 HTTP 接口。

教训:一个动作只能有一条执行路径。两条路,必有一条是坏的。

坑 5:JS 字符串里混进真实换行,整页按钮全死

现象:控制台能打开,但所有按钮点了没反应,数据也不加载。

原因:删除确认框的文案里有一个真实换行:

1
2
if (!confirm('删除《' + slug + '》?
会同时重建站点')) return;

JS 字符串不能跨行 → 整段脚本语法错误 → 一个事件都没绑定。

修法:node --check 检查;文案写成一行。

教训:改完前端一定要做语法检查,肉眼看不出来。

坑 6:缺 import sys,服务重启就崩

现象:改完聊天服务,systemctl restart 之后变成 activating 循环。

原因:新加的 sys.path.insert(...) 用到 sys,但文件里没 import。

修法:补 import。

教训:ast.parse 只能查语法,查不出名字错误。要么跑一遍,要么用 pyflakes。

坑 7:轮询在「不忙」时自己停了

现象:流水线跑完之后,界面永远停在旧时间。

原因:if (!d.busy) clearInterval(timer) —— 一次空闲就把轮询杀了。

修法:改成「忙 2 秒、闲 8 秒」的自调度,只有离开页面才停。

坑 8:location.hash 为空时不启动轮询

现象:第一次点进「运行」页,进度不动;刷新一下(URL 带 #run)就正常了。

原因:if (location.hash) startPolling(),从概览点标签进来时 hash 是空的。

修法:进这个标签就无条件启动。

坑 9:新文章 404,但它其实存在

现象:回归脚本报两篇文章 404。

原因:不是 bug。那两篇的日期是「今天 09:00」和「明天 09:00」,而 Hexo 配置 future: false —— 未来时间的文章不生成。

修法:回归脚本要识别排期文章,跳过。

教训:测试的误报,杀伤力和 bug 一样。 每次误报都会消耗你对测试的信任。

坑 10:指定话题抓取,请求打到了已退休的端口

现象:说「抓一批赛博朋克」,她答「行吧,这次抓赛博朋克」,但队列里什么都没变。

原因:whale-chat 把请求发到 127.0.0.1:8121 —— 那是合并进 core 之前的老爬虫端口,服务早就停了。请求打到空气里,没有任何报错。

修法:改到 8130/crawl,并且带上 topic 参数。

教训:重构之后要全局搜一遍旧端口号。 打不通的 HTTP 请求不会吵,它只是安静地失败。

坑 11:换主题传错了字段名

现象:「换主题 美食」永远回答「不在预设里」,但 presets.json 里明明有美食。

原因:发的是 {"preset": "美食"},接口收的是 {"name": ...};而且鉴权用 ?token= 查询参数,而控制台早就禁用了查询参数鉴权。

修法:改成直接读写本地 config.json(同一台机器,不需要 HTTP)。

坑 12:去重键撞在日期上,等于没去重

现象:学习脚本越跑,档案越大,重复条目越来越多。

原因:

1
2
seen.add(line[2:].strip()[:12])
# "[2026-11-01] 上海波龙畅吃 598" 的前 12 字 = "[2026-11-01]"

所有条目的去重键都一样。

修法:先剥日期前缀,再取正文前 16 字;梗额外按名字(| 前那截)去重。

坑 13:价格加权对每一条都生效

现象:问「波龙多少钱」,排第一的是「锅太小,波龙放不下」。

原因:加权条件是「条目里有数字」,而每条都带日期 [2026-11-01],日期里有数字。

修法:剥掉日期再判断。

坑 14:两份 cron 抢同一个模型

现象:偶尔出现模型调用失败,日志里是限流错误。

原因:复盘(每 10 分钟)和学习(每 2 小时)可能同时跑,各自一口气发好几个请求。

修法:共用一把文件锁:

1
2
3
4
5
lock = open('/var/lock/blog-agent-learn.lock', 'w')
try:
fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
except OSError:
return # 别人在跑,这次跳过

复盘:这 14 个坑的共同点

把它们分成四类:

类型 例子 怎么防
语法/名字错误 坑 1、5、6 改完立刻 ast.parse + node --check
两条执行路径 坑 4、10、11 重构后全局搜旧地址/旧脚本
状态不一致 坑 3、7、8、12 一个数字只有一个来源
测试/加权误伤 坑 9、13 先问「这个条件是不是对所有条目都成立」

最值钱的两条经验:

一、让工具替你检查。 31 项回归脚本,跑一次两秒。它抓出了「待写数把点评也算进去」这种肉眼看不出的错。

二、日志要写清楚「为什么跳过」。 我改了很多地方,把「静默失败」变成「明确返回原因」:

1
2
3
今天已经发了 7 篇(上限 5),明天再说吧
刚跑过,还差 8 分钟
今天已经发了 7 篇,上限 5,只抓不写

这些句子比任何监控都管用——因为它们是给人看的。