#include 指示詞 （C/C++）

告知預處理器在指示詞出現時包含指定檔案的內容。

語法

#include "path-spec "
#include <path-spec >

備註

您可以將常數和宏定義組織成 包含檔案 （也稱為 頭檔），然後使用 #include 指示詞將它們新增至任何原始程序檔。 Include 檔對結合外部變數及複雜資料類型的宣告也很有用。 這些類型只可在針對該目的所建立的 Include 檔中定義和命名一次。

path-spec 是一個檔名，其前面可能會有目錄規格。 檔案名稱必須指定現有的檔案名稱。 path-spec 的語法取決於編譯程式所在的操作系統。

如需如何在使用 /clr編譯C++應用程式中參考元件的資訊，請參閱 #using 指示詞。

這兩種語法形式都會讓 #include 指示詞取代為指定檔案的整個內容。 這兩種表單之間的差異在於預處理器在未完全指定路徑時所搜尋的路徑順序。 下表顯示這兩種語法形式之間的差異。

語法形式	動作
有引號的形式	前置處理器會依此順序搜尋 Include 檔： 1） 在與包含 #include 語句之檔案相同的目錄中。 2） 在目前開啟之 include 檔案的目錄中，以開啟檔案的反向順序進行。 搜尋會從 Include 檔的父目錄開始，並向上繼續搜尋所有上層 Include 檔的目錄。 3） 沿著每個 /I 編譯程式選項所指定的路徑。 4） 沿著環境變數所 INCLUDE 指定的路徑。
角括弧形式	前置處理器會依此順序搜尋 Include 檔： 1） 沿著每個 /I 編譯程式選項所指定的路徑。 2） 在命令行上進行編譯時，沿著環境變數所 INCLUDE 指定的路徑。

前置處理器只要找到具有指定名稱的檔案，就會立即停止搜尋。 如果您以雙引號 （） 括住包含檔案的完整明確路徑規格，" "預處理器只會搜尋該路徑規格並忽略標準目錄。

如果以雙引弧括住的檔名是不完整的路徑規格，預處理器會先搜尋 父 檔案的目錄。 父檔案是包含指示詞的 #include 檔案。 例如，如果您在名為 file1 的檔案中包含名為 file2 的檔案，file1 就是父檔案。

包含檔案可以是巢狀 的： #include 指示詞可以出現在由另一個 #include 指示詞命名的檔案中。 例如， file2 可以包含 file3。 在此情況下，file1 仍然是 file2 的父代，但它會是 file3 的祖系。

當包含檔案是巢狀的，以及在命令行上編譯時，目錄搜尋會從父檔案的目錄中開始。 然後，它會繼續進行任何祖父母檔案的目錄。 也就是說，搜尋會相對於包含目前處理中原始檔的目錄開始進行。 如果找不到檔案，搜尋會移至 [其他包含目錄] 編譯程式選項所/I指定的目錄。 最後，會搜尋環境變數所 INCLUDE 指定的目錄。

在 Visual Studio 開發環境中， INCLUDE 會忽略環境變數。 會改用 include 目錄的項目屬性中指定的值。 如需如何在 Visual Studio 中設定 Include 目錄的詳細資訊，請參閱 Include Directory 和其他 Include 目錄。

此範例使用角括弧示範檔案包含：

#include <stdio.h>

此範例會將名為 stdio.h 的檔案內容新增至來源程式。 角括弧會導致預處理器搜尋 環境變數stdio.h所INCLUDE指定的目錄，在搜尋編譯程式選項所/I指定的目錄之後。

下一個範例使用引號形式示範檔案包含：

#include "defs.h"

此範例會將 所 defs.h 指定的檔案內容新增至來源程式。 引號表示前置處理器會先搜尋包含父原始程式檔的目錄。

Include 檔的巢狀可以擴充到最多 10 層。 完成巢狀 #include 處理時，預處理器會繼續將封入父 Include 檔案插入原始原始程式檔中。

Microsoft特定

若要找出要包含的來源檔案，預處理器會先搜尋編譯程式選項所 /I 指定的目錄。 /I如果選項不存在，或如果選項失敗，預處理器會使用INCLUDE環境變數來尋找角括號內的任何包含檔案。 INCLUDE環境變數和/I編譯程式選項可以包含多個路徑，並以分號 （;） 分隔。 如果多個目錄顯示為選項的 /I 一部分，或出現在環境變數內 INCLUDE ，預處理器會依出現的順序搜尋它們。

例如，命令

CL /ID:\msvc\include myprog.c

會導致預處理器搜尋目錄 D:\msvc\include\ ，以尋找包含檔案，例如 stdio.h。 命令

SET INCLUDE=D:\msvc\include
CL myprog.c

有相同的效果。 如果兩個搜尋集合失敗，就會產生嚴重編譯器錯誤。

如果完整指定檔名給包含冒號的路徑包含冒號的 include 檔案， F:\MSVC\SPECIAL\INCL\TEST.H預處理器會遵循路徑。

針對指定為 #include "path-spec"的包含檔案，目錄搜尋會從父檔案的目錄中開始，然後繼續執行任何祖系檔案的目錄。 也就是說，搜尋會開始相對於包含所處理來源檔案的目錄。 如果沒有祖父母檔案，仍然找不到檔案，搜尋會繼續，就像檔名以角括弧括住一樣。

END Microsoft 特定

另請參閱

預處理器指示詞
/I （其他包含目錄）