打开 CubeMX 生成的工程你会找到一个FreeRTOSConfig.h在 CubeMX 里对应FREERTOS → Config parameters。这个文件里密密麻麻几十个宏每个都控制着内核的一个开关或参数。新手通常的做法是全部保持默认能跑就行。直到某天任务起不来、或者 RAM 不够、或者栈溢出没报警才回头来翻这个文件。这篇把FreeRTOSConfig.h里真正会影响你工程的十几个配置项挑出来讲清楚每个填什么、填错的后果、F103C8 上的推荐值。这不是文档翻译而是哪些你必须懂、哪些可以忽略的实战指南。FreeRTOSConfig关键配置项分类一、配置项分四类先抓重点FreeRTOSConfig.h里的几十个宏按影响程度分四类类别重要度例子资源类决定吃多少 RAM/Flash⭐⭐⭐ 必懂堆大小、优先级数、最小栈安全类决定能不能及时发现问题⭐⭐⭐ 必懂栈溢出检测、各类 Hook功能开关决定哪些机制可用⭐⭐ 按需互斥量、任务通知、时间片内核细节一般不用动⭐ 看一眼Tick 配置、CPU 时钟宏下面逐类讲。所有推荐值针对F103C864K Flash / 20K RAM。二、资源类决定 RAM/Flash 用量这三个配置项直接决定 FreeRTOS 吃掉多少内存必须懂。1. configTOTAL_HEAP_SIZE —— 堆大小#define configTOTAL_HEAP_SIZE ((size_t)3072)作用heap_4 动态分配的堆大小。所有osThreadNew、osMessageQueueNew等动态创建都从这个堆里分。填小的后果任务/队列创建失败osThreadNew返回 NULL功能起不来。填大的后果挤占其它 RAM栈、全局变量严重时链接器报 region RAM overflow。F103C8 推荐值场景推荐值3~5 个轻量任务30723KB6~8 个任务 几个队列40964KB任务多、队列多不超过 6144否则 RAM 紧张怎么判断够不够用xPortGetMinimumEverFreeHeapSize()查堆历史最小剩余需开启configUSE_MALLOC_FAILED_HOOK/** * brief 查询堆剩余字节 * note 返回历史最小值说明堆最紧张时刻还剩多少 */ size_t free_heap xPortGetMinimumEverFreeHeapSize(); printf([HEAP] min free %u bytes\r\n, (unsigned)free_heap);经验堆剩余保持在总数的 20% 以上。低于 20% 说明快不够了要么加堆、要么减少任务。2. configMAX_PRIORITIES —— 最大优先级数#define configMAX_PRIORITIES 7作用任务可用的优先级数量。优先级范围是 0 ~ (MAX_PRIORITIES - 1)。填小的后果想给某任务高优先级时没档位可用任务都挤在低优先级实时性差。填大的后果每级优先级要维护一个就绪链表每级占一点 RAM几十字节。F103C8 上别超过 10。推荐7。对应 CMSIS-RTOS v2 的枚举档位Low/BelowNormal/Normal/AboveNormal/High/Realtime 等够用。注意这个数和 CMSIS-RTOS v2 的osPriority_t枚举值不是一回事。v2 枚举值是离散的大数字如 osPriorityNormal24内核内部会映射到 0~MAX_PRIORITIES-1 的连续范围。3. configMINIMAL_STACK_SIZE —— 空闲任务栈#define configMINIMAL_STACK_SIZE ((uint16_t)64)注意单位是字word不是字节64 字 256 字节。作用空闲任务Idle Task和定时器服务任务的栈大小。这俩任务由内核自动创建栈也由这个宏决定。填小的后果空闲任务栈溢出。如果你在空闲钩子里干了点活比如统计、喂看门狗更容易溢出。填大的后果浪费 RAM两个任务都按这个值共两份。F103C8 推荐64 字256 字节。如果空闲钩子里有 printf加到 128 字512 字节。这是 FreeRTOS 为数不多的以字为单位的配置和osThreadAttr_t.stack_size字节不同容易搞混。记住configMINIMAL_STACK_SIZE是字osThreadNew的 stack_size 是字节。三、安全类开发期必开这两个能在出问题时第一时间告诉你开发阶段绝不能省。4. configCHECK_FOR_STACK_OVERFLOW —— 栈溢出检测#define configCHECK_FOR_STACK_OVERFLOW 2作用0关 / 1快检 / 2严检第 07 篇详解过。开发期必开 2。检测到溢出会调用vApplicationStackOverflowHook你可以在里面复位或记录。为什么有人量产关掉怕增加 CPU 开销。但实测开销极小每次任务切换检查一次量产也建议保持开启比产品现场死机强。5. configUSE_MALLOC_FAILED_HOOK —— 堆分配失败钩子#define configUSE_MALLOC_FAILED_HOOK 1作用当 heap_4 分配失败堆不够时内核调用vApplicationMallocFailedHook。为什么重要任务创建失败时如果你没检查osThreadNew返回值问题会变成某个功能莫名其妙不工作极难定位。开这个钩子分配失败立刻报警。实现钩子/** * brief 堆分配失败钩子 * details 当 configTOTAL_HEAP_SIZE 不够、动态分配失败时被调用。 * 说明堆太小或任务/队列创建过多。 * note 开发期在此打印诊断信息量产可记录后复位。 */ void vApplicationMallocFailedHook(void) { printf([FATAL] Heap alloc failed! configTOTAL_HEAP_SIZE too small?\r\n); /* 可在此打印当前堆剩余辅助定位 */ }黄金组合configCHECK_FOR_STACK_OVERFLOW2configUSE_MALLOC_FAILED_HOOK1能覆盖 80% 的 RTOS 内存类 bug。四、功能开关按需启用这些开关控制 FreeRTOS 的各种同步/通信机制。用到哪个开哪个不用的关掉省 Flash。宏作用默认建议configUSE_MUTEXES互斥量含优先级继承1用就开configUSE_RECURSIVE_MUTEXES递归互斥量1不用可关省点 FlashconfigUSE_COUNTING_SEMAPHORES计数信号量1不用可关configUSE_TASK_NOTIFICATIONS任务通知轻量同步1强烈建议开本系列第三系列主讲configUSE_QUEUE_SETS队列集0多源事件才开configUSE_TIMERS软件定时器1用就开需配configTIMER_TASK_STACK_DEPTHconfigUSE_PREEMPTION抢占式调度1几乎总是开第 13 篇细讲configUSE_TIME_SLICING同优先级时间片轮转1几乎总是开第 14 篇细讲configUSE_IDLE_HOOK空闲钩子0需要时开第 18 篇细讲configUSE_TICK_HOOKTick 钩子0需要时开关掉不用的功能能省多少 Flash粗略参考关掉项约省 Flash递归互斥量1~2KB计数信号量1KB队列集1~2KBF103C8 有 64K FlashHAL 库吃掉一大半能省就省。建议一开始全开保证功能功能稳定后逐个关闭确认无影响省出 Flash 空间。五、内核细节看一眼即可这些通常 CubeMX 会帮你配好但你要看得懂。6. configTICK_RATE_HZ —— Tick 频率#define configTICK_RATE_HZ 1000作用每秒多少个 Tick。本系列固定10001ms 一个 Tick。• 填小如 100osDelay 精度变 10ms省点 CPUTick 中断少了但实时性下降• 填大如 10000精度到 0.1ms但 Tick 中断太频繁CPU 开销上升。1000 是大多数项目的平衡点。7. configMAX_SYSCALL_INTERRUPT_PRIORITY —— 系统调用中断上限#define configMAX_SYSCALL_INTERRUPT_PRIORITY 5作用只有优先级数值 ≥ 这个值的中断才能调用FromISR系列 API带系统调用的中断。这是 FreeRTOS 的中断安全机制核心。这个非常重要但容易搞反本系列第三系列中断篇会专门讲。这里只需记住数值大 优先级低ARM Cortex-M 的反直觉规则。设成 5意思是优先级 515 的中断才能调 ISR API04 的高优先级中断不能调。填错的后果要么高优先级中断调 API 导致崩溃要么所有中断都不能调 API。8. configCPU_CLOCK_HZ 和 configSYSTICK_CLOCK_HZ#define configCPU_CLOCK_HZ 72000000ULCubeMX 根据时钟树自动填72MHz。一般不用手动改。六、一个综合配置清单F103C8 推荐起步值把上面汇总成一张表新建 F103C8 工程时直接照着设配置项推荐值说明configTOTAL_HEAP_SIZE30723KB 堆起步按需加configMAX_PRIORITIES7够用configMINIMAL_STACK_SIZE64 (字)空闲/定时器任务栈256字节configCHECK_FOR_STACK_OVERFLOW2严检configUSE_MALLOC_FAILED_HOOK1开configUSE_MUTEXES1开configUSE_TASK_NOTIFICATIONS1开configUSE_TIMERS1开configUSE_PREEMPTION1抢占式configUSE_TIME_SLICING1时间片configUSE_IDLE_HOOK1开用于低功耗/统计configTICK_RATE_HZ10001ms 精度configMAX_SYSCALL_INTERRUPT_PRIORITY5ISR 安全上限Memory schemeheap_4动态分配带合并在 CubeMX 里设置这些在Middleware → FREERTOS → Config parameters里都能找到对应项。CubeMX 改完后重新生成代码会自动更新FreeRTOSConfig.h。重要不要直接手动改FreeRTOSConfig.h因为下次 CubeMX 重新生成会覆盖你的修改。所有配置改动都要在 CubeMX 界面里做。CubeMX 会在文件里标注/* USER CODE BEGIN *//* USER CODE END */区域只有这些区域里的手改才不会被覆盖。七、验证打印配置确认生效写一个小任务启动后打印当前关键配置确认 CubeMX 的设置真的生效了/** * file config_check.c * brief 打印当前 FreeRTOS 配置确认生效 * date 2026-07-15 * version V1.0 - 初版创建 */ #include cmsis_os2.h #include stdio.h /** * brief 配置自检任务 * details 打印内核版本、tick 频率、当前任务数确认环境正确 */ static void ConfigCheckTask(void *argument) { (void)argument; for (;;) { printf( FreeRTOS Config \r\n); printf(Tick freq : %lu Hz\r\n, (unsigned long)osKernelGetTickFreq()); printf(Kernel state : %d\r\n, (int)osKernelGetState()); printf(Current tick : %lu\r\n, (unsigned long)osKernelGetTickCount()); printf(Heap min free: %u bytes\r\n, (unsigned)xPortGetMinimumEverFreeHeapSize()); printf(\r\n); osDelay(5000); } }串口结果 FreeRTOS Config Tick freq : 1000 Hz Kernel state : 2 Current tick : 5000 Heap min free: 1432 bytes 串口设置USART1115200-8-N-1。观察点1.Tick freq 1000确认configTICK_RATE_HZ1000生效2.Kernel state 2即osKernelRunning说明调度器在跑3.Heap min free 1432说明堆 3072 里历史最少剩 1432用了约 1640余量充足。如果Heap min free很小如只剩几十字节说明堆快不够要加大configTOTAL_HEAP_SIZE。八、本篇要点回顾1.FreeRTOSConfig.h几十个宏重点抓三类资源类堆/优先级/栈、安全类栈溢出检测/堆失败钩子、功能开关。2.资源类configTOTAL_HEAP_SIZEF103C8 起步 3KB、configMAX_PRIORITIES7、configMINIMAL_STACK_SIZE64 字。3.安全类configCHECK_FOR_STACK_OVERFLOW2、configUSE_MALLOC_FAILED_HOOK1开发期必开。4.功能开关用哪个开哪个不用的递归互斥量、队列集可关省 Flash。5.改配置必须在 CubeMX 界面改不要手改 FreeRTOSConfig.h会被重新生成覆盖。6. 用xPortGetMinimumEverFreeHeapSize监控堆剩余低于 20% 要警惕。总结FreeRTOS 的强大与灵活很大程度来自这个配置文件。理解了这十几个关键宏你就能针对 F103C8 的资源约束做精准裁剪——既能保证功能完整又不会被默认值浪费宝贵的 RAM/Flash。