如果你维护过手写 Makefile 的 C/C++ 嵌入式工程，下面这两句话你一定不陌生：“我明明改了头文件，怎么一点反应都没有？”以及“串行编得好好的，一开 -j 就随机炸”。这俩症状凑在一起，基本能断定：工程的依赖信息没有真正进入构建系统，或者进入的方式根本经不起并行。我在一个嵌入式交叉编译项目上就被这么折腾过整整一轮，从“本地能编”到“并行必挂”，中间踩过的坑几乎可以写成一本书。今天不绕弯子，把四个核心问题逐个拆开，从症状、根因、修复代码到排查思路完整复盘一遍，建议手写构建脚本的朋友直接对照检查。

1. 先别急着背锅：两个症状背后是同一套账

1.1 “改了 .h 不重编”的前因后果

很多人以为编译器会“自动发现”头文件变化，这是一个非常大的误会。Make 这类增量构建工具并不看文件内容，它只看目标和先决条件的时间戳：当目标文件比任何一个先决条件旧，就执行规则重新生成目标；如果目标比所有依赖都新，就跳过。

问题就在这里。如果你的编译规则写的是：

main.o: main.c $(CC) $(CFLAGS) -c main.c -o $@

那么 Make 判定main.o是否需要重建的时候，只检查main.c的时间戳，头文件根本不在依赖列表里。你改了main.h，Make 完全不知道，自然认为main.o还是最新的。这种“改了 .h 不重编”的根因，不是编译器坏了，也不是 Make 傻了，而是依赖信息缺失。

更隐蔽的情况是：你手动写了一堆头文件依赖：

main.o: main.c main.h config.h $(CC) $(CFLAGS) -c main.c -o $@

今天没问题，但明天你新加了一个debug.h，并把它 include 进main.c，却忘了更新规则。Make 依然不知道debug.h的存在，于是“改头文件不重编”再次出现。手动维护头文件列表在工程文件少的阶段还能撑，一旦源文件变成几十个，必然出错。所以正确做法不是“别忘”，而是让编译器自己生成依赖文件，再让构建系统把这些依赖信息吃进去。

1.2 “-j 一开就炸”的炸弹埋在依赖关系里

make -j8的本质是多任务调度，Make 会按照依赖关系构造一个有向无环图：只有当一个目标的全部先决条件都完成后，才执行这个目标的规则。听起来很完美，但前提是“依赖关系完整”。

如果缺少头文件依赖，并行时的影响可不是“少一次重编”那么简单。比如有两个源文件a.c和b.c都 include 了同一个头文件，你改了头文件后跑make -j8。理论上只有依赖到这个头文件的.o需要重建，但依赖信息缺失时，a.o重建了，b.o因为根本没记录头文件依赖而被跳过。于是你得到一份“半新半旧”的产物，轻则行为怪异，重则直接链接失败。

除了依赖缺失，并行还会放大另一个问题：构建规则之间共享资源的竞争。比如多个编译任务同时需要创建同一个输出目录，或者多个子项目同时调用同一个归档工具，稍有不慎就会出现随机性故障。这也是为什么很多人发现“串行稳如狗，一开 -j 就翻车”。本质不是 -j 本身有毒，而是你的依赖描述太粗糙，经不起并发调度。

2. 四个坑挨个复盘：每个都值得一次复盘

2.1 坑一：依赖文件没进 Makefile，头文件被当成空气

这个坑是最经典的，症状就是标题里的“改了 .h 不重编”。我先说最原始的写法，很多人一开始都是这么写的：

OBJS := main.o utils.o main.o: main.c $(CC) $(CFLAGS) -c main.c -o $@ utils.o: utils.c utils.h $(CC) $(CFLAGS) -c utils.c -o $@

看着没毛病，编译能过，但头文件列表全靠手动维护。更致命的是，如果某个.c文件 include 了一堆头文件，你大概率会漏掉其中一两个。漏掉的那个头文件一旦被修改，Make 永远不知道要重建。

我的修复方案是让编译器在编译的同时生成依赖文件，并且把这些依赖文件纳入 Makefile：

CFLAGS += -MMD -MP %.o: %.c $(CC) $(CFLAGS) -c $< -o $@

这里的关键是-MMD和-MP两个参数。-MMD会在编译时额外生成一个与目标同名的.d文件，内容类似：

main.o: main.c main.h config.h

也就是说，依赖信息是编译器根据实际 include 情况自动生成的，你不需要手动维护。-MP则会给每个头文件生成一个伪目标，比如：

main.h:

这样做的意义在于：当你把某个头文件删掉，而旧的.d文件里还留有它的记录时，Make 不会报“No rule to make target”并中断，而是把它当成一个没有规则的普通目标跳过，避免“删个没用的头文件导致整个工程编不了”。

有了.d文件还不够，你必须把这些依赖文件在 Makefile 里 include 进来：

DEPS := $(OBJS:.o=.d) -include $(DEPS)

注意这里要用-include而不是include。因为第一次全量编译时，.d文件还不存在，-include会静默忽略不存在的文件，而include会直接报错。这一步做完，“改头文件不重编”的根上问题才算解决。

注意：-MMD只会排除系统头文件，不会排除你的项目头文件。如果你的工程里有第三方头文件也希望参与依赖追踪，可以用-MD而不是-MMD。差别就在第一个 M 上，实际使用时要根据项目需要选。

2.2 坑二：并行编译遇上了“裸奔”的中间目录

这个坑通常不是一上来就发生的，而是工程从“单目录”扩展到“多目录”之后突然爆发。比如源文件在src/下，目标文件输出到build/obj/，编译规则里顺手写了创建目录的逻辑：

build/obj/%.o: src/%.c mkdir -p build/obj $(CC) $(CFLAGS) -c $< -o $@

单线程编译时，这个mkdir -p基本不会出问题，因为规则是一条一条顺序执行的。但当你make -j8时，多个编译任务会同时触发mkdir -p build/obj。虽然大多数平台的mkdir -p在目录已经存在时会静默成功，但某些环境下这种并发调用依然可能产生竞态，而且这还只是表层问题。

真正麻烦的是跨层目录。假设src/sub/deep/file.c对应的输出是build/obj/sub/deep/file.o，你在规则里只mkdir -p build/obj，那么并行时file.o的输出父目录build/obj/sub/deep/可能还没被创建，于是编译直接失败。这种失败还是随机性的：有时候目录先创建好了，编译通过；有时候任务调度顺序一变，就炸了。

一个更优雅的解法是 order-only 前置依赖。普通前置依赖会影响时间戳判断，目标比依赖旧就重建；而 order-only 前置依赖只保证“依赖先执行”，不参与时间戳比较。写法是竖线后面的目标：

build/obj: mkdir -p $@ build/obj/%.o: src/%.c | build/obj $(CC) $(CFLAGS) -c $< -o $@

这样每个.o规则都依赖build/obj先创建，但不会被目录的时间戳干扰。对于多级目录，还需要在规则内部再补一个mkdir -p $(dir $@)：

build/obj/%.o: src/%.c | build/obj @mkdir -p $(dir $@) $(CC) $(CFLAGS) -c $< -o $@

因为 order-only 只保证了最上层目录存在，不能保证每一层二级目录都存在，$(dir $@)的作用就是把当前目标文件所在的具体目录也创建出来。加上mkdir -p是幂等操作，即使在并行环境下重复执行，也不会造成严重后果。

2.3 坑三：隐式规则与变量污染，把环境变成黑盒

有些工程看起来没写编译规则，却能编过，靠的是 Make 的内置隐式规则。比如 Make 知道%.o: %.c这个模式，会默认用$(CC) $(CPPFLAGS) $(CFLAGS) -c来生成.o。但这套隐式规则只包含源文件依赖，不包含任何头文件依赖。所以你一旦依赖隐式规则，又不显式生成依赖文件，“改 .h 不重编”依然存在。

隐式规则本身没问题，怕的是你对它“半懂不懂”。比如你看着工程能编译，就以为 Make 帮你管理了所有依赖，其实它只完成了最基础的动作，根本没有建立依赖图。我的建议是：不管内置规则多省事，只要是想长期维护的工程，都要显式写出编译规则，并且把依赖生成放进去。隐式规则可以留着给那些你确实不想管的目标用，但主要产物不要依赖它。

变量污染是另一个更隐蔽的问题。很多人喜欢在 Makefile 开头写：

CFLAGS = -Os -Wall

这里用的=是普通赋值，它会在定义时覆盖环境变量或上层传入的 CFLAGS。这通常没问题，但反过来，如果你想让使用者从命令行临时调整编译参数，比如：

make CFLAGS="-O2 -g"

命令行变量会覆盖 Makefile 里的普通赋值，这没问题。麻烦的是?=这种写法：

CFLAGS ?= -Os -Wall

?=的意思是“如果变量没有被定义过，才赋予这个值”。如果 CI 环境里恰好导出了一个 CFLAGS，这个外部值就会静默地替代你的工程默认值。头文件路径不对、编译选项不同、优化级别改变，最后整套构建行为变成黑盒。

我的习惯是把“用户可调的开关”和“内部固定的配置”分开。用户可调的用?=，比如：

BUILD_DIR ?= build OPT ?= -Os CROSS_COMPILE ?= arm-none-eabi-

内部必须一致的用:=，并且不暴露成通用名：

CC := $(CROSS_COMPILE)gcc CFLAGS := -Iinclude -Wall -O2

这样用户能改的只有少数开关，核心编译选项不会被环境变量凭空污染。如果必须允许用户传 CFLAGS，就显式给变量命名，比如PROJECT_CFLAGS，不要直接复用 CFLAGS 这个被各种工具链盯上的通用变量。

2.4 坑四：清理、伪目标和输出日志，细节连着炸

这个坑通常排在最后爆发，因为你前面几个坑都填完以后，工程看起来能编了，但“长时间维护”的问题开始冒头。

第一个细节是.PHONY。Make 里的clean只是一个普通目标，如果当前目录恰好有个叫clean的文件，Make 会认为这个目标已经存在且不需要更新，直接跳过，于是make clean什么也不干。同理，all如果碰到了同名文件，也会出现莫名“Everything is up to date”。正确做法是把所有非文件目标全部声明为伪目标：

.PHONY: all clean distclean

第二个细节是清理不彻底。很多人的clean只删了.o和最终产物，忘了删.d依赖文件。旧的.d文件如果描述的是一个老版本的头文件集合，而目标.o因为某种原因没被重建，这个过期依赖会一直残留，导致后续每次增量编译都得到错误结论。最稳妥的办法是直接删整个构建目录：

clean: rm -rf $(BUILD_DIR)

把所有中间产物、依赖文件和最终产物一次清干净，避免脏文件“赖账”。

第三个细节是并行输出日志。make -j8会同时跑多条编译命令，如果每个命令都直接往 stdout 打印，日志会被切碎。明明有编译错误，但错误信息夹在大量输出中间，很难定位。GNU Make 提供了输出同步功能，最常用的是：

make -j8 --output-sync=recurse

也可以把每个编译任务的日志重定向到独立文件，最后统一汇总。比如：

%.o: %.c $(CC) $(CFLAGS) -c $< -o $@ > $@.log 2>&1

这样每个对象的日志互不干扰，失败时再单独看对应日志。虽然略显啰嗦，在 CI 里排查问题时会省很多时间。

3. 实操落地：一版抗住 -j8 的手写构建脚本

3.1 先定目录和变量，避免全局散养

好的构建脚本应当先想清楚“东西放哪”，而不是让中间产物散落在源码目录里。我常用的布局是：

project/ ├── Makefile ├── src/ │ ├── main.c │ └── drivers/ │ ├── uart.c │ └── gpio.c ├── include/ │ ├── board.h │ └── driver.h └── build/ ├── obj/ └── bin/

所有编译产物统一放到build/下，源码目录保持干净。这样clean直接删目录就行，也方便 CI 把整个构建目录当作缓存或临时区域处理。

变量部分，我会区分“用户可以覆盖”和“内部固定”：

BUILD_DIR ?= build OPT ?= -Os CROSS_COMPILE ?= arm-none-eabi- CC := $(CROSS_COMPILE)gcc AR := $(CROSS_COMPILE)ar CFLAGS := -Wall -Wextra -mcpu=cortex-m4 -mthumb $(OPT) CPPFLAGS := -Iinclude -I$(BUILD_DIR)/gen LDFLAGS := -Tlink.ld

BUILD_DIR、OPT、CROSS_COMPILE用?=，方便在命令行或环境中调整；CC、CFLAGS等内部变量用:=固定，避免被同名环境变量污染。

3.2 依赖生成三板斧：-MMD、-MP、-include

接下来是核心逻辑。假设你要把src/main.c、src/drivers/uart.c编译到build/obj/下，目标文件路径要保持相对结构，方便同名源文件共存：

SRCS := $(shell find src -name '*.c') OBJS := $(patsubst src/%.c,$(BUILD_DIR)/obj/%.o,$(SRCS)) DEPS := $(OBJS:.o=.d)

编译规则要同时完成“编译”和“生成依赖文件”两件事：

$(BUILD_DIR)/obj/%.o: src/%.c @mkdir -p $(dir $@) $(CC) $(CPPFLAGS) $(CFLAGS) -MMD -MP -MT $@ -MF $(@:.o=.d) -c $< -o $@

这里拆开解释一下工具链参数：

• -MMD：编译时生成依赖信息，排除系统头文件；
• -MP：为每个头文件生成伪目标，避免删头文件后 Make 报缺失目标错误；
• -MT $@：告诉编译器依赖文件里的目标是当前这个.o的完整路径，防止 .d 文件里写的目标和实际目标不一致；
• -MF $(@:.o=.d)：把生成的依赖文件放到与.o同目录下，只是后缀换成.d，例如build/obj/src/main.d。

然后在 Makefile 底部把所有依赖文件加载进来：

-include $(DEPS)

这样 Make 每次运行时，都能看到src/main.c到底 include 了哪些头文件。头文件的时间戳一变，相关.o就会自动进入重建队列。

3.3 并行安全的关键写法：order-only 与预建目录

上面的规则里用了@mkdir -p $(dir $@)，这句在并行下基本都是安全的，因为mkdir -p幂等。但为了更稳妥，我还会配合 order-only 依赖先把顶层目录建好：

$(BUILD_DIR): mkdir -p $(BUILD_DIR)/obj $(BUILD_DIR)/obj/%.o: src/%.c | $(BUILD_DIR) @mkdir -p $(dir $@) $(CC) $(CPPFLAGS) $(CFLAGS) -MMD -MP -MT $@ -MF $(@:.o=.d) -c $< -o $@

竖线后面的$(BUILD_DIR)是 order-only 先决条件。它保证在开始编译之前build/目录一定存在，但目录本身的时间戳变化不会触发.o重建。配合规则内的$(dir $@)，可以覆盖所有层级目录。

链接规则不需要并行，反而必须等所有.o都完成：

$(BUILD_DIR)/bin/app.elf: $(OBJS) @mkdir -p $(dir $@) $(CC) $(LDFLAGS) $^ -o $@ $(LIBS)

只要app.elf依赖了全部OBJS，Make 就会等所有.o编译完成后再执行链接。这里不要画蛇添足地加-j，链接阶段本身不依赖并行，而且并行链接多个产物反而容易触发资源竞争。

全部拼起来之后，一个最小可复现的完整 Makefile 长这样：

BUILD_DIR ?= build OPT ?= -Os CROSS_COMPILE ?= arm-none-eabi- CC := $(CROSS_COMPILE)gcc CFLAGS := -Wall -Wextra $(OPT) CPPFLAGS := -Iinclude SRCS := $(shell find src -name '*.c') OBJS := $(patsubst src/%.c,$(BUILD_DIR)/obj/%.o,$(SRCS)) DEPS := $(OBJS:.o=.d) all: $(BUILD_DIR)/bin/app.elf $(BUILD_DIR): mkdir -p $(BUILD_DIR)/obj $(BUILD_DIR)/obj/%.o: src/%.c | $(BUILD_DIR) @mkdir -p $(dir $@) $(CC) $(CPPFLAGS) $(CFLAGS) -MMD -MP -MT $@ -MF $(@:.o=.d) -c $< -o $@ $(BUILD_DIR)/bin/app.elf: $(OBJS) @mkdir -p $(dir $@) $(CC) $(CFLAGS) $^ -o $@ .PHONY: all clean clean: rm -rf $(BUILD_DIR) -include $(DEPS)

这套脚本我用在嵌入式裸机工程上，make -j8反复全量编译、增量编译都没问题。

3.4 增量验证清单，每次改动按这个走

脚本写完之后，我建议做一轮系统验证，不要停留在“能编过”这个层面。以下是我的固定测试流程：

1. 全量编译一次：make clean && make -j8，确认干净环境下可以构建。
2. 再次执行make -j8，确认没有任何重建动作。
3. 修改某一个头文件，执行make -j8，确认只有真正 include 了它的.o被重建。
4. 删除某个已经被 include 的头文件，执行make -j8，确认不会因为缺失目标文件而报错。
5. 修改编译选项，比如把OPT从-Os改成-O2，执行make -j8，确认旧产物没有“赖着不更新”。

这里最容易被忽略的是第五点。Make 本身不追踪变量变化，它的视野里只有文件时间戳。如果你改了 CFLAGS 但目标文件比源文件新，Make 会认为不需要重编。这不是因为依赖文件没用，而是构建系统不感知变量变化。工程小的时候手动 clean 就行；工程大了，可以把编译选项写进一个生成的头文件或者构建配置，让源文件依赖它，让依赖链自动捕捉配置变化。

4. 排查实录：我遇到过的典型问题与解法

4.1 问题速查表：照着症状配药

4.2 排查心法：先证明“全量能编”，再谈增量

遇到“改了 .h 不重编”或者“-j 一开就炸”这类问题，我最常用的排查顺序是先做两个对照实验。

第一，跑一次绝对干净的全量编译：

make clean && make -j1

如果这一步都失败，问题多半在工具链或源文件本身，和依赖关系无关。全量能过之后，再跑：

make clean && make -j8

这一步用来确认“并行问题”是不是必然复现。如果全量并行能过，但增量并行炸了，那基本锁定是依赖信息缺失或目录创建时序问题。如果全量并行本身就随机失败，重点看共享资源竞争和输出目录逻辑。

第二步是检查 Make 实际执行了哪些规则。可以用：

make -n

看“预测执行”的命令顺序；也可以加--debug=b输出 Make 的决策日志，从中能找到“该重建却没重建”的目标。先证明全量能编，再谈增量，能帮你把“构建脚本问题”和“源代码问题”快速分开。

4.3 一次典型的“改头文件没重编”定位过程

我印象最深的一次问题复盘，症状非常典型：改了一个公共头文件board.h，编译结果里只有一部分.o重编了，另一个模块app_bsp.o纹丝不动。我先检查app_bsp.d，发现里面确实没有board.h。也就是说，编译器生成的依赖信息没有覆盖到这个头文件。

但源码里明明 include 了board.h，为什么不生成依赖？后来发现，app_bsp.o是更早之前、在没有开启-MMD参数时编译出来的，对应的.d文件是一个旧版本。由于 Make 认为app_bsp.o已经是最新，就不会重新编译，自然也不会更新.d。这个过期的依赖信息从此“赖”在构建目录里，每次增量编译都沿用旧结论。

make clean之后全新编译，再改board.h，才恢复正常。这给我的教训是：依赖生成机制加入工程之后，必须配合一次干净的全量重建，否则旧的.d文件会继续产生误导。所以我在所有工程的clean里都直接删除整个构建目录，绝不让旧依赖文件有“续命”的机会。

另一个排查技巧是：如果怀疑依赖信息不完整，不要只盯着最新改的那个文件，而是把所有.d文件拉出来看一遍。比如：

find build -name '*.d' | xargs grep "board.h"

哪些对象依赖了board.h，一眼就能看清楚。如果某个应该重建的.o没有出现在结果里，基本可以判定它的.d文件缺失或过期。

5. 最后想说两句大实话

构建系统是个“不爆发问题就没人在意”的东西，但真到了-j一开就炸的时候，往往不是一两句命令能救回来的。从我自己的实践来看，手写 Makefile 完全能做到并行安全，前提是别和编译器对着干：头文件依赖交给-MMD/-MP生成，目录创建交给 order-only 前置依赖，输出日志用make -O` 统一，clean 直接把整个构建目录删掉。

最后再分享一个小技巧：如果你第一次引入依赖生成功能，记得在提交信息里写清楚“需要 clean 后重建”，不然同事还在用旧的构建目录跑增量，那些过期的.d文件会让他们以为脚本没生效。构建脚本的价值不在于“能编”，而在于“能稳定地重新编”，能讲清楚每一次重编的理由，才算真正把这些坑填完了。