光輝咖碼

CSS Border-radius 指南, 不是只能畫圓角

2026-01-10T00:00:00Z

border-radius 通常用來做這些事：
按鈕變圓一點
卡片看起來柔和一點
border-radius: 50% 畫一個圓
其實它還能做更多： border-radius 其實是一個「形狀語言」
試試看下面這個實驗，你會發現很多「看起來很設計感的形狀」，其實只是 CSS。

為什麼要重新認識 border-radius？

在現代 UI 裡，圓角早就不是裝飾，而是結構的一部分：

設計系統會定義 radius token（sm / md / lg），確保視覺一致性
元件之間的「柔軟程度」需要一致，影響整體品牌感受
不同裝置尺寸下，圓角感覺要穩定，避免在小螢幕上過於突兀

border-radius 其實有很多實用功能，但可能比較少被注意到。

這篇文章會介紹：

✅ 它的「計算模型」和瀏覽器行為
✅ 斜線語法，用來創造有機形狀
✅ 瀏覽器什麼時候會自動調整值，以及為什麼
✅ 如何有意識地設計形狀，而不只是「試試看哪個值好看」
✅ 常見的實戰技巧和需要注意的地方

border-radius 的基本語法

一個值

/* 最簡單的用法：四個角使用相同的半徑值
 * 適合：統一的設計風格，快速原型開發 */
border-radius: 12px;

12px

👉 四個角都一樣，最常用也最簡單。

兩個、三個、四個值的規則

兩個值：

/* 對角線模式：第一個值給左上和右下，第二個值給右上和左下
 * 適合：創造對角線節奏，增加視覺動感 */
border-radius: 8px 16px;

8px 16px

實際展開是：

左上 / 右下 → 8px（對角線）
右上 / 左下 → 16px（對角線）

三個值：

/* 不對稱模式：左上獨立，右上和左下相同，右下獨立
 * 適合：創造「方向感」，引導視線流向 */
border-radius: 8px 16px 24px;

8px 16px 24px

實際展開是：

左上 → 8px（獨立值）
右上 / 左下 → 16px（共享值）
右下 → 24px（獨立值）

四個值：

順序永遠是：左上 → 右上 → 右下 → 左下（順時針）

/* 完全控制模式：每個角都可以獨立設定
 * 適合：精細的設計調整，創造複雜的視覺節奏
 * 記憶技巧：從左上開始，順時針方向 */
border-radius: 8px 12px 20px 4px;

8px 12px 20px 4px

💡 小提醒：如果視覺效果不如預期，可能是角順序記錯了。記住：從左上開始，順時針方向！

單位很重要：px vs %

px：固定幾何

/* 固定像素值：無論元素大小如何變化，圓角半徑都保持不變
 * 適合：按鈕、卡片等需要「一致視覺大小」的元件 */
border-radius: 24px;

24px

特點：

✅ 不會隨容器比例變
✅ 適合元件設計（button / card）- 保證一致的視覺大小
✅ 在設計系統中容易維護（固定的 token 值）

%：相對於「盒子尺寸」

/* 百分比值：相對於元素自己的寬度和高度計算
 * 50% 表示：水平半徑 = 寬度的 50%，垂直半徑 = 高度的 50% */
border-radius: 50%;

50%

50% (長方形)

重點不是「50% 很圓」，而是：

百分比是根據「盒子自己的寬高」算的

正方形 → 圓（因為寬高相等）
長方形 → 膠囊（pill）（因為寬高不同）

實用技巧：

📌 為什麼有些人會用 9999px？

因為無論元素多大，9999px 都保證會讓元素變成最大可能的圓角（通常就是圓形或膠囊形）。這是一個「懶人技巧」，但要注意：

✅ 優點：不需要計算，總是最大圓角
⚠️ 缺點：不夠語義化，在設計系統中不推薦

/ 斜線語法：border-radius 的真正威力

這個語法比較少被提到，但它是創造「有機形狀」的關鍵。

/* 斜線語法：分開控制水平和垂直半徑
 * 格式：水平半徑 / 垂直半徑
 * 這個例子：所有角的水平半徑是 40px，垂直半徑是 20px */
border-radius: 40px / 20px;

40px / 20px

代表：

水平方向半徑：40px（X 軸）
垂直方向半徑：20px（Y 軸）

關鍵理解： 每個角其實是一段橢圓弧，不是圓弧。 當水平和垂直半徑不同時，就會形成橢圓形的圓角，這是創造各種有機形狀的基礎。

完整語法

/* 完整語法：8 個值控制 4 個角的 X 和 Y 半徑
 * a b c d：四個角的 X 軸（水平）半徑
 * e f g h：四個角的 Y 軸（垂直）半徑
 * 順序：左上 → 右上 → 右下 → 左下（順時針） */
border-radius: a b c d / e f g h;

/ 前：X 軸半徑（水平方向）
/ 後：Y 軸半徑（垂直方向）
每個角都可以獨立控制，創造無限可能

X軸: a b c d
Y軸: e f g h

📌 這就是很多「有機形狀」的來源。

瀏覽器其實會「偷偷修正」你的 radius

如果你這樣寫：

width: 100px;
height: 50px;
/* 你設定了 80px，但元素寬度只有 100px */
border-radius: 80px;

會發生什麼？

實際上：

瀏覽器會自動 clamp（限制）半徑值
確保圓角不會超過元素尺寸的一半
在這個例子中，實際生效的是 50px（高度的一半）

這個行為是 CSS 規範中的正常機制，不是 bug。

計算規則：

水平半徑不能超過 width / 2
垂直半徑不能超過 height / 2
如果超過，瀏覽器會自動縮放兩個半徑，保持比例

💡 實用技巧：當你輸入很大的 radius 值時，畫面看起來「卡住不動」，是因為瀏覽器已經自動調整到最大可能值了。如果你想要「最大圓角」，直接設定一個很大的值（如 9999px）即可。

設計感十足的圓角應用

1. 膠囊按鈕 - 現代 UI 的經典

<button class="capsule-button">立即下載</button>

.capsule-button {
  /* 內距：垂直 12px，水平 24px，創造舒適的點擊區域 */
  padding: 12px 24px;
  border: none;
  
  /* 關鍵技巧：使用固定 px 值，約為按鈕高度的一半
   * 這樣可以創造完美的膠囊形狀，不受文字長度影響
   * 如果使用 50%，在按鈕寬度變化時會變成橢圓形 */
  border-radius: 25px;
  
  /* 漸層背景增加視覺吸引力 */
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  color: white;
  font-weight: 500;
  
  /* 陰影增加深度感，顏色與背景色調一致 */
  box-shadow: 0 4px 15px rgba(102, 126, 234, 0.4);
  
  /* 平滑過渡效果，讓互動更自然 */
  transition: all 0.3s ease;
  cursor: pointer;
}

.capsule-button:hover {
  /* 微妙的向上移動，創造「浮起」的視覺效果 */
  transform: translateY(-2px);
  
  /* hover 時增強陰影，強化浮起感 */
  box-shadow: 0 8px 25px rgba(102, 126, 234, 0.6);
}

2. 不對稱設計卡片 - 創造視覺層次

<div class="asymmetric-card">
  <div class="card-title">不對稱設計</div>
  <p>利用不同大小的圓角創造視覺節奏，讓設計更有個性和現代感。</p>
</div>

.asymmetric-card {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  
  /* 不對稱圓角模式：左上/右下大，右上/左下小
   * 順序：左上 → 右上 → 右下 → 左下（順時針）
   * 這種模式創造出「對角線節奏」，比完全對稱更有動感 */
  border-radius: 20px 8px 20px 8px;
  
  padding: 24px;
  
  /* 柔和的陰影，顏色與背景呼應 */
  box-shadow: 0 8px 32px rgba(102, 126, 234, 0.3);
  color: white;
}

.card-title {
  margin: 0 0 12px 0;
  color: white;
  font-size: 18px;
  font-weight: 600;
}

.asymmetric-card p {
  margin: 0;
  /* 使用 rgba 而非 opacity，避免影響子元素 */
  color: rgba(255, 255, 255, 0.9);
  line-height: 1.5;
  font-size: 14px;
}

不對稱設計

利用不同大小的圓角創造視覺節奏，讓設計更有個性和現代感。

3. 漸層背景 + 圓角 - 創造深度感

<div class="gradient-depth-card">
  <div class="card-title">漸層深度效果</div>
  <p>結合漸層背景和微妙的邊框效果，創造出立體的視覺深度。</p>
</div>

.gradient-depth-card {
  /* 三色漸層：從藍紫到粉紫，創造豐富的視覺層次 */
  background: linear-gradient(135deg,
    #667eea 0%,
    #764ba2 50%,
    #f093fb 100%);
  
  /* 統一的圓角，讓整體更和諧 */
  border-radius: 16px;
  padding: 20px;
  
  /* 相對定位，讓 ::after 偽元素可以絕對定位 */
  position: relative;
  color: white;
  
  /* 深色陰影增加立體感 */
  box-shadow: 0 10px 40px rgba(102, 126, 234, 0.3);
}

.gradient-depth-card::after {
  content: '';
  position: absolute;
  
  /* inset: 0 等同於 top: 0; right: 0; bottom: 0; left: 0;
   * 讓偽元素完全覆蓋父元素 */
  inset: 0;
  
  /* 重要：繼承父元素的圓角，確保邊框也跟著圓角 */
  border-radius: 16px;
  
  /* padding 創造邊框的「厚度」 */
  padding: 2px;
  
  /* 半透明白色漸層，模擬高光效果 */
  background: linear-gradient(135deg, rgba(255,255,255,0.2), rgba(255,255,255,0.05));
  
  /* mask 技巧：只顯示邊框區域，隱藏中間內容
   * content-box 只顯示 padding 區域（即邊框）
   * exclude 模式讓邊框區域可見，內容區域透明 */
  mask: linear-gradient(#fff 0 0) content-box, linear-gradient(#fff 0 0);
  mask-composite: exclude;
}

.card-title {
  margin: 0 0 12px 0;
  font-size: 18px;
  font-weight: 600;
}

.gradient-depth-card p {
  margin: 0;
  opacity: 0.9;
  line-height: 1.5;
  font-size: 14px;
}

漸層深度效果

結合漸層背景和微妙的邊框效果，創造出立體的視覺深度。

4. 動畫過渡 - 互動體驗

<div class="interactive-morph">Hover Me</div>

.interactive-morph {
  width: 120px;
  height: 120px;
  
  /* 對角漸層，從紅到青，視覺對比強烈 */
  background: linear-gradient(45deg, #ff6b6b, #4ecdc4);
  
  /* 初始狀態：小圓角 */
  border-radius: 20px;
  
  /* 關鍵：只對 border-radius 做動畫，使用緩動函數
   * cubic-bezier(0.4, 0, 0.2, 1) 是 Material Design 的標準緩動
   * 創造出「先快後慢」的自然動畫效果 */
  transition: border-radius 0.6s cubic-bezier(0.4, 0, 0.2, 1);
  
  cursor: pointer;
  display: flex;
  align-items: center;
  justify-content: center;
  color: white;
  font-weight: bold;
  box-shadow: 0 8px 32px rgba(255, 107, 107, 0.3);
}

.interactive-morph:hover {
  /* hover 時變成大圓角（接近圓形）
   * 因為元素是正方形，60px 約等於寬度的一半，形成圓形 */
  border-radius: 60px;
  
  /* 同時放大，增強互動感 */
  transform: scale(1.1);
}

Hover Me

滑鼠移到上面看看動畫效果

5. 多層次圓角設計

<div class="layered-design">
  <div class="inner-content">
    <div class="accent-element"></div>
    <div class="card-title">多層次設計</div>
    <p>不同大小的圓角創造視覺層次，讓介面更有深度和趣味。</p>
  </div>
</div>

.layered-design {
  /* 外層：大圓角，作為容器的「框架」 */
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  border-radius: 24px;
  
  /* padding 創造內外層之間的「間隙」 */
  padding: 16px;
  position: relative;
  color: white;
}

.inner-content {
  /* 內層：較小的圓角，形成層次對比
   * 24px vs 16px 的差異創造視覺深度 */
  background: rgba(255, 255, 255, 0.95);
  border-radius: 16px;
  padding: 20px;
  
  /* 陰影讓內層「浮」起來 */
  box-shadow: 0 8px 32px rgba(0,0,0,0.15);
  position: relative;
  
  /* 毛玻璃效果（如果瀏覽器支援） */
  backdrop-filter: blur(10px);
}

.accent-element {
  position: absolute;
  
  /* 負值定位，讓元素「溢出」容器邊界
   * 創造出「貼紙」或「標籤」的視覺效果 */
  top: -8px;
  right: -8px;
  
  width: 40px;
  height: 40px;
  background: linear-gradient(135deg, #ff6b6b, #4ecdc4);
  
  /* 中等大小的圓角，與其他層次形成對比 */
  border-radius: 12px;
  
  /* 強烈的陰影，讓這個元素更突出 */
  box-shadow: 0 6px 20px rgba(255, 107, 107, 0.6);
  
  /* 白色邊框，與背景形成對比，增強視覺分離 */
  border: 3px solid white;
}

.card-title {
  margin: 0 0 12px 0;
  color: #333;
  font-size: 16px;
  font-weight: 600;
}

.layered-design p {
  margin: 0;
  color: #666;
  line-height: 1.5;
  font-size: 14px;
}

多層次設計

不同大小的圓角創造視覺層次，讓介面更有深度和趣味。

小挑戰

試試只用 border-radius 創造這些形狀：

水滴形狀：

/* 技巧解析：
 * X軸：四個角都是 50%（標準圓角）
 * Y軸：上方 60%（較圓），下方 40%（較尖）
 * 這樣創造出上圓下尖的水滴效果 */
border-radius: 50% 50% 50% 50% / 60% 60% 40% 40%;

有方向感的卡片：

/* 對角線模式：左上/右下大圓角，右上/左下小圓角
 * 創造出「指向性」的視覺效果，適合用在需要引導視線的地方 */
border-radius: 16px 4px 16px 4px;

方向感卡片

柔軟的 blob（有機形狀）：

/* 進階技巧：使用百分比創造不規則的有機形狀
 * X軸：40% 60% 60% 40% - 左右不對稱
 * Y軸：60% 30% 60% 40% - 上下也不對稱
 * 這種組合創造出「柔軟、有機」的視覺感受
 * 適合用在需要「親和力」的設計中 */
border-radius: 40% 60% 60% 40% / 60% 30% 60% 40%;

重點總結

border-radius 是一個形狀語言，不只是簡單的圓角裝飾
斜線語法 / 是核心：水平和垂直半徑可以分開控制，創造橢圓和有機形狀
瀏覽器會自動 clamp 數值：確保圓角不會超出元素範圍，這是正常機制
單位選擇很重要：
- px：固定幾何，適合元件設計，保證一致的視覺大小
- %：相對尺寸，適合響應式設計，但要注意比例變化
好的圓角來自有意識的選擇：理解計算模型、單位差異和瀏覽器行為
實戰技巧：
- 膠囊按鈕：使用固定 px 值（約為高度一半）
- 最大圓角：使用 9999px 或 50%（取決於需求）
- 有機形狀：使用百分比配合斜線語法
- 多層次設計：外層大圓角，內層小圓角，創造深度

延伸學習

想要更深入？試試這些進階主題：

與 clip-path 結合：創造更複雜的形狀
動畫技巧：讓形狀在 hover 時平滑變形
響應式圓角：使用 CSS 變數和媒體查詢
效能考量：大量圓角元素的優化技巧

希望這些內容對你有幫助。🎨

在 Eleventy（11ty）中優雅地使用 Svelte：一套實用的 Vite-based islands 架構

2026-01-06T00:00:00Z

為什麼我想在 11ty 裡用 Svelte？

Eleventy（11ty）是一個我非常喜歡的靜態網站產生器：

快
簡單
不綁框架
非常適合寫技術文章

但寫久了總會遇到一個問題：

文章裡想放一點互動的東西

例如：

小型計算器
Demo widget
可重複使用的互動範例
教學用的即時操作元件

這時候我並不想：

把整個網站搬去 SvelteKit
或為了一個元件引入一整套 SPA 架構

於是我選擇了一條折衷但非常實用的路：

11ty 負責靜態內容
Svelte 只負責「局部互動」

這篇文章會介紹什麼？

這篇會完整說明我目前在用的一套做法：

在 11ty 文章中用 shortcode 插入 Svelte 元件
Svelte 元件集中管理、每個元件一個檔案
透過 Vite 自動打包整合到 11ty build
支援 Barba.js 無刷新換頁
最後會比較這套做法和 11ty is-land 的差異

整合步驟

整個流程其實很單純：

Markdown 文章中放一個「Svelte 插槽」
11ty build 時輸出普通 HTML
瀏覽器載入後：
- JS 掃描插槽
- 找到對應的 Svelte 元件
- mount() 掛載上去

Markdown
  ↓
HTML（含 data-svelte-component 插槽）
  ↓
Vite bundle（含 Svelte）
  ↓
Client-side mount

專案目錄結構: 把 Svelte 元件集中管理：

src/
├─ svelte/            # 專門放 Svelte 元件
│  ├─ Counter.svelte
│  └─ MyWidget.svelte
└─ assets/
   └─ js/
      ├─ site.js
      └─ svelte-loader.js

好處很明確：

元件與文章內容完全解耦
同一個元件可以在不同文章重複使用
不會污染 11ty 的模板系統

Step 1：在 11ty 中啟用 Svelte（Vite）

我使用的是官方的 plugin：

@11ty/eleventy-plugin-vite
@sveltejs/vite-plugin-svelte

修改 eleventy.config.js

import EleventyVitePlugin from "@11ty/eleventy-plugin-vite"; // 11ty 官方 Vite 插件
import { svelte } from "@sveltejs/vite-plugin-svelte"; // Svelte Vite 插件

export default async function (eleventyConfig) {
  eleventyConfig.addPlugin(EleventyVitePlugin, { // 啟用 11ty Vite 插件
    viteOptions: {
      plugins: [
        svelte(), // 讓 Vite 能編譯 .svelte 檔案
      ],
    },
  });

  return {}; // 返回 11ty 配置物件
}

這裡的重點觀念是：

11ty 不負責編譯 Svelte
Svelte 完全交給 Vite

Step 2：建立一個 Svelte shortcode（關鍵）

這一步是整個架構的靈魂，也沒那麼誇張啦，就是使用 11ty shortcode 產生 html 放 svelte 元件位置

修改 eleventy.config.js

eleventyConfig.addShortcode("svelte", (name, props = {}) => { // 註冊 "svelte" shortcode
  const propsString = JSON.stringify(props) // 將 props 物件序列化為 JSON 字串
    .replace(/'/g, "&apos;"); // 將單引號轉義為 HTML 實體，避免 HTML 屬性解析錯誤

  return ` // 返回 HTML 字串，創建一個空的 div 作為 Svelte 元件掛載點
    <div
      data-svelte-component="${name}" // 指定要掛載的 Svelte 元件名稱
      data-svelte-props='${propsString}'> // 以 JSON 格式傳遞 props 給元件
    </div>
  `;
});

這個 shortcode 做的事情只有一個：

在 HTML 中留下「我之後要掛哪個 Svelte 元件」的資訊

Step 3：在 Markdown 文章中使用

放在文章任何位置都行。


{% svelte "Counter", { "count": 10, "label": "目前點擊數" } %} 

<!-- 使用 svelte shortcode 插入 Counter 元件，並傳遞初始 props -->

此時請記住一件事：

這裡不會渲染 Svelte 只會產生 shortcode 設定的 HTML，例如：

<div
  data-svelte-component="Counter"
  data-svelte-props='{"count":10,"label":"目前點擊數"}'>
</div>

Step 4：撰寫一個 Svelte 元件

ex: Counter.svelte

<script>
  let { count = 0, label = "Count" } = $props(); // 解構 props，設定預設值
</script>

<div class="p-4 border rounded my-4"> <!-- 使用 Tailwind CSS 樣式 -->
  <p>{label}: {count}</p> <!-- 顯示標籤和計數值 -->

  <button onclick={() => count--}>-1</button> <!-- 減少按鈕 -->
  <button onclick={() => count++}>+1</button> <!-- 增加按鈕 -->
</div>

這是一個非常普通的 Svelte 元件，沒有任何 11ty 耦合。

Step 5：Client-side Svelte Loader（核心）

基本版本（全部一起打包）

ex: svelte-loader.js

import { mount } from "svelte"; // Svelte 5：掛載元件

const modules = import.meta.glob("../../svelte/*.svelte", { eager: true }); // 小元件：直接全打包
const components = {}; // { ComponentName: Component }

for (const filePath in modules) { // "../../svelte/Counter.svelte"
  const name = filePath.split("/").pop().replace(".svelte", ""); // "Counter"
  components[name] = modules[filePath].default; // 註冊元件
}

export function initSvelteComponents(root = document) { // 允許傳入 Barba container
  root.querySelectorAll("[data-svelte-component]").forEach((el) => {
    if (el.dataset.svelteInitialized) return; // 已初始化就跳過

    const name = el.dataset.svelteComponent; // 元件名稱
    const Component = components[name]; // 取得元件

    if (!Component) { // 以前你這邊是 return（太安靜）
      console.warn(`[svelte] component not found: "${name}"`);
      return;
    }

    let props = {};
    const raw = el.dataset.svelteProps || "{}"; // props 字串（預設空物件）

    try {
      props = JSON.parse(raw); // parse props JSON
    } catch (err) {
      console.warn(`[svelte] invalid props JSON for "${name}": ${raw}`, err); // 以前你是吞掉
      props = {};
    }

    mount(Component, { target: el, props }); // 掛載元件
    el.dataset.svelteInitialized = "true"; // 標記完成
  });
}

這裡利用了 Vite 的 import.meta.glob：

自動掃描 src/svelte/
不需要手動 import 每個元件
新增元件只需要放檔案即可

Step 6：整合 Barba.js

如果你使用 Barba.js 或 PJAX 類工具，這一步非常必要：

import { initSvelteComponents } from "./svelte-loader.js"; // 匯入 Svelte 元件初始化函數

document.addEventListener("DOMContentLoaded", () => { // 頁面首次載入時
  initSvelteComponents(); // 初始化所有 Svelte 元件
});

barba.hooks.afterEnter(() => { // Barba.js 換頁完成後
  initSvelteComponents(); // 重新初始化新頁面的 Svelte 元件
});

原因很簡單：

Barba 換頁不會重新載入 JS，但新頁面需要重新掛載 Svelte

那這套和 11ty is-land 有什麼不同？

簡單對照

項目	本文做法	11ty is-land
架構	CSR islands	SSR + hydration
初始 HTML	插槽是空的	可預渲染
SEO	不太好	較佳
載入策略	手動控制	宣告式（on:visible）
Barba 相容	非常好	需額外處理
複雜度	不好說	不好說

實務建議

部落格互動元件 → 本文這套
SEO 關鍵內容元件 → is-land
已有 Vite / Barba 架構 → 本文這套會非常順

大多數使用 Svelte 的目的應該是為了互動操作，如果是為了 SEO 產生內容，那這樣用 Svelte 就不太適合了。

結語

這套做法本質上是一種：簡單可控的 islands 架構

它不追求「什麼都幫你包好」，而是讓你清楚知道：

元件什麼時候被載入
JS 什麼時候被執行
換頁時發生了什麼事

如果你正在用 11ty 寫技術部落格，又偶爾需要一點互動，svelte 是一個還不錯的方式。

CSS Stacking Context 教學：z-index 為什麼不聽話？

2026-01-05T00:00:00Z

你一定遇過這些情況：
z-index: 9999 還是沒用、dropdown 被切掉、modal 被 header 壓住。
這篇文章會用一個「投影片世界」的比喻，就像上面這張圖，馬上就能了解問題的根源。

核心概念：什麼是 Stacking Context（堆疊上下文）

在多數人的直覺裡，z-index 像是一個「數字越大就越上面」的全域排序系統。
但實際上，CSS 的層級運作方式完全不是這樣。

比較正確的理解方式是：

z-index 只在同一個 stacking context 裡有意義。

投影片世界的比喻

可以把整個畫面想成很多層透明投影片疊在一起。

預設情況下，所有元素都在同一個「大投影片」裡
一旦某個元素建立了 stacking context
它就變成一疊「自己的小投影片」

這個小投影片裡面的子元素：

彼此之間可以用 z-index 排名
但永遠無法跳出這一疊，跟外面的元素比較

也就是說：

子元素的 z-index: 9999
永遠贏不了父層 stacking context 在外部世界的順位

記住這句就好：
z-index 不是全域排名，而是「區域內排序」。

z-index 會失效的真正原因

在實務中，z-index 不聽話通常不是因為你寫錯數字，而是因為你忽略了下面兩件事。

z-index 不是隨便就能用

預設情況下，元素是 position: static，而這種狀態下：

.badge {
  z-index: 10; /* 不會生效 */
}

原因是： static 元素根本不參與層級計算。

正確寫法至少要這樣：

.badge {
  position: relative; /* 或 absolute / fixed / sticky */
  z-index: 10;
}

可以把它想成：你必須先「加入層級系統」，才有資格比大小。

父層一旦建立世界，子層就被封印

當父元素建立 stacking context 時，會發生一件非常關鍵的事：

子元素的 z-index，只在這個父世界裡有效。

這也是為什麼很多人會遇到：

子元素數字設很大
卻還是被外面的元素壓住

因為瀏覽器實際比較的是：

父層 stacking context vs 父層 stacking context

而不是你以為的子元素。

哪些情況會建立新的 Stacking Context

你不需要記完整規格，但下面這些是實務中最常踩到的。

常見觸發條件整理

類型	會建立 Stacking Context 的情況
定位	`position: relative / absolute` 且 `z-index` 不是 `auto`
固定定位	`position: fixed`、`sticky`
視覺效果	`opacity < 1`、`filter` 非 `none`
變形	`transform`（即使只是 `translate(0)`）
最安全做法	`isolation: isolate`

這裡面最容易被忽略的是 transform，因為它看起來只是動畫用，但實際上會直接改變層級行為。

isolation: isolate 是救命用的

如果你希望某個區塊：

內部層級自己處理
不影響外部，也不被外部影響

請直接用：

.section {
  isolation: isolate;
}

這個屬性唯一的目的就是建立 stacking context，不會順便影響定位、動畫或 layout，非常適合拿來當「防火牆」。

為什麼 z-index: 9999 還是輸

這是一個最典型、也最容易誤判的例子。

結構範例

<div class="header">
  zindex 1
  <div class="dropdown">
    zindex 9999
    我是 dropdown
  </div>
</div>

<div class="sidebar">
  zindex 2
  我是 sidebar
</div>

.header {
  position: relative;
  z-index: 1;
}

.dropdown {
  position: absolute;
  z-index: 9999;
}

.sidebar {
  position: relative;
  z-index: 2;
}

實際發生了什麼事

你以為 dropdown 會是最上面，實際上不是。

瀏覽器不是在比：

dropdown (9999)
sidebar (2)

而是在比：

.header (1)
.sidebar (2)

因為 .dropdown 被鎖在 .header 的世界裡。

結果就是：

整個 header（包含裡面的 dropdown）都會被 sidebar 壓在下面

這也是為什麼調整 dropdown z-index 永遠沒用。

三個最常見、也最痛的實戰坑

overflow: hidden 把浮層切掉

這種情況常見於 card、layout container。

.card {
  overflow: hidden;
}

即使你的 dropdown 或 tooltip z-index 再高，只要超出這個容器，就會被裁掉。

常見解法有兩種：

把浮層移到不受 overflow 限制的父層
直接用 portal，掛到 body

「Portal」是一種技術手法，讓浮層元素能直接渲染到 body 或其他節點，跳脫原本的 DOM 階層，常用於各種前端框架。例如：

transform 讓層級突然亂掉

很多動畫會這樣寫：

.panel {
  transform: translateY(0);
}

但這行其實已經：

建立新的 stacking context
改變 fixed / absolute 的參考行為

實務建議是：

不要在 layout 最外層用 transform
動畫盡量包在最內層元素

fixed 不再相對視窗

如果某個祖先元素有：

transform
filter
perspective

那麼：

.modal {
  position: fixed;
}

會變成「相對那個祖先」，而不是瀏覽器視窗。

這也是為什麼 modal 明明是 fixed，卻會跟著捲動。

實用的 Debug 思考流程

當你發現層級怪怪的，可以照這個順序檢查。

這個元素有沒有 position？
最近的 stacking context 是誰？
有沒有祖先用了 transform / opacity / filter？
壓住它的元素，父層是誰？

在 Chrome DevTools 裡：

Elements 面板往上看 computed styles
Layers 面板可以直接看到層級分組

專案等級的 z-index 管理方式

如果沒有規範，最後一定會出現：

z-index: 9999999;

建議一開始就定義層級語意。

:root {
  --z-base: 0;
  --z-header: 100;
  --z-dropdown: 300;
  --z-overlay: 900;
  --z-modal: 1000;
  --z-toast: 1100;
}

使用時只用語意，不用數字。

.modal {
  position: fixed;
  z-index: var(--z-modal);
}

如果你真的不想再跟 stacking context 糾纏，最穩定的方式只有一種：

把浮層直接掛在 body 底下。

<button id="btn">Hover</button>
<div id="tip" class="tip">Safe tooltip</div>

.tip {
  position: fixed;
  z-index: var(--z-toast);
  opacity: 0;
  pointer-events: none;
}

const btn = document.querySelector('#btn');
const tip = document.querySelector('#tip');

btn.addEventListener('mouseenter', () => {
  const rect = btn.getBoundingClientRect();
  tip.style.left = `${rect.left + rect.width / 2}px`;
  tip.style.top = `${rect.bottom + 8}px`;
  tip.classList.add('show');
});

這也是大多數 UI library 採用的做法。

總結

z-index 不是全域排序
stacking context 才是真正的邊界
父層層級決定一切
浮層想省事，直接走 portal

只要你開始用「世界」來思考層級問題， z-index 就再也不會無止盡的 999999...。

在 Eleventy（11ty）整合 Pagefind：回到「最簡單」的做法

2025-12-26T00:00:00Z

在把網站從 WordPress 搬到 11ty 之後，一直在研究一件事情，就是如果沒有了後端程式，也沒有資料庫，該怎麼做站內搜尋，Google Programmable Search Engine 也可以，但就走走看看有沒有別的選擇。

參考其他的 11ty 網站發現還蠻多人在用 Pagefind，而且這個工具是任何網頁架構都可以使用，不是只支持 11ty。

Pagefind 是為「靜態網站」設計的全文搜尋工具，不需要後端、不需要資料庫，搜尋全在前端完成。

而且老實說，Pagefind 本身真的不難。難的是：一開始我完全用錯方式在理解它。

一開始的誤會：把 Pagefind 當成「一般前端套件」

最一開始，我直覺用熟悉的方式來：

pnpm install pagefind

然後開始想：

CSS 要怎麼 include？
JS 要不要丟進 Vite？
要不要跟 11ty build 流程整合？
能不能 build 完 HTML 就自動跑 Pagefind？

於是開始把 Pagefind 拉進前端打包流程、寫 script、試著「一次 build 全部搞定」。

結果就是：流程越來越複雜、錯誤越來越難 debug。

到這裡才意識到一件事——

Pagefind 不是前端套件，它是「建索引的工具」。

所以我又執行了

pnpm remove pagefind

換個想法：Pagefind 只需要做一件事就好

我完全換了一個角度：

11ty 就負責把 HTML 生出來 Pagefind 只負責「讀這些 HTML，建立搜尋索引」

只要守住這個界線，事情瞬間變得很單純。

Step 1：直接 include Pagefind 產生的 CSS / JS

Pagefind 在建索引時，會自動產生 /pagefind/ 資料夾，裡面就包含 UI 所需的檔案。

所以什麼 bundler 都不要碰，直接 include：

<link href="/pagefind/pagefind-ui.css" rel="stylesheet">
<script src="/pagefind/pagefind-ui.js"></script>

Step 2：放一個搜尋欄位容器

<div id="search"></div>

Step 3：標記「真正要被搜尋的內容」

這一步非常重要，也是 Pagefind 最好用的地方之一。

記得在文章內容外層加上：

<div data-pagefind-body>
  {{ content | safe }}
</div>

這代表：

Pagefind 只會索引這個區塊內的文字
header、footer、選單、側邊欄都不會被吃進搜尋結果
搜尋結果乾淨很多

（也要注意：一旦用了 data-pagefind-body，沒有加這個 attribute 的頁面就不會被索引，這通常是好事。）

Step 4：初始化 PagefindUI

<script>
  window.addEventListener("DOMContentLoaded", () => {
    new PagefindUI({
      element: "#search",
      showSubResults: false,
    });
  });
</script>

到這一步，前端其實就已經準備好了。

Step 5：建索引（這行才是 Pagefind 的本體）

pnpm dlx pagefind --site _site --glob "**/*.html"

重點只有兩個：

_site：11ty build 出來的資料夾
**/*.html：全部 HTML 都拿來建索引

跑完之後，你會看到 _site/pagefind/ 被建立起來。

Step 6：收進 package.json

build 11ty site 和建立搜尋索引拆開：

{
  "scripts": {
    "build": "NODE_ENV=production ELEVENTY_PROFILE=true pnpm exec eleventy",
    "build:pagefind": "pnpm dlx pagefind --site _site --glob \"**/*.html\""
  }
}

為什麼？

因為這樣：

出問題很好 debug
不會搞混是 11ty 還是 Pagefind 壞掉
想自動化，之後再加一行 pnpm build && pnpm build:pagefind 就好

最後：上傳

只要你的部署流程會把 _site/pagefind/ 一起上傳，搜尋就能直接在純靜態網站上跑起來。

不用 server、不用 API、不用資料庫。

結束了嗎，對啊，就醬。

進階補充

Pagefind × Barba.js 切頁時要注意的事

如果你跟我一樣，網站有用 Barba.js 做 PJAX / page transition，那你幾乎一定會踩到這個坑。

問題是什麼？

PagefindUI 預設會在：DOMContentLoaded 時初始化。

但 Barba 切頁時：

不會重新載入整個頁面
#search 這個 DOM 可能被重建
PagefindUI 早就綁在舊的 DOM 上了

結果就是：

搜尋框還在
但點了沒反應，或結果怪怪的

最穩的做法：切頁後重新初始化

概念只有一句話：

只要搜尋欄位被重新 render，就重建 PagefindUI

範例（Barba hooks）：

let pagefindInstance = null;

function initPagefind() {
  const searchEl = document.querySelector("#search");
  if (!searchEl) return;

  // 避免重複初始化
  searchEl.innerHTML = "";

  pagefindInstance = new PagefindUI({
    element: "#search",
    showSubResults: false,
  });
}

window.addEventListener("DOMContentLoaded", initPagefind);

barba.hooks.afterEnter(() => {
  initPagefind();
});

這樣做的好處：

不管是不是 PJAX 切頁
只要 #search 出現，就一定能用
不會卡在奇怪的「第一次正常，之後失效」

哪些頁面「不該被搜尋」

Pagefind 很貼心的一點是：你可以選擇性讓頁面完全不進索引。

情境舉例

標籤列表頁
分頁頁面（page/2、page/3）
純導覽頁、實驗頁
404 / redirect 頁

作法一：根本不加 data-pagefind-body

只有「文章內容」才包：

<div data-pagefind-body>
  {{ content | safe }}
</div>

其他頁面自然就被排除。

作法二：明確標記「不要索引」

如果你有某些頁面「結構很像文章，但不該被搜」，可以加：

<body data-pagefind-ignore>

或包在區塊上：

<div data-pagefind-ignore>
  ...
</div>

這在做實驗頁、A/B test、或 draft 頁面時很有用。

Pagefind 的搜尋品質，其實取決於你的 HTML 結構

Pagefind 不是魔法，它完全相信你的 HTML。

所以這幾件事，會直接影響搜尋結果好不好用：

1️⃣ 標題階層很重要

<h1>文章標題</h1>
<h2>段落標題</h2>
<h3>小節</h3>

Pagefind 會用這些來：

判斷內容結構
顯示搜尋結果摘要

亂用 div + class，搜尋結果就會很扁平。

2️⃣ 不要把整篇文章塞進奇怪的 wrapper

例如：

<div class="prose">
  <article>
    <section>
      <div>
        {{ content }}
      </div>
    </section>
  </article>
</div>

這不是不行，但層級越乾淨，搜尋摘要越好看。

3️⃣ Code block 其實會被索引（而且有時很棒）

這點對技術部落格來說是加分：

指令
API 名稱
錯誤訊息

都能被搜到。

如果你真的不想讓 code block 被搜，再局部加 data-pagefind-ignore 即可。

結語

Pagefind 不複雜，複雜的是我們一開始就想把它變得很複雜，難的是「想一次做到太完美」

對我來說，現在這套流程剛剛好：

好理解
好 debug
出問題也知道在哪一段

回頭看，其實整個流程只有一句話：

HTML 先 build 好，Pagefind 再來掃。

一開始是想把它「工程化」、自動化、整合到所有流程裡；但對假設網站這件事來說，簡單、穩定，才是最重要的。不然就是回復備份流程做得快又方便也是 OK 的啦。

(靜態網站不管是備份還是回復舊版本都超方便的啦，一點都不害怕弄壞了什麼)

在 Eleventy（11ty）文章中做出像 WordPress 的 Feature Image 特色圖片

2025-12-24T00:00:00Z

目標效果

一般模式（預設）
- 文章開頭顯示靜態 feature image
特效模式（可選）
- hover 時 feature image 裂成四塊飛散
- 同時顯示文章資訊文字（feature_meta_text）

步驟 1：在每篇文章 frontmatter 加上 feature image 設定

參考如下 frontmatter 範例：

---
# 文章標題
title: 從 WordPress 搬家到 Eleventy（11ty）：你一定會遇到的幾個注意事項整理

# 文章描述（常用在 SEO、OpenGraph、列表摘要）
description: 從 WordPress 搬家到 Eleventy 靜態網站生成器的完整指南，整理了遷移過程中常見的注意事項、坑洞與解決方案。包含內容匯出、圖片處理、前端框架整合等實戰經驗分享。

# Feature image：文章開頭的主圖（你用相對路徑）
feature_image: "../img/feature-images/11ty-notes.png"

# 是否啟用「裂開 hover 特效」
# false = 用一般 <img> 呈現
# true  = 用特效版本（四塊碎片 + 文字）
use_feature_split: false

# 特效模式時要顯示的文章資訊文字（簡短、像副標）
feature_meta_text: WordPress 到 Eleventy 的遷移之旅

# 發佈時間（用 ISO 格式很標準）
date: 2025-12-22T10:00:00.000Z

# metadata 結構（分類、文章型態、canonical url）
metadata:
  categories:
    - 架設網站
    - 靜態網站生成器
  type: wordpress-migration
  url: https://kamadiam.com/wordpress-to-eleventy-migration/

# tags（文章標籤）
tags:
  - wordpress
  - eleventy
  - 11ty
  - 靜態網站
  - 網站搬家
  - 遷移指南
  - 前端開發
  - 網站優化

# 指定 Markdown 的模板引擎, 可以避免不同程式語法衝突
templateEngineOverride: md
---

frontmatter 可以很簡單的自定義資料格式，可以控制文章的顯示或行為。

feature_meta_text 建議保持「一句話」即可，越短越像 WordPress 的「精選摘要」
use_feature_split 預設 false，要用特效的文章再開即可，這個是額外加入的小趣味。

步驟 2：在 post.njk 加入條件邏輯

修改的主要邏輯是：

如果 feature_image 存在 → 即顯示 feature image
如果 use_feature_split 且 feature_image 存在 → feature image 要加上特效

請參考範例，（PS:nunjucks 註解格式為 {# ... #}）：


{# 
============================================================
  Feature image 渲染入口：
  - use_feature_split = true  → 顯示裂開特效版本
  - use_feature_split = false → 顯示一般 <img>
============================================================ 
#}

{# 1) 這裏是特效模式：需要 use_feature_split=true 且有 feature_image #}
{%- if use_feature_split and feature_image %}

  {# 你自訂的 filter：把 frontmatter 的相對路徑，解析成可用的 URL #}
  {%- set resolvedImagePath = feature_image | resolveImagePath %}

  {# 確保解析成功才渲染，避免 broken image #}
  {%- if resolvedImagePath %}

    <div class="feature-wrap">
      {# figure：使用 CSS 變數 --img 把圖片 URL 傳給 CSS #}
      <figure
        class="feature-split"
        aria-label="Article feature image"
        style="--img: url('{{ resolvedImagePath }}')"
      >
        {# 視覺底座：提供圓角/背景框（因為不使用 overflow hidden） #}
        <div class="feature-frame" aria-hidden="true"></div>

        {# 四塊碎片：四個 span 用同一張圖切成 2x2 #}
        <div class="tiles" aria-hidden="true">
          <span class="tile t1"></span>
          <span class="tile t2"></span>
          <span class="tile t3"></span>
          <span class="tile t4"></span>
        </div>

        {# 底部文字資訊：如果有 feature_meta_text 才顯示 #}
        {%- if feature_meta_text %}
          <div class="feature-text">{{ feature_meta_text }}</div>
        {%- endif %}

      </figure>
    </div>

  {%- endif %}

{# 2) 這裏是一般模式：有 feature_image 就用普通 img #}
{%- elif feature_image %}

  {# 這裡直接用 feature_image（相對路徑）顯示圖片 #}
  <img
    src="{{ feature_image }}"
    alt="Feature image for {{ title }}"
    class="post-feature-image"
  >

{%- endif %}

步驟 3：套用 CSS，做出「裂成四塊」的核心效果

效果就是自由發揮，如果不想只是顯示一張圖，讓文章有趣一點，或是埋藏彩蛋，可以自由修改 html 搭配 css 展現特別效果。

/* ============================================================
  feature-wrap：用 padding + 負 margin 擴大 hover 觸發區域
  目的：讓滑鼠不要一定得壓在圖片上，稍微靠近也能觸發
============================================================ */
.feature-wrap {
  position: relative;

  /* 擴大 hover 區域（包含圖片周圍） */
  padding: var(--space-2xl);

  /* 用負 margin 把版面位置「抵回來」，避免整體被撐大 */
  margin: calc(-1 * var(--space-2xl));
}


/* ============================================================
  feature-split：核心容器（不裁切，碎片可以飛出去）
  --img：圖片 URL（由 inline style 傳進來）
  --radius：圓角
  --spread：裂開距離
  --lift：hover 上浮高度
============================================================ */
.feature-split {
  --img: url("");
  --radius: var(--space-3xs);
  --spread: var(--space-l);
  --lift: var(--space-s);

  position: relative;
  width: 100%;
  aspect-ratio: 16 / 9;

  /* ✅ 不裁切：碎片可以飛出原本框 */
  overflow: visible;

  border-radius: var(--radius);

  /* 初始位置明確指定 translateY(0)，避免 hover 回彈視覺跳一下 */
  transform: translateY(0) translateZ(0);

  /* 只讓 transform 動畫（效能最好） */
  transition: transform 620ms cubic-bezier(.2, .85, .2, 1);

  margin: var(--space-m) 0;
}


/* ============================================================
  feature-frame：視覺底座
  因為 overflow 沒有 hidden，不能靠裁切做圓角
  所以用這層提供背景/邊框/圓角，讓「合起來」時像一張完整圖
============================================================ */
.feature-frame {
  position: absolute;
  inset: 0;
  background: var(--neutral-color);
  border-radius: var(--radius);
  pointer-events: none;
}


/* ============================================================
  tiles：四塊碎片的容器
============================================================ */
.tiles {
  position: absolute;
  inset: 0;
  border-radius: var(--radius);
}


/* ============================================================
  tile：單一碎片
  技術重點：
  - 每塊 50% x 50%
  - 背景圖放大成 200% 200%（因為只顯示四分之一）
  - 用 background-position 決定顯示哪一個象限
============================================================ */
.tile {
  position: absolute;
  width: 50%;
  height: 50%;

  /* ✅ 同一張圖，放大兩倍再切成四塊 */
  background: var(--img) center / 200% 200% no-repeat;

  border-radius: calc(var(--radius) - var(--space-3xs));

  /* 合起來時不顯示邊框，裂開時才顯示（避免抖動就用 transition） */
  border: 1px solid transparent;

  box-shadow: 0 var(--space-s) var(--space-l) rgba(0, 0, 0, .22);

  /* ✅ 動畫只做 transform/filter/opacity/border-color（效能好） */
  transition:
    transform 620ms cubic-bezier(.2, .85, .2, 1),
    filter 620ms cubic-bezier(.2, .85, .2, 1),
    opacity 620ms cubic-bezier(.2, .85, .2, 1),
    border-color 620ms cubic-bezier(.2, .85, .2, 1);

  will-change: transform;
  backface-visibility: hidden;
}


/* ============================================================
  四塊的位置與對應的背景象限
============================================================ */
.t1 { left: 0;  top: 0;  background-position: 0% 0%; }
.t2 { left: 50%; top: 0; background-position: 100% 0%; }
.t3 { left: 0;  top: 50%; background-position: 0% 100%; }
.t4 { left: 50%; top: 50%; background-position: 100% 100%; }


/* ============================================================
  feature-text：hover 時顯示的文字資訊
============================================================ */
.feature-text {
  position: absolute;
  left: 50%;
  top: 50%;

  /* 初始略縮小 + 隱藏 */
  transform: translate(-50%, -50%) scale(0.9);
  opacity: 0;

  transition: transform 520ms cubic-bezier(.2, .85, .2, 1), opacity 520ms ease;
  pointer-events: none;

  color: var(--text-color);
  font-size: var(--step--1);
  font-weight: 500;
  letter-spacing: .2px;
  line-height: 1.6;
  text-align: center;

  white-space: nowrap;

  background: rgba(255, 255, 255, .92);
  backdrop-filter: blur(12px);
  border-radius: var(--space-l);
  border: 1px solid var(--color-gray-20);
  box-shadow: 0 var(--space-l) var(--space-2xl) rgba(0, 0, 0, .15);
  padding: var(--space-2xs) var(--space-2xs);
  max-width: 80%;
}


/* ============================================================
  Hover 動畫（只在支援 hover 的裝置上）
============================================================ */
@media (hover: hover) and (pointer: fine) {

  /* 容器上浮（你同時支援 feature-wrap:hover 與 figure:hover） */
  .feature-wrap:hover .feature-split,
  .feature-split:hover {
    transform: translateY(calc(-1 * var(--lift))) translateZ(0);
  }

  /* 四塊向四個方向飛散 + 旋轉 */
  .feature-wrap:hover .feature-split .t1,
  .feature-split:hover .t1 {
    transform: translate(calc(-1 * var(--spread)), calc(-1 * var(--spread))) rotate(-4deg);
  }

  .feature-wrap:hover .feature-split .t2,
  .feature-split:hover .t2 {
    transform: translate(var(--spread), calc(-1 * var(--spread))) rotate(4deg);
  }

  .feature-wrap:hover .feature-split .t3,
  .feature-split:hover .t3 {
    transform: translate(calc(-1 * var(--spread)), var(--spread)) rotate(3deg);
  }

  .feature-wrap:hover .feature-split .t4,
  .feature-split:hover .t4 {
    transform: translate(var(--spread), var(--spread)) rotate(-3deg);
  }

  /* 碎片顏色更有精神 + 裂開時顯示邊框 */
  .feature-wrap:hover .feature-split .tile,
  .feature-split:hover .tile {
    filter: brightness(.92) saturate(1.12) contrast(1.03);
    border-color: var(--color-gray-20);
  }

  /* 裂縫光出現 */
  .feature-wrap:hover .feature-split .crack,
  .feature-split:hover .crack {
    opacity: 1;
  }

  /* 文字卡片縮放淡入 */
  .feature-wrap:hover .feature-split .feature-text,
  .feature-split:hover .feature-text {
    transform: translate(-50%, -50%) scale(1);
    opacity: 1;
  }
}

CSS 技術實作原理

一張圖切四塊，不需要四張圖片

每個 .tile 都是同一張背景圖：

tile 本身只有 50% × 50%
但背景圖用 200% 200% 放大
然後用 background-position 指定顯示哪個象限

所以你只要準備 一張 feature image，就能切出四塊。

為什麼動畫只用 transform？

transform（位移/旋轉/縮放）通常可以走 GPU 合成層，效能最好。

如果你用 top/left 去動，瀏覽器比較容易重新排版，會卡。

最後：整合到 11ty 的使用方式

你的使用方式會長這樣：

一般文章（不需要特效）：use_feature_split: false
特別文章（想要效果）：use_feature_split: true

在 11ty 只要維持一致的 frontmatter key，就能像 WordPress 一樣「每篇都有封面」，而且還能加進你的個人風格（裂開特效、資訊卡片、系列標籤都能玩）。

另外 手機沒有 hover，可以改成「進入視窗」才顯示文字，利用 IntersectionObserver 加 style class。

以上範例也可以獨立拆成獨立檔案例如 feature_image.njk，讓 post.njk 只要 {% include "feature_image.njk" %} 一行，管理 layout 更省心力。

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

2025-12-22T10:00:00Z

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/ 的站）

解法：使用 permalink 覆寫

在文章的資料設定（例如 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 兩個設計概念完全天差地遠。

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

把文章從 WordPress 搬出來：eleventy-import 的匯出方式

2025-12-15T10:00:00Z

eleventy-import，終於可以把 WordPress 資料好好搬出來

11ty 的作者真的很懂這個痛點，直接自己寫了一個官方匯入工具：eleventy-import。

在真正遇到它之前，我其實也走過不少冤枉路。

一開始的想法很直覺：

👉 用 WordPress 外掛把文章匯出成 Markdown，再慢慢整理。

問題是——事情完全沒那麼單純。

為什麼一般 WordPress 匯出方式這麼痛苦？

之前試過幾個 WordPress 匯出外掛，產生出來的檔案大多有這些問題：

夾雜大量 WordPress 專用標籤
各種外掛留下來的 短代碼（shortcode）
XML / HTML 混在一起，格式不統一
有的圖片是外掛語法，還有各種奇怪的包法

最麻煩的是：

👉 這些雜物沒有固定格式，根本沒辦法用一支 script 全部清乾淨

每篇文章都像在開盲盒，例外狀況多到讓人直接放棄。

於是這件事就這樣被擱著了。

官方出手：11ty 的 WordPress 轉移教學

直到有一天，在 11ty 官網亂逛時，看到這一頁：

👉 https://www.11ty.dev/docs/migrate/wordpress/

不只寫了完整教學，作者本人還拍了一支影片，標題是「Escape From WordPress」，整個就是用意非常明顯 😂

影片在這裡：

https://www.youtube.com/watch?v=WuH5QYCdh6w

看到這裡才發現：

👉 原來 11ty 早就把「從 WordPress 逃離」這件事想好了。

使用 eleventy-import 匯出 WordPress 文章

直接執行一行指令

使用方式非常暴力，也非常爽快：

npx @11ty/import wordpress https://your-site.com/

或者如果習慣 pnpm

pnpm dlx @11ty/import wordpress https://your-site.com/

第一次看到這行指令的反應是：

不是吧？就這樣？

沒了？

結果真的就 完成了，YA。

匯出後的目錄結構

eleventy-import 會直接幫你輸出成 11ty 最愛的格式：

your_project/
  assets/
    image1
    image2

  article1.md
  article2.md

幾個我覺得「非常關鍵」的點：

每一篇文章都是 乾淨的 Markdown
所有圖片自動整理進 assets/ 目錄
文章內的圖片連結也已經幫你改好
幾乎沒有 WordPress 遺毒

一句話總結：

👉 這個輸出結果，完全就是為了「直接丟進 11ty」而設計的。

下一步：選擇 11ty Starter

文章資料已經乾乾淨淨了，接下來就是選一個起始專案。

eleventy-base-blog

GitHub：

eleventy-base

優點：

官方範例，結構清楚
幾乎沒有多餘抽象
非常適合「想自己慢慢加功能」的人
好改、不綁架設計

缺點：

功能極簡
SEO、樣式、搜尋、圖片優化都要自己補
一開始看起來有點「什麼都沒有」

eleventy-excellent

網站：

eleventy-excellent

優點：

幾乎什麼都幫你準備好了
包含 SEO、圖片處理、效能最佳化
設計完成度高，很快就能上線

缺點：

設計與架構選擇比較多是「作者的想法」
想大改時，需要先理解一整套設計哲學
對我來說，反而有點太滿了

最後選擇

一開始其實是用 eleventy-excellent，因為真的很省事。

但實際調整一陣子後發現：

👉 一定會有一些地方「不是自己想要的方式」

而要改動那些地方，反而得先拆作者原本的設計。

最後決定回頭選擇 eleventy-base-blog：

從最簡單的開始，

需要什麼，再一個一個加。

啟動 11ty，驗收成果

把剛剛匯出的文章與 assets 目錄，放進：

content/blog/

然後啟動專案：

pnpm run start

打開瀏覽器，直接進：

http://localhost:8080/文章名稱/

你會看到一件很神奇的事：

文章內容完整
圖片全部正常
但樣式幾乎全沒了

這一刻這是感動萬分！。

因為這代表：

👉 資料真的已經完全脫離 WordPress 了。

從這一刻起，是全新的開始

這樣的網站：

快到不行，幾乎是秒開
什麼功能都沒有
但結構乾淨、可控、沒有包袱

這就是取捨啊。

WordPress 的功能真的很方便，

但當你選擇 11ty，簡單也不是壞事。

用效能、掌控感，交換即插即用的便利性。

接下來，才是真正有趣的地方。我想要網站愈來愈有趣，而不是愈來愈失去興趣。

WordPress vs 11ty：各自的優缺點與取捨

2025-12-08T10:00:00Z

WordPress 作為全球最受歡迎的內容管理系統，已經幫助數百萬人建立了自己的網站。然而，近年來靜態網站生成器如 11ty 也逐漸受到開發者和內容創作者的青睞。這兩種工具各有優缺點，選擇哪一個取決於你的需求、技術背景和維護意願。

本文將比較 WordPress 與 11ty，從多個面向分析兩者的差異，幫助你做出最適合的選擇。

基本概念與定位

WordPress：成熟的全功能 CMS

WordPress 是一個功能完整的內容管理系統，提供完整的後端管理介面、資料庫儲存、動態內容生成等功能。它最初設計為部落格平台，但現在已經演變成一個全功能的 CMS，可以建立任何類型的網站。

11ty：現代化的靜態網站生成器

11ty（Eleventy）是一個以 JavaScript 為基礎的靜態網站生成器。它不依賴資料庫，而是將內容檔案轉換為靜態 HTML 檔案，在建置時生成完整網站。

主要差異比較

技術架構

WordPress 的動態架構

資料庫驅動：所有內容都儲存在 MySQL/PostgreSQL 等資料庫中
動態生成：每次頁面請求時，PHP 會從資料庫提取資料並動態生成 HTML
依賴關係：需要 PHP 運行環境、資料庫伺服器、Web 伺服器（如 Apache/Nginx）

11ty 的靜態架構

檔案驅動：內容以 Markdown、HTML 等檔案格式儲存
預先建置：在開發階段就生成所有靜態檔案
獨立部署：只需要靜態檔案伺服器，無需資料庫或特定運行環境

開發體驗

WordPress：視覺化編輯優先

優點：

所見即所得編輯器：古騰堡編輯器讓非技術人員也能輕鬆編輯內容
即時預覽：修改後立即在前端看到效果
外掛生態：有數萬個外掛可以快速增加功能

缺點：

學習曲線：雖然編輯簡單，但要客製化主題仍需學習 PHP、WordPress Hook 等
外掛相容性：不同外掛間可能衝突，需要花時間測試和調試

(現代 PHP 和 WordPress 也改善很多開發流程和工具了) 參考：如何使用 Herd 在本機架設 WordPress 網站

11ty：程式化開發體驗

優點：

版本控制友好：所有內容和設定都以檔案形式存在，可以用 Git 完整管理
完全客製化：從頭到尾控制每一個細節
現代開發工具鏈：可以使用 npm scripts、現代 CSS 框架、模組化 JavaScript

缺點：

學習門檻：需要基本程式設計知識
建置步驟：每次修改都需要重新建置才能看到效果

效能表現

WordPress：需要持續優化

初始載入：動態生成內容導致首次載入較慢
快取需求：需要安裝快取外掛（如 WP Rocket、LiteSpeed Cache）來改善效能
伺服器負載：高流量時需要更多伺服器資源

11ty：天生高效能

極快載入：純靜態檔案，CDN 快取效果極佳
低伺服器成本：可以使用免費的靜態託管服務
無資料庫查詢：沒有資料庫延遲問題

在相同的機器規格上，11ty會消耗較少資源，也不需要資料庫的建置，但你也可以購買專用主機，直接提升效能。

安全性考量

WordPress：常見攻擊目標

風險點：

外掛漏洞：許多安全性問題來自過時或有漏洞的外掛
PHP 環境：動態執行的本質帶來更多攻擊面
資料庫安全：需要保護資料庫免於攻擊

優點：

活躍社群：有大量安全性外掛和監控工具
定期更新：核心系統和外掛都會定期修補漏洞

11ty：本質安全

優點：

最小攻擊面：沒有資料庫、沒有動態執行，極難被入侵
內容驗證：建置時可以驗證所有內容和程式碼
相依性控制：可以精確控制所有第三方程式庫

考量點：

建置安全：需要保護建置過程和部署金鑰
第三方服務：如果整合外部服務（如表單、評論），需要注意這些服務的安全性

11ty 的好處是沒有後台登入功能，會被破解的地方就是主機本身，如果主機使用不夠安全，用什麼架構都一樣不安全。

維護成本與複雜度

WordPress：持續維護需求高

定期任務：

軟體更新：核心、主題、外掛都需要定期更新
安全性修補：監控並修補已知漏洞
效能優化：定期檢查和優化網站速度
備份管理：資料庫和檔案的備份策略

雖然都很簡單的定期更新，就是很繁雜，但外掛版本和 WordPress 版本和 PHP 版本之間的相容性需要考量。

11ty：一次性設定，長期穩定

維護內容：

內容更新：只需要編輯 Markdown 檔案
相依性更新：偶爾更新 npm 套件
重新部署：修改後重新建置和部署

內容管理與協作

WordPress：多人協作友好

角色權限系統：支援不同層級的使用者權限
即時協作：多個編輯者可以同時工作
審核流程：支援草稿、審核、發布流程

以我個人的情境來說（主要是一人維護與發文），WordPress 的角色權限與協作流程屬於「用得到很強，用不到就比較像是額外的系統功能」。相對地，我更在意的是內容變更是否能被精準追蹤與回溯。

而且你也很難追蹤另一個 WordPress 使用者動了什麼東西，改了什麼設定。

11ty：開發者導向協作

Git 工作流程：任何微小變動都清清楚楚，輕易追蹤管理版本。
內容即程式碼：內容和程式碼使用相同工具管理
版本歷史：完整的內容修改歷史記錄

適合的使用情境

選擇 WordPress 的情境

非技術使用者：如果你不熟悉程式設計，但需要快速建立網站
複雜功能需求：需要會員系統、電子商務、複雜表單等動態功能
多人協作內容：有多個內容編輯者，需要完善的權限管理
預算有限：不想花時間學習技術，希望快速上線
經常變更內容：網站內容需要頻繁更新，希望即時生效

選擇 11ty 的情境

技術背景使用者：熟悉 HTML、CSS、JavaScript，有程式設計基礎
效能至上：對網站載入速度有極高要求
安全性重視：希望最小化安全風險
長期維護考量：希望降低長期維護成本
個人/小型專案：部落格、作品集、文件網站等
版本控制需求：需要完整的內容版本歷史和協作流程

這些只是比較適合的點，並不代表這個功能一定得用某個技術才行。

實際案例分析

WordPress 適合案例

新聞網站：需要頻繁更新內容、多個編輯者協作
企業網站：需要 CMS 整合、聯絡表單、會員系統
電子商務：需要購物車、付款閘道、庫存管理
社群平台：需要用戶生成內容、評論系統

11ty 適合案例

個人部落格：內容創作者專注於寫作而非維護
產品文件：技術文件、API 文件等需要版本控制
作品集網站：設計師、開發者的個人展示網站
公司官網：簡單的企業介紹頁面，重視品牌形象

事實上 11ty 能做的事，WordPress 都做得到，但選擇 11ty 通常不是太功能上的選擇，很多是想在技術上架構上簡單透明一點。

遷移與轉換考量

從 WordPress 遷移到 11ty

優點：

大幅改善效能和安全性
降低託管成本
獲得更多控制權

挑戰：

需要將動態功能改為靜態或外部服務
失去所見即所得編輯體驗
需要學習新的工作流程

從 11ty 遷移到 WordPress

優點：

快速增加複雜功能
降低內容編輯門檻
支援更多非技術使用者

挑戰：

效能下降
維護複雜度增加
安全性風險提高

結論：沒有絕對的「最好」

WordPress 和 11ty 代表兩種不同的網站建置哲學：

WordPress 強調易用性和功能完整性，適合需要快速上線、複雜功能、或多人協作的專案
11ty 強調效能、安全性和開發體驗，適合技術背景的使用者和重視長期維護的專案

最終的選擇應該基於：

你的技術能力：熟悉程式設計嗎？
專案需求：需要哪些功能？預算多少？
維護意願：願意投入多少時間在網站維護上？
成長規劃：網站未來可能如何演變？

建議你可以先評估自己的需求，必要時甚至可以考慮混合使用兩者。例如，使用 11ty 建立主要內容網站，WordPress 作為後台內容管理系統。

無論選擇哪一個工具，重點是找到最適合自己工作流程和需求的解決方案。技術工具應該服務於內容創作，而不是成為創作的障礙。

WordPress 看很多了，來看看幾個 11ty 的網站

https://chrisburnell.com/
https://www.zachleat.com/
https://eleventy-excellent.netlify.app/

相關資源：

1 個程式範例，快速學習 JavaScript 物件導向語法

2024-01-01T00:27:42Z

當深入 JavaScript 的核心時，傳統的物件導向編程（OOP）技術顯得非常重要。這種編程風格不僅為程式碼提供了清晰的結構，而且還促進了模組化和重用，這對於大型和複雜的應用程式開發尤為關鍵。

為什麼要學習 JavaScript OOP？

JavaScript 雖然最初是基於原型的語言，但 ES6（ES2015）引入了類別（class）語法，讓開發者能夠使用更傳統的物件導向編程方式。這種方式讓程式碼更容易理解、維護和擴展。

本篇文章將透過一個完整的範例，一步步探討 JavaScript 中傳統物件導向編程的關鍵概念，包括類別的定義、公共和私有屬性的宣告、建構函數、方法的使用，以及類別的繼承等。這將幫助你深入理解 JavaScript 中的 OOP，並將這些知識應用於編程實踐中。

完整 OOP 語法範例：

// 定義一個類別 (Define a Class)
// 類別是 JavaScript 中用於建立物件的模板。它封裝了相關的屬性和方法。
class Car {
    // 公共屬性 (Declare a Public Property)
    // 公共屬性可以在類別實例的任何地方被存取和修改。
    color;

    // 私有屬性 (Declare a Private Property)
    // 私有屬性僅在定義它們的類別內部可存取，外部無法直接存取。
    #brand;

    // 建構函數 (Declare Constructor)
    // 建構函數是在建立類別實例時自動呼叫的特殊方法，用於初始化類別的屬性。
    constructor(brand, color) {
        this.#brand = brand;
        this.color = color;
    }

    // 公共方法 (Declare a Public Method)
    // 公共方法可以被類別實例及繼承該類別的其他類別的實例呼叫。
    displayInfo() {
        console.log(`This is a ${this.color} car.`);
    }

    // 私有方法 (Declare a Private Method)
    // 私有方法僅能在定義它的類別內部被呼叫，對外部是不可見的。
    #privateMethod() {
        return `Brand is ${this.#brand}`;
    }

    // Getter 和 Setter
    // Getter 和 Setter 用於對類別的私有屬性進行安全的存取和更新。
    get brand() {
        return this.#privateMethod();
    }

    set brand(newBrand) {
        this.#brand = newBrand;
    }

    // 靜態方法和屬性 (Static Methods and Fields)
    // 靜態方法和屬性屬於類別本身，而不是類別的任何特定實例。
    static numberOfWheels = 4;

    static carDescription() {
        return `Cars usually have ${this.numberOfWheels} wheels.`;
    }
}

// 擴展一個類別 (Extend a Class)
// 使用 'extends' 關鍵字建立一個新類別，繼承另一個類別的屬性和方法。
class ElectricCar extends Car {
    constructor(brand, color, batteryLife) {
        super(brand, color); // 呼叫父類別建構函數
        this.batteryLife = batteryLife;
    }

    // 覆寫方法
    displayInfo() {
        console.log(`This is a ${this.color} electric car with a battery life of ${this.batteryLife} hours.`);
    }
}

// 建立一個實例 (Create an Instance)
// 使用 'new' 關鍵字和類別名稱建立該類別的一個新實例。
const myCar = new ElectricCar('Tesla', 'red', 24);

// 呼叫方法 (Call a Method)
// 透過類別實例呼叫在類別中定義的方法。
myCar.displayInfo(); // This is a red electric car with a battery life of 24 hours.

// 點表示法 vs 括號表示法 (Dot vs Bracket Notation)
// 使用點表示法或括號表示法存取物件的屬性。點表示法更直觀，而括號表示法在屬性名為變數時很有用。
console.log(myCar.color);    // red (點表示法)
console.log(myCar['color']); // red (括號表示法)

這個範例透過詳細的註解解釋了 JavaScript 中的關鍵物件導向概念，包括如何定義類別、宣告屬性和方法、建立和使用實例，以及如何實現繼承和多型性。透過這個實際的範例，你可以更好地理解和掌握 JavaScript 的物件導向特性。

範例說明：

這個範例建立了一個 Car 類別作為基礎類別，然後建立了一個 ElectricCar 類別來繼承它。這展示了：

如何定義類別和屬性
如何使用建構函數初始化物件
如何定義公共和私有方法
如何使用繼承擴展類別功能
如何覆寫父類別的方法

重點整理

以下是 JavaScript 物件導向編程的關鍵概念：

類別（Class）：用於建立物件的模板，封裝了相關的屬性和方法。類別定義了物件的結構和行為。
公共與私有屬性：公共屬性可被外部存取和修改，私有屬性（以 # 開頭）僅在類別內部可存取，這提供了更好的封裝性。
建構函數（Constructor）：在建立實例時自動呼叫的特殊方法，用於初始化物件的屬性。這是建立物件時的第一個步驟。
繼承（Inheritance）：使用 extends 關鍵字讓子類別繼承父類別的屬性和方法。這允許你重用程式碼並建立更複雜的類別層次結構。
靜態方法與屬性：屬於類別本身，不需要建立實例即可使用。通常用於工具函數或類別層級的資料。
Getter 和 Setter：提供安全的方式存取和修改私有屬性。這允許你在存取屬性時執行額外的邏輯，例如驗證或計算。

實際應用：

透過這些概念，你可以建立結構清晰、易於維護的 JavaScript 程式碼。物件導向編程特別適合：

大型應用程式的開發
需要重用程式碼的場景
需要模組化和封裝的專案
團隊協作開發

掌握這些概念後，你就能夠寫出更專業、更易於維護的 JavaScript 程式碼。

如何在 SvelteKit 中管理前端環境變數

2023-12-30T01:06:48Z

大家都知道後端節點（如 Node.js）可以輕鬆地透過 .env 檔案或 process 物件來存取環境變數。但在純前端應用程式，尤其是使用如 SvelteKit 這樣的現代框架時，這個任務看起來就沒那麼直觀了。本文將介紹如何在 SvelteKit 中有效地管理和存取環境變數。

在 Node.js 中讀取 `.env` 檔案

在 Node.js 應用程式中，環境變數通常透過 .env 檔案來管理。這些變數可以用來儲存應用程式配置、機密鑰匙或其他環境特定的設定。下面是如何在 Node.js 中讀取 .env 檔案的範例：

import dotenv from 'dotenv';

dotenv.config();

console.log(process.env.YOUR_ENV_VARIABLE);

在上述程式碼中，我們使用 dotenv 函式庫來載入 .env 檔案中的變數。然後，你可以透過 Node.js 的 process.env 物件來存取這些變數。

在 SvelteKit 中管理環境變數

SvelteKit 是一個基於 Svelte 的全端框架，提供了一套更高層次的抽象，特別是在管理環境變數時。在 SvelteKit 中，環境變數不是直接讀取 .env 檔案中的變數。相反，它們需要透過特定的配置來使其在前端程式碼中可用。

SvelteKit 不能直接讀取 .env 檔案的環境變數，意思是它們不是自動地、直接地從 .env 檔案讀取並暴露給前端程式碼。這與 Node.js 中的處理方式有所不同，Node.js 可以直接透過 process.env 存取 .env 檔案中的變數。

在 SvelteKit 中，雖然 .env 檔案仍然用於定義環境變數，但這些變數需要透過 SvelteKit 和其底層的建置工具（Vite）的特定配置來暴露。有一個重要規則：在 .env 檔案中定義的變數需要以 PUBLIC_ 開頭，這樣 Vite 才會在建置過程中將它們暴露給前端程式碼。

所以，當我們在 SvelteKit 中談論環境變數時，它們確實是在 .env 檔案中定義的，但它們的暴露和存取方式是由 SvelteKit 和 Vite 的配置決定的，而非直接從 .env 檔案自動讀取。這是一個重要的安全機制，確保只有明確標記為公開的變數才會暴露給前端。

讀取環境變數範例

步驟 1：創建 `.env` 檔案

首先，在你的 SvelteKit 專案根目錄下創建一個 .env 檔案。例如：

PUBLIC_CLIENT_ID="test-id"

PUBLIC_CALLBACK="http://localhost:5173/oauth2callback"

在 SvelteKit 中，所有要公開的環境變數都應以 PUBLIC_ 開頭，這樣它們才會被 Vite（SvelteKit 底層的構建工具）公開給前端。

步驟 2：存取環境變數

在 SvelteKit 應用程式中，可以直接 import $env/static/public 來存取這些變數：

<script>
  import { PUBLIC_CALLBACK, PUBLIC_CLIENT_ID } from '$env/static/public';

  const redirect_uri = PUBLIC_CALLBACK

  const client_id = PUBLIC_CLIENT_ID
</script>

步驟 3：切換開發環境與正式環境

你可以在專案根目錄放兩個 .env 檔案，分別是 .env 和 .env.production。這樣當你在本機開發使用 pnpm run dev 時，程式會使用 .env 的變數，而當你使用 pnpm run build 時，就會改為使用 .env.production 中的變數。這讓你可以輕鬆地在開發和正式環境之間切換不同的配置。

完整說明請參考 $env/static/public

光輝咖碼

CSS Border-radius 指南, 不是只能畫圓角

目錄

為什麼要重新認識 border-radius？

border-radius 的基本語法

一個值

兩個、三個、四個值的規則

單位很重要：px vs %

px：固定幾何

%：相對於「盒子尺寸」

/ 斜線語法：border-radius 的真正威力

完整語法

瀏覽器其實會「偷偷修正」你的 radius

設計感十足的圓角應用

1. 膠囊按鈕 - 現代 UI 的經典

2. 不對稱設計卡片 - 創造視覺層次

3. 漸層背景 + 圓角 - 創造深度感

4. 動畫過渡 - 互動體驗

5. 多層次圓角設計

小挑戰

重點總結

延伸學習

在 Eleventy（11ty）中優雅地使用 Svelte：一套實用的 Vite-based islands 架構

目錄

為什麼我想在 11ty 裡用 Svelte？

這篇文章會介紹什麼？

整合步驟

Step 1：在 11ty 中啟用 Svelte（Vite）

Step 2：建立一個 Svelte shortcode（關鍵）

Step 3：在 Markdown 文章中使用

Step 4：撰寫一個 Svelte 元件

Step 5：Client-side Svelte Loader（核心）

Step 6：整合 Barba.js

結語

CSS Stacking Context 教學：z-index 為什麼不聽話？

目錄

核心概念：什麼是 Stacking Context（堆疊上下文）

投影片世界的比喻

z-index 會失效的真正原因

z-index 不是隨便就能用

父層一旦建立世界，子層就被封印

哪些情況會建立新的 Stacking Context

常見觸發條件整理

isolation: isolate 是救命用的

為什麼 z-index: 9999 還是輸

結構範例

實際發生了什麼事

三個最常見、也最痛的實戰坑

overflow: hidden 把浮層切掉

transform 讓層級突然亂掉

fixed 不再相對視窗

實用的 Debug 思考流程

專案等級的 z-index 管理方式

最穩定的 Tooltip / Modal 解法

總結

在 Eleventy（11ty）整合 Pagefind：回到「最簡單」的做法

目錄

一開始的誤會：把 Pagefind 當成「一般前端套件」

換個想法：Pagefind 只需要做一件事就好

Step 1：直接 include Pagefind 產生的 CSS / JS

Step 2：放一個搜尋欄位容器

Step 3：標記「真正要被搜尋的內容」

Step 4：初始化 PagefindUI

Step 5：建索引（這行才是 Pagefind 的本體）

Step 6：收進 package.json

最後：上傳

進階補充

Pagefind × Barba.js 切頁時要注意的事

哪些頁面「不該被搜尋」

Pagefind 的搜尋品質，其實取決於你的 HTML 結構

結語

在 Eleventy（11ty）文章中做出像 WordPress 的 Feature Image 特色圖片

目錄

目標效果

步驟 1：在每篇文章 frontmatter 加上 feature image 設定

步驟 2：在 post.njk 加入條件邏輯

步驟 3：套用 CSS，做出「裂成四塊」的核心效果

CSS 技術實作原理

一張圖切四塊，不需要四張圖片

為什麼動畫只用 transform？