> For the complete documentation index, see [llms.txt](https://overleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://overleaf-pro.ayaka.space/latex/zh-tw/shen-ru-wen-zhang/06-an-introduction-to-kpathsea-and-how-tex-engines-search-for-files.md).

# Kpathsea 簡介，以及 TeX 引擎如何搜尋檔案

## 簡介

本文介紹 TeX 引擎如何定位排版文件所需的檔案——無論使用 LaTeX 或其他巨集套件。雖然 Overleaf 讓使用者免於管理 TeX 安裝的種種挑戰（[TeX Live](https://www.tug.org/texlive/)），但若你想建立資料夾結構來協助管理 Overleaf 專案，了解 TeX 引擎如何搜尋檔案的基本原理將會很有用／很有趣。

為什麼會這樣呢？如果你把 Overleaf 專案的某些檔案存放在資料夾中，LaTeX 可能找不到那些檔案，因為預設情況下，TeX 引擎（編譯器）可能不會 *知道* 必須搜尋那些資料夾——因此就找不到其中包含的檔案。為了避免這種情況，你可以建立一個稱為 [latexmkrc 檔案](https://mg.readthedocs.io/latexmk.html#configuration-files) 的設定檔，用來告訴 TeX 引擎你的資料夾存在，且它應該去搜尋它們。

如果你想直接看一個展示 latexmkrc 檔案的範例，可以閱讀這篇說明文章： [如何在 Overleaf 中使用 latexmkrc：範例與技巧](/latex/zh-tw/shen-ru-wen-zhang/28-how-to-use-latexmkrc-with-overleaf.md)。這個 latexmkrc 檔案究竟如何運作、為什麼有效，可能不會立刻顯而易見。如果你想知道原因，並且也許進一步了解如何將其用於專案的其他組態可能性，那就請繼續閱讀……在本文結尾，我們將逐步介紹一個 [實作範例](#kpathsea-and-texinputs-latexmkrc-file-to-the-rescue)——運用我們對 TeX 搜尋檔案方式的了解——來建立一個 latexmkrc 檔案，以管理包含圖形檔的巢狀資料夾。

## TeX 與平台獨立性

當 Knuth 創造 TeX 時，平台獨立性是指導其設計與實作的核心原則，而這種理念也貫穿於 TeX 的內部運作（例如：使用整數算術、「自製」字串處理、記憶體管理等）。即使到了今天，現代基於 TeX 的引擎之平台獨立性仍在公開論壇上引發問題與討論；例如，請參閱 tex.stackexchange 上的這個討論： [XeTeX 和 LuaTeX 是否依賴平台？](https://tex.stackexchange.com/questions/94297/are-xetex-and-luatex-platform-dependent) 其中包含多位知名 TeX 專家所提出的評論與觀察。

不過，現在先把更細節的部分放到一邊，並注意到 TeX 引擎仍然必須具有高度可攜性——能在多種作業系統上運作並產生「相同」的結果。可攜性的一個關鍵面向，就是以平台無關的方式搜尋檔案。

## TeX 引擎不會搜尋檔案……真的嗎！？

不，TeX 引擎不會 *直接* 搜尋檔案 *自行*。在處理 `.tex` 某個檔案時，TeX 引擎可能會辨識出需要開啟特定檔案，但它 *會委派* 給另一個稱為 [*Kpathsea*](https://tug.org/kpathsea/)：這是一個外部軟體函式庫，不屬於 TeX 引擎的 *核心* 原始碼。Kpathsea 實際上提供的是一個 API（[應用程式介面](https://en.wikipedia.org/wiki/Application_programming_interface)），TeX 引擎（加上 BibTeX、MetaPost 及其他應用程式）只要需要開啟特定檔案時就可以呼叫它：真正負責定位該檔案的是 Kpathsea。

當 Knuth 撰寫最初的 TeX 引擎——其他所有 TeX 引擎最終都源自它——時，尋找／開啟檔案的問題是一大挑戰，部分原因在於當時技術生態系極為分歧。事實上，在 TeX 的原始碼中，Knuth 將檔案輸入／輸出稱為「可攜性的禍根」（見第 12 頁，第 25 節， [《TeX：程式》](https://www.amazon.co.uk/Computers-Typesetting-TeX-Program-TEX/dp/0201134373)).

TeX 社群意識到有必要協調（標準化）TeX 的檔案搜尋——*以及 TeX 相關軟體*——並決定提供 TeX 完成這件事所需的工具。為了處理以平台無關方式尋找檔案這個極其棘手的問題，TeX 社群的重要成員 Karl Berry 撰寫了用來解決 *路徑*-搜尋問題的軟體：他將這個解決方案命名為 [**Kpathsea**](http://tug.org/texinfohtml/kpathsea.html)——這個名稱源自 **K**arl 的 **Path** **Sea**搜尋（請參閱這個 [與 Karl Berry 的訪談](http://www.tug.org/interviews/berry.html)).

我們可以注意到，它被稱為 K**路徑**sea，而不是 K**檔案**sea，因為，如 [說明文件](http://tug.org/texinfohtml/kpathsea.html) 所指出的，它是一個 \*路徑\* 搜尋函式庫。重要的是要認識到，Kpathsea 不僅被 TeX 引擎使用；各種與 TeX 相關的程式，包括 BibTeX 和 MetaPost，也會使用 Kpathsea 來搜尋輸入檔。

概括來說，每當 TeX/LaTeX 巨集需要開啟特定檔案時，構成那些巨集的命令最終會被轉換成 TeX 引擎實際執行的低階 TeX 指令（TeX primitives）。如果這些指令包含需要開啟檔案，TeX 引擎就會呼叫 Kpathsea，等於是在說：「請幫我找到這個檔案」；如果該 Kpathsea 搜尋成功，檔案就會被開啟。不過，如果 Kpathsea 無法定位檔案，TeX 引擎就會得知這點，並停止執行，發出那個惡名昭彰的錯誤 ``！我找不到檔案 `...'`` 事實上，Kpathsea 無法找到它。

### 關於 LuaTeX 的註記

嚴格來說，我們應該先提醒一下：LuaTeX 確實提供了一種機制，讓使用者可透過使用 *回呼函式*。LuaTeX 讓使用者能以 Lua 腳本語言撰寫函式，並將其註冊到 LuaTeX，使其在 LuaTeX 執行過程中的某些階段呼叫該使用者定義的函式——因此稱為 *回呼函式*回呼 [LuaTeX 參考手冊](http://www.pragma-ade.com/general/manuals/luatex.pdf) 。這是一種非常強大的技術，有興趣的讀者可在

### Kpathsea 組態檔：texmf.cnf

每個 TeX 安裝都包含一個名為 `texmf.cnf` 的文字檔，它是 Kpathsea 使用的組態檔：其中包含許多「設定變數」，這些變數定義了 Kpathsea 會用來搜尋 TeX 引擎（或 BibTeX、MetaPost 等）可能需要的各類檔案之路徑。如我們下面將看到的，這些「設定變數」定義了由所謂的 *路徑元素*所構成的搜尋路徑：透過各種結構、變數與參數，將每個路徑元素定義為一個「模板」，供 Kpathsea 處理後產生實際上要搜尋的實體目錄。

先舉一個具體例子，這裡有一個這樣的設定變數，它定義了 OpenType 字型的搜尋路徑——先別擔心這條路徑的組成意義：

```
OPENTYPEFONTS = .;$TEXMF/fonts/{opentype,truetype}//;$OSFONTDIR//
```

這裡重要的是， `texmf.cnf` （由 Kpathsea 讀取）定義了一個名為 `OPENTYPEFONTS` 的設定變數，而它用來定義 Kpathsea 將用於搜尋 OpenType 字型的路徑。等號右邊看起來不像一般裝置上會看到的路徑，因為它是利用各種變數與參數構成，把每個路徑定義成一個 Kpathsea 會用來產生實際要搜尋目錄的「模板」或「藍圖」。

### Kpathsea 對「路徑」的概念

或許最核心、需要掌握的概念是 Kpathsea 所理解的「路徑」：Kpathsea 用來判定某個檔案位於何處的基本構造。正如我們在 `OPENTYPEFONTS` 上面的範例中看到的，Kpathsea 對路徑的理解與我們在桌面或可攜式裝置上習慣使用的路徑非常不同。

引用 Kpathsea 的 [說明文件](http://tug.org/texinfohtml/kpathsea.html#Searching-overview):

> …… *搜尋路徑* 是由冒號分隔的一串 *路徑元素*，也就是帶有一些「額外裝飾」的目錄名稱。

——但請注意，分號（`;`）也用來分隔 *路徑元素*。稍後，我們會簡要說明其中一些「額外裝飾」的性質。

在我們的 `OPENTYPEFONTS` 範例中有三個路徑元素，每個都以分號（`;`):

![顯示 Kpathsea 路徑定義中所含路徑元素的圖片](/files/919dda1b1cd9a569fe6367a7254bffe2d88fd526)

1. `.` （表示目前目錄）
2. `$TEXMF/fonts/{opentype,truetype}//`
3. `$OSFONTDIR//`

請注意，雙斜線（`//`）在路徑元素中表示搜尋子目錄（遞迴地）。

典型的 `texmf.cnf` 檔案會包含許多「設定變數」，用來定義 Kpathsea 可搜尋的檔案類型之搜尋路徑。

## Kpathsea：極簡概覽

Kpathsea 是一個精密的函式庫——具有許多細節與微妙之處——即使只是稍微瀏覽其 [說明文件](http://tug.org/texinfohtml/kpathsea.html) 也足以看出我們無法深入所有細節。不過，我們可以試著提供其功能概覽——幫助你建立概念，並提供進一步閱讀的起點。

### Kpathsea 的核心用途

如文件所述，Kpathsea 的基本目的就是「從使用者指定的一串目錄中回傳檔名」，而這些目錄（搜尋路徑）是以「一些額外裝飾」來指定的。

### 那些「額外裝飾」

上面提到的「一些額外裝飾」包括 Kpathsea 用來建構搜尋路徑（或「路徑模板」）的各種參數與變數，使其能以更一般化的方式定義路徑。當 TeX 引擎實際執行時，Kpathsea 可以利用那些參數／變數的目前值，透過將這些變數替換為其實際（執行時）值來算出實際路徑。你可以很容易辨識這些變數（在路徑元素中），因為它們都以 `$` 符號。

因此，我們說 Kpathsea *會展開* 一個路徑元素，也就是將那些參數與變數轉換：把一個路徑「模板」變成一個或多個實體目錄的實際名稱，以便在其中尋找檔案。這提供了很大的彈性，代表 Kpathsea 可能會為單一的路徑元素建構一份目錄清單——例如，如果它被要求搜尋子目錄。

### 我們再次回顧 OpenType 範例

我們將把各個脈絡整合起來，並探討 `OPENTYPEFONTS` 更詳細一些：

```
OPENTYPEFONTS = .;$TEXMF/fonts/{opentype,truetype}//;$OSFONTDIR//
```

讓我們來看這兩個路徑元素 `$TEXMF/fonts/{opentype,truetype}//` 和 `$OSFONTDIR//`。在這裡，Kpathsea 注意到大括號的使用 `{...}` 並將 `$TEXMF/fonts/{opentype,truetype}` 視為代表 *兩個* 路徑元素：

1. `$TEXMF/fonts/opentype//`
2. `$TEXMF/fonts/truetype//`

以及 *子目錄* 也應一併搜尋（由結尾的 `//`).

**注意**：請參閱 Kpathsea 文件中關於 [子目錄展開](http://tug.org/texinfohtml/kpathsea.html#Subdirectory-expansion) ，其中有一個重要注意事項，關於任何層級的子目錄搜尋順序（未予指定）。

我們將對 `$TEXMF` 作幾點說明。

#### $OSFONTDIR//

`$OSFONTDIR` 是一個變數，其值應定義為一個環境變數，內容為字型存放的位置：當然，確切值會取決於執行 TeX 所使用的作業系統。請注意，在這裡，結尾的 `//` 會指示 Kpathsea 在尋找 OpenType 字型時搜尋子目錄。

的預設定義 `OSFONTDIR` 在 `texmf.cnf` 的一般形式如下：

```
OSFONTDIR = /please/set/osfontdir/in/the/environment
```

因此，如果你想使用它，確實需要自行設定——你的環境變數會覆蓋其中所包含的這個「佔位」定義 `texmf.cnf`.

如果你確實設定了環境變數 `OSFONTDIR` 那麼，在執行時，只要 Kpathsea 看到 `$OSFONTDIR` 作為路徑元素的一部分（在 `texmf.cnf`）時，它就可以將變數 `$OSFONTDIR` 替換為環境變數中儲存的實際值 `OSFONTDIR`。請記住，當在 `texmf.cnf` 路徑元素中使用時，我們要指定變數 `$OSFONTDIR`——在前面加上 `$`——以告訴 Kpathsea 這是一個其 *值* 需要使用的變數。

#### 關於 $TEXMF 的簡短說明

`TEXMF` 是另一個定義於 `texmf.cnf`；例如，在 TeX Live 主分發版本中你會看到：

```
TEXMF = {$TEXMFAUXTREES$TEXMFCONFIG,$TEXMFVAR,$TEXMFHOME,!!$TEXMFLOCAL,!!$TEXMFSYSCONFIG,!!$TEXMFSYSVAR,!!$TEXMFDIST}
```

你不必在意這個定義的細節 `TEXMF`——我們不會深入所有細節，只需注意 `$TEXMF` 這個變數會在路徑元素中使用，因為它定義了一系列頂層資料夾（稱為「texmf 樹」），你可以從這些資料夾開始搜尋檔案。

`TEXMF` 如果你想要，或需要，將一個 TeX 安裝分散到多個目錄（或目錄「樹」）中，這就非常有用。例如，你可以有一套主要或主控的 TeX/LaTeX 套件集合（如 TeX Live），以及另一套用來存放本機 LaTeX 套件的檔案與資料夾集合——或者用來存放本機組態檔或標準套件的自訂版本。以這種方式分割 TeX 安裝，可以讓管理主要／主控套件集合（發行版）的升級更容易，因為你的本機集合與主檔案分離，而主檔案會在你升級 TeX Live 發行版／安裝時更新。

若要進一步了解如何管理更複雜的 TeX 安裝，有興趣的讀者可參考這兩篇論文：

* [管理多個 TDS 樹](http://tug.org/TUGboat/Articles/tb22-3/tb72downes.pdf) 作者：Michael J Downes；
* [玩轉 texmf 樹](http://www.ntg.nl/maps/27/17.pdf) 作者：Siep Kroonenberg。

#### TeX 目錄結構

任何管理過 TeX 安裝的人都知道，現代的 TeX 系統，例如 TeX Live，包含數以萬計的檔案，涵蓋極其廣泛的檔案類型。TeX Directory Structure（TDS）被設計為組織實際 TeX 安裝中龐大檔案集合的最佳實務「藍圖」，並且強烈建議與 Kpathsea 搭配使用。

欲知更多資訊，請讀者參閱 TDS 規格： [TeX 檔案的目錄結構](https://www.tug.org/tds/tds.pdf).

## Kpathsea 檔案類型

使用 Kpathsea 的一系列應用程式需要存取廣泛的檔案類型，因此 Kpathsea 會使用「設定變數」來識別其支援的每一種檔案（或檔案群組）的路徑。線上文件有完整清單（另見我們的 [下方摘要表](#table-listing-kpathsea-config-variables)）但以下是較常見檔案類型的「設定變數」：

|                     |                |
| ------------------- | -------------- |
| **設定變數**            | **檔案類型範例**     |
| TEXINPUTS           | TeX 原始檔與圖表／圖形檔 |
| BIBINPUTS、BSTINPUTS | BibTeX 書目來源檔   |
| TTFONTS             | TrueType 向量字型  |
| OPENTYPEFONTS       | OpenType 向量字型  |

`TEXINPUTS` 是一個格外重要的設定變數，因為它指定 TeX 引擎取得輸入原始檔的位置。請注意，圖像檔也被視為輸入檔，並且也可以使用由 `TEXINPUTS`.

### 一些 Kpathsea 的細節

如前所述，Kpathsea 有許多細節，我們無法在此詳細探討。不過，以下是一些讀者可能想進一步了解的功能：

* **檔名資料庫：** 為了將磁碟搜尋降至最低，Kpathsea 可以利用一個「由外部建立的 [名為 ls-R 的檔名資料庫檔案](http://tug.org/texinfohtml/kpathsea.html#Filename-database) ，用來將檔案對應到目錄」。TeX Live 有提供這種檔案，若新增檔案也有可更新它的工具。
* **環境變數**：除了「設定變數」（例如 `OPENTYPEFONTS`）之外，Kpathsea 也巧妙運用 [環境變數](https://en.wikipedia.org/wiki/Environment_variable)；例如，環境變數的執行時值可用來定義 `texmf.cnf` 檔案中的路徑元素（也可能用來覆蓋定義於 `texmf.cnf`).
* **程式名稱：** Kpathsea 行為中一個微妙但重要的面向，是它可以利用可執行程式的名稱（例如 TeX 引擎）來建構特定程式的搜尋路徑組合。這提供了相當大的彈性，因為路徑搜尋可以針對特定 TeX 引擎的檔案。例如，對 LuaTeX/LuaLaTeX 而言：

  ```
  TEXINPUTS.lualatex = .;$TEXMF/tex/{lualatex,latex,luatex,generic,}//
  TEXINPUTS.luatex = .;$TEXMF/tex/{luatex,plain,generic,}//
  ```
* **找出 `texmf.cnf`**：你可能會問，Kpathsea 如何知道 `texmf.cnf` 存放在哪裡？答案是一個名為 `TEXMFCNF`。它需要（在執行 TeX 的裝置／平台上）設定為 `texmf.cnf` 的存放路徑。

#### Kpathsea 問題除錯

Overleaf 使用者大概不需要這些功能，但為求完整仍列出如下：

* **kpsewhich**：一個獨立程式（隨 TeX Live 提供），可用來測試你的設定：確定變數值並尋找檔案。有興趣的讀者可參考 [線上文件](http://tug.org/texinfohtml/kpathsea.html#Invoking-kpsewhich) 以取得更多資訊。
* **環境變數**：Kpathsea 支援一個名為 [`KPATHSEA_DEBUG`](http://www.tug.org/texinfohtml/kpathsea.html#Debugging) 的環境變數，以協助除錯其行為。你可以設定 `KPATHSEA_DEBUG` 為不同的值，視你需要多少除錯資訊而定。設定 `KPATHSEA_DEBUG=-1` 會產生 *大量* 的資料。

## 最後：資料夾、圖形檔與 latexmkrc

那麼，上述內容與 latexmkrc 有何關聯？如果你閱讀這篇文章 [如何在 Overleaf 中使用 latexmkrc：範例與技巧](/latex/zh-tw/shen-ru-wen-zhang/28-how-to-use-latexmkrc-with-overleaf.md) 你可以看到 latexmkrc 範例中的（Perl）程式碼設定了一個環境變數的值 `TEXINPUTS`:

```
$ENV{'TEXINPUTS'}='./tex//:' . $ENV{'TEXINPUTS'};
```

請注意，這裡使用的冒號（：`./tex//**:**`）為 *極其* 很重要。如果你省略那個冒號，TeX/LaTeX 可能無法找到重要的系統檔案，例如 LaTeX 套件！

這個 latexmkrc 檔案實際上所做的是新增一個頂層資料夾路徑（`./tex` （如上例所示）到系統定義的 `TEXINPUTS` 環境變數中，使得當 Kpathsea 使用變數 `$TEXINPUTS` 時，它就會知道資料夾 `/tex//` 應該被搜尋以尋找輸入檔。若你仔細看，會發現實際使用的路徑是 `./tex//:` 該 `//` 會告訴 Kpathsea 遞迴搜尋 tex 資料夾——也就是查看 `tex` 資料夾中包含的任何子資料夾。如前所述，我們也加上了重要的冒號字元。

我們也可以對圖形檔使用完全相同的技巧。

### 順帶一提 BibTeX

如前所述，BibTeX 程式也會使用 Kpathsea 來搜尋其輸入檔；特別是：

* 該 `BSTINPUTS` 設定變數（搜尋路徑）用於搜尋 `.bst` 檔案；
* 以及 `BIBINPUTS` 設定變數（搜尋路徑）將用於搜尋 `.bib` .bib 檔案。

如果你新增 `.bst` 或 `.bib` 檔案到你的 Overleaf 專案中，你可以使用下方的技巧來指示 BibTeX 到哪裡尋找這些檔案——你需要替換 `TEXINPUTS` 與 `BSTINPUTS` 和／或 `BIBINPUTS`.

### TEXINPUTS，以及使用巢狀資料夾存放圖形檔

如果你的專案有很多圖形檔，建立一組資料夾來儲存與管理它們會很方便。例如，下方截圖顯示一個 Overleaf 專案的一部分，它使用了一個名為 **`graphics`**:

![顯示 Overleaf 專案中巢狀資料夾的圖片](/files/189686f070ac6f39f779716e08c9055873d8a1ef)

其中有許多（巢狀）子資料夾，包含文件各個部分的圖形。

假設我們有上述資料夾結構，並想使用 `graphicx` 套件（`\usepackage{graphicx}`）而且我們嘗試這樣做：

```latex
\documentclass{article}
\usepackage{graphicx}
\begin{document}
\\includegraphics{endlinechar}% 最佳做法是不使用副檔名
\end{document}
```

這樣行不通，你會得到如下錯誤：

```
！LaTeX 錯誤：找不到檔案 `endlinechar'。
l.4 \\includegraphics{endlinechar}
我無法以以下任何副檔名找到該檔案：
.pdf,.PDF,.ai,.AI,.png,.PNG,.jpg,.JPG,.jpeg,.JPEG,.jp2,.JP2,.jpf,.JPF,.bmp,.BMP,
,.ps,.PS,.eps,.EPS,.mps,.MPS,.pz,.eps.Z,.ps.Z,.ps.gz,.eps.gz
```

該錯誤的原因是我們的圖形檔儲存在 TeX/LaTeX（以及 Kpathsea）不知道的位置，因此無法找到它——圖形檔的路徑是：

```
./graphics/Introduction/Chapter1/Section1/Subsection3/endlinechar.png
```

**注意**：一般公認的最佳做法是 ***避免在資料夾名稱中使用空格字元***。雖然資料夾名稱中當然可以有空格，並且也能使用下文討論的技巧處理，但基於文件在 Overleaf 平台外的可攜性，我們還是建議不要這麼做。

如這篇 [Overleaf 說明文章](/latex/zh-tw/geng-duo-zhu-ti/27-inserting-images.md) 你當然可以使用資料夾來存放圖形，但必須告訴 LaTeX 它們存放在哪裡。這裡我們來看兩種解決方案：

* 使用 \\\graphicspath 指令；
* 運用我們對 Kpathsea 的了解以及 `TEXINPUTS`.

### 使用 \\\graphicspath

該 `graphicx` 套件提供了 `\\graphicspath` 指令，你可以用它來宣告圖形所在的路徑；因此我們可以這樣做：

```latex
\\graphicspath{{./graphics/Introduction/Chapter1/Section1/Subsection3/}}
```

而 LaTeX 現在就能找到儲存在該路徑下的任何圖形。

**注意**：如果你 *必須* 的資料夾名稱中有空格，那麼你需要將路徑用雙引號（`"..."`):

```latex
\\graphicspath{{"./graphics/Introduction/Chapter 1/Section 1/Subsection 3/"}}
```

**注意**：你可以像這樣宣告多個路徑：

```latex
\\graphicspath{{path1}{path2}{path3}...{pathN}}
```

其中 `...` 表示以大括號括住的其他路徑。

**注意**：我們將路徑以 `./graphics` 開頭，而不是只用 `/graphics`。句點（.）告訴作業系統該路徑是相對於目前工作目錄。

該 `\\graphicspath` 指令運作良好，但如果你有很多資料夾，要一一加入每個路徑就會相當繁瑣；此外，透過 `\\graphicspath` 所定義的路徑在你重新命名資料夾或重新結構化後就不再適用。有沒有更簡單的方法？有，你可以使用 latexmkrc 檔案！

#### \\\graphicspath 與遞迴（子目錄）

請注意，網路上對於某些系統是否支援／啟用 `\\graphicspath` 在加入時可否遞迴搜尋子目錄 `//` ，已有討論：例如，請參閱 tex.stackexchange 上的這些討論：

* [LaTeX \\\graphicspath 遞迴搜尋](https://tex.stackexchange.com/questions/25443/latex-graphicspath-recursive-search);
* [MikTeX 的 Graphicspath](https://tex.stackexchange.com/questions/3131/graphicspath-for-miktex).

為了獲得最高相容性，你應該假設 `\\graphicspath` 不支援遞迴目錄搜尋。

### Kpathsea 與 TEXINPUTS（latexmkrc 檔來解救）

**注意：** 請注意，以下技巧在 Overleaf 以及適當設定的本機 TeX 安裝上都能良好運作； **但** 如果你使用 latexmkrc 檔案，你的專案可能會與其他 TeX 安裝不相容，例如出版商與線上期刊投稿系統所使用的安裝。第三方 TeX 安裝可能支援，也可能不支援或允許使用 latexmkrc。若你需要將 Overleaf 專案匯出到其他地方使用，或想投稿期刊，你應該從路徑名稱中移除任何空格字元，並為了提高相容性，加入一個 `\\graphicspath` 定義所有路徑的指令：

```latex
\\graphicspath{{path1}{path2}{path3}...{pathN}}
```

其中 `...` 表示以大括號括住的其他路徑。

下文討論的技巧（使用 `TEXINPUTS`）已在 Overleaf 上使用 pdfTeX、XeTeX 與 LuaTeX 引擎成功測試（也就是 Overleaf 選單中的 pdfLaTeX、XeLaTeX 與 LuaLaTeX 編譯器選項）：

![顯示如何在 Overleaf 選擇 LaTeX 編譯器的圖片](/files/f55712f04872bd88d01ca97d35684ed0aa08af64)

回到我們的範例，我們想要使用這段程式碼（搭配深度巢狀的資料夾），並利用 latexmkrc 檔案來達成：

```latex
\documentclass{article}
\usepackage{graphicx}
\begin{document}
\\includegraphics{endlinechar}% 最佳做法是不使用副檔名
\end{document}
```

這裡有一張螢幕截圖，顯示上述程式碼正常運作：LaTeX 已找到我們的圖形檔（`endlinechar.png`），即使它位於一個深度巢狀的資料夾結構中（且資料夾名稱沒有任何空格）。

![顯示含有巢狀資料夾的專案在 Overleaf 上編譯的圖片](/files/cd99d133e9ce4136e9222e67e341c274f7229964)

那麼，我們是怎麼做到的呢？你只需要：

* 建立一個沒有副檔名的新檔案，並將它命名為 latexmkrc；
* 在該檔案中加入以下一行：

  ```
  $ENV{'TEXINPUTS'}='./graphics//:'.$ENV{'TEXINPUTS'};
  ```

Kpathsea 現在會知道位於下方的資料夾 `**graphics**` 而且由於 `//` 它也會查看子資料夾。

再次注意，中的冒號 `./graphics//:` 其實是 *極其* 很重要。如果你省略那個冒號，TeX/LaTeX 可能無法找到重要的系統檔案，例如 LaTeX 套件！

使用上方的簡單專案範例，你現在可以編譯它，然後瞧！LaTeX 找到了你的圖形檔——而且你可以重新命名或重新整理 /graphics 底下的資料夾，這不會阻止 LaTeX 找到它們。

## Kpathsea「設定變數」列表表格

下表是根據以下資料整理出的摘要 [Kpathsea 文件中列出的資料](http://tug.org/texinfohtml/kpathsea.html#Supported-file-formats).

|                                                     |                                     |                                |
| --------------------------------------------------- | ----------------------------------- | ------------------------------ |
| **Kpathsea 設定變數**                                   | **檔案類型說明**                          | **檔案副檔名**                      |
| AFMFONTS                                            | Adobe 字型度量                          | .afm                           |
| MFBASES, TEXMFINI                                   | Metafont 記憶體傾印                      | .base                          |
| BIBINPUTS, TEXBIB                                   | BibTeX 參考書目來源                       | .bib                           |
| BLTXMLINPUTS                                        | 供 Biber 使用的 BibLaTeXML 參考書目檔案       | .bltxml                        |
| BSTINPUTS                                           | BibTeX 樣式                           | .bst                           |
| CLUAINPUTS                                          | Lua 的動態函式庫                          | .dll 和 .so                     |
| CMAPFONTS                                           | 字元對應表檔案                             | .cmap                          |
| TEXMFCNF                                            | 執行階段設定檔                             | .cnf                           |
| CWEBINPUTS                                          | CWEB 輸入檔                            | .w, .web, .ch                  |
| TEXCONFIG                                           | Dvips 的 'config.\*' 檔案，例如 config.ps |                                |
| ENCFONTS                                            | 編碼向量                                | .enc                           |
| TEXFORMATS, TEXMFINI                                | TeX 記憶體傾印                           | .fmt                           |
| FONTCIDMAPS                                         | CJK 對應                              | .cid                           |
| FONTFEATURES                                        | 主要用於 OpenType 字型特性                  | .fea                           |
| FONTS, GFFONTS, GLYPHFONTS, TEXFONTS                | 通用字型點陣圖                             | .gf                            |
| TEXPICTS, TEXINPUTS                                 | 封裝式 PostScript 圖形                   | .eps, .epsi                    |
| TEXINDEXSTYLE, INDEXSTYLE                           | makeindex 樣式檔                       | .ist                           |
| LIGFONTS                                            | 連字定義檔                               | .lig                           |
| TEXMFDBS                                            | 檔名資料庫                               |                                |
| TEXFONTMAPS                                         | 字型對應表                               | .map                           |
| MPMEMS, TEXMFINI                                    | MetaPost 記憶體傾印                      | .mem                           |
| MPSUPPORT                                           | 供 DMP 使用的 MetaPost 支援檔              |                                |
| MFINPUTS                                            | Metafont 原始碼                        | .mf                            |
| MFPOOL, TEXMFINI                                    | Metafont 程式字串                       | .pool                          |
| MFTINPUTS                                           | MFT 樣式檔                             | .mft                           |
| MISCFONTS                                           | 不屬於其他類別的字型相關檔案                      |                                |
| MLBIBINPUTS, BIBINPUTS, TEXBIB                      | MlBibTeX 參考書目來源                     | .mlbib, .mlbib                 |
| MLBSTINPUTS, BSTINPUTS                              | MlBibTeX 樣式                         | .mlbst, .bst                   |
| MPINPUTS                                            | MetaPost 原始碼                        | .mp                            |
| MPPOOL, TEXMFINI                                    | MetaPost 程式字串                       | .pool                          |
| OCPINPUTS                                           | Omega 編譯後的處理檔                       | .ocp                           |
| OFMFONTS, TEXFONTS                                  | Omega 字型度量                          | .ofm, .tfm                     |
| OPENTYPEFONTS                                       | OpenType 字型                         |                                |
| OPLFONTS, TEXFONTS                                  | Omega 屬性清單                          | .opl                           |
| OTPINPUTS                                           | Omega 轉譯處理檔                         | .otp                           |
| OVFFONTS, TEXFONTS                                  | Omega 虛擬字型                          | .ovf                           |
| OVPFONTS, TEXFONTS                                  | Omega 虛擬屬性清單                        | .ovp                           |
| PDFTEXCONFIG                                        | PDFTeX 專用設定檔                        |                                |
| PROGRAMFONTS, PKFONTS, TEXPKS, GLYPHFONTS, TEXFONTS | 壓縮點陣字型                              | .pk                            |
| TEXPSHEADERS, PSHEADERS                             | 可下載的 PostScript                     | .pro                           |
| RISINPUTS                                           | RIS 參考書目檔，主要用於 Bibe                 | .ris                           |
| SFDFONTS                                            | 子字型定義檔                              | .sfd                           |
| TEXINPUTS                                           | TeX 原始碼                             | .tex                           |
| TEXDOCS                                             | TeX 系統的文件檔                          |                                |
| TEXSOURCES                                          | TeX 系統的原始檔                          |                                |
| TEXMFSCRIPTS                                        | 在 texmf 樹中散布的架構無關可執行檔               |                                |
| TEXPOOL, TEXMFINI                                   | TeX 程式字串                            | .pool                          |
| TFMFONTS, TEXFONTS                                  | TeX 字型度量                            | .tfm                           |
| TRFONTS                                             | Troff 字型                            |                                |
| TTFONTS                                             | TrueType 向量字型                       | .ttf, ,TTF, .ttc, .TTC, .dfont |
| T1FONTS, T1INPUTS, TEXPSHEADERS, DVIPSHEADERS       | Type 1 PostScript 外框字型              | .pfa, .pfb                     |
| T42FONTS                                            | Type 42 PostScript 外框字型             |                                |
| VFFONTS, TEXFONTS                                   | 虛擬字型                                | .vf                            |
| WEBINPUTS                                           | WEB 輸入檔                             | .web, .ch                      |
| WEB2C                                               | web2c 實作專用檔案                        |                                |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://overleaf-pro.ayaka.space/latex/zh-tw/shen-ru-wen-zhang/06-an-introduction-to-kpathsea-and-how-tex-engines-search-for-files.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.