🎒 終極導覽：Hugo.toml 駕駛艙全攻略 —— 從新手出航到極客調校

各位旅客請繫好安全帶！歡迎登上 Hugo 靜態網站旗艦特快車 🚄。

我是大家的隨車導遊。在 Hugo 的世界裡，不管你的主題多華麗、內容多豐富，整座網站的心臟與中樞神經全都在這一檔：hugo.toml（早期版本為 config.toml）。

很多新手只把它當成填寫網站名稱的地方，但對老司機來說，這裡藏著編譯管線、網址架構、隱私防護與自動影像暗房的全部機關。今天導遊把基礎配備與內行密技一次打包，帶大家從頭到尾徹底走一遍！👇

📍 第一站：身分證與航線座標（全域基礎設定）

這幾行是整個網站的立足之本，上線前務必反覆確認：

baseURL = 'https://example.com/'
languageCode = 'zh-tw'
title = '老司機的數位探險筆記'
theme = 'ananke'

# 內容閱讀節奏
paginate = 10
summaryLength = 70

• baseURL（絕對不能寫錯的門牌） 🗺️：網站上線後的正式網址。新手最常遇到的「本地預覽正常，一上線 CSS/圖片全爆」災情，九成都是因為這裡少填了結尾的斜線 / 或網址有誤。
• languageCode（語系廣播） 🌐：通知瀏覽器與搜尋引擎你的主語言，繁體中文填 zh-tw，對 SEO 與字元渲染至關重要。
• theme（外觀戰袍） 👕：指定 themes/ 資料夾中對應的主題資料夾名稱，大小寫必須分毫不差。
• **paginate & summaryLength** 📖：分別控制首頁每頁顯示的文章篇數，以及列表頁自動抓取的摘要字元長度。

🧭 第二站：選單指南針與百寶袋（導覽與自訂參數）

# 頂部導覽列
[menus]
  [[menus.main]]
    name = '首頁'
    url = '/'
    weight = 1

  [[menus.main]]
    name = '旅遊日誌'
    url = '/posts/'
    weight = 2

# 主題專屬擴充參數
[params]
  author = '探險家小明'
  description = '紀錄程式與旅行的極簡空間'
  darkMode = true

• weight（排隊號碼牌） 🔢：數字越小排越左邊。調整導覽列順序只要改數字，完全不用手動搬動模板代碼。
• [params]（客製化外掛區） 🧰：主題開發者放自訂變數的地方（如社群連結、作者資訊、深色模式切換）。換新主題時，直接參考該主題的 README.md 把設定複製過來即可。

📂 第三站：路徑自定義與安檢名單（建置輸出與忽略規則）

當網站需要接入 CI/CD（GitHub Actions、Cloudflare Pages、Vercel）或文章庫包含私密筆記時，這兩項設定是救命解藥：

# 靜態網站編譯目的地（預設是 public）
publishDir = 'dist'

# 每次編譯前自動清空目的地舊檔案
cleanDestinationDir = true

# 編譯安檢：利用正則表達式（Regex）直接無視特定檔案
ignoreFiles = [
  '\\.tmp$',
  '\\.bak$',
  'draft-notes/.*',
  'README\\.md$'
]

• publishDir 📦：很多部署平台預設吃 dist 或 build 資料夾，直接改這行，省去寫建置腳本搬移檔案的麻煩。
• cleanDestinationDir = true 🧹：編譯前自動大掃除，避免伺服器殘留已被刪除文章的 HTML 死連結。
• ignoreFiles 🕵️‍♂️：套上隱形斗篷，編輯器暫存檔或未公開筆記完全不參與編譯，既加速又防機密外洩。

🔗 第四站：網址結構手術刀與隱私防護罩（SEO & Privacy）

# 網址結尾是否強制加上 .html（預設 false 為漂亮目錄網址）
uglyURLs = false

# 批量定義分類網址結構
[permalinks]
  posts = '/posts/:year/:month/:slug/'

# 內建隱私合規與外連控制
[privacy]
  [privacy.googleAnalytics]
    anonymizeIP = true
    respectDoNotTrack = true
  [privacy.youtube]
    privacyEnhanced = true # 使用 youtube-nocookie.com 嵌入

• [permalinks] 🗺️：不用一篇篇手動改 front matter，全站的文章（posts）會自動依照發布年份與月份產出如 /posts/2026/08/my-post/ 的專業 SEO 結構。
• [privacy] 🕶️：開啟 privacyEnhanced 後，內嵌 YouTube 自動切換為無 Cookie 模式，提升載入速度並符合 GDPR 隱私法規。

📸 第五站：隨車暗房（[imaging] 圖片全域優化引擎）

當模板呼叫 .Resize、.Fill 或 .Process 進行動態轉圖時，這裡就是控制畫質、體積與裁切焦點的司令部：

[imaging]
  # 預設壓縮品質（0 - 100，80~85 為畫質與體積黃金平衡點）
  quality = 82

  # 縮放濾鏡：lanczos 細節最銳利，catmullrom 為平衡預設值
  resampleFilter = 'lanczos'

  # 智慧裁切錨點：自動辨識畫面重心與人臉，避免切到主體
  anchor = 'smart'

  # 背景填充顏色（PNG 轉 JPEG 補邊色）
  bgColor = '#ffffff'

  # EXIF 隱私清理
  [imaging.exif]
    disableLatLong = true # 🔒 自動抹除照片 GPS 經緯度，保護隱私

• quality = 82 ⚖️：兼顧肉眼高解析度與輕量化體積的最佳甜蜜點。
• resampleFilter = 'lanczos' 🔬：使用最高階插值演算法，讓縮圖邊緣依然清晰銳利。
• disableLatLong = true 🛡️：自動剔除手機照片中的定位資訊，防止訪客下載原圖抓取住家座標。

⚙️ 終點站：Markdown 引擎解鎖（Goldmark 渲染）

[markup]
  [markup.goldmark.renderer]
    unsafe = true # 允許在 Markdown 中直接渲染原生 HTML 標籤

• unsafe = true 🔓：Hugo 出於安全性考量預設會過濾 HTML。開啟此設定後，你在 Markdown 裡手寫的 <iframe>（嵌入影片/地圖）或自訂按鈕樣式才能正常呈現。

🎯 導遊總結：核心屬性全景速查表

把這套完整的駕駛艙設定放進你的專案，終端機敲下 hugo server -D，準備享受極速、穩定又專業的靜態網站體驗吧！🚀