Visual C++ 預編譯頭 stdafx.h 強制首行包含規則原理解析

現象

專案啟用「使用預編譯頭 (/Yu)」且指定 stdafx.h，若 #include "stdafx.h" **非源文件第一行有效代碼** (前面只有註解/空行)，編譯報錯 fatal error C1010: unexpected end of file while looking for precompiled header。

原理

1. 預編譯頭 (PCH) 將常用穩定頭文件 (Windows SDK, STL, 專案公共頭) 預先編譯為二進制狀態檔 (.pch)，大幅加速編譯。
2. 編譯器處理源文件時，**掃描至第一個非註解/空行 Token**，若非 #include "stdafx.h"，直接報錯，因為 PCH 只能在編譯單元**最開頭**注入預編譯狀態。
3. stdafx.h 內部通常包含 #include , #include 等，且以 #pragma hdrstop (可選) 標記預編譯結束點。

正確源文件模板

// stdafx.cpp (僅此文件用 /Yc 建立 PCH)
#include "stdafx.h"

// 其他 .cpp (用 /Yu 使用 PCH)
#include "stdafx.h"   // 必須是第一行有效代碼
#include 
#include "my_header.h"
// ... 實現代碼

常見坑點

• 誤將 #include "stdafx.h" 放在命名空間、宏定義、其他 include 之後。
• 專案屬性不一致：部分文件 /Yc，部分 /Yu，導致 PCH 不匹配。
• 跨平台專案建議**棄用 PCH**，改用 CMake target_precompile_headers (CMake 3.16+) 或 Unity Build 統一管理。

參考深度解析

博客詳解：VC++ 預編譯頭強制首行包含原理