如何让 Keil 不再乱码：中文注释的终极解决方案
你有没有遇到过这种情况？昨晚还在电脑上好好显示的“初始化系统时钟”注释，今天在同事的机器上打开后变成了“鐫湁闂”这种鬼画符？或者提交 Git 后，CI 构建报错说某个头文件无法解析——原因竟是注释里的一个“配置”字触发了编码异常？
这并不是玄学问题，而是每一个在中国做嵌入式开发的人都绕不开的坑：Keil 中文注释乱码。
别急。这不是你的代码写得不好，也不是队友操作失误，而是你还没掌握那个被官方文档轻描淡写、却决定项目可维护性的关键细节——字符编码统一管理。
为什么 Keil 看不懂你的中文？
我们先来打破一个误解：很多人以为“只要操作系统是中文 Windows，Keil 就能自动识别中文”。错得很彻底。
Keil uVision（尤其是 V5.x 及更早版本）使用的编辑器内核非常古老，它对文本编码的处理逻辑极为原始：
- 没有智能探测机制：不能像 VS Code 或 Notepad++ 那样自动判断 UTF-8、GBK。
- 依赖 BOM 判断编码：
- 文件开头有
EF BB BF→ 当作 UTF-8 - 没有 BOM + 中文系统环境 → 默认当作 GBK/GB2312
- 不支持 UTF-8 without BOM：这是最致命的一点！很多现代工具默认保存为无 BOM 的 UTF-8，结果一进 Keil 就炸锅。
所以当你从 Git 拉下一个由 VS Code 创建的.c文件，即使内容全是标准 UTF-8 编码，只要没带 BOM，Keil 就会用 GBK 去解码那串字节——于是“中文”变成了“涓枃”。
📌一句话总结：
Keil 能不能正确显示中文，不取决于你说什么语言，而取决于文件有没有带上那个小小的BOM 标记。
正确姿势：UTF-8 with BOM 才是唯一答案
为什么选 UTF-8？
先说结论：在今天的嵌入式开发中，UTF-8 是唯一值得推荐的源码编码格式。
| 对比项 | UTF-8 | GBK |
|---|---|---|
| 兼容性 | ✅ 支持全球所有语言 | ❌ 仅限中文及部分符号 |
| ASCII 兼容 | ✅ 完全兼容 | ✅ |
| Git 友好度 | ✅ 行业标准 | ⚠️ 易引发 diff 异常 |
| 跨平台一致性 | ✅ Linux/macOS 原生支持 | ❌ 在非中文系统下极易出错 |
更重要的是，越来越多的静态分析工具（如 SonarQube、PC-lint Plus）、CI/CD 流水线、甚至编译器预处理器都默认以 UTF-8 解析源文件。继续使用 GBK，等于主动把自己隔离在现代化开发流程之外。
但注意：我们必须选择UTF-8 with BOM，而不是“纯”UTF-8。
💡 BOM（Byte Order Mark）是一段位于文件开头的特殊字节序列
EF BB BF，用于标识该文件采用 UTF-8 编码。虽然技术上不是必需的，但在 Keil 这类老派 IDE 中，它是唯一的“通行证”。
实战指南：四步打造永不乱码的工程环境
第一步：创建带 BOM 的模板文件
Keil 自己没法设置“默认保存为 UTF-8”，所以我们得“反向操作”——提前准备好正确的模板。
推荐操作（使用 VS Code）：
- 打开 VS Code，新建
template.c - 输入以下内容：
/** * @file main.c * @brief 主程序入口 * @author 开发团队 * @date 2025-04-05 * * 本模块实现LED闪烁功能，用于验证系统时钟初始化状态。 */ #include "stm32f1xx_hal.h" int main(void) { HAL_Init(); // 初始化HAL库 SystemClock_Config(); // 配置系统时钟 MX_GPIO_Init(); // 初始化GPIO while (1) { HAL_GPIO_TogglePin(GPIOA, GPIO_PIN_5); // 翻转PA5（连接LED） HAL_Delay(500); // 延时500ms } }- 点击右下角编码显示（通常是“UTF-8”），选择Save with Encoding
- 选择UTF-8 with BOM
✅ 成功！这个文件现在就是一个“免疫乱码”的种子文件。
你可以把它放进公司模板库，新人入职直接复制使用。
第二步：在 Keil 中安全地编辑和保存
打开 Keil 后不要急着敲代码，请先确认三件事：
✅ 检查当前文件是否真为 UTF-8 with BOM
方法一：用十六进制编辑器查看文件头部
可以用 HxD、WinHex 或命令行xxd查看前三个字节：
xxd main.c | head -n1 # 输出应为：00000000: efbb bf2f ...方法二：使用 Notepad++
打开文件 → 看右下角状态栏：
- 显示 “UTF-8-BOM” ✔️
- 显示 “UTF-8” ❌（危险！）
✅ 设置字体支持中英文混排
路径：Edit → Configuration → Editor Tab
- Font:Consolas/Microsoft YaHei UI/Courier New
- Encoding: 虽然这里写着“Chinese (Simplified) – GB2312”，但它其实只是启用双字节支持的开关，不影响实际保存编码
⚠️ 注意：这里的“Encoding”选项不会改变文件保存格式！它只影响显示。真正的编码由你如何“另存为”决定。
✅ 保存时务必确认编码
每次修改后，建议执行一次“另存为”操作，并手动选择编码：
File → Save As...- 在弹出窗口中点击“编码”下拉菜单
- 选择UTF-8 with BOM（可能显示为“Unicode (UTF-8 with signature)”）
🔧 小技巧：可以在桌面放一个批处理脚本，批量检测工程中所有
.c/.h文件是否有 BOM：
@echo off for %%f in (*.c *.h) do ( set /p byte1=<%%f if "%byte1:~0,3%"=="" ( echo [OK] %%f 已包含 BOM ) else ( echo [WARN] %%f 缺少 BOM！ ) ) pause第三步：用.gitattributes锁定编码行为
Git 本身不记录文件编码，但它可以根据.gitattributes控制检出时的处理方式。
在项目根目录添加这个文件：
*.c text eol=lf encoding=utf-8 *.h text eol=lf encoding=utf-8 *.s text eol=lf encoding=utf-8 *.inc text eol=lf encoding=utf-8 *.txt text eol=lf encoding=utf-8 Makefile text eol=lf encoding=utf-8作用是什么？
- 告诉 Git：“这些文件是文本文件，检出时请用 LF 换行符，并按 UTF-8 处理”
- 防止 Windows 用户拉取时被自动转成本地编码（如 GBK）
- 避免因换行符不同导致无意义的 diff
📦 提示：如果你使用的是企业级 Git 平台（如 Gitee、GitLab），建议将此文件纳入组织级模板仓库，一键同步给所有项目。
第四步：建立团队规范，杜绝编码污染
技术方案再完美，也抵不过一个人随手保存一次“UTF-8 without BOM”。
必须从流程上设防：
✅ 必做事项清单
| 项目 | 操作 |
|---|---|
| 新员工培训 | 明确讲解“Keil + 中文注释”编码要求 |
| 工程模板 | 提供预置 UTF-8+BOM 的.c/.h模板 |
| CI 流程 | 加入脚本检查所有源文件是否含 BOM |
| Wiki 文档 | 发布《源码编码管理规范》并链接到 PR 模板 |
❌ 绝对禁止行为
- 直接用记事本编辑 Keil 源文件（记事本默认保存为 ANSI）
- 使用“另存为 UTF-8”而不验证是否带 BOM
- 在不同编码文件之间复制粘贴中文内容
- 把 Keil 当作文本编辑器长期编写大量注释
常见坑点与调试秘籍
❓ 问：我已经保存为 UTF-8，为什么还是乱码？
答：大概率是你保存的是“UTF-8 without BOM”。Keil 看不到标记，就按系统默认 GBK 解码了。
👉 解法：重新用支持编码选择的编辑器打开，另存为“UTF-8 with BOM”。
❓ 问：能不能让 Keil 默认保存为 UTF-8？
答：不能。Keil 官方从未提供此功能。任何声称“改注册表就能解决”的说法都是误导。
唯一的办法是靠流程控制 + 外部工具辅助。
❓ 问：BOM 会影响编译吗？
答：不会。现代编译器（包括 ARMCC、GCC for ARM）都能正确跳过 BOM。实测 STM32、GD32、NXP LPC 等平台均无影响。
反而不加 BOM 导致编辑器误读，才是真正的问题源头。
❓ 问：如果团队有人坚持用 GBK 怎么办？
答：坚决反对。混合编码等于埋雷。
统一策略才是王道。可以这样说：“我们可以不用中文注释，但如果要用，就必须用 UTF-8 with BOM。”
写在最后：让母语成为生产力，而非障碍
允许工程师用自己的母语写注释，不是偷懒，而是尊重认知效率。
当你看到“此处需等待 ADC 完成校准”比“Wait for ADC calibration done”更快理解时，你就知道：清晰的表达本身就是高质量代码的一部分。
而我们要做的，不是放弃中文注释，而是学会如何让它安全、稳定、跨平台地存在。
这套基于UTF-8 with BOM + Git 属性控制 + 团队流程约束的方案，已经在多个量产项目中验证有效。无论是 STM32F1 的小系统，还是 RT-Thread 上的大应用，只要坚持这一套规则，就再也没人抱怨“谁的电脑又看不到注释了”。
如果你在实现过程中遇到了其他挑战，欢迎在评论区分享讨论。
