Visual Studio 預編譯標頭：StdAfx.h / StdAfx.cpp (PCH) 原理、配置與最佳實踐

一、 是什麼？

預編譯標頭 將穩定、龐大、頻繁包含的標頭檔 (如 MFC/ATL/STL/Boost 標頭) 預先編譯為二進制中間格式 (.pch)，後續編譯單元直接載入，跳過重複解析，大幅縮短建置時間。

二、 核心檔案角色

三、 運作機制

1. 編譯 StdAfx.cpp → 產生 Project.pch (及 StdAfx.obj)。
2. 其他 .cpp 編譯時，若第一行非註解為 #include "StdAfx.h"，編譯器直接載入 .pch，跳過對 StdAfx.h 及其遞迴包含標頭的解析。
3. 若 StdAfx.h 變更，重新編譯 StdAfx.cpp 更新 .pch，後續 .cpp 自動受益。

四、 VS 專案屬性配置

• StdAfx.cpp：C/C++ → Precompiled Headers → Create (/Yc)，指定 StdAfx.h。
• 其他 .cpp：Use (/Yu)，指定相同 StdAfx.h。
• 不使用 PCH 的檔案：Not Using Precompiled Headers。

五、 最佳實踐原則

1. 只放穩定標頭：系統/庫/專案通用標頭。頻繁變更的業務標頭 勿放入，否則頻繁觸發全專案重編。
2. 順序固定：所有 .cpp 第一行非註解 必須 是 #include "StdAfx.h"。
3. 避免巢狀包含：StdAfx.h 內部不再包含其他會變動的專案標頭。
4. 現代 CMake / VS2017+：target_precompile_headers、/Yc//Yu 自動管理，檔案常命名為 pch.h/pch.cpp。
5. 統一建置 (Unity Build)：超大專案可結合 Unity Build (合併多 .cpp 為單一編譯單元) + PCH，極致加速。