企业官网建设流程全解析

很多刚接触STM32的朋友，第一个纠结的问题往往不是学什么，而是“我该用哪个工具”。Keil、STM32CubeIDE、IAR、VS Code、GCC、OpenOCD……网上一搜一大堆，说法还互相矛盾。有些教程说Keil是行业标配，有些文章又力推官方免费的CubeIDE，还有人晒出自己的VS Code加命令行的工作流，看起来很酷，但新手照抄之后连工程都编译不过。

这篇文章就是来把这团乱麻理顺的。我做了很多年嵌入式开发，从最早的Keil MDK入门，到后来用STM32CubeIDE做量产项目，再到折腾CMake和命令行工具链，中间踩过的坑不算少。这篇文章会把STM32软件开发涉及的工具做一个全景拆解，讲清楚每个工具到底是干什么的、它们之间的边界在哪里、各自的优势和代价是什么，最后给出不同阶段、不同场景下最务实的选择建议。无论你是刚装了IDE还没建出第一个工程的初学者，还是在犹豫要不要把主力工具从Keil换成其他方案的老开发，这篇应该都能给你一个明确的参考。

1. IDE选型：别让编辑器成为你的第一个瓶颈

很多人把IDE当成开发工具的全部，其实IDE只是整个工具链的前台。它把编辑器、编译器、调试器、烧录工具集成到一个图形界面里，让你不用记命令行就能完成开发。但这并不意味着IDE可以随便选，不同的IDE绑定的编译器和调试方式完全不同，选错会在后面付出很大的迁移成本。

1.1 四大主流IDE的定位与适用场景

目前STM32开发者的IDE选择，基本集中在四个方向：Keil MDK、STM32CubeIDE、IAR Embedded Workbench、以及VS Code加插件生态。

Keil MDK是很多大学实验室和中小型公司的标配。它的历史很长，从8051时代就存在，因此积累了大量教程和案例。uVision界面在今天看起来有些过时，但胜在轻量、上手简单，对新手非常友好。它的编译器是ARM自家的Keil编译器（现在叫Arm Compiler），编译速度快，生成的代码效率也不错。不过Keil的授权模式比较麻烦，免费版本有代码容量限制，超出之后没法编译，正式版需要购买License，价格不便宜。

STM32CubeIDE是ST官方主推的免费IDE，基于Eclipse框架搭建，内置了GCC ARM工具链、调试器支持、以及CubeMX工程配置功能。免费这一点对于学习和个人开发是决定性优势，而且它对ST自家芯片的支持是最完整、最及时的，新芯片发布后CubeIDE基本都是第一时间支持。缺点是Eclipse老底子摆在那里，界面偏重，索引和编译速度在配置低的电脑上有点捉急，另外Linux下偶尔会有一些显示或输入法的小毛病。

IAR Embedded Workbench在工业界口碑很好，它的编译器优化能力是公认最强的，生成代码的体积和执行效率在几个工具链里往往是最好的一档，调试体验也很顺滑，支持非常细粒度的运行时分析。代价就是贵，而且它的工程文件格式和操作习惯跟其他工具差异很大，一旦用了IAR，基本就等于上了“贼船”，迁移成本很高。个人学习和一般项目不太建议一上来就选它。

VS Code加插件这条路是最近几年流行起来的，本质上是DIY一个轻量级IDE。通过C/C++扩展、CMake插件、Cortex-Debug调试插件，配合OpenOCD和GCC工具链，可以搭建一套完全免费且非常流畅的开发环境。好处是编辑器体验极佳、跨平台一致、可定制性极高，坏处是配置门槛较高，你需要自己理解编译和调试的底层逻辑，新手很容易在配置环境阶段就耗尽热情。

这四个方向没有绝对的优劣，关键在于匹配自己的场景。下面这张表可以直观对比一下：

1.2 我实际用下来的选择逻辑

我自己是Keil入门的，当年学校里的教材和实验指导书全是Keil截图，也没得选。后来工作后做量产项目，公司买了正版Keil，用了一段时间也算顺手。真正让我转向CubeIDE的是一个比较实际的痛点：公司有一款产品需要用到一颗新出的芯片，Keil的器件包支持滞后了两个月，而CubeIDE在芯片发布当天就直接支持了。从那之后我就开始把新项目都放到CubeIDE上。

中间也特意花了两个星期折腾过VS Code加CMake的流程，还写了一套自动构建脚本。结论是：这条路确实爽，尤其是配合命令行批量编译和持续集成时效率很高，但日常开发和调试的顺滑程度跟专门做嵌入式集成的IDE相比还是有差距。后来我的做法是两手都用：项目开发调试用CubeIDE，需要批量构建和自动化验证时用命令行工具链加CMake。

我的选择逻辑可以总结成几个问题：第一，你是要学习还是做产品？学习优先考虑免费和易上手。第二，你的团队或公司是否统一某种IDE？多人协作用同一个工具能省掉大量沟通成本。第三，你对芯片资源和运行效率的要求高不高？如果做大批量产品且对Flash和RAM抠得很死，IAR值得认真考虑。第四，你有没有精力自己折腾环境？没有的话老老实实用集成好的IDE。

1.3 给新手的第一套开发环境推荐

如果你是刚接触STM32的新手，我建议直接使用STM32CubeIDE加一块官方Nucleo开发板，不要犹豫。原因很简单：CubeIDE免费，官方板子自带ST-Link调试器，插上USB线就能识别，新建工程时CubeMX配置向导会帮你生成完整的外设初始化代码，编译烧录调试全都在这个软件里完成。从零到点亮一颗LED，全程不需要安装第三个工具。

安装和使用中有几个注意点：第一，CubeIDE内置了Java运行时，安装包比较大，下载时耐心等，不要中途关掉。第二，工作空间路径不要出现中文和空格，否则后面会有各种奇奇怪怪的问题。第三，第一次打开软件时它会做一次全量索引，界面会卡一会儿，这是正常的，不要以为是死机了。第四，新建工程时如果用的是中文芯片型号搜索，偶尔会出现搜不到的情况，直接输入具体型号比如STM32F103C8T6，关键字越精确越好。

2. 编译工具链：你写的是C代码，但决定性能的是编译器

在IDE里点一下“编译”按钮，背后其实是一整套工具链在干活。理解这层幕后逻辑，对你的调试和优化能力提升非常大。

2.1 ARM工具链的构成与安装

ARM嵌入式开发的标准开源工具链叫GNU Arm Embedded Toolchain，核心组件包括C/C++编译器、汇编器、链接器，以及一系列二进制处理工具。我们常说的arm-none-eabi-gcc只是其中的编译器，完整工具链还包含：

• arm-none-eabi-as：汇编器，把汇编代码转成机器指令
• arm-none-eabi-ld：链接器，把多个目标文件组合成最终的ELF文件
• arm-none-eabi-objcopy：把ELF文件转换成可烧录的bin或hex格式
• arm-none-eabi-size：查看编译产物在Flash和RAM中的占用情况
• arm-none-eabi-objdump：反汇编，查看程序对应的汇编指令

在Linux上安装很方便，一般用包管理器直接安装即可。比如在Ubuntu上：

sudo apt update sudo apt install gcc-arm-none-eabi

Windows用户可以到ARM官方页面下载Windows版本的exe安装包，装完把工具链的bin目录加进系统PATH，然后在命令行里输入arm-none-eabi-gcc --version验证是否成功。这里有个小坑：网上有些教程会让你装某个芯片厂商魔改版的工具链，除非你有特殊需求，不建议用魔改版本，直接用ARM官方工具链最稳定。

2.2 链接脚本入门：内存布局其实是这么回事

很多开发者写了好几年STM32代码，却从来没了解过链接脚本（Linker Script）是怎么工作的。实际上一旦你开始用GCC工具链做工程，链接脚本就成为一个绕不过去的东西。

链接脚本的作用是告诉链接器：这个芯片的Flash和RAM分别在哪里、容量多大、代码段放在哪、数据段放在哪、堆栈位置怎么安排。以STM32F103C8T6为例，它拥有64KB Flash和20KB SRAM，一个最小可用的链接脚本核心部分长这样：

MEMORY { FLASH (rx) : ORIGIN = 0x08000000, LENGTH = 64K RAM (rwx) : ORIGIN = 0x20000000, LENGTH = 20K } SECTIONS { .text : { KEEP(*(.isr_vector)) *(.text*) *(.rodata*) _etext = .; } > FLASH .data : { _sdata = .; *(.data*) _edata = .; } > RAM AT> FLASH .bss : { _sbss = .; *(.bss*) *(COMMON) _ebss = .; } > RAM }

这里有两个细节值得解释。第一，.data段为什么用了“> RAM AT> FLASH”这种写法？因为芯片上电后RAM的内容是随机的，初始值必须放在Flash里，启动代码需要先把存放在Flash中的初始值拷贝到RAM对应的位置，这个过程叫“加载域到运行域的复制”。第二，.bss段存放未初始化的全局变量，启动代码需要把它清零。这些动作都是在startup文件里完成的，搞清楚这段逻辑之后，你对嵌入式程序“从哪里开始执行”的理解就会通透很多。

2.3 编译优化等级与代码体积的取舍

GCC的编译优化选项对最终生成的代码影响巨大。调试阶段建议用-Og，它在保持调试体验的前提下做一些不干扰调试的优化。发布版本常用-Os，在兼顾体积的同时尽量不牺牲太多性能，也可以根据需求用-O2甚至-O3追求极限性能。

我在实际项目中见过太多“优化一开，程序就跑飞”的情况，多数问题其实不是编译器bug，而是代码本身存在未定义行为或者对硬件寄存器的访问缺少volatile修饰。比如一个延时函数：

void delay(void) { volatile uint32_t count = 100000; while(count--); }

如果这里的count不加volatile，编译器在-O2下会直接把它优化掉，因为循环体没有对外部可见的副作用，整个delay函数可能会变成空操作。我在一个数据采集项目里就踩过这个坑，那次是GPIO翻转延时，开-O2后输出波形频率直接翻了好几倍，查了很久才发现是volatile的问题。所以开优化之前，先检查所有与硬件交互的变量是否都有volatile修饰，这是一个很重要的习惯。

另外一个与体积相关的小技巧是合理利用编译优化属性。有些函数希望始终优化，有些则希望保持最低优化级别，可以用__attribute__((optimize("O0")))单独标注，不用为了个别函数牺牲整个项目的优化等级。

2.4 从Make到CMake：构建系统的现代化

CubeIDE和Keil都有内置的构建系统，点按钮就能编译。但当你的项目复杂度上来之后，手工维护IDE工程渐渐会变得吃力。比如你有多个变体（不同芯片型号、不同功能开关的版本），每个变体都要维护一个工程文件；或者你想在服务器上跑自动化编译，没有图形界面的IDE很难用。

这时候就该考虑CMake了。CMake本身不编译，它是生成构建规则的工具，可以生成Makefile、Ninja构建文件等，然后真正的编译还是交给GCC。一个最小的STM32工程CMake配置大概长这样：

cmake_minimum_required(VERSION 3.16) project(stm32_demo C ASM) set(CMAKE_SYSTEM_NAME Generic) set(CMAKE_SYSTEM_PROCESSOR arm) set(TOOLCHAIN_PREFIX arm-none-eabi-) set(CMAKE_C_COMPILER ${TOOLCHAIN_PREFIX}gcc) set(FLASH_ORIGIN 0x08000000) set(FLASH_SIZE 64K) set(RAM_ORIGIN 0x20000000) set(RAM_SIZE 20K) add_compile_options( -mcpu=cortex-m3 -mthumb -Os -Wall ) add_executable(${PROJECT_NAME} Core/Src/main.c Core/Src/stm32f1xx_hal_msp.c Core/Startup/startup_stm32f103c8tx.s Drivers/STM32F1xx_HAL_Driver/Src/stm32f1xx_hal.c ) target_link_libraries(${PROJECT_NAME} -T stm32f103c8t6.ld)

这里有个关键点：必须把芯片的启动文件（startup_xxx.s）和链接脚本通过编译和链接选项指定进去，CMake本身并不知道你的芯片长什么样。新手用CMake时经常会漏掉这两样东西，导致编译出来没法运行。所以我对新手的建议是：前期先用CubeIDE把编译链接的流程跑通，理解了工程结构之后，再考虑切换到CMake来管理复杂项目，否则纯粹是给自己增加难度。

3. 代码生成与HAL库：理解代码生成器的边界

STM32开发相比很多单片机开发的优势之一，就是有CubeMX这套图形化配置工具，能自动生成初始化代码。但代码生成器能做的事情是有限的，理解它的边界比理解它的功能更重要。

3.1 CubeMX的能干与不能干

CubeMX能做的事情包括：图形化分配引脚功能、配置外设参数（时钟频率、串口波特率、定时器模式等）、自动计算时钟树、配置中间件（FreeRTOS、FatFS、USB协议栈等）、生成对应的初始化代码。它的核心价值在于把芯片数据手册里繁琐的寄存器配置逻辑变成可视化操作，省掉了大量查阅手册的时间。

但它不擅长的事情也很明确：它不负责业务逻辑，不帮你设计应用层架构，不处理任何中断服务函数里的业务实现。生成出来的代码只是一个“骨架”，main.c里预留了USER CODE区域，外设回调函数默认是空的，具体业务全部需要你自己填充。

使用CubeMX时的核心原则是：永远在你自己的USER CODE区域里写代码，不要修改生成区域的内容。因为每次重新生成工程时，生成区域的代码会被完整刷新，只有USER CODE区域会被保留。一个常见的场景：你先用CubeMX配置了串口，生成了代码，后来工作需要加一个定时器，重新配置后再次生成，这时串口初始化代码会被重新生成，但你在USER CODE区域里写的发送逻辑会原样保留，这也是CubeMX经过多年迭代后在易用性上做得比较成熟的地方。

3.2 HAL库、LL库与寄存器开发的取舍

ST官方为STM32提供了三种开发层级：直接操作寄存器、HAL库、LL库。

直接操作寄存器是底层的做法，优点是代码最精简、执行效率最高、对硬件的理解最直接，缺点是开发效率极低，一个串口初始化可能要写几十行寄存器操作，而且每个芯片手册都几百页，查阅负担很大。学习阶段用它点亮LED、熟悉外设原理是非常好的；但做完整的产品就太吃力了。

HAL库是目前ST主推的开发方式，也是CubeMX默认生成的代码风格。它提供了高度抽象的API，比如HAL_UART_Transmit()、HAL_GPIO_WritePin()，同一套API可以平滑地用在STM32全系列芯片上，换芯片时改动很小。代价就是代码量大、中间层多、对实时性要求高的场景会产生额外的时间开销，甚至一些异步操作还需要依赖中断回调机制来完成。

LL库则是在HAL库基础上提供了一套更接近寄存器操作的轻量接口。它保留了HAL库的易用性，同时减少了抽象层级，代码执行速度更快、体积更小。适合对性能和资源敏感的场合，比如外部中断频繁翻转IO、定时器PWM对时序要求严格的场景。

三者的选择没有绝对标准。我的建议是：学习时以寄存器操作理解原理，用HAL库做实际开发；当某个外设对时序要求很高，HAL库的中断回调机制无法满足时，这个外设单独用LL库或直接寄存器操作；整体框架保持HAL库统一。这样兼顾了开发效率和性能。

3.3 从CubeMX生成到实际业务代码的衔接

从CubeMX生成工程到写出实际业务逻辑，有几个容易卡住新手的环节。

先看中断回调函数。HAL库的机制是：外设事件发生后，中断服务函数会调用对应外设的回调函数，你只需要在main.c里重写这个回调函数，就能实现自己的逻辑。比如串口接收，CubeMX生成的代码里会预留HAL_UART_RxCpltCallback()，你在里面判断数据内容并处理即可。但要注意：HAL库的中断回调默认是在中断上下文中执行的，不要在回调里做耗时操作，比如不要直接在里面调用HAL_UART_Transmit()发送很长的数据，否则会拖慢整个中断响应。正确做法是把数据拷贝到缓冲区，设置一个标志位，在主循环里再处理。

再看外设句柄。CubeMX生成的代码会为每个外设创建一个句柄结构体，比如UART_HandleTypeDef huart1，你在业务代码里调用HAL函数时都要传入这个句柄的指针。如果需要在其他C文件中使用，记得用extern声明。这里常见的坑是：多个文件引用同一个外设句柄时，拷贝了局部变量而不是使用全局句柄，导致外设操作无效。

4. 调试器与调试手段：学会了看寄存器，才算入门

写代码谁都会，会调试才是嵌入式开发的真功夫。STLink、J-Link这些调试器解决的就是“程序到底卡在哪里”的问题。

4.1 ST-Link、J-Link和OpenOCD的取舍

ST-Link是ST官方推出的调试探针，Nucleo开发板上直接集成了ST-Link电路，用一根USB线就能完成供电和调试，成本几乎为零。它的调试速度在大多数场景下足够用了，SWD模式下支持常见的断点、单步、读写寄存器、烧录等功能。缺点是在高速调试、复杂断点条件、运行时追踪等方面不如J-Link专业。

J-Link是SEGGER公司的产品，也是行业事实标准。它的调试速度快很多，SWD接口频率可以拉到很高，支持Flash下载编程、J-Link RTT（一种通过调试接口进行实时日志输出的技术）、以及丰富的命令行工具。缺点是正版价格不菲，而网上大量低价的所谓“J-Link”其实是盗版芯片方案，固件容易崩溃，稳定性没保障。

OpenOCD是一个开源调试工具，它不依赖特定品牌的调试器硬件，可以配合ST-Link、CMSIS-DAP等低成本探针使用，支持GDB远程调试。如果你喜欢命令行调试方式，或者想在CI服务器上跑自动化测试，OpenOCD是一个很灵活的方案。

4.2 调试会话的建立与关键操作

在CubeIDE里调试一个工程的基本流程是：确认调试器型号（通常选ST-LINK）、设置Flash下载选项（勾选Reset and Run）、配置SWD接口频率（建议初始用4MHz，不稳定再降）。新建调试配置后点击Debug，程序会停在main函数入口处。

接下来要用好调试窗口。Watch窗口可以输入变量名查看其实时值；Peripherals窗口可以直接查看和修改外设寄存器的当前值，比如查看某个GPIO口的状态、UART的状态寄存器；Disassembly窗口可以看当前C语句对应的汇编指令。调试时养成一个习惯：遇到程序运行结果不对，先看Peripherals窗口里相关外设的寄存器值是否符合预期，再推断程序逻辑问题，这个思路能节省很多排查时间。

这里有非常值得记的一个经验：不要在断点状态下长时间挂机。如果你在调试中设置了断点，程序停在断点处，此时如果有实时性要求的外设（比如PWM输出、正在通信中的UART）还在运行，会导致通信超时或电机异常。因此调试带有实时外设的代码，尽量使用硬件断点配合条件判断，或者在中断服务函数里设置断点但快速跳过无关代码。

4.3 没有调试器也能定位问题的土办法

不是所有场景都有调试器可用。比如样机已经发给现场了，或者板子处于高速运行状态，这时候最常用的定位手段是打印日志。

对STM32而言，最常见的日志方式是printf重定向到串口。在基于HAL库的工程里，可以这样实现：

int _write(int fd, char *ptr, int len) { HAL_UART_Transmit(&huart1, (uint8_t*)ptr, len, 0xFFFF); return len; }

但这不是万能灵药。printf本身是堵塞型串行输出，如果在主循环里高频调用，会严重拖慢程序执行速度；如果是在中断里调用，甚至可能会造成死锁。我的实践经验是：日志输出一定要分级，平时运行只输出关键事件（比如状态切换、错误标志），调试时才输出每帧数据；同时用环形缓冲区配合DMA发送，让日志输出不阻塞主流程。另外，不要忘记用LED作为最原始的状态指示。很多低级错误（比如某段代码没执行、某个条件没满足）用一两个LED的亮灭就能快速判断，这比接串口看日志更快更直观。

5. 辅助工具链：版本管理、构建自动化与代码质量

工具链不只是编译器和调试器，还包括所有围绕开发流程的工具。这部分对新手来说可能没那么紧迫，但到了团队协作或产品化阶段，它就是决定开发效率的分水岭。

5.1 把Git用起来：不要再用“最终版_v10.hex”命名固件

STM32项目的代码量虽然不大，但修改频繁，变量命名、外设参数、引脚分配变来变去。如果不做版本管理，用“最终版_v10.hex”“最终版_v11_真最终.hex”这种命名方式硬扛，只需要一次功能回退就能让你崩溃。

Git对嵌入式项目是完全适用的。需要明确的一点是：CubeMX生成的代码要不要入库？我的建议是入。虽然生成的代码理论上可以重新生成，但CubeMX的版本不同，生成的代码也会有差异，而且仓库里有一份完整可编译的代码，换人接手会更顺畅。

一个STM32工程的最小.gitignore可以这样写：

build/ Debug/ Release/ *.o *.elf *.hex *.bin

这里要留意：启动文件和链接脚本必须入库，因为它们虽然也是生成文件，但直接决定了程序的启动和内存布局，丢失后很难恢复。CubeMX的.ioc配置文件也要入库，它记录了引脚配置和时钟树，团队其他人拉下来之后用CubeMX打开就能重建工程。

5.2 静态分析与代码规范

嵌入式代码最容易出的问题：数组越界、空指针、整数溢出、位运算错误。大部分问题在编译期不一定报错，运行时才暴雷。静态分析工具可以提前发现大量隐患。

Cppcheck是一个免费开源的C/C++静态分析工具，安装简单，使用也直观：

cppcheck --enable=all --error-exitcode=1 --suppress=missingIncludeSystem Core/ Drivers/

它会以警告的方式指出数组越界、空指针解引用、资源泄漏、未初始化变量等问题。clang-tidy则更关注代码风格和可维护性，可以和CMake配合在构建时自动执行。对STM32开发者来说，不是所有警告都必须消除干净，但至少要建立“定期跑一遍静态分析，把明显问题处理掉”的习惯。配合MISRA C规范做代码审查，能让水平提升很快。MISRA C是汽车行业制定的C语言编码规范，它的很多条目（比如禁止使用动态内存分配、控制表达式必须显式布尔化等）对嵌入式安全场景非常有指导意义，个人项目不必强求合规，但参考它去审视自己的代码习惯是非常好的。

5.3 单元测试：嵌入式代码也能测试

很多STM32开发者认为单元测试是上位机开发的事情，跟单片机无关。实际上，我们完全可以把与硬件无关的纯逻辑代码（校验算法、状态机、协议解析）抽出来，在PC上用Unity或者Ceedling框架测试，然后再交叉编译到固件中。这样既能快速验证算法逻辑，又不需要在硬件上反复烧录调试。

一个最小化的Unity测试用例看起来类似：

#include "unity.h" #include "crc.h" void setUp(void) {} void tearDown(void) {} void test_crc16_compute_known_value(void) { uint8_t data[] = {0x01, 0x02, 0x03}; TEST_ASSERT_EQUAL_UINT16(0x1234, crc16_compute(data, sizeof(data))); } int main(void) { UNITY_BEGIN(); RUN_TEST(test_crc16_compute_known_value); return UNITY_END(); }

这里的思路是：把协议解析、数据校验、状态切换这类纯逻辑代码放到一个独立的目录，在PC上编译测试，测试通过后再把同一份源码编译进固件。我自己的经验是，这样的流程可以极大减少在目标板上查协议逻辑错误的时间。当然，这需要前期做好代码分层，把硬件相关代码和逻辑代码清晰分离，这也正是对代码架构能力的一个很好的锻炼。

6. 常见问题与排查技巧实录

最后这部分，我把这些年包括帮其他开发者排查过程中遇到的典型问题整理一下，做成速查表。每一个问题都对应一段真实的踩坑经历。

6.1 编译报错速查表

其中Flash溢出这个问题，我见过很多新手一头雾水。这里有一个排查套路：用arm-none-eabi-size命令查看编译产物的段占用情况，比如显示text段占了50KB、data段5KB、bss段10KB，你就能清楚知道是哪类内容占的空间。如果是text段过大，通常是因为代码逻辑复杂或者优化等级太低；如果是R/O Data大，可能是有大的常量数组；如果是bss大，那就有大量全局缓冲区。

6.2 下载失败与调试器连接问题

关于调试器连接，还有一个隐蔽的问题：如果目标芯片的SWD引脚被程序复用为普通GPIO，可能导致无法再次连接。这种情况下，需要把BOOT0引脚拉高让芯片进入系统存储器模式（Bootloader模式），先擦除芯片，再恢复SWD功能。这是STM32开发里几乎所有人都会遇到一次的坑。

6.3 代码生成覆盖手写代码的灾难

CubeMX重新生成代码时覆盖自定义代码，这个问题几乎每个使用CubeMX的开发者都经历过。最典型的场景：在main.c里写了一段外设初始化代码，重新配置CubeMX后生成，发现那段代码没了。

其实CubeMX的生成机制是明确且可预测的：只有位于Begin和End注释标记之间的代码会被保留：

/* USER CODE BEGIN Includes */ #include "my_custom_module.h" /* USER CODE END Includes */

所有写在标记之外的代码，都面临被覆盖的风险。为了避免灾难，下面两个习惯必须养成。第一，自定义代码统一放到USER CODE区域，不要在生成区域内添加任何自定义内容。第二，重要代码及时提交到Git，一旦发生覆盖，通过版本恢复，避免返工。

还有一个很多人不知道的经验：如果只是微调引脚功能或外设参数，不需要使用“生成代码”（Generate Code）按钮，可以直接手改初始化代码。CubeMX的参数配置和工程中的实际代码有时候不同步，但你手动修改了代码之后，下次生成时参数会以CubeMX配置为准，所以“先手改解决问题、再同步到CubeMX配置”是两步都要做的。否则会出现“CubeMX接管后手改被覆盖”的尴尬。

玩工具这件事，光看教程是学不会的，必须自己上手折腾。我个人这些年最深的感触是：工具的目的是服务开发效率，不要成为工具的奴隶。新手阶段认准一套官方推荐的工具链（CubeIDE + ST-Link + 官方开发板）踏踏实实用起来，比什么都重要。等代码量上来、项目复杂度上来，你自然会理解为什么要引入版本管理、为什么要做自动化构建、为什么要把代码逻辑和硬件解耦。那时候再换工具，就是水到渠成的事情，而不是被环境配置折磨出来的恐惧。最后送上一句话：先能跑通，再谈优化；先学会一个，再讨论选型。工具切换这件事，不是选择题，而是阶段题。