应选择STM32CubeMX模板，它会自动生成.ioc文件并绑定CubeMX工具链，确保外设配置、时钟树和HAL初始化正确联动；若误选其他模板则无.ioc文件，导致CubeMX配置无法同步且调试器识别失败。
CLion里点“New Project”后选什么模板
直接选 STM32CubeMX 模板，别选 CMake、Empty Project 或其他嵌入式相关名称含糊的选项。这个模板是 CLion 官方为 STM32 项目预置的入口，它会自动生成 .ioc 文件并绑定 CubeMX 工具链，后续所有外设配置、时钟树、HAL 初始化都从这里出发。
常见错误现象：选了 Embedded Development 大类下的通用 C/C++ 项目，结果没有 .ioc 文件，CubeMX 配置无法联动，调试器也识别不到芯片型号。
注意点：
- Windows 用户路径不能含空格或中文（例如
C:\stm32\led_demo可以，C:\My Projects\led会触发 OpenOCD 启动失败） - 首次创建时若提示“找不到 STM32CubeMX”，说明 Settings → Embedded Development 里没填对路径，不是插件没装
- 项目名建议全小写+下划线，避免 CubeMX 生成的文件名在某些工具链中出错
STM32CubeMX 配置完必须点“Generate Code”再回 CLion
在 CubeMX 中完成引脚分配、时钟树、USART/ADC 等配置后，必须手动点击 Project → Generate Code（快捷键 Alt+K），否则 CLion 里看不到 Core/Src/ 和 Core/Inc/ 下的 HAL 初始化文件，CMakeLists.txt 也不会自动包含这些源码路径。
容易踩的坑：
- 只保存
.ioc文件但不生成代码 → CLion 编译报undefined reference to MX_GPIO_Init - 生成时
Toolchain / IDE下拉菜单没选STM32CubeIDE→ 生成的文件结构与 CLion 预期不符，CMake 找不到main.c - 勾选了
Copy all used libraries into the project folder→ 导致工程体积暴涨且后续 HAL 升级困难，不推荐
CMakeLists.txt 里要显式 include HAL 和 CMSIS
CLion 自动生成的 CMakeLists.txt 通常只处理 Core/Src/ 下的文件，但 HAL 库和 CMSIS 头文件路径不会自动加入。你得手动补上这几行：
include_directories(${CMAKE_SOURCE_DIR}/Drivers/STM32F1xx_HAL_Driver/Inc)
include_directories(${CMAKE_SOURCE_DIR}/Drivers/CMSIS/Device/ST/STM32F1xx/Include)
include_directories(${CMAKE_SOURCE_DIR}/Drivers/CMSIS/Include)
link_directories(${CMAKE_SOURCE_DIR}/Drivers/STM32F1xx_HAL_Driver/Lib)
否则编译会卡在 fatal error: stm32f1xx_hal.h: No such file or directory。
性能影响：如果用 add_subdirectory(Drivers/...) 替代 include_directories，CMake 配置时间会明显变长，尤其在大型项目中；对小工程来说差别不大，但没必要复杂化。
调试配置里 OpenOCD 脚本路径必须指向具体 board 文件
在 Run → Edit Configurations → OpenOCD Download and Run 中，“OpenOCD Script”字段不能只填 interface/stlink.cfg，必须补全 board 层级，比如：
interface/stlink.cfg + target/stm32f1x.cfg（F103）interface/jlink.cfg + target/stm32f0x.cfg（F030）
否则会卡在 Info : Unable to match requested speed 1000 kHz, using 950 kHz 之后无响应，或者报 Error: Target not examined yet。
真实场景中，不同探头（ST-Link V2/V3、J-Link、DAPLink）对应 interface 脚本不同，同一芯片家族不同子型号（如 F103C8 vs F103ZE）可能需要微调 target 脚本里的 flash size 和 memory map —— 这些细节藏在 openocd/scripts/target/ 目录下，别直接复制网上的通用配置。
最后提醒一句：.svd 文件（用于外设寄存器视图）不是调试必需项，但一旦配错路径，Peripherals 标签页会空白且不报错，排查起来比编译错误更隐蔽。
