你還在用手動上傳 HTML 檔案、或是每個月花幾百塊租虛擬主機嗎？

今天我要教你一個超實用的技巧：用 Docker 在五分鐘內把 Hugo 靜態網站架起來。
不管你是想寫個人部落格、公司官網，還是專案文件頁面，這招都能讓你省下至少五小時的設定時間，而且完全免費、搬家超簡單。

Hugo 是目前最快的靜態網站產生器之一，搭配 Docker 容器化技術，你可以在任何電腦、任何雲端主機上，用一模一樣的環境跑起來。
這篇文章會從零開始，帶你一步一步完成。放心，你不需要很懂程式，只要會複製貼上指令就夠了。

為什麼要學這招？｜省時省錢又省心

先講個真實故事。
我有一位在香港做 freelancer 的朋友，之前幫客戶做一個小型公司官網。客戶要求用 WordPress，每個月主機費要 HK$200 多，還要定期更新外掛、處理資安漏洞。
結果不到半年，客戶嫌維護麻煩，乾脆把網站關了。

後來我用 Hugo + Docker 幫他重做一個靜態網站，主機費直接歸零（放在 GitHub Pages 或 Cloudflare Pages 上），更新內容只要改一個 Markdown 檔案，重新跑一次 Docker 指令就搞定。

這就是這招的威力：

  • 零主機成本：靜態網站可以免費託管在 GitHub、Netlify、Cloudflare 上。
  • 環境一致：你在 Mac、Windows、Linux 上都能用同樣的 Docker 映像檔，不會有「在我電腦跑得好好的」這種問題。
  • 速度超快：Hugo 產生靜態頁面只要幾毫秒，用戶載入網站幾乎不用等。

第一步：安裝 Docker｜你的萬能工具箱

在開始之前，你需要一個工具：Docker Desktop。

如果你用的是 Windows，請下載 Docker Desktop for Windows，並確認 WSL 2 已啟用。
如果是 macOS（Intel 或 Apple Silicon 都行），直接下載 Docker Desktop for Mac。
Linux 使用者則用 apt 或 yum 安裝 docker 和 docker-compose。

安裝完成後，打開終端機（Terminal），輸入以下指令測試是否成功：

docker --version

如果看到類似 Docker version 27.0.3 的訊息，代表安裝成功。

💡 小提示：如果你在香港或台灣，下載 Docker 映像檔時可能會比較慢。建議在 Docker Desktop 設定中，把 Registry 鏡像改成 mirror.gcr.io 或 dockerproxy.com，速度會快很多。

第二步：建立 Hugo 專案｜五分鐘內搞定

現在我們要建立一個 Hugo 網站專案。
打開終端機，建立一個新資料夾，然後進入該資料夾：

mkdir my-hugo-site
cd my-hugo-site

接著，用 Docker 執行 Hugo 指令來初始化網站。
這一步會自動下載 Hugo 的 Docker 映像檔，並在當前資料夾中建立網站骨架：

docker run --rm -v $(pwd):/src -u $(id -u):$(id -g) \
  klakegg/hugo:latest new site . --force

參數說明：

  • --rm：執行完後自動刪除容器，不留垃圾。
  • -v $(pwd):/src：把當前資料夾掛載到容器內的 /src，這樣產生的檔案會直接留在你的電腦上。
  • -u $(id -u):$(id -g)：用你當前的使用者權限執行，避免檔案權限問題。

執行後，你會看到資料夾裡多了這些東西：

  • archetypes/：文章模板
  • content/：你的文章放這裡
  • layouts/：自訂版面
  • config.toml：網站設定檔

第三步：挑選與安裝主題｜讓網站變漂亮

Hugo 有上千個免費主題，我推薦用 PaperMod，簡潔、速度快、支援黑暗模式。

首先，把主題下載到 themes/ 資料夾：

git clone https://github.com/adityatelange/hugo-PaperMod themes/PaperMod

然後編輯 config.toml，在檔案末尾加上這行：

theme = "PaperMod"

你也可以用其他主題，只要把 GitHub 網址換掉就行。
安裝完主題後，就可以開始寫文章了。

第四步：寫第一篇文章｜用 Markdown 就搞定

在 content/posts/ 資料夾裡，建立一個 Markdown 檔案，例如 my-first-post.md：

---
title: "我的第一篇 Hugo 文章"
date: 2026-05-20
draft: false
---

哈囉！這是我用 Docker 和 Hugo 建立的第一篇文章。  
靜態網站超快、超安全，而且完全免費！

Hugo 使用 Markdown 語法，你不需要學 HTML，只要用 # 標題、** 粗體、- 列表，就能寫出結構清晰的文章。

第五步：在本機預覽網站｜即時看到效果

想看看網站長怎樣？執行以下指令啟動 Hugo 開發伺服器：

docker run --rm -v $(pwd):/src -p 1313:1313 \
  klakegg/hugo:latest server

打開瀏覽器，輸入 http://localhost:1313，你就會看到網站了！
而且 Hugo 支援即時重新載入：你修改任何檔案，瀏覽器會自動更新，不用手動重整。

第六步：產生靜態檔案｜準備上線

當你寫完文章、調整好設定，最後一步是產生靜態 HTML 檔案：

docker run --rm -v $(pwd):/src \
  klakegg/hugo:latest

這會在 public/ 資料夾裡產生所有靜態檔案。
把這個資料夾的內容上傳到 GitHub Pages、Netlify 或 Cloudflare Pages，你的網站就正式上線了！

以 GitHub Pages 為例，只要把 public/ 推送到 gh-pages 分支，GitHub 會自動幫你託管。

實戰技巧｜讓網站更快、更安全

技巧一：用 Docker Compose 簡化指令

每次都打一串 docker run 指令很麻煩。建立一個 docker-compose.yml 檔案：

version: '3'
services:
  hugo:
    image: klakegg/hugo:latest
    command: server
    volumes:
      - .:/src
    ports:
      - "1313:1313"

之後只要輸入 docker-compose up 就能啟動開發伺服器，超方便。

技巧二：自動化部署

如果你用 GitHub，可以設定 GitHub Actions，每次推送到主分支時自動產生靜態檔案並部署。
這部分比較進階，但學會後你連手動上傳都不用了。

技巧三：加入搜尋功能

Hugo 原生不支援搜尋，但你可以用 Lunr.js 或 Pagefind 加上客戶端搜尋。
Pagefind 特別好用，只要在產生靜態檔案後執行一次指令，它會自動建立搜尋索引。

總結｜你已經學會了！

今天你學會了：

  1. 安裝 Docker 並確認環境正常
  2. 用 Docker 建立 Hugo 網站專案
  3. 安裝主題並寫第一篇文章
  4. 在本機預覽和產生靜態檔案
  5. 實戰技巧讓工作流程更順暢

現在就去試試看吧！五分鐘後，你就會擁有自己的網站。
如果你在過程中遇到問題，別擔心，下面的常見問題區已經整理好最常發生的狀況。

延伸閱讀

常見問題

Q: 為什麼執行 docker run 時出現權限錯誤？
A: 這是因為 Docker 容器預設用 root 執行，產生的檔案會屬於 root。解決方法是在指令中加入 -u $(id -u):$(id -g)，如文章中所示，這樣檔案就會屬於你目前的使用者。

Q: 我在 Windows 上用 PowerShell，$(pwd) 沒作用怎麼辦？
A: PowerShell 使用 ${PWD} 而不是 $(pwd)。請將指令中的 $(pwd) 改成 ${PWD}，例如：docker run --rm -v ${PWD}:/src ...。

Q: Hugo 網站可以放在香港或台灣的免費主機上嗎？
A: 可以！GitHub Pages、Netlify 和 Cloudflare Pages 都支援香港和台灣的用戶，而且速度不錯。Cloudflare Pages 在亞洲節點尤其快，推薦使用。

Q: 我安裝的主題沒有顯示圖片或樣式壞掉？
A: 這是因為 config.toml 中的 baseURL 設定不正確。在開發階段，請設為 baseURL = "/"；上線前再改成你的網域名稱，例如 baseURL = "https://你的網站.com"。

Q: 如何更新 Hugo 版本？
A: 只要更新 Docker 映像檔即可：docker pull klakegg/hugo:latest。之後再執行 docker run 時就會使用最新版本。

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "為什麼執行 docker run 時出現權限錯誤？",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "這是因為 Docker 容器預設用 root 執行，產生的檔案會屬於 root。解決方法是在指令中加入 -u $(id -u):$(id -g)，這樣檔案就會屬於你目前的使用者。"
      }
    },
    {
      "@type": "Question",
      "name": "我在 Windows 上用 PowerShell，$(pwd) 沒作用怎麼辦？",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "PowerShell 使用 ${PWD} 而不是 $(pwd)。請將指令中的 $(pwd) 改成 ${PWD}，例如：docker run --rm -v ${PWD}:/src ...。"
      }
    },
    {
      "@type": "Question",
      "name": "Hugo 網站可以放在香港或台灣的免費主機上嗎？",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "可以！GitHub Pages、Netlify 和 Cloudflare Pages 都支援香港和台灣的用戶，而且速度不錯。Cloudflare Pages 在亞洲節點尤其快，推薦使用。"
      }
    },
    {
      "@type": "Question",
      "name": "我安裝的主題沒有顯示圖片或樣式壞掉？",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "這是因為 config.toml 中的 baseURL 設定不正確。在開發階段，請設為 baseURL = \"/\"；上線前再改成你的網域名稱，例如 baseURL = \"https://你的網站.com\"。"
      }
    },
    {
      "@type": "Question",
      "name": "如何更新 Hugo 版本？",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "只要更新 Docker 映像檔即可：docker pull klakegg/hugo:latest。之後再執行 docker run 時就會使用最新版本。"
      }
    }
  ]
}
</script>