make: No rule to make target 报错速查
更新时间：2026-10-24。FAQ 速查页，面向在 Linux/macOS 上用 GNU make 构建 C/C++（或其他）工程的同学。make: No rule to make target 是 makefile 报错里出现频率最高的一条：make 想造某个目标，翻遍所有规则都找不到能产出它的办法，只能停机。报错本身信息量不大，但引号里那个目标名就是全部线索——它是目标拼写错了、依赖的文件真不存在、路径写岔了、VPATH 没搜到、规则压根没写、还是自动生成的
.d文件里残留了已删头文件，六根轴顺一遍基本必中。本篇以报错原文为锚逐条定位；如果是链接阶段报undefined reference，请转 undefined reference 链接错误速查；CMake 连编译器都找不到的看 CMake 找不到编译器速查。
本文要回答的问题
No rule to make target 'xxx', needed by 'yyy'里两个名字分别是什么角色？- 文件明明在目录里，make 为什么还说没有规则？
- VPATH/vpath 的搜索顺序会怎样悄悄改变报错内容？
- 自动生成依赖的
.d文件为什么会在删了头文件之后炸出这条错？ - 怎么一条命令让 make 自己承认「我真的搜不到」？
一、报错原文与典型现象
报错固定长这样（工程路径以 /proj/demo 占位）：
$ make
cc -c -o build/main.o src/main.c
make: *** No rule to make target 'src/util.h', needed by 'build/main.o'. Stop.或者目标名直接打错时：
$ make cleen
make: *** No rule to make target 'cleen'. Stop.还有一种变体是缺了 needed by 尾巴——说明这个目标是你命令行上直接点名要的（比如 make install 而 makefile 里没写 install 规则），不是被谁依赖出来的。读懂引号里的名字和 needed by 的指向，是选排查分支的第一步：前者是「造不出来的东西」，后者是「谁需要它」。
二、病因处置速查表
| 报错现象 / 场景 | 可能原因 | 快速验证 | 处置 |
|---|---|---|---|
make cleen 之类目标名报错 | 命令行目标名拼写错误 | make -n <目标> 或翻 makefile 目标列表 | 改对目标名；make help（若定义）看可用目标 |
报 'src/foo.h', needed by ... | 依赖的源/头文件被删或改名 | ls src/foo.h 确认不存在 | 恢复文件，或从规则/.d 里删掉该依赖 |
| 文件在但目录层级写错 | 相对路径相对的是 make 启动目录 | make -w 看工作目录，ls <报错路径> | 按报错路径修正规则里的路径 |
大小写差一个字母（Util.h vs util.h） | 大小写敏感文件系统不匹配 | ls src/ 逐一比对大小写 | 统一大小写；macOS 默认大小写不敏感，上 Linux 才炸 |
| 源文件在别的目录，靠 VPATH 找 | VPATH/vpath 没包含该目录或顺序不对 | make -p 看 VPATH 实际值 | 补 VPATH 目录或改用 vpath 按模式指定 |
报 'build/foo.o' 造不出来 | 对应规则没写 / 模式规则不匹配 | make -n build/foo.o 空跑看能否展开 | 补规则，或检查模式规则的词干是否匹配 |
| 删了头文件后整库报这条 | .d 自动依赖文件残留旧头文件条目 | grep 旧头文件 build/*.d 有命中 | 删掉过期 .d 后重新生成，规则里加 -MP |
| 项目重命名/移动目录后批量报错 | makefile 里写死的绝对路径失效 | grep -n 旧路径 Makefile | 改用变量与相对路径，清理重编 |
三、排查决策图
下面这张图是按报错原文分岔的标准路线，颜色按角色区分：红是报错入口与命中的根因，蓝是排查动作，绿是通过分支，橙是修复动作，紫是防复发沉淀。
读这张图抓住一个分水岭：先对报错引号里的名字跑 ls。文件不存在（左支）是事实层问题——拼写、删除、大小写，跟规则无关；文件存在（右支）才轮到 make 的搜索机制——VPATH 没搜到、模式规则不匹配、.d 文件给了过期情报。两边修法完全不同，混着修会来回空转。
四、逐条排查展开
第一步：把报错引号里的名字当文件路径去 ls。 这是最快的分档动作：
ls src/util.h
# ls: cannot access 'src/util.h': No such file or directory不存在就直接进左支。先查拼写：命令行目标名打错（make cleen 想敲 clean）是最低级也最常见的一种，make 对命令行给的目标名不做任何猜测，直接报 No rule。再查文件是否被删或改名——比如同事把 util.h 重构拆成了 util_base.h 和 util_io.h，而旧的 .o 规则或 .d 文件还引用老名字。
大小写是跨平台协作的暗坑。 macOS 与 Windows 默认文件系统大小写不敏感，#include "Util.h" 引用 util.h 在 Mac 上编得好好的，提交到 Linux CI 上立刻 No rule to make target。确认办法是 ls src/ 把真实文件名打出来逐一比对，修法是统一全小写命名并全库替换。
文件存在时，轮到 make 的搜索机制。 用 make -p 或空跑看它到底怎么找：
make -p | grep '^VPATH'
# VPATH = src:include
make -n build/foo.o
# 空跑若能展开出编译命令，说明规则在；否则规则缺失或模式不匹配VPATH 是 make 的「依赖文件搜索路径」：规则里写 foo.o: foo.c，而 foo.c 实际在 src/ 下时，make 会沿 VPATH 逐目录找。VPATH 没包含 src/、或目录顺序把同名文件引向了错误的那份，都会报 No rule。多个目录各放一类文件时，用 vpath %.c src 按模式指定比一个大 VPATH 更可控。模式规则不匹配也很常见：写了 %.o: %.c 但源文件后缀是 .cpp、或词干对不上（目标 build/foo.o 而源文件在 src/foo.c，隐含规则不会自动跨目录），就得显式写 $(BUILD)/%.o: $(SRC)/%.c 这样的模式规则。
.d 残留是「我什么都没改怎么炸了」的标准答案。 现代 makefile 常用编译器的 -MMD 自动生成头文件依赖（每个 .o 配一个 .d），再 include 进来。一旦你删了某个头文件，旧 .d 里还写着 build/main.o: src/util.h，make 发现 util.h 不存在、又没有规则能造它，就报 No rule to make target。处置是删掉过期 .d（或干脆 make clean）重新生成；根治是在编译参数里加 -MP——它给每个头文件生成一条空规则，头文件消失时 make 走空规则而不是报错。
改完先空跑再真编。 make -n（或 --dry-run）只打印将执行的命令不真跑，是验证规则修复的最小闭环；空跑能展开出完整编译序列，再 make 全量构建就是顺理成章的事。
五、规范做法与预防
- 路径一律走变量：
SRC := src、BUILD := build，规则里只写$(SRC)/foo.c，改目录结构只动一行。 - 自动依赖必加
-MP：-MMD -MP成对出现，从根上消灭「删头文件炸 No rule」这一类。 - 目标名给 help 兜底：定义
help目标列出可用目标，减少命令行拼写错误。 - 文件名全小写：跨平台项目强制小写文件名，规避大小写敏感差异。
- clean 做得彻底：
make clean连同.d一起删，避免过期依赖文件跨构建存活。 - CI 跑一遍 Linux 构建：大小写与路径分隔问题在 Mac 上不可见，Linux CI 是最便宜的照妖镜。
这一篇在知识体系里的位置
本篇是 Makefile 排错速查簇的入口篇，定位「make 在展开规则阶段就失败」：目标与依赖找不到看本篇；编译过了、链接阶段报符号找不到的看 undefined reference 链接错误速查；用 CMake 生成构建系统、配置阶段就报找不到编译器的看 CMake 找不到编译器速查。make -n、make -p、ls 三件排查套在所有 make 系报错间完全通用。
一句话总结
make: No rule to make target 先对报错引号里的名字跑 ls 分档：文件不存在是事实层——改对目标名拼写、恢复被删文件、统一大小写、按 make 工作目录修相对路径；文件存在是搜索层——make -p 查 VPATH 与模式规则是否覆盖该目标，删掉引用已删头文件的过期 .d 并在编译参数里加 -MP 根治；修完 make -n 空跑复验再全量构建。路径变量化、自动依赖加 -MP、clean 连 .d 一起清、Linux CI 兜底，这条报错即可基本绝迹。