我整理了 16 条程序员真实踩坑，每条四步拆解：症状→根因→修复→避免

踩过坑、修好坑、记住坑——同一个坑不踩第二次。

写了几年代码，发现自己踩过的坑有一个共同特点：修的时候花了好几个小时，但根因往往就一行代码的事。更气人的是，过几个月又踩一遍。

于是我做了一件事：把踩过的坑按统一格式整理出来——每条固定四个段落：

  • 🩺 症状：你看到什么？
  • 🔬 根因：到底为什么出问题？
  • 🔧 修复：怎么做？
  • 🛡️ 怎么避免：下次怎么不踩？

攒了 16 条，放在 GitHub 开源仓库里，也搭了个简单的展示站。

举三条最有共鸣的

1. Git push SSL 握手失败

症状：git push 到 GitHub 每次报 SSL/TLS handshake 失败

根因：Git 没走系统代理，直连被墙

修复：一行命令 —— git config --global http.proxy http://127.0.0.1:7897

教训：新机器第一件事就是设全局 Git 代理，不要只给单个仓库设

2. Python 缩进导致 140 行代码静默跳过

症状：AstrBot 微信公众号被动回复永远不执行，日志无任何报错

根因：140 行被动回复代码缩进在了 if active_send_mode: 块内部（12 空格对齐），当 active_send_mode=False 时整个 if 块被跳过

修复：代码提到 if 外面，和 if 同级缩进

教训：Python 缩进错误在特定条件下才暴露——代码在，逻辑在，就是进不去。排查时先怀疑控制流缩进

3. 公众号明文模式下回复被错误加密

症状：微信后台设为明文模式，AI 正常生成回复，日志无报错——但用户永远看不到

根因：_maybe_encrypt() 函数用 nonce 和 timestamp 是否存在来判断要不要加密。但微信在明文模式的 POST URL 里也携带这两个参数（用于 URL 签名验证，不是加密开关）→ 条件为真 → 加密了 → 微信明文模式解密不了 → 静默丢弃

修复：明文分支中 nonce = None; timestamp = None，同时增加类级别 _is_encrypted 标志做双重防护

教训：加密函数不能靠 nonce/timestamp 是否存在来判断模式——它们在明文模式下也存在

全部 16 条踩坑

# 踩坑 核心教训
1 Git Push SSL 握手失败 新机先设 --global http.proxy
2 Python UTF-8 BOM 编码陷阱 encoding='utf-8' → 'utf-8-sig'
3 公众号中文乱码 requests json= → data=json.dumps(ensure_ascii=False)
4 规划写完忘记 commit 规划完成立刻 commit，不等会话结束
5 docx 表格跨页断开 cantSplit=True 防止断表
6 Excel COM Save 静默失败 wb.Save() 静默失败必须用 SaveAs
7 Gitee 重复建仓库 建仓库前先查已有列表
8 TRIGGERS 多场景匹配漏读 多路由命中要 AND 合并全量加载
9 Cloudreve/Cloudflare 上传超时 免费版 100s 超时，调小分块
10 Python 缩进导致代码静默跳过 检查控制流缩进
11 Gitee 镜像已配还手动 push 镜像自动同步，删冗余 remote
12 AstrBot XML 二次包装 完整 XML 被又包一层 → 嵌套 XML
13 公众号明文模式误加密 nonce/timestamp 别当加密开关
14 Hugo 手写单篇跳全量构建 必须 hugo -d docs/ -F（已犯 3 次+）
15 sed 假阳性验证 grep -q 验证通过 ≠ 代码写对了
16 WSL Write 工具路径不一致 写完不验证 = 写了等于没写

链接

  • 🌐 网站：https://worldcorner.xyz/pitfalls/
  • 📂 GitHub：https://github.com/zhao818/claude-memory/tree/master/pitfalls

每条踩坑都是真实踩过的——不是因为聪明才写，是因为踩疼了才记住。欢迎补充你踩过的坑，一起把仓库养大。