为何C头文件的包含保护（Include guards）失效？

问题场景 #

先看带有包含保护的头文件header.h代码：

#ifndef HEADER_H
#define HEADER_H

typedef enum {
    ENUM_1,
    ENUM_2,
} enumerator;

typedef struct {
    uint8_t struct_field_1;
    bool struct_field_2;
} structName

void functionName(uint8_t arg1, uint32_t arg2);

#endif 

该头文件被file1.h和file2.h通过#include <header.h>包含，随后foo.c同时引入这两个头文件：

#include "../../../file1.h"
#include "../../../file2.h"

此时出现编译错误：previous declaration of 'structName' was here、conflicting types for 'enumerator'，明明使用了包含保护却失效。

原因分析 #

1. 路径解析差异导致预处理器误判文件
   预处理器判断头文件是否重复包含，是基于文件的实际解析路径而非文件名。如果file1.h和file2.h所在目录不同，它们引入header.h时的路径被解析为不同的绝对路径（哪怕实际是同一个文件），预处理器会认为是两个不同的头文件，此时HEADER_H宏只会在第一次引入时生效，第二次引入时会重新展开内容，导致重复定义。

2. 语法错误引发解析混乱
   header.h中structName的定义末尾缺少分号;，这会破坏预处理器的正常解析逻辑，间接引发后续的重复定义类错误。

修复方案 #

1. 先修复语法错误 #

给structName的定义末尾添加分号，修正后的代码片段：

typedef struct {
    uint8_t struct_field_1;
    bool struct_field_2;
} structName; // 补充分号

2. 统一头文件引入方式 #

• 让file1.h和file2.h使用完全一致的方式引入header.h，比如都用相同的相对路径，或者将header.h所在目录添加到编译的头文件搜索路径（例如GCC用-I参数），之后统一用#include "header.h"或#include <header.h>引入，确保预处理器将其识别为同一个文件。
• 检查编译环境的头文件搜索路径配置，避免路径解析歧义。

3. 改用#pragma once（可选） #

部分主流编译器支持#pragma once指令，它直接基于文件本身而非宏来防止重复包含，能规避宏冲突或路径解析的问题。替换后的header.h：

#pragma once

typedef enum {
    ENUM_1,
    ENUM_2,
} enumerator;

typedef struct {
    uint8_t struct_field_1;
    bool struct_field_2;
} structName;

void functionName(uint8_t arg1, uint32_t arg2);

注意：#pragma once不属于C标准，但GCC、Clang、MSVC等主流编译器均支持。

内容的提问来源于stack exchange，提问作者Jan Wang