从Keil到VS Code：STM32嵌入式AI编程环境搭建指南

1. 从 Keil 换到 VS Code，这一步到底图什么

做嵌入式这一行十年，前八年我的电脑上一直躺着 Keil。它没坏，编译也快，问题是这几年我的工作方式变了——代码里有一半是 AI 帮我写的，调试思路有一半是 AI 帮我理的，而 Keil 这套封闭的 IDE 天然跟这套新玩法格格不入。所以这个系列写到第 7 篇，我们必须把「编辑器」这件事彻底解决掉：安装 VS Code 与 STM32 扩展工具，不是为了追新，而是为了给后面所有 AI 编程环节留出一个能插得进手的接口。

先说清楚这篇写给谁看。如果你手上已经有一块 STM32 的开发板，会点亮 LED，会用 Keil 或 CubeIDE 打开工程，但一直觉得那套界面又重又老、写代码没有补全、想接个 AI 助手却不知道从哪下手，那这篇就是给你的。如果你是完全的新手，也没关系，我会把每个插件干什么、每个路径为什么要这么填都讲清楚，照着走一遍就能跑起来。整套流程在 Windows 上验证过，大部分内容在 macOS 和 Linux 上同样成立，只是路径写法要换一下。

这里先给一个结论，省得你看到后面迷路：最终我们要搭出来的东西是「VS Code + C/C++ 扩展 + CMake Tools + Cortex-Debug + ST 官方 STM32 扩展 + arm-none-eabi-gcc + OpenOCD」这样一套组合。编辑器负责写和看，GCC 负责编译，OpenOCD 负责把程序推进芯片，Cortex-Debug 负责断点和看寄存器，ST 官方扩展负责管芯片包、生成工程骨架、一键烧录。后面接入 AI 编程助手时，它面对的就是这套开放的工具链，而不是一个黑盒。

1.1 三个现实痛点：授权、插件生态、AI 接入

第一个痛点是授权和协作。Keil 的免费版有 32KB 代码限制，商业授权按年付费，团队里换台电脑就要重新折腾一遍许可证。VS Code 本身免费，底层工具链全是开源项目，编译器和调试器都没有代码体积限制。这对做毕业设计的学生党尤其友好，你不需要为了一个几万行的工程去纠结授权问题，也不会因为换了台机器就把环境搞崩。

第二个痛点是插件生态。嵌入式开发的日常其实很杂：看十六进制文件、比对 git 差异、连串口看日志、画时序图、查寄存器手册。这些需求在传统 IDE 里要么没有，要么得装一堆配套软件；VS Code 里基本都能找到插件，装完就在同一个窗口里用，上下文不用来回切。这种「一个窗口干完所有事」的体验，用过就回不去了。

第三个也是最重要的痛点，AI 接入。现在主流的 AI 编程助手，几乎都是优先适配 VS Code 的，因为它的扩展 API 足够开放。你在编辑器里选中一段 HAL 代码，让它解释、重构、补全、生成单元测试，这些动作都建立在「编辑器能对外暴露代码上下文」这个前提上。Keil 做不到这一点，CubeIDE 也做不到。所以这一篇不是可选项，是整条 AI 编程路径的地基。

1.2 这套工具链最终长成什么样

先把全景画出来，后面每一节都是往这个骨架里填肉。整个链路是这样的：STM32CubeMX 或 CubeCLI 负责生成初始化代码和引脚配置，产出一个带 CMake 的工程目录；VS Code 打开这个目录，C/C++ 扩展负责语法分析和补全，CMake Tools 负责调用构建系统；arm-none-eabi-gcc 是真正干活的编译器，把 C 代码变成 ELF 和 HEX；OpenOCD 通过 ST-Link 把程序下载进芯片，并在调试时充当 GDB Server；Cortex-Debug 在 VS Code 里提供图形化的断点、变量监视和外设寄存器查看。

这套链路的关键在于「每一层都是可替换、可观测的」。编译器版本不对，你换一个路径就行；调试器连不上，你单独跑一次 OpenOCD 看日志就知道卡在哪；AI 生成的代码编译不过，报错信息是 GCC 原生的，直接丢给 AI 就能定位。相比之下，传统 IDE 把编译、下载、调试全部包在一个按钮后面，出问题时你只能看到一句「Build Failed」，连编译器到底在抱怨什么都不知道。

提示：不要在同一个工程上混用 Keil 和 VS Code 两套构建系统。Keil 用 armcc/armclang，VS Code 用 GCC，两者的启动文件、链接脚本、内联汇编语法都不一样，混着改很容易出现「Keil 能过 VS Code 报错」的假象，白白浪费时间。

2. VS Code 安装：官网下载、路径选择和首选项调优

安装本身没什么技术含量，但有几个细节如果一开始没注意，后面会以很奇怪的方式咬你一口。我见过最典型的例子是安装路径里带中文，结果 CMake 缓存路径出现乱码，构建直接失败，排查了两个小时才回过神来。所以这一节虽然基础，但我建议你认真看完，尤其是路径相关的部分。

2.1 版本与安装包选择的一个小细节

去官网下载的时候，你会看到 Windows 平台通常提供两种安装包：User Installer 和 System Installer。User Installer 只装到当前用户目录，不需要管理员权限，更新也不容易和系统权限打架；System Installer 装到 Program Files，所有用户都能用。如果你只是自己一台开发机，我建议用 System Installer，原因是后面调用调试器、写系统级环境变量时更顺，尤其是团队里共用一台测试机的情况。

如果你的电脑上已经装过 VS Code，先确认版本。太老的版本（比如 1.6x 以前）对某些新插件的 API 支持不全，Cortex-Debug 和外设寄存器视图都可能出问题。团队协作时建议大家把版本统一，扩展的版本也跟着统一，避免出现「我这边能调试你那边不行」这种低级扯皮。VS Code 的自动更新默认是开着的，可以保留，但如果你在做交付期的紧张项目，建议临时关掉自动更新，免得某天早上打开电脑发现插件全变了。

2.2 安装时必须留意的三件事

第一件事，安装路径不要有中文、空格和特殊符号。推荐直接用默认路径，或者自己指定一个纯英文的短路径，比如D:\DevTools\VSCode。原因在于后面 arm-none-eabi-gcc、OpenOCD、CMake 的路径都会被写进 JSON 配置文件和 CMake 的缓存里，一旦出现中文或者空格，转义处理非常麻烦，报错信息还特别难看懂。

第二件事，安装向导里那几个勾选项要看清。我一般会勾上「添加到 PATH」和「将“通过 Code 打开”操作添加到资源管理器目录上下文菜单」，前者让命令行里可以用code .直接打开当前目录，后者让你在工程文件夹上右键就能打开，日常用起来省很多事。至于「注册为文件类型编辑器」，随意，看个人习惯。

第三件事，第一次启动时不要急着把能装的插件都装上。VS Code 的插件是启动时加载的，装几十个之后启动会明显变慢，嵌入式项目又经常要开好几个窗口。我的做法是按 Profile 分组：一个 Profile 专门放嵌入式相关插件，另一个放前端或文档类插件，切换工作区时换 Profile，启动速度能差出一倍。这个习惯在项目多起来之后会非常值。

2.3 装机后立刻要改的配置项

装完先别写代码，花五分钟把几个配置调好，后面会省很多力气。打开设置面板，搜索下面这几项逐个改：

• files.autoSave：设为onFocusChange。写嵌入式代码经常需要在编辑器和串口终端之间来回切，自动保存能避免忘了存盘就编译的尴尬。
• editor.tabSize：设为 4。这是嵌入式 C 代码的社区惯例，STM32 HAL 库本身也是四空格缩进，跟库保持一致，diff 看起来才干净。
• editor.formatOnSave：看情况开。如果你用 clang-format 统一风格就开，如果只是随手改改别人的代码，先别开，免得一保存整个文件全是改动痕迹，git diff 没法看。
• editor.minimap.enabled：建议关掉。STM32 工程里一个文件几百行很常见，小地图占地方又几乎用不上。
• telemetry.telemetryLevel：设为off，开发机没必要往外报东西。
• C_Cpp.intelliSenseEngine：保持默认的default即可，后面配好c_cpp_properties.json之后它会自动识别。

字体可以换成等宽编程字体，比如 Cascadia Code 或者 JetBrains Mono，对括号和数字 0/O、1/l 的区分明显好一些，看寄存器地址的时候不容易看错。做完这些，基础环境就算干净了。

3. STM32 扩展工具选型：到底该装哪几个

插件市场里搜 STM32，能出来几十个结果，新手很容易装一堆互相冲突的东西。我踩过的坑包括：同时装了 C/C++ 扩展和 clangd，两边抢同一份索引，补全一会儿有一会儿没有；装了两个功能重叠的串口插件，结果谁都收不到数据。所以这一节我把插件按「职责」分三层，一层装一个，不要贪多。

3.1 官方扩展、调试扩展、辅助扩展的分工

第一层是代码理解层，核心是 Microsoft 出的C/C++扩展。它负责语法高亮、跳转定义、补全、错误提示，是所有后续功能的基础。这一层不要装两个，装了 C/C++ 就不要再装 clangd，二选一。

第二层是构建和调试层。构建方面用CMake Tools，因为 STM32CubeMX 现在生成的工程默认支持 CMake，比手写 Makefile 好维护得多。调试方面装Cortex-Debug，它支持 OpenOCD、J-Link、pyOCD、ST-Link GDB Server 等多种后端，能看外设寄存器（需要配 SVD 文件），是我目前用得最顺手的一个。

第三层是 ST 官方的STM32 VS Code Extension。这个扩展是 ST 官方维护的，作用是把 CubeMX、CubeCLI、CubeProgrammer 这几个工具在 VS Code 里串起来，可以图形化地选芯片、生成工程、配置外设、一键烧录。它的价值在于「省去来回切窗口」——引脚分配在 VS Code 里改，代码就在旁边，改完立即编译，节奏很顺。缺点是对网络有依赖，头一次用需要下载对应的芯片包，公司内网环境要提前确认能不能访问。

除此之外，可以根据自己的项目补几个辅助插件，但都属于「锦上添花」：

3.2 工具链三件套：GCC、OpenOCD、CubeCLI

插件装完还得装它们背后依赖的可执行程序，这三样少了任何一个都会报「找不到命令」。第一个是arm-none-eabi-gcc，ARM 官方的 GNU 工具链，负责把 C 代码编译成 Cortex-M 能跑的机器码。下载时认准 xPack 打包版本或者 ARM 官方发布版，解压到一个纯英文路径下，比如C:\gcc-arm-none-eabi\bin，然后把这个 bin 目录加到系统环境变量 PATH 里。

第二个是OpenOCD，开源片上调试工具，作用是充当 GDB Server，把 ST-Link 和芯片连起来。它自带各种调试器和目标芯片的配置文件，STM32 系列的配置基本都覆盖了。安装同样是解压即用，重点是记住scripts目录的位置，写调试配置的时候要用到里面的 cfg 文件。

第三个是STM32CubeMX或命令行版CubeCLI。图形版适合手动配引脚，命令行版适合脚本化和批量生成，两个都装也不冲突。此外建议再装一个STM32CubeProgrammer，用于独立烧录和读芯片信息，有时候 OpenOCD 连不上，用它一验就知道是硬件问题还是软件配置问题。

注意：这三件套的安装路径，千万别放进带中文或空格的目录。我见过把工具链放在「D:\嵌入式工具\gcc」下导致 GCC 找不到链接脚本的例子，报错信息只提到「No such file」，很难联想到是路径问题。

3.3 路径验证与环境变量排查

装完不要急着建工程，先开一个终端，把下面几条命令逐条跑一遍，全都返回版本号才算过：

arm-none-eabi-gcc --version openocd --version cmake --version STM32_Programmer_CLI --version

任何一条报「不是内部或外部命令」，说明 PATH 没生效。这时候有两个常见原因：一是你只在当前终端窗口里改了环境变量，没有写进系统级设置；二是改完之后没重开终端，旧进程读的还是老的环境变量。最稳的做法是改完系统环境变量后，把所有终端窗口和 VS Code 全部关掉再重开，不要在已经开着的窗口里反复重试。

如果系统里同时存在多套 GCC（比如装了 MinGW、又装了 Keil 自带的 armcc、再加上 STM32 的 GNU 工具链），arm-none-eabi-gcc一般不会冲突，因为名字够独特，但cmake、make这类通用名就有风险了。用where arm-none-eabi-gcc（Windows）或which arm-none-eabi-gcc（macOS/Linux）确认实际调用的是哪一个，如果指向的不是你装的那个，调整 PATH 里的顺序，把正确的路径往前放。

4. 实操：半小时搭出一个能编译能断点的 STM32 工程

环境装好之后，我们用一个最小工程把整条链路走通。选一个你手头有的芯片，比如 STM32F407 或者 F103 都行，思路完全一样。整件事的节奏是：先生成工程骨架，再配三个 JSON 文件，然后编译、烧录、打断点，最后看一眼寄存器。走完一遍，你对这套工具链的掌控感会完全不一样。

4.1 用 CubeMX 生成 CMake 工程骨架

打开 STM32CubeMX，新建工程，在芯片选择器里输入型号。这里有个小技巧：型号后面的封装和温度等级后缀对软件开发没影响，选你板子上实际的那颗就行。选完芯片进到配置界面，先做三件事：配置外部晶振（如果你的板子有），配置 SysTick 时基，配置调试接口为 SWD 并保持使能。

SysTick 那一项特别容易被忽略。STM32CubeMX 默认会把时基从 SysTick 切到某个 TIM，如果你又用这个 TIM 做别的事，HAL 的HAL_Delay()就会失效或者延时不准。我的习惯是让 SysTick 保持作为 HAL 时基，把业务用的定时器单独分配，省得后面出现「延时突然变慢十倍」这种诡异现象。

然后是调试接口，一定要把 SYS 里的 Debug 设为 Serial Wire。这一步如果漏了，芯片下进去程序之后可能就再也连不上了，只能靠上电瞬间的时机去抢连或者用 BOOT 引脚救回来。配置完引脚和时钟树，在 Project Manager 里把工具链选成 CMake，勾上「为所有外设生成独立 .c/.h 文件」和「复制必要的库文件」，生成代码。

生成的目录结构大致是这样的：Core/Inc和Core/Src放业务代码，Drivers下面放 HAL 库和 CMSIS，根目录有CMakeLists.txt、cmake子目录和链接脚本。记住这个结构，后面写 includePath 就靠它。

4.2 三个 JSON 文件决定体验上限

工程目录下按 F1、输入「C/C++: Edit Configurations (JSON)」，会生成.vscode/c_cpp_properties.json。这个文件决定补全和跳转能不能用，是新手最容易翻车的地方：

{ "version": 4, "configurations": [ { "name": "STM32", "includePath": [ "${workspaceFolder}/Core/Inc", "${workspaceFolder}/Drivers/STM32F4xx_HAL_Driver/Inc", "${workspaceFolder}/Drivers/STM32F4xx_HAL_Driver/Inc/Legacy", "${workspaceFolder}/Drivers/CMSIS/Device/ST/STM32F4xx/Include", "${workspaceFolder}/Drivers/CMSIS/Include" ], "defines": [ "USE_HAL_DRIVER", "STM32F407xx" ], "compilerPath": "C:/gcc-arm-none-eabi/bin/arm-none-eabi-gcc.exe", "cStandard": "c11", "intelliSenseMode": "gcc-arm", "configurationProvider": "ms-vscode.cmake-tools" } ] }

几个关键点解释一下。includePath必须把 HAL 库、CMSIS 内核头、芯片头目录全部列进去，缺一个就会有一片红色波浪线。defines里的宏定义要和CMakeLists.txt里的一致，否则#ifdef分支会被 IntelliSense 判成不存在，看起来像错误其实不是。compilerPath指向真正的交叉编译器，这样扩展才能拿到正确的内置宏（比如__ARM_ARCH这类），跳过这一步补全质量会差很多。最后的configurationProvider让 CMake Tools 把编译参数自动喂给 IntelliSense，写起来最省事。

第二个文件是.vscode/tasks.json，定义构建任务：

{ "version": "2.0.0", "tasks": [ { "label": "Build STM32", "type": "shell", "command": "cmake", "args": [ "--build", "${workspaceFolder}/build", "--target", "all", "-j", "8" ], "group": { "kind": "build", "isDefault": true }, "problemMatcher": ["$gcc"] } ] }

-j 8是并行编译的线程数，按你 CPU 核数调整，STM32 这种规模的项目一般几秒就编完了。如果你装了 CMake Tools，其实可以不用手写这个文件，直接用状态栏的构建按钮，但手写一份的好处是可控，出问题时你能看到完整的命令行。

第三个文件是.vscode/launch.json，决定断点调试能不能用：

{ "version": "0.2.0", "configurations": [ { "name": "Debug (OpenOCD)", "type": "cortex-debug", "request": "launch", "servertype": "openocd", "cwd": "${workspaceFolder}", "executable": "${workspaceFolder}/build/${workspaceFolderBasename}.elf", "configFiles": [ "interface/stlink.cfg", "target/stm32f4x.cfg" ], "svdFile": "${workspaceFolder}/STM32F407.svd", "runToEntryPoint": "main", "preLaunchTask": "Build STM32" } ] }

几个容易踩的地方。configFiles里的两个文件名要跟你本地 OpenOCD 的scripts目录对得上，新版 OpenOCD 里 ST-Link 的配置文件统一叫stlink.cfg，老版本是stlink-v2.cfg、stlink-v2-1.cfg这种分开的，写错了会直接报找不到文件。executable的路径要指向实际生成的 ELF，如果 CubeMX 生成的工程名带下划线，这里也要一一对应。svdFile是外设寄存器视图的数据来源，可以从 ST 官网下载对应芯片的 SVD 文件，也可以从 CubeMX 的安装目录里找，配上之后调试时能在侧边栏直接看 GPIO、TIM 的每一位，比翻手册快多了。

4.3 编译、烧录、打断点、看寄存器

按下 Ctrl+Shift+B 触发构建。第一次构建会慢一点，因为 CMake 要配置一遍，之后再编译就是增量的。终端里看到[100%] Built target xxx.elf就说明成功了，同时会输出固件占用的 Flash 和 RAM 大小，这个数字要留意，超了就要想办法压。

接下来把 ST-Link 插上，板子供电，在调试面板选刚才那个配置，按 F5 启动。正常情况下 VS Code 会先跑一遍 OpenOCD，然后停在main函数入口。如果屏幕左下角的状态栏变成橙色，说明已经进入调试会话。这时候你可以：在任意一行按 F9 打断点，按 F10 单步跳过，按 F11 单步进入；在左侧变量面板看局部变量；在外设寄存器视图里翻 GPIO 的 ODR 寄存器，看某一位有没有翻转。

这一步如果能走通，说明整套工具链已经活了。后面写业务代码、接 AI 助手，都是在这个基础上做加法。我个人习惯是在main循环里放一个计数器，每轮加一，调试时盯着这个变量变化，既能确认程序在跑，也能粗略判断主循环的周期，比盲目加串口打印快得多。

5. 把 AI 助手接进这套工作流

前面四节都是准备工作，真正的重点从这里开始。为什么费这么大劲把环境换成 VS Code——因为只有在这个开放环境里，AI 编程助手才能拿到完整的代码上下文、编译报错和调试信息，给出真正可用的输出。下面讲的三件事，是我实际用下来收益最明显的部分。

5.1 AI 在嵌入式开发里能干哪些活

第一类是样板代码生成。HAL 库的初始化代码格式高度固定，GPIO、UART、I2C 的配置套路几乎一模一样，这种活交给 AI 最划算。你描述清楚「用 PA9/PA10 做 USART1，波特率 115200，8 位数据位，无校验」，它能把MX_USART1_UART_Init()里的结构体填得明明白白，比对着手册一个个查快得多。

第二类是寄存器层面的解释。手头有个别人的工程，某一行写着TIM2->CCMR1 |= 0x68，你不确定它在干什么，直接选中让 AI 解释，它会告诉你这是在配置 PWM 模式 1 加预装载使能。这种「把魔数翻译成人话」的能力，读老代码时特别有用。

第三类是排错。GCC 的报错信息和 OpenOCD 的日志相对规范，直接把整段报错粘给 AI，让它结合上下文分析，命中率比搜索引擎高。尤其是链接阶段的错误，比如undefined reference to后面跟着一串被打乱顺序的符号名，人工看很费劲，AI 拆解起来很快。

第四类是状态机和协议解析这类逻辑代码。比如写一个 Modbus RTU 的从机响应流程，或者一个按键消抖加长按短按识别的状态机，AI 给出的初版结构通常都不错，你只需要按自己的时序要求微调。

5.2 提示词模板：让 AI 吐出能编译的 HAL 代码

AI 写嵌入式代码最容易犯的毛病是「幻觉 API」——编出一个不存在的函数名，或者把 F1 系列的寄存器名安到 F4 上，编译一跑全是错。想提高一次通过率，提示词要包含四个要素：芯片型号、库版本、外设配置、输出格式要求。

我常用的模板长这样：

芯片：STM32F407ZGT6，使用 STM32CubeMX 生成的 HAL 库工程，库版本 F4 V1.27。 需求：用 TIM3 产生 1kHz 的周期中断，在中断回调里对一个全局计数器累加， 主循环里检测到计数器达到 1000 时翻转 PC13 上的 LED。 约束： 1. 只给需要我手动添加的代码，包括全局变量声明、初始化调用位置、回调函数实现； 2. 回调函数必须是 HAL_TIM_PeriodElapsedCallback 的正确签名； 3. 不要重复生成 CubeMX 已经生成的初始化代码； 4. 涉及中断共享的变量要加 volatile； 5. 说明 TIM3 的预分频和重装载值是怎么算出来的。

这个模板里最值钱的是第 5 条。让 AI 把计算过程写出来，你就能顺手校验一遍：假设 APB1 定时器时钟是 84MHz，要 1kHz，那么预分频和重装载值的乘积应该是 84000，比如 84-1 和 1000-1，或者 840-1 和 100-1。它要是给出一个对不上的数字，你立刻就知道这版代码不能用。这种「逼它把过程摊开」的写法，比让它直接给结果安全得多。

5.3 拿到 AI 代码后的审查清单

AI 给的代码我从来不会直接烧进板子，都会过一遍下面这份清单。这五条是我在实际项目里被坑出来的：

除此之外还有一条经验：AI 生成的代码里，凡是带while等待标志位的写法，都要重点看一眼有没有加超时。HAL 库里很多HAL_xxx_Transmit内部就是这样等的，如果外设没接好，程序会永远卡在那里，看门狗都救不回来。让 AI 补一个超时计数，是几秒钟就能做完但能省掉大量排查时间的事。

6. 踩坑实录与排查速查表

这一节全是实战里撞出来的东西。我可以负责任地说，前四节按部就班走一遍，你大概率会遇到下面至少两个问题，这不是你操作有问题，是这套工具链本身就有点碎。提前知道怎么处理，能省下一个下午。

6.1 头文件红色波浪线为什么最烦人

从 Keil 工程迁移过来的人，第一眼看到的就是满屏红色波浪线，尤其是#include "stm32f4xx_hal.h"下面那条。这种情况九成不是编译错误，而是 IntelliSense 找不到头文件。排查顺序是这样的：先看c_cpp_properties.json里的includePath有没有覆盖到报错头文件所在的目录，再看compilerPath有没有填对，最后看defines里的芯片宏是不是和CMakeLists.txt里的一致。

还有一个隐蔽原因是路径分隔符。Windows 上 JSON 里的反斜杠要转义，写C:\\gcc\\bin或者干脆用正斜杠C:/gcc/bin，两种都行，但混着写就容易出问题。VS Code 里的${workspaceFolder}变量指向工程根目录，如果你打开的不是工程根目录而是它的父目录，所有相对路径就全错了。确认一下左侧资源管理器里最外层文件夹是不是你生成代码的那一层。

如果一切都配置对了还是有波浪线，试着在命令面板里跑一次「C/C++: Rescan Workspace」强制重建索引；再不行就删掉.vscode/ipch缓存目录重启编辑器。这一步我在一个二十多万行的工程上跑过一次，重建索引大概花了一分多钟，之后所有跳转都正常了。

6.2 编译、烧录、调试三类报错的排查顺序

出错时最忌讳的就是乱改配置，一定要先分类。下面这张表是我自己常用的排查路径：

关于栈溢出我想多说一句。STM32 的默认栈大小通常在链接脚本里定义，一般几 KB，很多 AI 生成的代码会在大数组或者递归函数上直接踩线。表现往往很玄学：程序在某些分支下莫名复位，或者变量值莫名其妙被改。这时候去看一眼启动文件里的_Min_Stack_Size，把可疑的函数单独跑一遍，心里就有数了。

6.3 几条用久了才体会到的经验

第一条，优先用 CMake 而不是手写 Makefile。一开始我也觉得手写可控，改到第三个工程就放弃了。CMake 处理头文件依赖、条件编译、多目标输出都省心，更重要的是 AI 对 CMakeLists 的理解明显比 Makefile 好，让它帮你加一个源文件或者改编译选项，基本一次就对。

第二条，把工具链版本写进项目文档。arm-none-eabi-gcc大版本更新有时会改变对某些内联汇编的处理方式，HAL 库的版本不同也可能导致编译告警数量变化。团队里每个人用不同版本，就会出现「我这能编你那不能编」的情况，写清楚版本号是最低成本的解决方案。

第三条，调试配置单独放一份，不要和主配置混在一起。我会把launch.json拆成两个配置，一个走 OpenOCD，一个走 ST-Link GDB Server，遇到某一种连不上时直接切另一个，能快速判断是调试器的问题还是配置的问题。这个习惯在一次赶项目的深夜救过我，当时 OpenOCD 死活连不上，换成 GDB Server 一秒就连上了，省了一小时的折腾。

第四条，把常用的串口日志、固件大小检查、清构建缓存做成 task，挂在命令面板里一键调用。清缓存那条尤其有用，CMake 的缓存偶尔会因为改了工具链路径而失效，手动删build目录再重新配置，比到处找原因快得多。

第五条，AI 生成的每一段代码都要在真板上验证一遍，不要只看它编译通过就放心。编译通过只说明语法和符号对，运行时的时序、并发、边界问题它一概不知道。我的做法是每加一个新功能，先在调试会话里跑一遍关键路径，看一眼变量和外设寄存器状态，确认无误再往下写。这个习惯养成了，出问题的概率会低一个数量级。