用 STM32CubeMX 开发 STM32 的朋友大概率都遇到过这种情况从同事手里接过来的工程打开 main.c 发现初始化函数排了十几行MX_USART1_UART_Init、MX_I2C1_Init、MX_ADC1_Init一个不少但真正在业务代码里用到的可能只有三四个。你问为什么留着没人说得清只留下一句“之前调过”。更麻烦的是这些历史遗留的初始化代码并不只是多占几行 ROM它们还会把对应的引脚强制配置成特定复用功能导致你想用的新外设只能在夹缝里找引脚。这篇文章就聊一个很具体的问题怎么在 STM32CubeMX 里防止生成未使用外设的初始化代码以及把这些代码干净地清出去。内容来自我实际维护多个产品工程的经验适用于所有用 CubeMX 生成代码的开发者和团队。1. 为什么 CubeMX 会把没用的初始化代码“硬塞”给你1.1 问题根因CubeMX 的生成逻辑里没有“未使用”这个概念先说清楚一个底层逻辑CubeMX 的代码生成器并不是一个“智能编译器”它不会去分析你的 main.c 里到底调用了哪些外设接口也不会判断某个外设的函数在业务逻辑里是否被引用。它只做一件事读取.ioc配置文件里记录的“哪些外设处于使能状态、哪些引脚被分配给哪些复用功能”然后老老实实生成对应的初始化代码。这个机制本身没有问题问题在于很多开发者把.ioc当成一个“随便点一点试试”的工具今天勾个 SPI 测一下 flash明天勾个 I2C 挂个传感器后天又勾个 ADC 读电池电压。测试完不清理配置直接关掉 CubeMX然后继续写业务代码。等到下次重新生成代码时CubeMX 就会把这几份“过期配置”原封不动地翻译成代码。也就是说未使用外设初始化代码的根源不是 CubeMX 的 bug而是“曾经使能过但从未禁用”的配置残留。CubeMX 的设计理念是只要你在图形界面里没有明确把某个外设关掉它就认为这个配置仍然有效。这就像一位很热情的厨师你只要在菜单上点过一次菜它就会一直把菜往桌上端即使你后来重新点了别的菜它也不会主动把前面那道菜撤掉。1.2 一段未使用外设的代码到底带动了多少“隐藏配置”很多人觉得禁用外设只是省掉 main.c 里一两行MX_xxx_Init()调用实际上这远不是全部。一个外设的初始化是一个连锁动作背后的隐藏配置往往比你在图形界面看到的要多得多。以常见的 USART1 为例CubeMX 生成代码时至少会写入以下四块内容首先是在 main.c 里生成一个MX_USART1_UART_Init()函数并在main()函数中调用它。这个函数里会配置串口句柄huart1包括波特率、数据位、停止位、校验方式等。其次是在stm32f1xx_hal_msp.c或对应型号的 HAL msp 文件里生成HAL_UART_MspInit()回调函数里面包含 USART1 的引脚 GPIO 时钟使能、GPIO 配置为复用功能AF、以及如果使能了串口中断还会配置 NVIC 中断优先级并使能中断。第三如果外设还挂了 DMA 通道那么 CubeMX 还会生成hdma_usart1_rx和hdma_usart1_tx这样的 DMA 句柄并在HAL_UART_MspInit()里把它们关联到串口句柄上。DMA 又会牵扯到 DMA 通道的时钟使能、中断配置等。第四某些外设的初始化函数还会在HAL_UART_Init()之后启动底层接收中断或 DMA 传输这些都会让“未使用”的外设仍然在后台占用资源和功耗。所以你以为只是没用的几行代码实际上一整套 GPIO、时钟、中断、DMA 配置都被塞进了你的工程。这就是为什么我经常说清理未使用外设不是“代码洁癖”而是降低工程复杂度、避免引脚冲突和隐藏功耗问题的重要手段。1.3 为什么不能靠编译器自动“优化掉”未使用代码有些朋友会想既然没用到编译器链接的时候应该会自动剔除吧这个想法理论上成立但前提是那些未使用外设的初始化函数是“孤立”的没有被任何地方引用。现实情况是CubeMX 默认会把MX_xxx_Init()的调用直接写进main()而main()是整个程序入口链接器无论如何都不会把它丢掉的。即使你把main()里的调用注释掉这个初始化函数依然可能因为以下原因被保留第一CubeMX 生成的初始化函数没有static限定至少在旧版本中它们被声明在头文件里编译单元会认为这是一个外部符号链接器不确定是否被其他文件引用所以可能不会仅凭一个未使用就裁剪掉。第二如果你的全局中断服务程序USART1_IRQHandler()被使能它会进入中断向量表而中断向量表是强引用的所以相关代码必然保留。第三编译器虽然可以在开启-ffunction-sections -fdata-sections -Wl,--gc-sections选项后做函数级垃圾回收但前提是你必须正确配置这些编译选项而且即使回收了未使用的初始化函数CubeMX 在下次重新生成代码时依旧会把它们加回来因为配置文件没有改。因此真正有效的做法只有一个在源头修改 CubeMX 的配置让生成器在代码生成阶段就不产生这些初始化代码。2. 清理的核心思路让 CubeMX 忘记这些外设2.1 方法一在 Pinout Configuration 面板里禁用外设这是最直接、最符合正常操作习惯的方法。以 CubeMX 6.x 版本界面为例5.x 也类似打开你的.ioc工程后左侧会有一个Categories列表里面列出了System Core、Analog、Timers、Connectivity、Multimedia等分类。你要找的外设可能分散在不同的分类里比如 USART 在Connectivity下ADC 在Analog下TIM 在Timers下。点击你要清理的外设名比如USART1右侧会打开一个配置界面最上方有一个Mode下拉框。只要这个下拉框当前的选项不是Disabled就说明外设仍然处于使能状态。把它改成Disabled然后往下检查Configuration区域里的DMA、NVIC、Interrupts等相关配置。通常当你把 Mode 改为 Disabled 后CubeMX 会自动清除一些关联项但为了保险起见你仍然需要逐项检查一下是否存在残留的 DMA 通道或中断配置。保存.ioc文件重新生成代码main()里的MX_USART1_UART_Init()调用就会消失。这里要特别提醒一个容易忽略的点不要只在Pinout view里右键引脚选择Reset_State就以为万事大吉了。Reset_State只是把某个引脚恢复成 GPIO 复位状态如果外设配置里还有中断或 DMA 在使能状态重新生成代码时它可能通过别的路径把引脚配置又“带”回来。所以最稳妥的做法是先从外设配置面板里把 Mode 改为 Disabled再检查依赖项。2.2 方法二在芯片引脚图上直接复位引脚反向关闭外设有些时候你记不清某个外设叫什么名字只记得芯片上某个引脚之前被占用得厉害你希望看到这个引脚恢复成普通 GPIO。这时候可以直接在右侧芯片引脚图上操作。找到目标引脚比如 PA9右键点击它在菜单里找到Reset_State或GPIO_ResetState不同 HUB 版本文字略有差异点击确认。如果这个引脚只被一个外设占用CubeMX 会直接恢复引脚为复位状态同时把对应外设的 Mode 改成 Disabled。如果这个引脚被多个外设共享或者处于冲突状态CubeMX 会弹窗询问你要释放哪一个外设这时候需要你根据实际需求做选择。这个方法比较适合排查引脚冲突把 Pinout view 上那些绿色、黄色、橙色的“霸占”引脚依次释放掉。不过我不建议完全依赖它来清理外设因为如果你只是复位了引脚但外设配置面板里的 Mode 没有被同步改成 Disabled某些版本的 CubeMX 会在重新生成代码时报冲突或者自动把引脚重新分配出去。2.3 方法三直接操作 .ioc 文件的进阶玩法.ioc文件本质上是一个属性文件里面记录了整个工程的所有配置信息。你有经验之后可以打开它并定位到对应外设的配置块。比如需要禁用 USART1正常情况下你会看到类似这样的内容USART1.ModeAsynchronous USART1.BaudRate115200 USART1.WordLength8b ... Mcu.Pin.9PA9 Mcu.Pin.9.SignalUSART1_TX要快速清理可以把USART1.ModeAsynchronous改为USART1.ModeDisable然后删除或注释掉与 USART1 相关的引脚映射行。但这里我不推荐大家直接改.ioc来清理单个外设原因有两个一是.ioc文件里的键值对之间还有隐藏的依赖关系比如 DMA 请求映射、中断优先级分组的依赖只改一行很可能留下孤儿配置二是 CubeMX 在加载.ioc文件时会做完整性检查格式不对会导致打不开工程文件。当然如果你有大量工程需要批量做“外设清理”可以用脚本辅助。比如用 Python 解析.ioc文件统计所有Mode前缀的配置然后输出一个外设启用清单方便你对照清理。脚本逻辑很简单但只能起到“检查辅助”作用真正修改配置还是要在 CubeMX 里完成。2.4 三种清理方式的取舍我把三种方式整理成了一个表格方便你平时快速判断用哪个方式优点缺点适用场景外设配置面板禁用最直观能看到所有关联配置项需要逐个外设点击步骤稍多日常清理单个外设最推荐引脚图右键复位快速释放冲突引脚操作直接可能遗漏外设配置面板里的残留项排引脚冲突、快速试探修改 .ioc 文件可以批量处理、脚本化容易改坏文件依赖关系难排查有经验者批量检查建议只读不改3. 实测把一套“留着没用的外设”从工程里清掉3.1 动手前的盘点列出现有的初始化列表在我维护的一个传感器采集项目中早期测试时开了不少外设正式产品里实际上只需要 USART1 作为调试串口、I2C1 接传感器、TIM1 做 PWM。但打开 main.c 时我发现初始化列表里还有MX_USART1_UART_Init、MX_USART2_UART_Init、MX_SPI1_Init、MX_ADC1_Init。其中 USART1 和 USART2 都被配置过而最终只用 USART1SPI1 只是当时测过一次外部 flash之后完全没碰过ADC1 则是早期做按键检测方案时申请的后来改成了直接 GPIO 读取。我先在工程里做了一个“初始化函数盘点表”方便等会儿对照验证清理是否彻底外设main.c 中的初始化函数当前业务代码是否使用清理决策USART1MX_USART1_UART_Init使用保留USART2MX_USART2_UART_Init未使用禁用SPI1MX_SPI1_Init未使用禁用ADC1MX_ADC1_Init未使用禁用I2C1MX_I2C1_Init使用保留TIM1MX_TIM1_Init使用保留这一步很重要因为很多人清理到一半经常会把正在用的外设也误删了。先列一个清单后面所有操作都以这个表格为准。3.2 在 CubeMX 中把未使用外设彻底禁用清单确认后我打开.ioc工程先双击左侧Connectivity分类下的USART2右侧 Mode 从Asynchronous改成Disabled。随后我检查了NVIC Settings之前使能的USART2 global interrupt已经被自动取消因为改成 Disabled 后CubeMX 会级联关闭相关中断但这一步不同版本表现不一样所以一定要自己再确认一次。然后我在Configuration里的DMA Settings看了一下没有残留通道保存。接下来是 SPI1操作路径是Categories - Connectivity - SPI1Mode 从Full-Duplex Master改成Disabled。这里有一个细节SPI1 的 NSS、SCK、MISO、MOSI 四个引脚原本都被配置成了 AF 模式我在外设配置面板改成 Disabled 后右侧引脚图上的对应引脚还是显示为绿色这说明引脚还没有被释放。我需要在引脚图上把 SCK、MISO、MOSI、NSS 这四个引脚挨个右键选择Reset_State让它们恢复成普通 GPIO。这一步不能省否则即使外设初始化函数不生成引脚仍然会在HAL_GPIO_Init()里被配置成奇怪的状态或者被其他外设复用时报冲突。ADC1 的清理稍微特殊一点。ADC1 的 Mode 在Analog分类下我把它从Independent mode改成Disabled之后原本配置的IN0、IN1引脚也确实恢复了。但我遇到的问题是在DMA Settings里残留了一路 ADC1 DMA 请求。这是因为我在早期测试时给 ADC 开了 DMA 传输模式后来虽然改了 Mode但 DMA 配置没有被自动清掉。我手动进入 DMA Settings删掉了那个 DMA channel再把中断清理干净才算彻底关闭。3.3 重新生成代码检查 main.c 和 MspInit 文件配置改完并保存.ioc后我点击GENERATE CODE。生成完后第一件事是打开 main.c定位到main()函数里那一段 CubeMX 管理的初始化代码你会发现原来的十几行调用现在只剩下了这几个HAL_Init(); SystemClock_Config(); MX_GPIO_Init(); MX_USART1_UART_Init(); MX_I2C1_Init(); MX_TIM1_Init();USART2、SPI1、ADC1 的初始化调用已经从 main.c 中彻底消失。为了确认不是只删了调用、还留了个空函数我用工程里的全局搜索功能找了一下USART2、SPI1、ADC1这几个关键词在main.c、stm32f1xx_hal_msp.c、stm32f1xx_it.c里都没有再出现相关代码。如果这里还能搜到残留说明你前一天生成时是“部分生成”模式或者.ioc没保存干净需要回到上一步重新处理。还有一个细节值得看在stm32f1xx_hal_msp.c里HAL_UART_MspInit()中原来配置 USART2 GPIO 的代码段已经没了HAL_SPI_MspInit()里的 SPI GPIO 配置也没了。这说明 CubeMX 在重新生成文件时会同步重建整个 msp 文件而不仅仅是覆盖你修改过的那几行所以只要配置正确它不会再产生历史残留。3.4 手动清理独立外设文件与最终编译这里要特别提醒一个坑如果你之前生成的工程采用了“每个外设独立一个 .c/.h 文件”的模式就是说生成了usart.c、spi.c、adc.c这类文件那么即使 CubeMX 重新生成了代码它也不会回收这些“孤儿文件”。我这次工程里就有一个spi.c和一个adc.c虽然 main.c 不再调用它们了但它们还静静地躺在项目目录里并且仍然在 IDE 的工程列表里参与编译。解决办法很简单在 CubeMX 左侧面板里确认这些外设已经 Disabled 后生成完代码到项目目录里手动删除对应的.c和.h文件然后在 IDE 里移除这些文件再重新编译。如果不删不会报错但会给后面的维护者留下“SPI 到底用没用”的误判信息。清理完文件后我做了最终编译。编译器很干净地通过了没有任何未定义引用说明工程里已经不存在对hspi1、hadc1、huart2这类句柄的依赖。为了保险我在调试模式下跑了一遍传感器读取和 PWM 输出确认清理没有影响实际功能。4. 常见问题排查与避坑指南4.1 为什么我明明禁用了外设重新生成后代码还在这个情况最常见的原因就是没有保存.ioc文件或者 CubeMX 在执行生成时使用的是缓存里的旧配置。CubeMX 的代码生成动作是读取当前内存中的工程配置而不是每次生成前自动重新解析磁盘上的.ioc文件。所以如果你在图形界面里改完配置直接点了生成理论上它应该用新配置但如果界面存在未刷新或卡顿还是建议先选择File - Save或直接按Ctrl S多等一两秒再点生成。另一个非常隐蔽的原因是你在 CubeMX 的“外设独立文件”模式下只是把外设的 Mode 改成Disabled但旧的usart.c文件还在项目目录中。这种情况下 main.c 里的调用确实被移除了但旧文件因为已经不再被 CubeMX 管理不会被自动删除所以你会误以为“代码还在”。解决办法就是我上面说的手动删除旧文件。还有一种情况是工程使用了多配置Multi-Configuration比如针对不同板子定义了config1和config2你只在当前激活的配置里禁用了外设但另一个配置还处于使能状态。生成代码时 CubeMX 会按当前激活的配置来管理文件可如果你在 IDE 里同时编译了多个配置就会再次看到未使用外设的初始化代码。建议检查左下角当前激活的配置名。4.2 外设明明没用了为什么引脚还是被占用并报冲突如果你已经在外设配置面板里把 Mode 改成了 Disabled但引脚图上对应引脚仍然是彩色状态说明这个引脚还被其他外设占用着。STM32 的引脚复用很复杂同一个引脚经常可以被多个外设使用比如 PA9 既可以是 USART1_TX也可以是 TIM1_CH2还可能是 GPIO。CubeMX 在解析配置时如果发现同一引脚被两个外设都要求使用就会把引脚标红或标橙同时提示你解决冲突。处理方法是逐个排查占用同一引脚的外设。可以点击彩色引脚CubeMX 会列出当前请求该引脚的所有外设选项你在列表里把不需要的那几个模式改成 Disable然后把这个引脚 Reset_State直到引脚变成普通 GPIO 视觉状态。如果你的工程里存在“外设 A 的引脚复用依赖外设 B 的引脚配置”这种复杂情况建议先从外设配置面板的GPIO部分查看别名和冲突列表不要一味地在引脚图上硬删。4.3 禁用外设后编译报错找不到huart2/hspi1这类句柄这个问题特别常见尤其是当你在业务代码里直接写过类似HAL_UART_Transmit(huart2, ...)这样的调用时。禁用外设后CubeMX 不再生成对应的外设句柄定义当然就报huart2未声明了。这不是 CubeMX 清理不干净而是你的业务代码还在依赖一个已经被禁用外设的句柄。解决思路是要分清到底是“这个外设真的没用了”还是“你其实还想用只是暂时没接设备”。如果确实没用了那就把业务代码里所有依赖该句柄的段落一并删掉或改成其他外设。如果只是暂时没接设备但未来还要用我建议不要把外设禁用而是在初始化函数里保留但不要在main()里调用它不过这又绕回了“未使用初始化代码”的问题。我个人的经验是不要搞“暂时保留”产品代码就是要干净要么用要么彻底关掉。未来真需要用重新打开 CubeMX 配置并生成一次代码的成本很低。4.4 常见问题速查表我在下面整理了一张速查表覆盖了平时遇到的高频问题方便你随时排查问题现象可能原因解决方案禁用后 main.c 仍有 MX_xxx_Init 调用.ioc 未保存使用的不是当前激活配置先保存 .ioc再重新生成代码外设配置已禁用但引脚仍彩色占用引脚被其他外设复用在引脚图上右键 Reset_State 并检查冲突列表旧的外设独立文件还留在工程里启用独立文件生成模式后CubeMX 不自动删除孤儿文件手动删除 .c/.h并从 IDE 项目移除编译报错找不到 huart1 / hspi1业务代码引用了已删除外设的句柄删除相关业务代码或恢复外设使能禁用外设后其他功能反而异常两个功能共用了同一 DMA 通道或中断检查 DMA 通道、NVIC 中断配置的重复分配CubeMX 生成代码时提示配置冲突同一引脚被多个外设占用逐项禁用冲突外设释放引脚禁用外设后代码体积依旧很大HAL 库文件被整体复制进工程改用“Copy only necessary library files”模式4.5 从源头防止再犯的几个习惯最高效的清理是从一开始就不让未使用外设进入代码。我现在的习惯是在 CubeMX 里做完任何一个新功能评估性验证之后立刻把该外设的 Mode 改回 Disabled然后保存。不要想着“等会儿一起清”因为“等会儿”往往会变成“几个月后”到时候只能对着 main.c 里密密麻麻的初始化函数发呆。另一个建议是给每个外设做好标记。CubeMX 允许在 GPIO 标签里写注释比如USART1_TX、KEY_ADC之类的。这样你在 Pinout view 里扫一眼就知道哪些引脚是给哪个功能用的不敢乱删。如果你的项目代码已经接手很久里面各种外设命名混乱那就需要先做一次完整盘点再动刀清理。5. 让生成的代码从一开始就保持精简的进阶配置5.1 把每一个外设的初始化代码独立成文件CubeMX 的 Project Manager 里Project Settings - Code Generator有一个选项Generate peripheral initialization as a pair of .c/.h files per peripheral。这个选项默认是不勾选的生成的初始化代码全部塞在main.c里。如果你要长期维护一个复杂工程我非常建议勾选它。勾选之后每个外设会生成独立的usart.c、i2c.c、tim.c等文件main.c 只保留MX_xxx_Init的函数调用。这样当你禁用某个外设时只需要把对应的文件从工程里移除main.c 的变动会非常小。更重要的是团队协作时每个人负责的外设可以各管各的文件合并代码时冲突概率大大降低。不过要记住一点独立文件模式下旧文件不会自动删除禁用外设后一定记得手动清理。5.2 按需复制 HAL 库文件减小固件体积在同一个Code Generator设置面板里还有一个HAL Settings或Library Settings区域里面有一个选项叫Copy only necessary library files。如果选择这个CubeMX 只会把当前工程实际使用到的 HAL 库源文件复制到你的工程目录里而不是把整个 HAL 库都复制一遍。这在禁用外设后效果很明显禁用 USART2、SPI1、ADC1 后重新生成工程你会发现stm32f1xx_hal_uart.c、stm32f1xx_hal_spi.c、stm32f1xx_hal_adc.c可能都不再出现在工程目录里或者至少不会在编译时被引用固件体积自然就变小了。但要注意这个选项和“复制所有库文件”模式相比对后续手工修改更敏感。如果你在 CubeMX 之外手动调用了某个新外设的 HAL 函数但工程里没有对应库文件会直接链接失败。所以更适合熟悉 HAL 库、工程外设边界明确的团队。5.3 用脚本检查 .ioc 里的隐性外设配置当工程多了以后手动检查每个工程是否残留未使用外设是一件很痛苦的事。我写了一个简单的 Python 脚本思路可以解析.ioc文件提取所有Mode字段并判断哪些外设不是Disable方便在代码提交前做一次快速巡检。代码不复杂核心逻辑就是逐行读取.ioc文件用正则匹配类似^\w\.Mode的行然后排除掉GPIO、RCC、SYS这些基础外设剩下的就是自定义外设启用列表。import re def check_ioc(ioc_path): enabled [] pattern re.compile(r^(?Pperiph[A-Z0-9_])\.Mode(?Pmode.*)$) with open(ioc_path, r, encodingutf-8) as f: for line in f: m pattern.match(line.strip()) if not m: continue periph m.group(periph) mode m.group(mode) if periph in (GPIO, RCC, SYS): continue if mode.lower() not in (disable, disabled, ): enabled.append((periph, mode)) return enabled print(check_ioc(my_project.ioc))这个脚本对普通开发者来说更像是锦上添花但如果你在 CI 流程里做代码检查它可以帮助你在工程管理阶段就捕获“多开了外设”的问题。另一个思路是直接搜索生成目录里有没有MX_开头的初始化函数再用脚本判断它是否被main()调用但这涉及更多代码分析不如直接看.ioc来得快。5.4 把“外设启用清单”写进工程规范如果你在带团队我强烈建议把“开发阶段外设清理”写进代码审查检查项。具体来说每次 MR 里只要包含 CubeMX 生成代码的变更都要看一遍 main.c 的初始化函数列表凡是和本次业务需求无关的MX_xxx_Init调用一律打回修改。这个规则看着简单却能避免大量历史债务。我自己的习惯是每次生成代码后第一时间把main()里的初始化列表截图或复制进 commit message说明本次启用了哪些外设、禁用了哪些外设。这样下次有人看到这版代码时不会对着初始化函数列表瞎猜。久而久之你会发现 CubeMX 工程的可维护性提升非常明显而且很少再出现“编译器帮我优化掉”或者“运行时外设莫名在跑中断”这种诡异问题。深入维护几年的工程后再回头看看这些细节绝对能帮你省下大量排查时间。