C 预处理器

是什么，为什么存在

C 预处理器读取源文件，在正式编译前处理以 # 引导的 预处理指令 。#include 引入文件内容，#if 选择保留的词元，#define 创建 宏 。预处理器不理解 C 对象的类型、作用域或运行时值。

预处理解决的是编译前的组合与配置问题。公共声明可以放在头文件中，平台适配层可以在构建时选择实现，重复的词元模式也可以由宏生成。你会在库的公共头文件、构建系统传入的 -D 定义、日志和断言封装、平台检测代码中遇到它。

「文本替换」是方便的近似说法，但不够精确。宏按预处理词元工作，不会替换字符串字面量内部的字符，也不会随意拼接出半个词元。# 和 ## 有专门的字符串化与词元粘贴规则。

预处理器的输出仍不是可执行程序。一个 .c 文件经过包含和宏替换后形成 翻译单元 ，随后才由编译器检查声明、类型与表达式，再交给汇编和链接步骤。用 gcc -E 可以观察这个边界。

工作原理

下面的流程只画出理解日常代码所需的边界。标准规定多项翻译阶段；实现可以合并这些阶段，只要结果符合规定。

指令出现之前

反斜杠紧接换行会先把两行拼成一个逻辑行。源字符随后被识别为预处理词元和空白，每条注释在这个过程中替换为一个空格。因此，多行宏末尾的反斜杠后面不能夹入会阻止拼接的字符。

预处理指令中的 # 必须是逻辑行上的第一个预处理词元，前面可以有空白。指令只控制预处理阶段；在普通 C 语句块里缩进 #if 不会让它变成运行时 if。被条件指令排除的组不会进入后续编译。

#include 使实现找到指定文件，并把它当作该指令处的输入继续处理。双引号形式与尖括号形式使用不同的实现定义搜索序列；具体目录来自编译器默认值和 -I 等选项，不能仅凭标点推断任意工具链的完整路径。

对象式宏与函数式宏

对象式宏在名称出现时替换为其替换列表。函数式宏只有在宏名后跟调用括号时才展开，形参接收的是实参词元序列，不是已经带有 C 类型的值。

普通形参在代入替换列表前会先完成宏展开。形参若紧邻 # 或 ##，这一轮不会先展开，所以字符串化已展开值通常需要一层间接宏。替换结果还会重新扫描，允许新出现的宏名继续展开。

正在展开的宏会在这次扫描的相应位置暂时禁止再次替换。这条规则阻止直接或间接自引用无限递归，但残留的宏名往往会形成无效 C 代码。宏递归不是通用的循环机制。

条件指令与定义状态

#ifdef NAME 只询问名称是否已定义，不关心替换列表是不是 0。#if NAME 会先展开表达式；剩余的普通标识符按 0 参与预处理常量表达式计算。需要区分「未提供」与「显式关闭」时，应组合 defined(NAME) 与数值检查。

构建系统常用 -DNAME=value 提供定义，头文件则用 #ifndef NAME 给出默认值。配置应有一个明确的所有者；命令行、生成头文件和普通头文件若分别定义同名宏，结果会依赖包含顺序并可能触发重定义诊断。

#error 会让当前预处理失败，适合拒绝不支持或自相矛盾的配置。C23 还标准化了 #warning，但警告通常不应承担必须阻止构建的约束。必须满足的条件应使用 #error 或编译阶段的静态断言。

预定义名称与宏生命周期

实现会在处理用户源码前提供一组标准预定义宏。它们适合报告源码位置和判断语言实现环境，但不能替代构建系统拥有的产品配置。__func__ 是函数体中的预定义标识符，不是预处理宏。

检查版本时，应先用 defined(__STDC_VERSION__) 处理没有该宏的模式，再比较所需版本编号。编译器名称宏只能描述当前实现；把 __GNUC__ 当成某项具体功能的充分证明，可能误判兼容编译器或不同版本。

#undef NAME 结束名称后续的宏替换，可用于收回局部辅助宏或允许受控的重新配置。同一名称若在仍已定义时获得不同替换列表，通常会触发诊断；依赖这种重定义结果会让包含顺序变成隐藏输入。

标准保留了多类标识符供实现使用，尤其是文件作用域下划线开头名称和双下划线形式。项目代码应使用明确前缀，而不是模仿预定义宏的命名样式。

头文件防重复包含

头文件可能沿多条包含路径到达同一个翻译单元。 头文件防重复包含 用一个唯一宏包住文件内容，使后续包含看到宏已定义并跳过正文。

#ifndef ACME_NET_PACKET_H
#define ACME_NET_PACKET_H

struct packet;
int packet_size(const struct packet *value);

#endif

保护宏必须在项目范围内足够唯一。两个无关头文件若碰巧使用同一个保护名，先包含的文件会让另一个文件悄悄消失。#pragma once 被主流工具链支持，但它不是 C23 语言标准中的指令。

防重复包含只防止同一头文件正文在一个翻译单元中重复处理。它不会解决互相依赖的完整类型，也不会把头文件中的普通外部定义变成整个程序唯一的定义。应通过前向声明拆开依赖，并把需要唯一存储的定义放进一个源文件。

示例

下面四个程序依次展示间接字符串化、语句式宏、构建开关和 X macro。每个文件都用 GCC 13.3.0 的 -std=c2x -Wall -Wextra -Wconversion -Wpedantic -Werror 编译，显示的是实际运行输出。

展开后再字符串化

直接写 STRINGIFY_RAW(API_MAJOR) 会得到 "API_MAJOR"，因为 # 抑制该形参的预展开。外层 STRINGIFY 先展开实参，再把结果传给执行字符串化的内层宏。

相邻字符串字面量由编译器连接，所以 API_VERSION 最终形成一个字符串。这里的两层宏不是装饰；去掉外层就会改变可观察结果。

这个模式也用于把构建定义写进诊断文本。若需要保存数值供 C 表达式使用，应继续使用 API_MAJOR 本身，不要把字符串化结果再解析回来。

包住多条语句与可选参数

语句式宏采用 do { ... } while (0)，因此调用处可以像普通语句一样写一个分号。C23 的 __VA_OPT__ 只在可变参数非空时插入逗号。

#include <stdio.h>

#define AUDIT(format, ...)                                      \
    do {                                                        \
        printf("[audit] " format __VA_OPT__(,) __VA_ARGS__);   \
        putchar('\n');                                         \
    } while (0)

static void record_login(int accepted) {
    if (accepted)
        AUDIT("login accepted");
    else
        AUDIT("login rejected for user %d", 17);
}

int main(void) {
    record_login(1);
    record_login(0);
    return 0;
}

[audit] login accepted
[audit] login rejected for user 17

外层结构把宏展开变成一条语句，避免调用者的 else 绑定到宏内部的 if。宏定义结尾不带分号；分号属于调用语法。

这个宏仍没有格式类型安全。编译器可能依据 printf 属性给出诊断，但宏本身不会验证格式串与实参。更复杂的日志策略应交给函数，只把源码位置或条件删除留给薄宏层。

用构建定义选择实现

此文件用数值宏表示功能状态，并拒绝 0 和 1 之外的值。下面的输出来自额外传入 -DENABLE_METRICS=1 的构建。

#include <stdio.h>

#ifndef ENABLE_METRICS
#define ENABLE_METRICS 0
#endif

#if ENABLE_METRICS != 0 && ENABLE_METRICS != 1
#error "ENABLE_METRICS must be 0 or 1"
#endif

#if ENABLE_METRICS
static void record_metric(const char *name, int value) {
    printf("metric %s=%d\n", name, value);
}
#else
#define record_metric(name, value) ((void)0)
#endif

int main(void) {
    record_metric("requests", 3);
    printf("metrics: %s\n", ENABLE_METRICS ? "enabled" : "disabled");
    return 0;
}

metric requests=3
metrics: enabled

若改成 #ifdef ENABLE_METRICS，默认定义 0 也会选择启用分支。数值开关应使用 #if ENABLE_METRICS；只表达存在性的标记才适合 #ifdef。

关闭分支把调用替换为 ((void)0)，也就不会求值 name 和 value。如果实参带副作用，启用与关闭构建会有不同运行时行为；调用代码不应依赖日志或指标实参的副作用。

用一张列表生成一致声明

X macro 把数据列表与每次遍历时的动作分开。这里同一张状态表生成枚举成员和 switch 分支，避免手工维护两个顺序容易漂移的列表。

#include <stdio.h>

#define STATUS_LIST(X)  \
    X(PENDING, 10)      \
    X(RUNNING, 20)      \
    X(COMPLETE, 30)

#define DECLARE_STATUS(name, code) STATUS_##name = code,
enum status {
    STATUS_LIST(DECLARE_STATUS)
};
#undef DECLARE_STATUS

static const char *status_name(int value) {
    switch (value) {
#define STATUS_CASE(name, code) case STATUS_##name: return #name;
        STATUS_LIST(STATUS_CASE)
#undef STATUS_CASE
    default:
        return "UNKNOWN";
    }
}

int main(void) {
    printf("%d %s\n", STATUS_RUNNING, status_name(STATUS_RUNNING));
    printf("%d %s\n", 99, status_name(99));
    return 0;
}

20 RUNNING
99 UNKNOWN

每次使用后 #undef 动作宏，缩短它污染后续源码的时间。STATUS_LIST 本身可以保留为公共生成入口，但它的行格式和参数数量已经构成需要维护的接口。

这种技术适合一个小而稳定的声明清单。若列表需要条件、嵌套数据或外部工具也要读取，同一份 YAML、JSON 或生成脚本通常更容易验证；不要把预处理器硬扩展成数据语言。

陷阱

把括号当成单次求值保证

修复： 值计算优先使用 static inline 函数，让每个实参只在调用前求值一次。宏确实必须接受多种类型时，也要把「实参不得有副作用」写进契约并用诊断和测试约束调用点。

用 #ifdef 读取数值开关

修复： 用 #if FEATURE_X 读取 0 或 1 开关，并通过 #ifndef 提供默认值。必须区分缺省状态时，先用 defined(FEATURE_X) 检查是否提供，再单独校验允许的数值。

让多语句宏泄漏控制流

修复： 用 do { ... } while (0) 包住语句式宏，定义末尾不放分号。更稳妥的调用代码仍应给 if 与 else 使用花括号，并保持宏内部的 return、break 与 continue 可见且有文档。

让宏名和保护名互相碰撞

修复： 公共宏使用项目与组件前缀，头文件保护名包含稳定的项目路径信息，内部辅助宏用后立即 #undef。不要定义实现保留的标识符，也不要在公共头文件中留下通用名称。

默认依赖编译器扩展

修复： 先用目标标准提供的函数、__VA_OPT__ 和普通指令。确需扩展时，把它隔离在一个适配头文件中，以编译器与版本条件保护，并在 CI 中实际构建承诺支持的每套工具链。

延伸阅读

先查 C23 工作草案中的预处理指令与宏替换规则，再用 GCC 手册确认本地工具链的选项和扩展。cppreference 适合快速定位指令语法，但标准草案和编译器文档决定最终判断。

• WG14 N3096：C23 工作草案
• GCC 13.3：C 预处理器
• GCC 13.3：预处理选项
• cppreference：C 预处理器