企业官网建设流程全解析

1. 为什么要在STM32CubeIDE里折腾RT-Thread

1.1 这套组合到底解决什么问题

如果你手头有一块STM32的板子，想跑一个带任务调度、信号量、消息队列的实时操作系统，又不想脱离ST官方那套顺手的IDE环境，那STM32CubeIDE加RT-Thread基本就是最省心的路子。STM32CubeIDE负责芯片底层的时钟树、引脚分配、外设初始化代码生成，RT-Thread负责在上面搭起多线程的骨架，两者分工明确，不用你从零去啃启动文件和链接脚本。

我见过不少新手一上来就去手动改Makefile、自己写SysTick配置，结果卡在中断优先级冲突上好几天。其实用CubeIDE生成基础工程，再把RT-Thread的源码以软件包或者手动移植的方式挂进去，整个流程能压缩到半小时以内。这套方案适合三类人：一是刚接触RTOS想找个能跑起来的模板的嵌入式新手；二是从裸机开发转过来、需要快速验证多任务架构的工程师；三是做课程设计或者小批量产品原型、需要稳定调度内核的开发者。

RT-Thread本身是国产的开源实时操作系统，组件丰富，社区资料多，nano版本内核极小，跑在STM32F103这种资源紧张的芯片上也没压力。而STM32CubeIDE集成了CubeMX配置器和Eclipse调试环境，图形化配置时钟和外设，生成的HAL库代码结构清晰。把两者结合，等于你既拿到了图形化配置的便利，又拿到了RTOS的任务管理能力。

1.2 选型背后的几个关键考量

有人会问，为什么不直接用Keil或者IAR？原因很实际：CubeIDE免费、跨平台、和CubeMX无缝集成，而且调试器用ST-Link原生的，断点、变量观察、寄存器查看都很顺。Keil虽然经典，但授权问题和界面老旧是硬伤。至于为什么不直接上FreeRTOS，那是因为RT-Thread的API更贴近国内开发者的阅读习惯，中文文档全，而且它的设备框架和组件生态（比如FinSH命令行、ulog日志）在调试阶段特别好用。

还有一个隐藏好处：RT-Thread支持动态加载软件包，你后期想加个Modbus、加个文件系统，直接在配置工具里勾选就行，不用满世界找移植教程。这一点在项目迭代阶段能省下大量时间。

注意：CubeIDE的版本和RT-Thread的版本要匹配。CubeIDE 1.10以上对GCC版本有要求，RT-Thread 4.1.x和5.0.x在编译选项上略有差异，建议新手先用RT-Thread nano 3.1.5配合CubeIDE 1.9到1.12之间的版本，踩坑最少。

2. 环境准备与工程骨架搭建

2.1 软件清单和版本选择

动手之前，先把家伙什备齐。我列一个实测稳定的组合：

芯片方面，我用的是STM32F103C8T6最小系统板，Flash 64K，RAM 20K，跑RT-Thread nano绰绰有余。如果你用的是F4或者H7系列，流程一样，只是时钟配置和堆栈大小要调整。

RT-Thread nano的源码可以从官方仓库下载，也可以直接在CubeIDE的软件包管理器里找。不过我建议手动下载源码包，因为软件包管理器有时候网络不稳定，而且手动添加能让你更清楚每个文件的作用。

2.2 用CubeMX生成基础工程

打开CubeIDE，新建STM32工程，选好芯片型号。第一步是配置时钟树，F103的话，外部晶振8MHz，倍频到72MHz，APB1分频2得到36MHz，APB2不分频72MHz。这些参数在Clock Configuration标签页里拖一拖就出来了。

第二步配置调试接口。在System Core的SYS里，Debug选Serial Wire，这样ST-Link才能连上。Timebase Source保持SysTick，虽然RT-Thread会接管SysTick，但HAL库初始化阶段还需要它。

第三步配置一个串口，比如USART1，波特率115200，用于打印日志。引脚PA9和PA10自动分配。NVIC里把USART1的中断使能勾上，优先级先默认。

第四步配置一个GPIO输出，比如PC13接LED，推挽输出，初始低电平。这个用来做任务闪烁测试。

第五步在Project Manager里，Toolchain选STM32CubeIDE，代码生成选项里勾上“Generate peripheral initialization as a pair of .c/.h files”，这样外设初始化代码会单独成文件，方便后续管理。

点生成代码，CubeIDE会自动创建工程结构，main.c里会有HAL_Init、SystemClock_Config、MX_GPIO_Init、MX_USART1_UART_Init这些函数。

2.3 把RT-Thread nano源码挂进工程

在工程根目录下新建一个文件夹叫RT-Thread，把下载的nano源码里的src、include、libcpu三个文件夹拷进去。libcpu里只需要保留arm/cortex-m3（F103是M3内核），其他的删掉减小体积。

然后在CubeIDE里右键工程，Refresh一下，让IDE识别新文件。接着打开工程属性，C/C++ Build的Settings里，在Include paths里添加：

• RT-Thread/include
• RT-Thread/src
• RT-Thread/libcpu/arm/cortex-m3

这一步很关键，不添加头文件路径的话，编译时会报找不到rtthread.h。

接下来要把RT-Thread的源文件加入编译。在工程属性里找到Source Location，或者直接在CubeIDE的Project Explorer里右键RT-Thread文件夹，选择“Add/Remove include path”不行，得用“Convert to C/C++ source folder”或者手动在Build配置里添加源文件目录。更稳妥的做法是在C/C++ General的Paths and Symbols里，把src和libcpu目录添加为Source Folder。

实操心得：很多人卡在“undefined reference to rt_thread_create”这种错误上，九成是因为源文件没被编译进去。你可以在编译输出里搜一下，看看rt_thread.c、rt_scheduler.c这些文件有没有出现在编译列表里。如果没有，就是源文件路径没加对。

3. 核心移植细节与配置修改

3.1 中断向量表和SysTick的交接

RT-Thread需要接管SysTick中断和PendSV中断。在CubeIDE生成的工程里，这两个中断的处理函数在stm32f1xx_it.c中。你要做的是把SysTick_Handler和PendSV_Handler里的内容替换成RT-Thread的调用。

具体操作：在stm32f1xx_it.c里找到SysTick_Handler，把HAL_IncTick()那行注释掉，换成RT-Thread的rt_tick_increase()。但前提是你得在文件开头包含rtthread.h，并且这个函数在RT-Thread里是存在的。

更规范的做法是不直接改it.c，而是在RT-Thread的board.c里实现SysTick_Handler，然后把it.c里的弱定义覆盖掉。但CubeIDE生成的it.c里是强定义，所以你得手动删掉it.c里的SysTick_Handler和PendSV_Handler，让RT-Thread的版本生效。

PendSV_Handler在RT-Thread的context_gcc.S里已经实现，你只需要确保it.c里没有重复定义。如果编译报“multiple definition”，就是这个问题。

另外，RT-Thread的启动流程和HAL库的启动流程要衔接好。RT-Thread的入口是rtthread_startup()，它会在main函数之前被调用。你需要在main.c里把原来的while(1)循环删掉，改成rt_thread_startup或者直接让main变成RT-Thread的一个线程。

我通常的做法是：在main.c里保留HAL_Init和SystemClock_Config，然后调用rtthread_startup()。但这个函数在RT-Thread的components.c里，你需要把components.c加入编译，并且实现rt_application_init()，在里面创建你的应用线程。

3.2 堆栈大小和内存分配

RT-Thread nano默认使用静态内存池，堆大小在board.c里定义，叫RT_HEAP_SIZE，默认是0，表示不使用动态堆。如果你想用rt_malloc，就得把它改大，比如1024或者2048。F103C8T6只有20K RAM，堆给2K比较合适，剩下的留给线程栈和全局变量。

线程栈大小也要注意。RT-Thread的线程栈单位是字节，不是字。创建一个LED闪烁线程，栈给512字节就够了。如果线程里用了printf，栈至少要1K，因为printf会消耗较多栈空间。

在rtconfig.h里，有几个宏需要检查：

• RT_THREAD_PRIORITY_MAX：最大优先级，默认32，够用。
• RT_TICK_PER_SECOND：每秒 tick 数，默认100，即10ms一个tick。
• RT_ALIGN_SIZE：对齐字节，默认4。
• RT_USING_HEAP：是否使用动态堆，如果要rt_malloc就打开。
• RT_USING_CONSOLE：是否使用控制台，打开后可以用rt_kprintf。

注意：rtconfig.h是RT-Thread的核心配置文件，改之前最好备份一份。改错了会导致编译失败或者运行异常。特别是RT_USING_HEAP，打开后链接器会需要更多空间，Flash小的芯片要留意。

3.3 串口控制台和FinSH组件的取舍

RT-Thread nano默认不带FinSH，但你可以手动加。FinSH是一个命令行组件，能让你在串口终端里输入命令查看线程状态、修改变量，调试时非常方便。不过它会增加大约4K到6K的Flash占用。

对于F103C8T6这种64K Flash的芯片，加了FinSH后剩余空间还够用，但如果你还要加其他组件，就得掂量一下。我的建议是：调试阶段加上FinSH，量产时去掉。加的方法是在rtconfig.h里定义RT_USING_FINSH，然后把finsh组件的源码加入编译，并在串口初始化后调用finsh_system_init()。

串口控制台的输出用rt_kprintf，它底层会调用你实现的rt_hw_console_output。你需要在board.c里实现这个函数，把字符通过HAL_UART_Transmit发出去。注意不要用printf，因为RT-Thread有自己的输出机制，混用会导致重入问题。

4. 完整实操流程与代码实现

4.1 一步步配置时钟和外设

打开CubeIDE，新建工程选STM32F103C8Tx。在Pinout视图里，先点RCC，High Speed Clock选Crystal/Ceramic Resonator。然后点SYS，Debug选Serial Wire。接着点USART1，Mode选Asynchronous，波特率115200。最后点PC13，选GPIO_Output。

转到Clock Configuration标签，Input frequency填8，PLL Source选HSE，PLL Mul选9倍频，System Clock Mux选PLLCLK，APB1 Prescaler选2，APB2选1。这样SYSCLK是72MHz，APB1是36MHz，APB2是72MHz。

在Configuration标签里，点USART1，NVIC Settings里勾上USART1 global interrupt。GPIO里把PC13的Output level设为Low，Mode设为Output Push Pull，Pull-up/Pull-down选No pull-up and no pull-down，Speed选Low。

Project Manager里，Project Name填个你喜欢的，Toolchain选STM32CubeIDE，Code Generator里勾上“Generate peripheral initialization as a pair of .c/.h files per peripheral”。点Generate Code。

4.2 添加RT-Thread源码并修改关键文件

把RT-Thread nano源码里的src、include、libcpu/arm/cortex-m3拷到工程目录下的RT-Thread文件夹。在CubeIDE里刷新工程，然后右键工程属性，C/C++ Build Settings，Tool Settings里MCU GCC Compiler的Include paths加上那三个路径。

在Source Location里，把RT-Thread/src和RT-Thread/libcpu/arm/cortex-m3添加为源文件夹。如果CubeIDE版本不支持直接添加，就在工程根目录的.cproject文件里手动加，或者用“New Folder”然后“Advanced”里链接到文件系统。

修改stm32f1xx_it.c，删掉SysTick_Handler和PendSV_Handler两个函数。如果编译报错说HAL_IncTick未定义，就在main.c里保留HAL_Init，但把SysTick中断的优先级设成最低，因为RT-Thread会接管。

在board.c里实现rt_hw_console_output：

void rt_hw_console_output(const char *str) { while (*str != '\0') { HAL_UART_Transmit(&huart1, (uint8_t *)str, 1, 1000); str++; } }

然后在rtconfig.h里打开RT_USING_CONSOLE和RT_USING_HEAP，把RT_HEAP_SIZE设为2048。

4.3 创建第一个闪烁线程并验证

在main.c里，包含rtthread.h，然后在main函数里调用rtthread_startup()。但rtthread_startup()会调用rt_application_init()，这个函数需要你实现。我在main.c里这样写：

#include "rtthread.h" #include "main.h" extern UART_HandleTypeDef huart1; static rt_thread_t led_thread = RT_NULL; static void led_thread_entry(void *parameter) { while (1) { HAL_GPIO_TogglePin(GPIOC, GPIO_PIN_13); rt_thread_mdelay(500); } } int main(void) { HAL_Init(); SystemClock_Config(); MX_GPIO_Init(); MX_USART1_UART_Init(); rt_thread_startup(led_thread); rt_system_scheduler_start(); return 0; }

但这样写有个问题：rt_thread_startup之前线程还没创建。正确的顺序是在main里先创建线程，再启动调度器。我改成：

int main(void) { HAL_Init(); SystemClock_Config(); MX_GPIO_Init(); MX_USART1_UART_Init(); led_thread = rt_thread_create("led", led_thread_entry, RT_NULL, 512, 20, 10); if (led_thread != RT_NULL) { rt_thread_startup(led_thread); } rt_system_scheduler_start(); return 0; }

编译下载，如果PC13的LED开始以1Hz频率闪烁，说明RT-Thread已经跑起来了。串口里应该能看到RT-Thread的启动logo，类似“\ | / - RT - Thread Operating System”的字符画。

实操心得：如果LED不闪，先检查SysTick_Handler是不是被RT-Thread接管了。你可以在rt_tick_increase()里加个计数器，用调试器看它有没有递增。如果没有，就是中断向量没对上。另外，HAL_Delay在RT-Thread启动后不能用了，因为它依赖SysTick中断，而那个中断已经被RT-Thread改写了。要用延时就用rt_thread_mdelay。

5. 常见问题排查与避坑指南

5.1 编译链接阶段的典型错误

HardFault是新手最容易遇到的。RT-Thread的PendSV中断优先级必须设为最低，SysTick的优先级也要低于其他外设中断。在CubeIDE里，NVIC的优先级数值越小优先级越高，所以PendSV和SysTick的Preemption Priority要设成15（最低）。

5.2 运行阶段的异常现象

LED闪烁频率不对，比如变成2Hz或者0.5Hz，通常是rt_thread_mdelay的参数理解错了。rt_thread_mdelay(500)是延时500个tick，如果RT_TICK_PER_SECOND是100，那就是5秒。想要500毫秒，应该写rt_thread_mdelay(50)。

串口输出乱码，检查波特率是否匹配，以及HAL_UART_Transmit的超时时间是否太短。如果系统tick很快，超时时间设1000可能不够，改成0xFFFF。

线程创建失败返回RT_NULL，多半是堆空间不够。把RT_HEAP_SIZE改大，或者改用静态线程rt_thread_init。

避坑技巧：在rtconfig.h里把RT_DEBUG打开，这样RT-Thread会在运行时检查参数合法性，出错时会调用rt_assert_handler，你能通过串口看到具体是哪个文件哪一行出了问题。虽然会增加一点代码量，但调试阶段非常值得。

5.3 调试器连接不上的处理

有时候下载完程序，ST-Link就连不上了，提示“Target not found”。这是因为程序一启动就进入了低功耗模式或者把SWD引脚复用了。检查你的代码里有没有把PA13和PA14配置成普通GPIO。CubeMX里SYS的Debug要选Serial Wire，这样它会保留SWD功能。

如果已经连不上，按住复位键，点下载，在松开复位的一瞬间程序开始下载，就能抢到连接。或者把BOOT0拉高，从系统存储器启动，这样芯片不会跑你的程序，ST-Link就能连上，然后擦除Flash。

6. 后续扩展与个人经验杂谈

6.1 从nano升级到完整版RT-Thread

nano版只有内核，没有设备框架和组件。如果你后续想用SPI、I2C的设备驱动，或者想加文件系统、网络协议栈，就得换成完整版。完整版的移植稍微复杂一点，需要实现rt_hw_board_init里的更多硬件初始化，还要配置设备驱动框架。

我的建议是：先用nano把任务调度跑通，理解线程创建、信号量、邮箱这些基本概念。等熟悉了，再换完整版。完整版的bsp目录里有现成的STM32模板，你可以参考它的board.c和drv_usart.c，把串口驱动注册到设备框架里，然后用rt_device_find和rt_device_open来操作串口，比直接调HAL库更规范。

6.2 中断优先级配置的深层逻辑

Cortex-M3的中断优先级寄存器是8位的，但STM32只用了高4位，所以优先级数值范围是0到15。RT-Thread要求PendSV和SysTick的优先级最低，是因为这两个中断负责任务切换和系统tick，如果它们的优先级高于其他中断，就会在中断嵌套时抢占其他中断，导致任务切换时机错乱。

具体配置：在HAL_Init之后，调用HAL_NVIC_SetPriority(PendSV_IRQn, 15, 0)和HAL_NVIC_SetPriority(SysTick_IRQn, 15, 0)。但RT-Thread的启动代码里已经做了这件事，你只需要确保CubeMX生成的NVIC配置没有覆盖它。在CubeMX的NVIC配置里，不要把PendSV和SysTick的优先级设得比15小。

6.3 我踩过的几个印象深刻的坑

第一个坑是串口重定向。我一开始用printf输出调试信息，结果程序跑着跑着就死机。后来发现printf不是线程安全的，多个线程同时调用会破坏栈。换成rt_kprintf后问题消失，因为RT-Thread对控制台输出做了互斥保护。

第二个坑是栈溢出检测。RT-Thread有个RT_USING_OVERFLOW_CHECK宏，打开后会在任务切换时检查栈魔数。我有个线程栈设了256字节，结果一跑就触发溢出检查。后来把栈加到512，问题解决。这个宏在调试阶段一定要打开，能帮你快速定位栈不够的线程。

第三个坑是Flash等待周期。F103跑72MHz时，Flash需要2个等待周期。CubeMX生成的SystemClock_Config里会自动设置，但如果你手动改时钟树，忘了改Flash Latency，程序会跑飞。检查HAL_RCC_ClockConfig里的FLASH_LATENCY_2参数。

6.4 一个实用的调试小技巧

在RT-Thread里，你可以用list_thread命令查看所有线程的状态、优先级、栈使用率。如果没加FinSH，也可以在代码里调用rt_thread_dump或者手动遍历线程链表。我习惯在串口里定期打印每个线程的栈剩余量，这样能提前发现栈快满的线程。

具体做法：在rtconfig.h里打开RT_USING_FINSH，然后在串口终端里输入list_thread，会输出类似：

thread pri status sp stack size max used left tick error -------- --- ------- ---------- ---------- ------ ---------- --- led 20 suspend 0x00000060 0x00000200 30% 0x0000000a 000 tidle 31 ready 0x00000080 0x00000100 50% 0x00000005 000

max used那一列就是栈使用峰值，如果超过80%，就该考虑加大栈了。

这套环境配置下来，从新建工程到LED闪烁，熟练的话20分钟能搞定。关键是理解每个步骤的目的，而不是机械地复制粘贴。遇到报错先看编译输出，再查RT-Thread的文档，大部分问题都能自己解决。