搞嵌入式的人，尤其是从STM32阵营跳到HC32L13x之后，十有八九会遇到这样一个场景：从某方手里接过一份Keil工程，按下编译按钮，屏幕上排山倒海飘过一整屏error: identifier "__WEAK" is undefined，而且光标还正好停在一堆中断函数定义上。我当初第一次看到这个报错时，第一反应是系统里是不是装了一个假的ARM编译器。后来查了一圈才明白，__WEAK根本不是编译器内置的绝对文法，而是CMSIS头文件里根据编译器类型定义出来的一个宏。Keil不认它的原因，大多数可以归结为“这个宏压根没进入编译单元”。
这篇文章就顺着HC32L13x这个具体场景，把Keil编译报错__WEAK不识别这件事从头到尾讲透。你会看到弱符号在中断函数定义里扮演什么角色、报错通常分哪几种形态、最可能的根因是什么、以及一套可以直接抄走的中断函数定义模板。不管你是刚拿到小华/华大半导体的板子，还是做工程迁移时被AC5切AC6折腾得头疼，照着下面的思路排查，基本都能解决。
1. 先看清楚你遇到的是哪种报错：__WEAK未定义的三张面孔
很多人一看到报错就急着改代码，其实同样的“__WEAK未定义”在Keil里会以不同形态出现，形态不同，指向的根因也不同。先别急着改，停下来看两样东西：报错出现在哪个文件，以及报错是只有一处还是满屏都是。
1.1 最常见形态：单个C文件里冒出的 error: #20
如果你用的是ARM Compiler 5（AC5），最典型的输出长这样：
Build target 'Target 1' compiling user_code.c... ..\USER\user_code.c(61): error: #20: identifier "__WEAK" is undefined __WEAK void TIM0_IRQHandler(void) ^ Target not created.注意两个细节。第一，报错的物理位置在你的C文件里，而不是SDK库文件里，这说明Keil在编译这个C文件时，从头到尾没有见过__WEAK这个符号。第二，报错紧挨着的是中断函数定义那一行，如果这个文件里还有其他__WEAK，会跟着一起报错，行号不同，本质相同。
换到ARM Compiler 6（AC6）下，报错文风会变得直接一些：
error: use of undeclared identifier '__WEAK'信息量一样，只是编译器换了“说话方式”。遇到这种单点报错，优先级最高的怀疑对象就是：这个C文件缺少对CMSIS核心头文件的包含，或者包含链路径断了。
1.2 满屏报错：Include Paths 路径失效
如果报错不只在你自己的C文件里，连SDK自带的hc32l13x_gpio.c、hc32l13x_timer.c这些文件也一起报，问题就基本不在单个文件了，而是整个工程的Include Paths没有正确指向SDK头文件目录。
这种情况我见过最多的是：工程压缩包发给别人、换了一台电脑、或者整个工程目录被挪到了别的层级，Keil工程文件里保存的相对路径就失效了。你打开魔术棒（Options for Target）里的C/C++选项卡，看到的还是..\Libraries\...这种相对路径，但实际目录结构变了，Keil找不到，于是报错。
1.3 高版本编译器才报：工程迁移的典型症状
还有一种很有意思的场景：同一个工程，在别人的电脑上用AC5编译一切正常，你拿到手用Keil默认的AC6一编，__WEAK不认识了。问题不在头文件，而在SDK版本太老，老版本的CMSIS头文件里对AC6的编译器识别分支不完善，压根没定义__WEAK这个宏。
这种现象在做工程迁移、升级编译器版本时非常常见。所以判断根因之前，先确认你当前用的Compiler版本是什么。Options for Target -> Target -> ARM Compiler里能看到下拉框，AC5和AC6的世界观不太一样。
提示：编译报错和链接报错是两码事。如果报错信息是
undefined symbol XXX_IRQHandler，那是链接器找不到函数定义；而identifier "__WEAK" is undefined是编译器根本不认识这个标识符。两者排查路径完全不同，别混着来。
2. __WEAK为什么会在中断函数定义里出现？它到底是不是编译器语法
在解决问题之前，很有必要搞清楚__WEAK为什么会在HC32L13x的SDK里成片出现。它不是某个工程师的恶趣味，而是嵌入式C里一个非常经典的“弱符号”设计。
2.1 弱符号：一个“可以被覆盖”的函数声明
弱符号（weak symbol）可以理解为：链接时，如果存在一个强符号（普通函数定义）和它重名，链接器直接采用强符号；如果强符号不存在，弱符号就作为默认兜底实现保留下来。
单片机中断处理非常依赖这个机制。SDK库文件里会写一堆默认的中断服务函数，比如：
__WEAK void TIM0_IRQHandler(void) { // 默认什么都不做，等待用户覆盖 }你拿到工程后，在自己的业务代码里同样定义一个void TIM0_IRQHandler(void)，不用修改SDK源码，不用删除任何文件，链接器就会自动把你的强函数“顶替”掉SDK里的弱函数。这样一来，中断触发后CPU跳进的是你的代码，而SDK自带的那个空实现就被丢弃了。
用大白话理解：弱函数是一个自带“欢迎覆盖”标签的默认工位，谁强谁上位。这个设计让芯片厂商可以把整个外设驱动库做得完整、可编译、可运行，同时把中断响应的最终决定权留给用户。
2.2 从启动文件到IRQHandler：HC32L13x的中断处理链路
HC32L13x是基于Cortex-M0+内核的MCU，它中断处理的完整链路是从启动文件开始的。芯片上电后，启动文件startup_hc32l13x.s（具体文件名以你拿到的SDK为准）里会初始化栈指针、调用SystemInit，然后填充一张中断向量表。这张向量表里每一项都对应一个中断源，直接或间接指向对应的IRQHandler函数。
从向量表到用户代码，大概是这样的路径：
- 外设触发中断请求。
- CPU根据中断号查向量表，拿到IRQHandler的入口地址。
- 如果用户代码里定义了同名强函数，向量表拿到的地址就是用户函数的地址。
- 如果用户没有定义，向量表拿到的是SDK弱函数的地址，中断会跳进一个空的默认实现，看起来就是“中断没反应”。
所以当你发现某个外设中断不生效时，很多时候不是没使能，而是你的强函数没有真正覆盖SDK的弱函数。后面第5章会专门讲怎么验证覆盖是否成功。
2.3 CMSIS里__WEAK的“身世”：宏，不是关键字
这里要澄清一个基本概念：__WEAK不是C标准关键字，也不是ARM编译器内置语法，它是CMSIS头文件里定义的一个宏。以core_cm0plus.h这类CMSIS核心头文件为例，里面的代码逻辑一般是这样的：
#if defined ( __CC_ARM ) #define __WEAK __attribute__((weak)) #elif defined(__ARMCC_VERSION) && (__ARMCC_VERSION >= 6010050) #define __WEAK __attribute__((weak)) #elif defined ( __GNUC__ ) #define __WEAK __attribute__((weak)) #elif defined ( __ICCARM__ ) #define __WEAK __weak #endif如果编译器是ARMCC，__WEAK最终等价于__attribute__((weak))；如果是IAR，等价于__weak。看到这里你就明白了：如果core_cm0plus.h没有被包含进编译单元，或者这个宏定义所在的分支没有匹配上当前的编译器环境，那么__WEAK在编译器眼里就是一个彻头彻尾的未知标识符，报“未定义”理所应当。
另一个容易踩的坑是：很多人在自己的C文件里也跟着SDK写__WEAK void XXX_IRQHandler(void)，但自己的文件根本没有包含SDK的主头文件，于是直接触发报错。而且说句实在话，用户业务代码里需要写__WEAK的场景非常少——SDK已经把弱函数定义好了，你只需要写不带__WEAK的强函数就够了。
3. 根因排查：为什么Keil偏偏不认这个关键字
报错形态和背景知识都有了，接下来就进入排查环节。我按出现频率从高到低，把可能导致__WEAK不识别的原因拆成四个。
3.1 根因一：文件里缺少对SDK主头文件的包含
这是最常见、也最好修的一种。新建的main.c、user_code.c或者其他模块文件，顶部写满了“看起来够用”的头文件，但唯独漏了hc32l13x.h或者ddl.h这种总入口头文件。__WEAK的定义藏在CMSIS核心头文件里，而CMSIS核心头文件通常是被hc32l13x.h间接包含进来的。没有这一层层包含链，__WEAK自然就不存在。
处理方式很简单：在文件头部补上：
#include "hc32l13x.h"如果你用的是厂商的完整驱动库，有的SDK会提供一个总入口ddl.h，里面把所有外设驱动头文件都包了一层，那你包含ddl.h也可以。
3.2 根因二：Include Paths 路径丢失或配置不全
单文件缺头文件属于“点”的问题，而Include Paths属于“面”的问题。如果工程里很多文件同时报__WEAK未定义，或者你明明写了#include "hc32l13x.h"但编译还是报错，优先怀疑编译器的头文件搜索路径根本没走到。
在Keil里排查路径的固定动作是：
- 点击魔术棒图标，打开Options for Target。
- 切到 C/C++ 选项卡（AC6下叫 Arm Compiler）。
- 找到 Include Paths 右侧的 “...” 按钮。
- 检查列表里有没有包含SDK的CMSIS目录、Device目录、以及DDL库的inc目录。
一个HC32L13x工程，典型的Include Paths里至少会有这几个方向：
..\Libraries\CMSIS\Include ..\Libraries\Device\HC32L13x\Include ..\Libraries\HC32L13x_DDL\inc具体文件夹名以你SDK包实际情况为准，但思路是固定的：找到所有带.h文件的目录，把它们加进来。移动过工程目录、或者从压缩包解压到不同层级导致相对路径失效，是很常见的诱因。
还有一种比较隐蔽的情况：Include Paths里带了中文路径或者特殊字符。绝大多数时候Keil能忍，但偶尔就会冒出来一些你完全想不到的结果，编程器都检查不出所以然。遇到诡异的编译问题，第一件事就是把整个工程挪到纯英文路径下再试一次，这个习惯能帮你排除掉大量玄学问题。
3.3 根因三：AC5切换到AC6，老SDK没跟上
AC5切AC6触发__WEAK不识别，本质上是CMSIS头文件对编译器版本的识别逻辑没匹配上。老版本SDK的CMSIS里，往往用#if defined (__CC_ARM)来判定ARMCC环境，这在AC5时代没问题。但AC6下编译器不再默认定义__CC_ARM，而是采用__ARMCC_VERSION这种版本号宏来标识自己。如果SDK里的CMSIS核心文件版本太老，没有针对AC6的分支判断，__WEAK就完全没有被定义。
判断方法很简单：在报错的C文件里，把光标放在__WEAK上，右键选择 Go To Definition，如果跳不过去，或者全局搜索#define __WEAK找不到任何定义，那基本就是这情况。
解决办法有三个方向：
- 升级SDK包里的CMSIS核心文件，换成支持AC6的版本；
- 临时把编译器切回AC5，保住工程进度；
- 在自己的业务代码或者一个公共头文件里，手动补上
__WEAK的宏定义兜底。
第三种方法虽然不够优雅，但作为应急处理完全没有问题。我会在下一章给你一个更彻底的替代写法。
3.4 根因四：把__WEAK写在了不适合的位置
最后一个原因来自写法本身。__WEAK本质是编译属性，不是普通的函数修饰符。有人把它写在返回类型和函数名中间、有人把它放在语句块内部、还有人把它用在局部变量上，这些用法都可能造成编译器解析出错。虽然报错内容不一定都是__WEAK undefined，但排查方向要涵盖这种情况。
另外，如果文件后缀不是.c而是.cpp，编译器会走C++的解析规则，CMSIS头文件对C++的兼容性又是一个单独话题。HC32L13x这种MCU项目里C++用得少，但也不是没有，如果确认是C++源文件，建议单独处理，不要一刀切。
下面这张表汇总了几种情况，方便快速对照：
| 现象 | 根因方向 | 首选排查动作 |
|---|---|---|
| 单独某个文件报错 | 该文件没包含SDK主头文件 | 补#include "hc32l13x.h" |
| 满屏报错、SDK文件也报 | Include Paths失效 | 检查魔术棒里的头文件路径 |
| 旧工程切换AC6后报错 | CMSIS版本对AC6不兼容 | 升级CMSIS，或临时切回AC5 |
| 报错在奇怪的位置 | __WEAK被当普通修饰符乱放 | 改成规范的函数前声明 |
4. 四种解法，从一行代码到工程级配置
找到根因之后，解决方案就是水到渠成的事了。我按从简单到彻底、从应急到治本的顺序，给你四种解法，你可以按情况选择。
4.1 第一招：立即在文件顶部补上SDK头文件
这是最快、最直接的方法，针对的就是3.1那种缺包含的场景：
#include "hc32l13x.h"如果你用的是厂商完整驱动库，也可以包含总入口：
#include "ddl.h"加完重新编译，报错大概率就消失了。但这个方法只解决“点”上的问题，如果整个工程还有别的地方也有类似问题，你还需要往下一招走。
4.2 第二招：绕过__WEAK宏，直接用编译器的原生写法
__WEAK既然是个宏，那就存在被覆盖、被误定义、或者在某些环境下根本没定义的可能。为了彻底摆脱对宏的依赖，你可以直接用编译器原生支持的弱属性写法：
__attribute__((weak)) void TIM0_IRQHandler(void) { }这个写法对ARMCC 5、ARMCC 6都有效，因为__WEAK宏最终展开出来就是这个东西。实测下来，它对头文件是否包含没有任何依赖，只要编译器支持GNU风格的attribute就能编过。
如果你想写上更保险一点，还可以组合used属性，防止链接器做垃圾回收时把弱函数裁掉：
__attribute__((weak, used)) void TIM0_IRQHandler(void) { }这在AC6工程里尤其有用。AC6默认情况下可能开启--gc-sections，未被引用的section会被丢弃，如果某个弱函数既没被强符号覆盖，又没有被向量表引用，就可能被优化掉。used属性的作用就是告诉编译器：这个符号即使看起来没有被引用，也要保留。
4.3 第三招：修正Include Paths，一次性根治
如果你的问题属于工程级路径配置，那诸如“在文件里补include”和“换属性写法”都只是缓解症状，真正需要做的是把编译器的头文件搜索路径修正到位。
具体步骤再强调一遍：
- 打开Options for Target。
- 切到 C/C++ 选项卡（AC6下叫 Arm Compiler）。
- 找到 Include Paths。
- 把SDK的CMSIS、Device、DDL头文件目录全部加入。
加完之后，可以做一个“验尸级”确认：在Build Output窗口里选择“完整编译命令行”模式，重新编译一次，你会看到类似这样的输出：
armclang -c --cpu Cortex-M0+ -I..\Libraries\CMSIS\Include -I..\Libraries\Device\HC32L13x\Include ...看到-I参数后面跟着的路径都指向真实存在的目录，说明配置生效了。这一步虽然看起来笨，但能排查掉绝大多数因为路径失效导致的编译问题。
小技巧：如果工程是多人协作的，尽量在Keil的Include Paths里使用相对路径，并约定大家的工程目录结构一致。否则每换一个人，都得重新配一次路径，非常痛苦。
4.4 第四招：升级SDK/CMSIS，或者临时切回原编译器版本
如果是AC5切AC6引起的兼容性问题，最理想的办法是升级SDK里的CMSIS核心文件。你可以直接去ARM官网下载新版CMSIS包，替换掉工程里旧版本的core_cm0plus.h以及对应该芯片的Device头文件。替换之前注意备份，别把整个SDK换坏了。
如果项目进度不允许你在编译器切换上花太多时间，临时把编译器切回AC5，保证编译链跑通，也是一种务实选择。等后续有时间了，再专门做编译器的平滑迁移。
我个人推荐的组合是：第一招加第三招。一个解决单点缺包含，一个解决全局路径配置，两者配合，基本能覆盖90%以上的HC32L13x工程场景。第二招作为保底方案，适合被头文件依赖折磨到想摔鼠标的时候直接用。
5. HC32L13x中断函数定义的正确姿势：从报错到稳定运行
报错解决之后，更核心的问题来了：HC32L13x的中断函数到底该怎么定义，才能保证中断稳定运行、不出幺蛾子。这一章我按实际操作顺序，带你从看清SDK结构一直走到验证中断触发。
5.1 先确认你该在IRQHandler层干活，还是在Callback层干活
HC32L13x SDK里的中断处理，和很多Cortex-M内核的MCU一样，分两种模式。
第一种是直接操作IRQHandler。启动文件的中断向量直接指向XXX_IRQHandler，SDK提供了空实现，用户写同名强函数覆盖。这种模式下，中断触发后直接进入你的代码，所有逻辑由你接管。
第二种是SDK内部的Callback机制。SDK已经实现了XXX_IRQHandler实体，并在内部根据中断状态挂回调函数指针，用户通过API注册自己的回调函数。这种模式下，如果你再去定义一个同名XXX_IRQHandler强函数，表面看编译能过，但实际上把SDK的中断分发逻辑整个替换掉了，之前注册的回调可能全部失效。
区分方法特别简单：去SDK源码里搜索你的外设XXX_IRQHandler定义，看看函数体是空的，还是里面已经调用了回调函数指针。如果是空的，直接重写IRQHandler；如果里面有分发逻辑，老老实实注册回调。
5.2 用户中断函数的完整代码模板
以一个GPIO外部中断为例，正确写法是这样的：
#include "hc32l13x.h" #include "hc32l13x_gpio.h" volatile uint8_t g_key_pressed = 0; void PORT0_IRQHandler(void) { if (GPIO_GetIrqFlag(PORT0, PIN00)) { GPIO_ClearIrqFlag(PORT0, PIN00); g_key_pressed = 1; } }这里有三个关键点。
第一，函数名必须和SDK里的弱函数完全一致，一个字母都不能差。大小写、下划线位置都会影响覆盖是否成功。最靠谱的做法是去启动文件或者SDK源码里复制确切的函数名，而不是凭记忆手打。
第二，不要加static。加了static之后，函数的作用域被限制在当前文件，链接器无法在全局符号表中用它去覆盖弱函数。结果就是：编译不报错，链接也不报错，但中断根本没进你的函数，SDK的那个空实现依然在“兜底”。
第三，中断函数体里尽量只做三件事：读中断状态、清中断标志、置一个全局标志位。不要在中断里做耗时操作，尤其不要用printf，不要做浮点运算。Cortex-M0+没有硬件浮点，一个浮点计算在中断里可能吃掉几十微秒，这对实时性要求高的系统是灾难。
5.3 初始化外设中断和NVIC的完整流程
中断函数定义好了还不够，你得让中断真正能触发。HC32L13x的初始化流程，通常分四步：
- 配置GPIO或者外设的工作模式。
- 配置外设的中断触发条件。
- 调用外设级中断使能函数。
- 调用NVIC对应的中断使能函数。
以GPIO按键中断为例，示意代码如下（API名称以你用的SDK版本为准）：
void KeyIrqInit(void) { stc_gpio_config_t stcCfg; MEM_ZERO_STRUCT(stcCfg); stcCfg.u16Dir = PIN_AIN; // 配置为输入 GPIO_Init(PORT0, PIN00, &stcCfg); GPIO_EnableIrq(PORT0, PIN00, GPIO_IRQ_RISING); // 上升沿触发 NVIC_ClearPendingIRQ(PORT0_IRQn); // 清挂起 NVIC_EnableIRQ(PORT0_IRQn); // 使能NVIC中断 }NVIC_ClearPendingIRQ这步很多人会忽略，但强烈建议保留。因为如果之前在调试、复位过程中已经产生过一次中断挂起，不提前清掉，一使能中断就会立刻进一次中断，表现就是“中断自己乱跳”。
5.4 中断不生效的几个常见坑
编译过了、代码也写了，但中断就是不执行，这类问题在MCU调试里非常典型。我把见过最多的情况整理成一个表：
| 现象 | 原因 | 解决办法 |
|---|---|---|
| 中断完全没反应 | 函数名拼错，强符号没覆盖弱符号 | 去启动文件/SDK源码复制函数名 |
| 中断没反应，且函数加了static | 符号局部化，链接器无法覆盖 | 去掉static |
| 链接报duplicate symbol | 工程里存在两个同名的强函数定义 | 检查哪些文件定义了同名的IRQHandler |
| 中断进去了，但反复触发 | 中断标志没有清除 | 在中断里调用清标志位的API |
| 中断里定义了变量，调试器看不到更新 | 全局标志没有用volatile修饰 | 加volatile uint8_t g_flag |
最后一行值得多说一句：中断函数里修改的全局变量，如果没加volatile，在某些优化等级下，编译器可能把变量缓存在寄存器里，主循环读到的还是旧值。嵌入式里“全局变量必须加volatile”这个规则，在中断和主线程通信的场景下几乎是铁律。
6. 我在这类问题里踩过的坑和总结的排查习惯
代码能编译、中断能触发，并不代表万事大吉。有些问题真的只会出现在你工程跑起来之后、板子开始“薛定谔地”工作的时候。下面这些经验是我在HC32L13x项目实战中积攒下来的，可能比报错本身的解决方案更有价值。
6.1 用Map文件确认弱符号覆盖是否成功
这是一个很容易被忽略但极其有效的动作。编译通过之后，打开工程输出目录下的.map文件，搜索你的IRQHandler名字。如果强符号覆盖成功，你会看到类似这样的内容：
PORT0_IRQHandler 0x000003a1 Thumb Code 42 user_code.o(.text)这个地址是用户代码段里的地址，说明你的函数确实进入了最终链接结果。如果你的函数名在Map文件里只有SDK库文件里的那个空实现地址，或者地址非常靠前、明显不在用户代码区，那就要警惕：中断仍然会跳进SDK默认的空函数，你的强函数可能因为各种原因没有覆盖成功。
Map文件还能帮你发现一个隐蔽问题：如果你在工程里不小心定义了两个同名的强函数，Map文件里只保留了一个，另一个会静默丢弃。这种“编译不报错、行为不对”的场景，靠Map文件一眼就能看穿。
6.2 通过反汇编验证中断入口
如果你还是不放心，可以在Keil里进Debug模式，打开Disassembly窗口，找到IRQHandler的入口，看它的汇编代码。
SDK默认的空弱函数，反汇编通常只有一两句，比如直接把寄存器恢复然后bx lr，函数体基本是空的。而你自己写的强函数，反汇编会看到实际处理逻辑，比如读标志寄存器、写清除位、更新内存变量。这个手段能帮你绕过所有中间层的怀疑，直接确认CPU到底跳进了哪里。
6.3 中断里真的别放大活
这一点前面已经提过，但值得再强调一次。在HC32L13x上，GPIO中断频率不高还好，如果是定时器中断、串口接收中断这类高频中断，一个不小心就会把CPU时间吃光。常规的做法是把中断函数当“闹钟”用——只负责标记事件，真正耗时的数据处理全部丢给主循环去消费。
我见过一个真实的翻车案例：有人在UART接收中断里直接处理一帧完整协议，还调用了很多阻塞型库函数，结果波特率一提高，串口直接丢失数据，从中断里跳出来后程序已经乱套。把接收数据丢进环形缓冲区、在主循环解析，才是更稳的架构。
6.4 把中断函数统一集中到一个文件里，方便复用
最后一个建议比较偏工程习惯。我会把用户自定义的IRQHandler强函数全部集中放在一个独立的文件中，比如叫it_user.c，文件顶部固定包含SDK主头文件，下面的函数一个接一个排好。
好处很明显：工程升级SDK包时，受影响的文件只有这一个，不会散落到各个模块源文件里；新同事接手项目，看中断处理逻辑也只需要打开这一个文件，不用在整个工程里翻来找去。另外，当你从HC32L13x迁移到其他芯片时，这个文件就是最核心的移植参考，直接复制过去，把函数名和寄存器操作换成新平台的API，就能省掉不少工作量。
我现在的习惯是，所有IRQHandler强函数文件里都不会再出现__WEAK这几个字母。SDK已经帮用户留好了弱符号的默认位置，用户只需要把自己的强函数放进去就够了。回到最开始的编译报错，其实它就是一道开胃菜，逼着我们去把弱符号、中断向量、Include Paths这些基础概念重新过一遍。把这些基本功练扎实了，后续再遇到其他Keil编译问题，心态就会稳很多。
