Eleventy (11ty) 入門：從零架設靜態網站

想做一個部落格，卻不想先養一台伺服器、設定資料庫，再和一堆後台登入畫面培養感情嗎？Eleventy（通常簡稱 11ty）可以把 Markdown、HTML 或其他模板檔案轉成靜態網站，讓你把心力放在內容上。

這篇會帶你從建立專案、安裝 11ty、產生第一個頁面，到啟動本機預覽與部署。你也會知道 11ty 的目錄與建置流程在做什麼，而不是只複製貼上指令，然後祈禱終端機不要突然開始說外星文。

Eleventy（11ty）是什麼？
為什麼選 11ty？
開始前：準備 Node.js
Step 1：建立專案目錄
Step 2：安裝 Eleventy
Step 3：建立第一個頁面
Step 4：執行建置
Step 5：啟動即時預覽
了解最基本的目錄與建置流程
Step 6：把常用指令寫進 package.json
Step 7：部署靜態網站
常見部署方式
11ty 和 Hugo 怎麼選？
總結：先做出一頁，再逐步長大
參考資料

Eleventy（11ty）是什麼？

Eleventy 是一個靜態網站生成器（static site generator，SSG）。它會讀取你寫好的內容與模板，經過建置後輸出 HTML、CSS、JavaScript 等靜態檔案。

「靜態」不代表網站只能放一張不會動的海報。它代表頁面通常在建置階段就先產生好；訪客請求頁面時，伺服器可以直接送出檔案，不必每次都重新查詢資料庫、組合模板。

Eleventy 本身是 JavaScript 專案，但你不必只用 JavaScript 寫文章。官方文件列出的模板語言包含 HTML、Markdown、Liquid、Nunjucks、Handlebars、Mustache、EJS、Haml、Pug 等。你可以選自己熟悉的格式，也可以在同一個專案逐步混用。

為什麼選 11ty？

11ty 下載統計截圖看看這個下載統計圖，大家的選擇應該沒什麼問題。

1. 預設設定少，保留彈性

Eleventy 不要求你先接受一套很厚的應用程式框架。小型網站可以從幾個檔案開始，需要時再加入資料檔、模板、集合（collections）或插件。

這種「先能跑，再慢慢長大」的方式很適合部落格、文件網站、作品集與活動頁面。網站不會因為今天只新增一篇文章，就先要求你召開架構評審會。

2. 輸出適合靜態託管

建置完成後，主要成果就是一批靜態檔案。你可以把輸出目錄交給支援靜態檔案的託管服務，實際部署方式則依服務商的設定而定。

這也讓 CDN、快取與版本控制比較容易搭配。當然，網站若需要會員登入、即時資料或購物車，仍可能需要另外接 API 或伺服器服務；靜態網站不是魔法，只是把一部分工作提前做完。

3. 內容與模板可以分開

你可以把文章放在 Markdown，把共用的頁首、頁尾與版面放在模板，再用資料檔管理網站設定。日後修改網站標題時，不需要拿著放大鏡在每篇文章裡搜尋。

開始前：準備 Node.js

Eleventy v3 需要 Node.js 18 或更新版本。請先在終端機確認版本：

node --version

如果版本太舊，請先依照 Node.js 官方網站的說明安裝或更新。版本符合後，再進行下面的專案設定。

Step 1：建立專案目錄

先建立一個可以隨時刪除的練習目錄，避免把測試檔案和正式網站混在一起：

mkdir try-11ty
cd try-11ty

接著初始化 Node.js 專案。使用 npm 可以執行：

npm init -y

如果你慣用 pnpm，則可以執行：

pnpm init

npm init -y 會使用預設值建立 package.json；pnpm init 則會依 pnpm 的流程建立專案設定。兩者都能完成初始化，挑你平常喝咖啡時比較順手的那杯就好。

Step 2：安裝 Eleventy

把 Eleventy 安裝為開發依賴。使用 npm：

npm install --save-dev @11ty/eleventy

使用 pnpm：

pnpm add --save-dev @11ty/eleventy

--save-dev 表示這是開發與建置階段會用到的套件。安裝完成後，package.json 的 devDependencies 應該會出現 @11ty/eleventy。

這篇不硬寫一個可能過時的版本號。Eleventy 會持續更新，實際安裝到的版本應以你的 package.json 與 lockfile 為準；若要鎖定或升級版本，請查看官方安裝文件與套件管理器的結果。

Step 3：建立第一個頁面

Eleventy 可以直接處理 HTML 和 Markdown。先建立一個 Markdown 檔案 index.md：

# 我的第一個 11ty 頁面

這是用 Markdown 寫的內容。

也可以建立一個簡單的 HTML 檔案 about.html：

<!doctype html>
<html lang="zh-Hant">
<head><meta charset="UTF-8"><title>第一個 11ty 網頁</title></head>
<body><p>第一個 11ty 網頁</p></body>
</html>

預設情況下，Eleventy 會處理專案中的模板檔案，並把結果輸出到 _site。

Step 4：執行建置

使用 pnpm 執行本地安裝的 Eleventy：

pnpm exec eleventy

使用 npm 則可以執行：

npx @11ty/eleventy

建置完成後，查看 _site 目錄：

ls _site

你應該能看到由輸入檔案產生的結果，例如 index.html 與 about.html。_site 是建置產物，不是你平常編輯文章的地方；原始檔留在專案目錄，產物則交給部署流程。

Eleventy 建置成功輸出範例

如果終端機顯示沒有產生檔案，先確認檔案副檔名、所在目錄與 Eleventy 設定。沒有輸入檔案時，看到 Wrote 0 files 並不奇怪，Eleventy 只是很誠實地告訴你：「今天沒有工作。」

Eleventy 建置時尚無輸入檔案的範例

Step 5：啟動即時預覽

每次修改文章都手動建置，幾次之後連咖啡都要替你嘆氣。啟動 Eleventy 的開發伺服器：

pnpm exec eleventy --serve

也可以使用簡寫：

pnpm exec eleventy -s

Eleventy 會監聽檔案變更並重新建置，終端機會顯示本機預覽網址。打開它，就能在瀏覽器查看網站。

如果需要指定埠號，可以使用 --port：

pnpm exec eleventy --serve --port=3000

Eleventy 開發伺服器範例

只想監聽並重新建置、不需要 Eleventy 提供開發伺服器時，可以使用 --watch：

pnpm exec eleventy --watch

了解最基本的目錄與建置流程

剛開始接觸 SSG 時，最容易把「輸入」和「輸出」搞混。可以先記住這條流程：

內容與模板 → Eleventy 建置 → _site 靜態檔案 → 靜態託管服務

輸入檔案

輸入檔案就是你實際編輯的內容，例如：

Markdown：文章與文件
HTML：不需要模板處理的頁面
Nunjucks、Liquid 等模板：共用版面與元件
JSON、JavaScript、YAML 等資料檔：網站資料

Eleventy 會依副檔名決定如何處理檔案；若要改變輸入或輸出目錄，可以在設定檔或 CLI 參數中指定。不要直接修改 _site 裡的檔案，因為下一次建置時它們可能會被重新產生。

模板與佈局

當網站不只一頁時，把完整 HTML 複製貼上到每篇文章會很快失控。模板與佈局可以集中管理 <head>、導覽列、頁尾等共用內容，文章只需要維護自己的正文。

Eleventy 的模板語言各有語法與功能，初學時不必一次學完所有選項。先選一種你看得懂的格式，把文章、共用版面與資料拆開，已經足以做出很實用的網站。

Collections 與資料

Eleventy 的 collections 可以把多個內容項目整理成一組，常見用途是文章列表、分類頁與標籤頁。資料檔則適合放網站名稱、作者資訊或導覽設定。

這些功能不必在第一天全部加入。先讓一篇文章成功輸出，再逐步抽出重複內容，通常比一開始就打造「未來可擴充到月球」的架構更容易維護。

Step 6：把常用指令寫進 package.json

為了不用每次都輸入完整指令，可以在 package.json 加入 scripts：

{
	"scripts": {
		"build": "eleventy",
		"start": "eleventy --serve"
	}
}

之後就能使用：

pnpm run build
pnpm run start

如果你使用 npm，對應指令是：

npm run build
npm run start

指令名稱可以依專案習慣調整；重要的是讓團隊知道哪個指令負責建置、哪個負責本機預覽。名稱統一，少一點「你那台可以跑嗎？」的辦公室靈異事件。

Step 7：部署靜態網站

部署前先執行正式建置：

pnpm run build

接著把輸出目錄中的內容交給你的靜態託管服務。不同服務的建置指令、輸出目錄、網域與重新導向設定不同，請依該服務的官方文件設定；Eleventy 的部署文件也整理了常見方向。

不論使用哪個平台，都可以先檢查：

建置是否成功完成。
_site 是否包含首頁與文章頁。
圖片、CSS、JavaScript 的路徑是否正確。
直接開啟頁面時，沒有把原始 Markdown 當成公開內容。
網站在手機與桌面寬度下都能閱讀。

部署的是建置後的檔案，不是整個原始專案。除非託管服務採用「從 Git 儲存庫自動建置」的模式，否則不要把 _site 裡的檔案和原始碼的角色混在一起。

常見部署方式

Eleventy 官方文件整理了多種靜態網站託管服務，以下是部分常見選項（圖片來源：Eleventy 官網）：

靜態網站託管平台列表

Git 儲存庫自動建置

許多託管服務可以連接 Git 儲存庫，在你推送變更後自動執行建置，再發布 _site。這種方式適合需要持續更新的部落格，因為每次部署都有提交紀錄可追蹤。

你需要在服務的專案設定中填寫類似以下資訊：

安裝依賴的指令，例如 pnpm install
建置指令，例如 pnpm run build
建置輸出目錄，例如 _site

實際欄位名稱和 pnpm 支援方式，請以該平台官方文件為準。

手動上傳

如果使用傳統虛擬主機或檔案管理器，可以先在本機建置，再上傳 _site 目錄裡的檔案。注意是上傳「裡面的內容」，而不是把整個 _site 當成網站根目錄再多包一層。

若網站部署在子目錄，還要確認資源路徑與網址前綴的設定。首頁能開不代表 CSS 一定找得到；網頁有時候只是很會假裝沒事。

例如使用虛擬主機的檔案管理器，可以先建立目錄，再把 _site 目錄裡的檔案上傳上去：

虛擬主機檔案管理器建立目錄

上傳完成後，在瀏覽器開啟網址就能查看成果：

部署後的 HTML 頁面預覽

部署後的 Markdown 頁面預覽

11ty 和 Hugo 怎麼選？

11ty 與 Hugo 都能用來建立靜態網站，但工作方式與生態系不同。Hugo 是以 Go 撰寫的工具；11ty 則建立在 JavaScript／Node.js 生態系上。選擇時可以從自己熟悉的工具、模板需求與團隊部署流程出發。

如果你已經熟悉 JavaScript、Node.js 或 Nunjucks，11ty 通常比較容易融入現有前端工具鏈。如果你偏好單一可執行檔、希望使用 Hugo 的模板與內容管理方式，Hugo 也值得評估。

不要只因為某個工具在排行榜上看起來很威風就選它。真正重要的是：你能不能順利寫文章、建置、部署，並在三個月後還看得懂自己的設定檔。工具會變，維護能力比較長壽。

總結：先做出一頁，再逐步長大

到這裡，你已經走過一個最小的 11ty 流程：

準備符合需求的 Node.js。
建立 Node.js 專案。
安裝 @11ty/eleventy。
用 Markdown 或 HTML 建立輸入檔案。
執行建置，查看 _site。
用 --serve 啟動本機預覽。
把建置結果部署到靜態託管服務。

接下來可以學習模板與佈局、資料檔、collections、分頁、短代碼與插件。建議一次只加入一個概念，先觀察建置結果，再繼續擴充。這樣遇到問題時，才知道是哪一杯咖啡打翻了。

如果你想繼續深入，先從 Eleventy 官方文件的 Getting Started、Configuration 與 Languages 章節開始。讀完再回頭整理自己的專案，通常比盲目複製一整套 starter 更容易建立真正的理解。

參考資料

Eleventy 官方文件：查閱 Eleventy 的安裝、建置與核心概念。
Eleventy Getting Started：官方快速入門流程與基本專案設定。
Eleventy 使用方式：查閱 CLI 建置、--serve 與 --watch 等指令。
Eleventy 設定檔：查閱輸入目錄、輸出目錄與專案設定方式。
Eleventy 模板語言：查閱支援的內容與模板格式。
Eleventy 部署：查閱將建置結果部署到託管服務的官方說明。
Node.js 官方網站：下載 Node.js 並查閱目前版本資訊。