CleanMyMac

從 WordPress 搬家到 Eleventy（11ty）：你一定會遇到的幾個注意事項整理

Feature image for 從 WordPress 搬家到 Eleventy（11ty）：你一定會遇到的幾個注意事項整理

WordPress 轉移到 Eleventy（11ty），表面上是「內容匯出＋Markdown 重建」，但實際動手後會發現，模板語法、網址結構、圖片路徑、建置流程，每一項都有細節要顧。

這篇文章不是介紹 11ty 是什麼，而是整理我在實際 migrate 過程中，真的踩到、也真的解掉的幾個坑。

目錄

Svelte 語法與 Nunjucks 衝突：為什麼會突然 build 失敗？

問題情境

如果你像我一樣，文章中會放一些 Svelte / 前端框架的範例碼，很快就會遇到這個錯誤：

  • {#if}
  • {#each}
  • {variable}

👉 11ty 會誤以為這是 Nunjucks 語法

導致：

  • build 直接報錯
  • 或輸出的 HTML 被吃掉一部分

解法：使用 {% raw %} 與 {% endraw %} 包起來

這是最直覺、也最安全的方法。

{% raw %}
{#if isOpen}
  <div class="menu">Hello</div>
{/if}
{% endraw %}

📌 適合情境

  • 教學文章
  • Code block 很多
  • 不想動全站設定

📌 缺點

  • 要記得包
  • 寫文章時稍微打斷思路

另一種解法：直接避開 Nunjucks

如果你某些文章 完全不需要 Nunjucks 功能，其實可以選擇「不讓它解析」。

在該篇 Markdown 的 frontmatter 加上：

templateEngineOverride: md

這代表：

  • 這篇文章 只用 Markdown
  • 不經過 Nunjucks 處理

📌 適合情境

  • 純技術筆記
  • 大量前端框架語法
  • 不需要 layout 邏輯的文章

📌 注意

  • {{ }}、{% %} 全都會被當純文字
  • 不適合需要動態資料的頁面

網址結構調整

預設行為的問題

使用官方 starter 或 blog 範例時，文章通常會變成：

/blog/your-article/

但很多從 WordPress 搬來的人會希望：

/your-article/

（尤其是原本就沒有 /blog/ 的站）

在文章的資料設定（例如 blog.11tydata.js）中加入：

permalink: "/{{ page.fileSlug }}/",

這樣產生的網址會是：

/article-name/

📌 建議

  • 搬家初期就決定好 URL 結構
  • 否則後面還要處理 redirect 與 SEO

圖片路徑一定會壞：WordPress 匯出後你要自己改

常見狀況

從 WordPress 匯出的 Markdown，圖片通常長這樣：

![](assets/image-6-OvqQDXqPWqL5.png)

但實際上你在 11ty starter 裡，圖片可能放在：

/img/

或你自己規劃的：

/src/img/

解法：統一調整成你實際的圖片目錄

例如我最後改成：

![](../img/image-6-OvqQDXqPWqL5.png)

📌 實戰建議

  • 不要照匯出的目錄走
  • 一開始就規劃好：
    • content
    • img
    • feature-images
  • 然後「全部改成一致」

（之後再加 eleventy-img 會輕鬆很多）

如何跳過不想 build 的文章（Draft 機制）

搬家時，很常會遇到：

  • 文章還沒整理完
  • 內容需要重寫
  • 只想先放著，不想出現在正式站

在 frontmatter 標記

本篇文章的 frontmatter 範例

---
title: 從 WordPress 搬家到 Eleventy（11ty）：你一定會遇到的幾個注意事項整理
description: 從 WordPress 搬家到 Eleventy 靜態網站生成器的完整指南，整理了遷移過程中常見的注意事項、坑洞與解決方案。包含內容匯出、圖片處理、前端框架整合等實戰經驗分享。
feature_image: "../img/feature-images/11ty-notes.png"
use_feature_split: false
feature_meta_text: WordPress 到 Eleventy 的遷移之旅
date: 2025-12-22T10:00:00.000Z
metadata:
  categories:
    - 架設網站
    - 靜態網站生成器
  type: wordpress-migration
  url: https://kamadiam.com/wordpress-to-eleventy-migration/
tags:
  - wordpress
  - eleventy
  - 11ty
  - 靜態網站
  - 網站搬家
  - 遷移指南
  - 前端開發
  - 網站優化
templateEngineOverride: md
---

最重要的只有這一行

templateEngineOverride: md

在 Eleventy 設定中統一處理 Draft

在 eleventy.config.js 中修改範例如下：

1️⃣ Preprocessor：正式環境直接不 build

eleventyConfig.addPreprocessor("drafts", "*", (data, content) => {
	if (data.draft) {
		data.title = `${data.title} (draft)`;
	}

	if (data.draft && process.env.NODE_ENV === "production") {
		return false;
	}
});

👉 開發環境看得到

👉 production 直接排除

2️⃣ Collection 排除 Draft

function getAllPosts(collectionApi) {
	return collectionApi
		.getFilteredByGlob('./content/blog/**/*.md')
		.filter(post => !post.data.draft);
}
eleventyConfig.addCollection("postsSorted", function (collectionApi) {
	return collectionApi
		.getFilteredByGlob('./content/blog/**/*.md')
		.filter(post => !post.data.draft)
		.reverse();
});

📌 好處

  • 不會出現在列表頁
  • 不會被 sitemap、RSS 收進去
  • 非常適合「搬家整理期」

結語：搬家不是一次性工作，而是一段整理過程

從 WordPress 搬到 Eleventy，最大的差別不是技術，而是控制權。

  • 你要自己決定 URL
  • 自己決定圖片結構
  • 自己決定什麼該被 build、什麼不該

但一旦整理完，整個網站會變得：

  • 輕
  • 可控
  • 而且長期維護成本極低

👉 如果你正在規劃 WordPress → 11ty

👉 或正卡在 migrate 的某個細節

這些注意事項，真的可以幫你少走很多冤枉路。

不要覺得 11ty 很麻煩，不同架構之間搬家本身就是麻煩事，尤其 WordPress 和 11ty 兩個設計概念完全天差地遠。

沒有最好的，只有最適合的。