Hugo 網站建置生命週期

Hugo 會從設定、掛載檔案、內容中繼資料、範本與資源建置網站。檔案位置是資料模型的一部分，因為它決定頁面類型、套件邊界與範本查找。

選取建置設定 #

hugo 命令會執行正式環境建置，除非 --destination 變更目標，否則寫入 public/。hugo server 會提供開發建置，並監看其相依性：

hugo --environment production
hugo server --environment development

環境預設值不同：hugo 使用 production，而 hugo server 使用 development。--environment 或 HUGO_ENVIRONMENT 會選取明確環境。專案可以使用一個如 hugo.toml 的設定檔、以逗號分隔的 --config 清單，或 config/_default/ 與 config/<environment>/ 下的分層檔案。較晚且更具體的設定會覆寫較早的設定，因此建置診斷應記錄命令與環境，而不只是儲存庫修訂版本。

模組掛載會在收集內容前解析。掛載可以將多個來源目錄組合成虛擬的 content、assets、static 或 layouts 樹；因此只檢查實體 content/ 目錄可能會遺漏建置輸入。

分類頁面、區段、分類法與資源 #

Hugo 會從檔案名稱與目錄結構推導頁面類型：

content/_index.md 提供首頁的內容與中繼資料。
區段目錄可以包含 _index.md，為該區段建立分支套件。
包含 index.md 的目錄是葉套件。其下的 Markdown 檔案是頁面資源，而不是獨立頁面。
其他內容檔案會成為其所屬區段內的普通頁面。
設定的分類法會從 front matter 產生分類法與術語頁面。

分支套件可以包含子頁面與區段。葉套件代表一個頁面及其資源，例如影像、資料或產生的檔案：

text

content/
  posts/
    _index.md
    canvas/
      index.md
      diagram.svg

posts/canvas/ 的頁面可以透過 .Page.Resources 解析 diagram.svg。static/ 下的檔案遵循不同路徑：Hugo 會將它們複製到目標，而不暴露為可處理頁面或全域資源。

從 Front Matter 與級聯建構頁面 #

Front matter 提供 title、date、draft、outputs、layout、type、分類法與自訂參數等欄位。Hugo 會將這些值與從路徑、語言、網站設定及 Git 中繼資料推導的預設值組合。

網站設定或分支套件的 _index.md 中的 cascade 會將 front matter 預設值提供給後代：

yaml

cascade:
  type: docs
  params:
    audience: developers

後代 front matter 可以覆寫級聯值。級聯也可以使用路徑、頁面類型、環境或語言的目標選取器。由於產生的頁面物件反映所有適用層，因此令人意外的 .Type 或 .Params 值應透過內容檔案與祖先級聯追蹤。

Hugo 也會在頁面建構期間關聯翻譯、別名、頁面資源、分類法術語與區段祖先。範本會使用完成的頁面圖，而不是獨立解析檔案。

轉換內容與渲染輸出 #

概念上的建置路徑如下：

載入設定、模組、資料、翻譯、範本與掛載檔案。
建立頁面與資源圖，包括區段與分類法。
解析內容、展開 shortcode，並呼叫 Markdown 渲染 hooks。
透過相符範本渲染每個啟用的輸出格式。
處理要求的資產，並發布渲染及靜態檔案。

範本評估可以延遲要求內容或資產轉換，因此這些階段是相依性，而不是內部 goroutine 順序的保證。shortcode 會在產生 .Content 時執行；周圍的頁面範本接著將該結果放入 HTML、RSS、JSON 或其他輸出。

輸出格式依網站與頁面類型設定。同一內容的頁面可以產生多個檔案：

yaml

outputs:
  home:
    - HTML
    - RSS
    - JSON

範本查找會考慮頁面類型、type、區段、layout、語言與輸出格式。HTML 單頁 layout 等格式專用範本不會自動提供 RSS 輸出。診斷意外後備方案時，使用具有範本指標或警告的 Hugo 執行，而不是假設一個硬編碼檔名。

考量快取與開發建置 #

Hugo 會快取下載的模組、遠端資源與已處理資產。資產指紋讓有效的快取結果可以重複使用，而範本或來源變更會使其相依項失效。resources/_gen/ 下的產生檔案可以在專案刻意使用該快取時提交或於 CI 還原，但它們是衍生成品而不是來源內容。

hugo server 會將相依性圖保留在記憶體中，監看變更，並使用快速渲染行為重建互動式開發所需的頁面。它通常從記憶體提供內容，而不是重現 public/ 中的確切檔案。需要完整開發環境重新渲染時，使用 --disableFastRender；只有在檢查磁碟上的伺服器輸出時才使用 --renderToDisk。

乾淨的正式建置仍是發布檢查，因為開發快取與增量渲染可能隱藏未宣告的相依性：

hugo --gc --cleanDestinationDir --environment production

--cleanDestinationDir 會移除目標中 Hugo 在目前建置未產生的檔案，而 --gc 會移除未使用的快取項目。兩個選項都不會修復錯誤的內容分類或範本查找；那些行為取決於專案結構與設定。