STM32CubeIDE 中文注释乱码速解：兼容 KEIL/IAR 的编码配置技巧

STM32CubeIDE 导入 KEIL 或 IAR 工程后，中文注释常显示乱码，核心原因是不同 IDE 的默认文件编码不同，导致 CubeIDE 解析方式不匹配。本文基于 ST 官方 LAT1390 应用笔记，详解乱码根源、分场景配置方案及预防措施，让中文注释快速正常显示，适用于所有跨 IDE 移植的 STM32 项目。

1. 核心问题与现象

1.1 典型场景

• 跨 IDE 移植：将 KEIL 或 IAR 创建的工程导入 STM32CubeIDE（1.13.0 及以上版本）；
• 现象：代码逻辑正常，但中文注释显示为问号、方框等乱码，文件数量多时无法逐一重新编写；
• 关键特征：乱码仅出现在注释，代码编译运行不受影响，排除文件损坏问题。

1.2 核心矛盾

2. 不同 IDE 的默认编码特性（关键前提）

2.1 KEIL MDK（v5.45.0.0 为例）

• 默认编码：ANSI（兼容系统 locale，中文环境下本质为 GB2312，可被 UTF-8 解析）；
• 编码查看 / 修改：菜单栏「Edit」→「Configuration」→「Encoding」，默认显示 “Encode in ANSI”；
• 适配 CubeIDE：直接用 UTF-8 解析即可正常显示中文注释。

2.2 IAR Embedded Workbench（v9.30.1 为例）

• 默认编码：Raw (C locale)（本质为 GBK 编码，与 ANSI 不兼容）；
• 编码查看 / 修改：右击工程→「Options」→「C/C++ Compiler」→「Code Encodings」，默认 “Default source file encoding” 为 “Raw (C locale)”；
• 适配 CubeIDE：必须用 GBK 解析，否则会出现乱码。

3. CubeIDE 编码配置实操（1 分钟搞定）

3.1 单文件编码配置（适用于少量文件）

1. 在 CubeIDE 中右键点击乱码文件（如ChineseComments_KEIL.c）；
2. 选择「Properties」→「Resource」，找到「Text file encoding」选项；
3. 按文件来源选择编码：
   • KEIL 来源文件：选择「Other」→ 输入「UTF-8」→ 回车，点击「Apply and Close」；
   • IAR 来源文件：选择「Other」→ 输入「GBK」→ 回车（无 GBK 选项时直接手动输入），点击「Apply and Close」；
4. 刷新文件，中文注释即可正常显示。

3.2 批量文件编码配置（适用于大量文件）

1. 右键点击工程文件夹→「Properties」→「Resource」→「Text file encoding」；
2. 选择「Other」，根据多数文件来源选择 UTF-8（KEIL 为主）或 GBK（IAR 为主）；
3. 勾选「Apply to all files and folders」，点击「Apply and Close」；
4. 若个别文件仍乱码，按 “单文件配置” 单独调整即可。

4. 预防措施：新项目统一编码，避免后续乱码

1. 新项目默认用 UTF-8 编码：
   • CubeIDE：新建工程后，按 “批量配置” 步骤将工程编码设为 UTF-8；
   • KEIL：菜单栏「Edit」→「Configuration」→「Encoding」，改为 “Encode in UTF-8”；
   • IAR：右击工程→「Options」→「Code Encodings」，将 “Default source file encoding” 改为 “UTF-8”；
2. 优势：UTF-8 是跨平台通用编码，支持所有 IDE 和系统，后续移植无需重复调整。

5. 关键注意事项

1. 编码不可混用：同一文件不可反复切换 UTF-8 和 GBK，否则会导致注释永久乱码；
2. 手动输入技巧：CubeIDE 中若未找到 GBK 选项，直接在「Other」输入框中敲入 “GBK” 并回车，即可生效；
3. 适配范围：该方法仅针对中文注释乱码，若代码中中文字符串乱码，按相同步骤配置编码即可；
4. 版本兼容性：KEIL v5.x、IAR v9.x、STM32CubeIDE v1.13.0 及以上版本均适用，低版本可参考操作逻辑。