MAKEOVERRIDES：递归 make 中命令行变量如何保住最高优先级

接手这套多层 Makefile 项目的时候，我被一个诡异现象折磨了很久：顶层跑make TARGET_PLATFORM=arm all，结果编译产物还是 x86 的。把$(MAKEOVERRIDES)和$(origin ...)一行行打出来之后，才明白问题出在“命令行变量在递归 make 调用中如何维持最高优先级”这条暗线上。

标题里的$(MAKEOVERRIDES)是 GNU Make 内部维护的一个自动变量，绝大多数人平时根本碰不到它，但它决定了你从命令行传入的变量，在子 make 进程里还能不能继续拥有“一票否决权”。这篇文章不讲死板的变量手册，而是把它放在真实构建场景里拆开看：它为什么存在、什么时候生效、哪些坑会让它失效。

1. 从递归构建的传参痛点说起

1.1 一次真实的多层构建调试经历

我之前维护过一套分层编译系统，结构大概是这样的：

# 顶层 Makefile all: $(MAKE) -C driver build $(MAKE) -C app build # driver/Makefile CFLAGS_EXTRA ?= -O2 build: @echo "driver CFLAGS_EXTRA=$(CFLAGS_EXTRA) origin=$(origin CFLAGS_EXTRA)"

当时我要给驱动模块额外加一条编译宏，于是运行：

make CFLAGS_EXTRA="-DDEBUG_LEVEL=3 -O0" all

顶层倒是正常，可 driver 子目录打印出来依然是-O2，仿佛我的命令行参数被黑洞吸走了。随手翻 Makefile，发现CFLAGS_EXTRA ?= -O2这个写法本身没有错，问题是环境里根本没有把命令行变量的“身份信息”传到子 make 进程里。后来把 Makefile 改成下面这样打印，才看到真相：

$(info [top] MAKEOVERRIDES = $(MAKEOVERRIDES)) $(info [top] CFLAGS_EXTRA = $(CFLAGS_EXTRA) origin=$(origin CFLAGS_EXTRA))

顶层显示MAKEOVERRIDES = CFLAGS_EXTRA=-DDEBUG_LEVEL=3 -O0，说明 make 确实把我的命令行参数收进了这个特殊变量。但到 driver 子目录里一查，MAKEOVERRIDES已经变成了别的值，或者干脆被 Makefile 里某个unexport干掉了。这一下定位到了问题核心：命令行变量不会凭空传给子 make，它在递归调用时依赖 MAKEOVERRIDES 做一次“身份绑定”，子 make 才能继续把它当命令行覆盖变量处理。

1.2 MAKEOVERRIDES 在整个变量传递体系中的坐标

GNU Make 的变量来源很多，常见的有命令行、环境变量、makefile 内赋值、自动变量、内置默认变量。MAKEOVERRIDES 不是一个用来存业务数据的变量，它更像一张“清单”，记录的是：

这一次 make 启动时，用户通过命令行显式定义了哪些变量，完整定义长什么样。

比如你运行make FOO=bar BAZ=hello，make 内部就会维护一个类似FOO=bar BAZ=hello的清单，并放进MAKEOVERRIDES。这张清单会被导出到子进程环境中，子 make 启动时解析它，把里面每一项重新注册成“命令行变量”。

为什么不能直接把变量本身放进环境变量就完事？因为环境变量在 make 变量优先级里排名太低了，makefile 里随便一个普通赋值就能压过环境变量。直接留环境变量，子 make 一看CFLAGS_EXTRA已经存在了，会当成“环境来源的普通变量”，若子 Makefile 里有CFLAGS_EXTRA := ...，照样被覆盖。只有通过 MAKEOVERRIDES 重新注册为命令行变量，才能在子 make 里保住最高优先级。

2. 先搞懂 make 的变量优先级

2.1 命令行覆盖为什么有“最高优先级”

GNU Make 处理变量赋值时，内部有一套固定的优先级顺序，从高到低大致是：

1. 命令行变量（make VAR=value传进来的）
2. makefile 里的显式赋值（VAR = ...、VAR := ...等）
3. 环境变量
4. make 内置的默认变量（比如默认的CC=cc）

make CFLAGS_EXTRA="-O0"之所以能压过 Makefile 里的CFLAGS_EXTRA ?= -O2，就是因为第一层优先级对第四层有绝对优势。这个设计的初衷是：构建系统必须允许使用者临时修改参数，而不需要改任何文件。发布版本和调试版本之间来回切换，靠的就是这一条。

如果你不想让命令行参数进入某个变量，make 还给了override指令来强行“上诉”：

override CFLAGS_EXTRA = -O2

一旦 Makefile 里写了override，即便用户在命令行传了CFLAGS_EXTRA=-O0，最终生效的依然是-O2。这个机制同样和 MAKEOVERRIDES 有关系：子 make 里如果对同一个变量做了override，那条命令行变量传递链会在这一层被切断。

2.2 makefile 赋值、环境变量之间的微妙差距

很多人分不清“环境变量”和“命令行变量”，但在递归 make 场景里，这俩差别是致命的。

先看一个最容易踩的坑：

# 方式一：把变量放进环境 DEBUG=1 make all # 方式二：把变量放命令行 make DEBUG=1 all

表面上看都是“设置了 DEBUG=1”，但 make 对它们的处理完全不一样：

• DEBUG=1 make all：DEBUG 是环境变量，make 把它当作环境来源的变量。如果 Makefile 里写DEBUG = 0，Makefile 赋值会赢，最终结果是 0。
• make DEBUG=1 all：DEBUG 是命令行变量，优先级最高，Makefile 里写DEBUG = 0也压不住它。

递归到子 make 时，这个差异会被放大。环境变量这条路径，子 make 里的 Makefile 只要有一个普通赋值，你的“环境传参”就失效了。命令行变量这条路径，靠 MAKEOVERRIDES 维持身份，子 Makefile 里普通赋值依然压不住它。

我把这个结论写进上面那个案例后，driver 子目录的origin CFLAGS_EXTRA从environment变成了command line，一切就解释通了。

2.3 用 $(origin) 看清变量来源

排查变量优先级问题，我习惯先给临时调试目标加上$(origin ...)输出：

debug-vars: @echo "CFLAGS_EXTRA = $(CFLAGS_EXTRA)" @echo "CFLAGS_EXTRA origin = $(origin CFLAGS_EXTRA)" @echo "MAKEOVERRIDES = $(MAKEOVERRIDES)"

$(origin ...)会返回一串描述变量来源的关键字，我最关心的取值有这几个：

如果子 make 里看到origin = command line，说明 MAKEOVERRIDES 这条传递链工作正常；如果看到origin = environment或file，就要检查是不是有人在子 Makefile 里unexport或手动修改了 MAKEOVERRIDES。

3. MAKEOVERRIDES 内部运行机制拆解

3.1 顶层 make 启动子 make 时发生了什么

GNU Make 启动时，先解析命令行参数。所有KEY=VALUE形式的参数会被收集起来，有两件事同时发生：

1. 在当前 make 进程里，把这些变量注册为“命令行变量”，优先级最高；
2. 把它们拼成一个内部字符串，存入MAKEOVERRIDES，并且标记为要导出到子进程环境中。

等到 Makefile 里执行$(MAKE) -C driver build时，顶层 make 会 fork 一个子进程去执行新的 make，子进程环境里会携带两部分内容：

# 环境变量示例 MAKEOVERRIDES=CFLAGS_EXTRA=-DDEBUG_LEVEL=3 -O0 CFLAGS_EXTRA=-DDEBUG_LEVEL=3 -O0

注意，CFLAGS_EXTRA本身也在环境里。这是因为 GNU make 会把命令行变量自动导出，确保子进程能看到它。就算没有 MAKEOVERRIDES，子 make 也能从环境里看到这个变量，只是它会被当成“环境变量”，优先级掉落一格。有了 MAKEOVERRIDES，子 make 就知道：这个变量不是普通环境变量，而是父进程命令行上给的覆盖变量，我要重新把它放进命令行变量表。

所以完整链条是：命令行 → 顶层 MAKEOVERRIDES → 子进程环境 → 子 make 解析 MAKEOVERRIDES → 重新注册为命令行变量 → 子 Makefile 里任何普通赋值都压不过它。

3.2 子 make 是怎么把“环境变量”重新识别为“命令行变量”的

在子 make 启动阶段，它读取环境变量MAKEOVERRIDES，按空格拆分出若干条KEY=VALUE记录。这里有个细节，make 对特殊字符的转义处理很刁钻：如果值里有空格、#、反斜杠，它会用反斜杠转义后再放进 MAKEOVERRIDES。例如：

make CFLAGS="-DNAME=\"hello world\" -O2"

MAKEOVERRIDES 里实际可能是：

CFLAGS=-DNAME=\"hello\ world\" -O2

子 make 用自己的词法解析器去还原这些转义，而不是简单地把整条字符串交给 shell。这一步非常关键，因为有经验的工程师会在命令行传带空格的宏定义，如果只是按空格切割，整个定义就碎成好几块了。

解析完成后，子 make 把这些变量标记为“来自命令行”。你可以直接在子 Makefile 里验证：

$(info [sub] CFLAGS = $(CFLAGS)) $(info [sub] origin = $(origin CFLAGS))

看到origin = command line，说明 MAKEOVERRIDES 的“身份恢复”机制生效了。

3.3 与 MAKEFLAGS、MAKELEVEL 的分工边界

MAKEOVERRIDES 经常和MAKEFLAGS、MAKELEVEL放在一起讨论，因为它们都服务于递归 make，但职责完全不同。

• MAKEFLAGS（以及旧的MFLAGS）负责传“选项”，比如-j4、-k、--no-print-directory这类开关；
• MAKEOVERRIDES负责传“命令行变量定义”，只记录KEY=VALUE；
• MAKELEVEL记录当前递归深度，顶层是 0，往下每层加 1。

有一个历史渊源：早期 GNU Make 曾把命令行变量定义混在 MAKEFLAGS 里传输，结果问题很多。因为变量值里可能带空格、反斜杠、井号，MAKEFLAGS 本来的定位是选项标志，硬要塞FOO=bar baz这种内容会让解析复杂化。后来社区决定把变量定义单独拆到 MAKEOVERRIDES，MAKEFLAGS 就专心管选项了。

这三兄弟的分工我可以粗略类比成：MAKEFLAGS 是“启动参数清单”，MAKEOVERRIDES 是“业务配置清单”，MAKELEVEL 是“递归深度计”。你调试递归构建时，建议把三者一起打印出来看，很快就能知道某一层到底丢的是选项还是变量。

4. 实操案例：让它按预期工作

4.1 默认递归传参测试

我先给出一套最朴素的测试用例，方便你复现：

# 顶层 Makefile all: $(MAKE) -C sub # sub/Makefile MY_FLAG ?= default-value sub-target: @echo "MY_FLAG=$(MY_FLAG)" @echo "origin=$(origin MY_FLAG)"

执行：

make MY_FLAG=hello all

预期输出：

make -C sub make[1]: Entering directory '.../sub' MY_FLAG=hello origin=command line

这里origin=command line是关键证据。如果没有这层身份，sub/Makefile里的MY_FLAG ?= default-value虽然不会覆盖已定义变量，但一旦你改成MY_FLAG = default-value或MY_FLAG := default-value，结果就会变成 default-value，命令行的 hello 直接被丢弃。

我这段时间在多个项目里见过同一类 bug：顶层 Makefile 用$(MAKE) -C sub传递BUILD_MODE=release，子目录 Makefile 却是BUILD_MODE := debug，结果发布包里的模块有的是 debug 编译，有的 release 编译。这类混乱本质上就是没理解“环境变量和命令行变量的身份差异”，MAKEOVERRIDES 在中间扮演的角色至关重要。

4.2 带空格和特殊字符的变量值传递

命令行变量最麻烦的不是普通键值，而是带空格的值。比如我传过这样的编译参数：

make CFLAGS="-DDEBUG -DFEATURE_STR=\"hello world\"" all

MAKEOVERRIDES 里会变成类似：

CFLAGS=\"-DDEBUG\ -DFEATURE_STR=\\\"hello\ world\\\"\"

听上去很吓人，但对 GNU Make 来说这是它每天处理的正常内容。只要我不主动破坏 MAKEOVERRIDES，子 make 能正确还原：

# sub/Makefile sub-target: @echo "CFLAGS=$(CFLAGS)" @echo "origin=$(origin CFLAGS)"

输出应该还是完整的：

CFLAGS=-DDEBUG -DFEATURE_STR="hello world" origin=command line

如果这里出了问题，常见原因不是 make 解析失败，而是有人用 shell 脚本或者 Makefile 函数重新加工过 MAKEOVERRIDES，比如$(subst ...)替换空格、$(strip ...)去空白，转义信息一旦被破坏，子 make 就还原不出原始值了。

碰到这种场景，我的建议是：别手动解析 MAKEOVERRIDES，它内部格式是 GNU Make 私有约定，不同版本可能有细微差异。你要想干预传递，尽量用“追加”或“整体清空”这种粗粒度操作，不要去做细粒度字符串手术。

4.3 过滤/清空 MAKEOVERRIDES 的副作用

有些构建系统故意不想让命令行的所有变量都自动传下去。比如顶层 Makefile 里有一个内部变量，使用者不小心从命令行改了它，结果子目录也跟着变，导致不可预期的行为。

一种做法是递归调用时显式指定只传哪些变量：

build: $(MAKE) -C sub MY_FLAG=$(MY_FLAG)

这样MY_FLAG以子 make 命令行变量的形式传下去，其余命令行变量虽然也在环境里，但子 Makefile 里如果有同名普通赋值，会被 makefile 覆盖。这样做的好处是接口收窄，子目录只看到你愿意暴露的参数。

另一个更粗暴的做法是清空 MAKEOVERRIDES：

MAKEOVERRIDES := build: $(MAKE) -C sub

这个操作会切断命令行变量的“身份链”。子 make 依然能从环境里看到这些变量，但它们不再是命令行变量，而是普通环境变量。子 Makefile 里只要出现普通赋值，就会赢过环境变量。如果你的目标就是让子 make 不接受父进程命令行覆盖，这个写法是有效的，但同时也要注意副作用：子 make 里如果有人用?=运算符，环境变量不会被覆盖，所以一部分变量还是会残留下来。

我在实际项目里见过有人把MAKEOVERRIDES清空后，又奇怪为什么某些环境变量还能透传到子目录，其实这正是“环境变量默认继承”在起作用，而不是 MAKEOVERRIDES 的功劳。

4.4 make 找不到 Makefile 的求助信号

标题相关的热搜里有一条常见报错：“make: *** 没有指明目标并且找不到makefile”。这个报错表面上看和 MAKEOVERRIDES 没关系，但在递归构建场景里，它经常是变量传递链断裂的并发症。

例如顶层 Makefile 这样写：

all: $(MAKE) -C $(SUBDIR) build

如果SUBDIR这个变量被某层 Makefile 重新赋值成了空，或者因为unexport导致子 make 里读不到，就会变成：

make -C build make: -C: 选项需要一个参数

另一种情况是某个子目录根本没有对应 Makefile，但你传过去的变量里包含了错误的目录路径：

make ROOT_DIR=/wrong/path all

ROOT_DIR被 MAKEOVERRIDES 一路传到子 make，子 Makefile 里所有基于$(ROOT_DIR)的依赖路径全部指向错误目录，最终 make 在错误目录里找不到 Makefile。

排查这种问题，我的习惯是先把这条链路上的目录变量打出来：

$(info [debug] ROOT_DIR=$(ROOT_DIR) origin=$(origin ROOT_DIR)) $(info [debug] MAKEOVERRIDES=$(MAKEOVERRIDES))

一旦看到origin=command line，说明变量是命令行来的；如果看到origin=undefined，说明这一层根本没继承到。用这个思路很快就能区分是“变量没传到底”还是“目标目录本身就不存在”。

5. 调试和加固建议

5.1 常用的三条调试路径

面对 MAKEOVERRIDES 相关问题，我一般按下面三条路走：

第一，打印法。在顶层和子层各放一个调试目标，同时打印$(MAKEOVERRIDES)、$(origin VAR)、$(MAKELEVEL)。对比各层输出，就能看出变量在哪一层丢了“命令行身份”。

debug: @echo "level=$(MAKELEVEL)" @echo "MAKEOVERRIDES=$(MAKEOVERRIDES)" @echo "VAR=$(VAR) origin=$(origin VAR)"

注意在递归调用之前，$(MAKELEVEL)还是 0；进入子目录后是 1。如果子层 MAKEOVERRIDES 为空，说明这条链在父层就被切了。

第二，make -p数据库导出法。make -p会把当前 make 进程的完整数据库（包括所有变量值和来源）打印出来。我们可以配合临时限制目标来看：

make -p | grep -E "MAKEOVERRIDES|MY_FLAG|^origin"

输出会很长，建议先grep关键变量。我通常先跑顶层，再跑子层，对比差异。

第三，外部环境检查法。在子 make 启动前，往 Makefile 里临时插入$(shell echo "MAKEOVERRIDES=$$MAKEOVERRIDES" >&2)这种输出，看到子进程环境里 MAKEOVERRIDES 的真实值。这能排除“Makefile 内操作”和“进程环境”的差异。

5.2 大型项目中的变量传递治理

递归 make 本身是很多大项目不推荐的做法，因为变量传递不可控，构建路径一深就难以追踪。但现实是大量项目依然在用。既然躲不开，就要立几条规矩：

1. 优先用$(MAKE) -C sub VAR=$(VAR)显式传参，不要完全依赖 MAKEOVERRIDES 的自动传递。显式传参虽然啰嗦，但可读性最好，子 Makefile 一眼能看出接受哪些外部变量。
2. 子 Makefile 里给外部参数设默认值时，务必用?=，而不是=或:=。因为?=只对“未定义变量”生效，这样可以避免误覆盖环境变量；如果用户用命令行传入，优先级最高，?=同样不会压过它。
3. 不要轻易清空 MAKEOVERRIDES，除非你真的了解副作用。清空后子 make 不会把环境变量当作命令行变量，但环境里已有的同名变量依然会被继承，容易造成“一半传了，一半没传”的错觉。
4. 排查时先看origin再改值。改任何一个 Makefile 之前，先确认变量到底从哪来。命令行变量就该被尊重，环境变量则要看是否有 makefile 赋值在竞争。
5. 跨版本注意行为差异。GNU Make 的不同版本对 MAKEOVERRIDES 的细节处理有调整，比如转义方式、是否把某些特殊变量排除在外。如果你维护的是要跑在很多环境下的公共构建脚本，建议锁定一个最低 make 版本，并在文档里说明。

我在实际维护中最大的体会是：MAKEOVERRIDES 就像一个看不见的快递单，它记录的不仅是变量值，还有变量的“法律地位”。你在顶层命令行写下的每个VAR=value，都靠这张快递单穿越多层子 make，保证到货后依然带着命令行覆盖的免死金牌。理解了这一点，递归 make 传参的很多诡异现象都能解释清楚，排查起来也比以前快很多。