Platform Pitfalls Playbook
疑难杂症不是玄学：每一条都是「本机全绿、目标平台爆炸」的事故换来的。
本手册把三类高频平台坑收敛成可执行的防御清单。
When to use
遇到以下任一情况，读对应章节（references/ 下）：
| 症状 | 读哪章 |
|---|---|
Windows 上中文变 璇峰•鎻•朵 / UnicodeEncodeError: 'charmap'/'gbk' codec |
@references/chinese-utf8-pipeline.md |
| 跨平台脚本/构建工具要处理中文路径、中文测试名、重定向日志 | @references/chinese-utf8-pipeline.md |
.ps1 脚本在中文 Windows PowerShell 5.1 上乱码 |
@references/windows-powershell-utf8.md |
| Python CLI 在 Windows 控制台 print 中文/emoji 炸 | @references/windows-powershell-utf8.md |
C++20 协程 -O3 悬空、mutex 内 resume 崩、ASan container-overflow |
@references/cpp20-coroutines.md |
核心原则（全章通用）
- 任何一层默认编码都不可信。每个边界显式声明 UTF-8。
- 本机 macOS/Linux 全绿不算数——默认 UTF-8 locale 掩盖一切，
中文 Windows 和 Windows runner 才是考场。 - 写完必须推真实 Windows CI 验收，含中文路径、中文内容、
重定向日志与失败诊断的可读性。 - 不静默吞错。
errors='replace'、空except、降级跳过都是把
事故变成更晚更难的排查。
沉淀新坑（本手册的维护方式）
踩到新平台坑并修复后，按「症状 → 原因 → 解法 → 验收命令」四段式追加进
对应章节；开新章节的标准：同类坑第二次出现、或独立成一个技术域。
不要记「某次会话里 AI 说了什么」，记可复现的工程事实。
章节索引
references/chinese-utf8-pipeline.md— 中文编码五层防线
（Python 入口 / 子进程 / 文件 IO / CMake / MSVC + 控制台）+ 验收
标准 + 常见误区（含 MSYS2/MinGW 关系澄清）references/windows-powershell-utf8.md— PowerShell 5.1 三层修复
（UTF-8 BOM + chcp 65001 + 关键字符串字节数组）+ Python 控制台姊妹问题references/cpp20-coroutines.md— C++20 协程 11 坑速查
（症状→原因→解法）+ TaskScope/事件循环/TLS 异步集成验收补充
