写技术文档时顺手打了个中文冒号，结果编译直接报错。这种问题太常见了，尤其在用 LaTeX、Markdown 转 PDF 或者写代码注释的时候，一个不小心，全篇卡住。
问题从哪来？
很多编译工具默认使用 ASCII 编码处理文本，而中文字符属于 Unicode 范畴。当你在文件路径、文件名、注释、标题甚至空格位置用了中文，比如：
第1章：环境搭建.md这里的“第”“章”“：”全是中文，某些工具链解析时会直接崩溃，提示“invalid byte sequence”或者“UnicodeDecodeError”。
常见翻车场景
同事小李写了一份项目说明，文件名叫《配置说明.docx》，转 Markdown 时用了自动化脚本，结果脚本不支持中文路径，直接跳过。后来改成 config_guide_v2.md 才顺利跑通。
另一个例子是 LaTeX 编译论文。有人在注释里写“作者：张三”，LaTeX 引擎没配 UTF-8 支持，编译就报错。解决方法其实简单：
\usepackage[utf8]{inputenc}加上这行，就能正常读取中文。
怎么避免踩坑
最稳妥的做法是：所有源文件命名用英文，路径也尽量避开中文。哪怕你自己电脑能识别，换台机器或上服务器可能就崩了。
如果非得用中文内容，比如写中文报告，确保你的工具链支持 UTF-8。比如 Pandoc 转换时加 --wrap=preserve，或者在 YAML 头部声明编码：
---
title: 中文标题
lang: zh
---再比如写 Makefile，里面别出现带中文的路径。一条规则写得好好的，结果因为目标文件夹叫“输出”，make 直接罢工。
编辑器也能帮大忙
现代编辑器如 VS Code、Typora 都能高亮显示异常字符。打开“显示空白符”和“控制字符”，那些看不见的中文空格、全角标点立马现形。我习惯用正则搜索 [\u4e00-\u9fa5] 快速定位文档里的中文，看看是不是出现在不该出现的地方。
还有个小技巧：写脚本处理文档时，先加一句检测编码的逻辑，发现非 ASCII 就报警，省得等到最后一步才炸。