光輝咖碼

Eleventy 怎麼顯示流程圖，Mermaid 的顯示和優化

2026-08-29T11:38:00Z

Mermaid 很方便：寫幾行文字，就能變成流程圖。問題是，如果每頁都把 Mermaid library 一起送到瀏覽器，讀者可能只是來看一篇文章，卻先搬一箱 JavaScript 回家。這篇的做法是：固定不變的圖在 build 時先匯出成 SVG 或 PNG，網頁只顯示普通圖片。

先講結論：固定圖在 build 時匯出

文章中的流程圖、架構圖通常不需要訪客現場編輯或互動。這類圖適合用 Mermaid CLI 在建置前轉成靜態檔，再用 <img> 顯示。

這樣做有三個好處：

不用每頁載入 Mermaid JavaScript。
Vite bundle 不會因為固定圖而一起變胖。
可以用圖片的 alt、width、height 和 <figcaption> 照顧可讀性與版面穩定。

如果圖真的會跟著訪客操作即時變化，才保留瀏覽器端 Mermaid。互動不是免費的，通常會用 JavaScript 預算付款。

SVG、PNG，還是瀏覽器端 Mermaid？

先看圖的用途，不要先看工具名稱。選錯格式，就像拿海報字體去印名片：不是不能用，只是會有點委屈。

情境	建議	取捨
一般流程圖、架構圖	build-time SVG	線條與文字縮放清楚；仍要檢查文字大小與對比
固定像素圖片、社群分享、不想處理 SVG	build-time PNG	瀏覽器處理單純；放大可能變糊，檔案也可能較大
圖會因操作即時改變	瀏覽器端 Mermaid	保留互動，但要負擔下載、解析與執行 JavaScript
想把圖直接放進 HTML	build-time inline SVG	少一次圖片請求；HTML 變大，也要審查 SVG 內容

多數教學文章先選 SVG。若你的分享流程、圖片處理或內容系統更適合 PNG，也可以在同一次 build 產出 PNG。重點不是「PNG 永遠比較快」，而是不要讓每個頁面都執行整套繪圖 library。

第一步：準備 Mermaid 原始檔

例如建立 src/diagrams/publish-flow.mmd：

flowchart TD
  A[寫文章] --> B{檢查}
  B -->|通過| C[Eleventy build]
  B -->|未通過| A
  C --> D[輸出靜態網站]

.mmd 是圖表的原始碼。它像食譜；SVG 或 PNG 才是端上桌的蛋糕。讀者通常只需要蛋糕，不需要一起下載烤箱。

第二步：用 Mermaid CLI 匯出 SVG 或 PNG

Mermaid 官方 CLI 的套件名稱是 @mermaid-js/mermaid-cli，命令名稱是 mmdc。可以全域安裝：

npm install -g @mermaid-js/mermaid-cli
mmdc -i "src/diagrams/publish-flow.mmd" -o "src/assets/diagrams/publish-flow.svg"
mmdc -i "src/diagrams/publish-flow.mmd" -o "src/assets/diagrams/publish-flow.png"

或者裝在專案內，讓本機和 CI 使用同一套依賴：

npm install --save-dev @mermaid-js/mermaid-cli
./node_modules/.bin/mmdc \
  -i "src/diagrams/publish-flow.mmd" \
  -o "src/assets/diagrams/publish-flow.svg"

mmdc 會依輸出副檔名產生 SVG、PNG 或 PDF。也可以在輸出時指定主題與透明背景：

mmdc -i input.mmd -o output.png -t dark -b transparent

網站有深色模式時要多留意：SVG 能縮放，不代表它會自動換成深色配色。需要時在 build 時產生 light／dark 兩份，或固定一套在兩種背景都看得清楚的主題。

第三步：讓 Eleventy 複製圖檔

如果圖片放在 src/assets/diagrams/，在 eleventy.config.js 加入 passthrough copy：

export default function (eleventyConfig) {
  eleventyConfig.addPassthroughCopy({
    "src/assets/diagrams": "assets/diagrams"
  });
}

這會把來源目錄複製到輸出目錄的 assets/diagrams。接著，文章或模板可以用普通 HTML 顯示圖片：

<figure class="diagram">
  <img
    src="/assets/diagrams/publish-flow.svg"
    alt="發布流程：寫文章後先檢查；通過才執行 Eleventy build，失敗則回到修改文章。"
    width="900"
    height="520"
    loading="lazy"
    decoding="async">
  <figcaption>圖一：文章從檢查到 Eleventy build 的流程。</figcaption>
</figure>

如果 Markdown 設定允許原始 HTML，直接放上面的 <figure> 即可。這裡要放的是 <img src="...">，不是 <div class="mermaid">。後者只是標記，仍需要 Mermaid JavaScript 在瀏覽器把它畫出來。

若 Markdown 會過濾 HTML，可改用 Nunjucks／WebC layout 或 shortcode 輸出同一段 HTML。不要為了繞過過濾器，就把所有內容無條件標成 safe。

第四步：讓圖片在手機上不拆台

圖片 CSS 可以先從這個版本開始：

.diagram {
  max-width: 100%;
  margin: 2rem 0;
}

.diagram img {
  display: block;
  width: 100%;
  height: auto;
  max-width: 100%;
}

.diagram figcaption {
  margin-top: 0.5rem;
  color: var(--muted, #666);
}

width 和 height 要填輸出圖片的實際像素尺寸。瀏覽器可以先依比例保留空間，降低圖片載入時內容跳動；如果比例填錯，反而可能失真或預留錯誤空間。

寬流程圖在手機上常見兩種結果：

圖縮到看不清楚：改成較短的縱向流程。
圖不能再縮：提供原尺寸圖片連結，讓讀者自行放大查看。

如果有不同寬度或解析度版本，再考慮 <picture> 和 srcset。不要把一張超大 PNG 無條件送給所有裝置。

`alt` 不要只寫「Mermaid 圖」

alt 應該描述讀者從圖中需要知道的結論或流程，例如「通過才執行 Eleventy build，失敗則回到修改文章」，而不是只寫「流程圖」。

如果正文已經完整說明同一個流程，圖片可以使用 alt=""，避免螢幕閱讀器重複朗讀。但正文不能因此消失。圖表不是把文字藏起來的魔法斗篷。

<figure> 讓圖片成為一個有語意的內容單位，<figcaption> 則提供看得見的圖說，也能成為父層 <figure> 的 accessible name。不要只靠顏色區分成功與失敗；把差異寫在節點文字、箭頭標籤或正文裡。

Vite 顯示 chunk 過大，應該怎麼判斷？

Vite 的 build.chunkSizeWarningLimit 預設是 500 kB。這是警告門檻，不是超過就會壞掉的硬限制；把數字調大，只會讓終端機比較安靜，不會讓下載速度變快。

可以用這張表判斷：

你遇到的情況	合理處理
固定 Mermaid 圖，文章不需要互動	build-time 匯出 SVG／PNG，頁面只載入圖片
只有少數頁面需要互動圖	用 `import('mermaid')` 延遲載入，並限制在需要的頁面
chunk 已經量測過，大小可接受，只是不想看到警告	調高 warning 門檻，但不要把它當效能修復
想改善快取與分組	使用手動切 chunk；它不會消除 Mermaid 的下載與執行成本

最後要看實際結果：檢查 build 後不看圖的頁面是否還載入 Mermaid chunk，再用瀏覽器 Network、Lighthouse 和行動裝置測試。警告是煙霧警報器，不是火災報告；先找煙從哪裡來。

上線前檢查清單

[ ] .mmd 與輸出的圖片都有納入版本控制，或 build 能穩定重建。
[ ] mmdc 固定在專案 dev dependency，避免 CI 和本機產出不同。
[ ] 輸出路徑與 <img src> 在開發伺服器、正式站與子路徑部署都正確。
[ ] 圖片有描述性 alt，需要時補上 <figcaption> 和正文文字版。
[ ] width／height 與 responsive CSS 已設定。
[ ] Light／dark mode 下文字與背景都有足夠對比。
[ ] 手機實機看得懂；太寬時提供原圖連結或拆成多張圖。
[ ] build 後確認不看圖的頁面沒有載入 Mermaid chunk。

結語：先把固定圖搬到 build 時間

固定圖先匯出，互動圖才在需要時載入 Mermaid。這個分工通常比「每頁都準備一套繪圖工具」更省事，也更符合靜態網站的個性。

下一次新增 Mermaid 圖時，可以先做一件事：用 mmdc 產出 SVG 或 PNG，放進 Eleventy 的 passthrough asset，再用帶有 alt、尺寸和圖說的 <figure> 顯示。先改一張圖，再看 build 與 Network 數據；咖啡可以慢慢喝，bundle 不必慢慢胖。

參考資料

Mermaid CLI 官方 README — 官方 CLI 安裝、mmdc 參數，以及 SVG／PNG／PDF 輸出。
Mermaid CLI 官方文件入口 — Mermaid CLI 文件入口。
Eleventy Passthrough File Copy — addPassthroughCopy 的來源與輸出路徑。
Vite Build Options — chunkSizeWarningLimit 的預設值與用途。
MDN：<figure> — figure、figcaption 與語意結構。
MDN：HTML images — img、alt 與圖片可及性。
MDN：Understanding and setting aspect ratios — 圖片尺寸與版面空間預留。

PHP 架站全指南：開發者必知的 5 個核心概念

2026-08-29T00:00:00Z

「PHP 已死」這句話聽了十多年，但 W3Techs 的每日統計在 2026 年 8 月仍顯示，約 70.5% 的「已知伺服器端語言」網站使用 PHP；WordPress 則約佔全站 41.2%。數字不會替語言辯護，卻說明一件事：架站與內容系統這條路上，PHP 仍然很有存在感。畢竟，真正退休的程式語言通常不會一直被拿出來宣布死亡。

本文用五個核心概念，幫你快速判斷「該不該學 PHP、怎麼開始、跟 Node.js／Python 怎麼選」。

5 個核心概念（TL;DR）

#	概念	一句話
1	PHP 是什麼	伺服器端腳本語言，在伺服器產生 HTML 再送給瀏覽器
2	為什麼還活著	WordPress 等 CMS 生態系仍佔網站 40%+
3	vs Node／Python	架站/CMS 選 PHP；即時 API／ML 選其他
4	PHP 8 新特性	JIT、Union types、Attributes 等現代語法
5	怎麼開始	本機 Herd／Docker + PHP 新手入門

1. PHP 是什麼：伺服器端腳本語言

PHP 早期名稱是 Personal Home Page，現在正式解釋為遞迴縮寫 PHP: Hypertext Preprocessor。它是特別適合網頁開發的開源通用腳本語言，通常在伺服器上執行。瀏覽器收到的通常是已經產生好的 HTML；資料庫查詢、登入驗證、表單處理，多半在伺服器端完成。

<?php
echo '<h1>Hello PHP</h1>';

把上面存成 index.php，用內建伺服器跑起來：

php -S localhost:8000

開啟 http://localhost:8000，就是最小的動態網頁。

和前端 JavaScript 的差別（簡化）：

	PHP	瀏覽器端 JavaScript
執行位置	伺服器	使用者裝置／瀏覽器
典型工作	資料庫、權限、API、產生 HTML	互動、動畫、SPA
部署	虛擬主機／VPS／容器皆常見	隨頁面下載

補充：JavaScript 也能在後端跑（Node.js），所以「語言名稱 ≠ 前後端」；PHP 則主要以網站後端與伺服器端腳本為人熟知。

常見用途：

動態網站與 CMS（WordPress、Drupal、Joomla）
電商與會員系統
REST API、Webhook
檔案上傳、郵件、排程腳本

2. 為什麼還有人用 PHP

市占與生態

伺服器端語言：PHP 約 70.5%（W3Techs，2026-08）
CMS：WordPress 約佔全站 41.2%（W3Techs，2026-08）

這些是會每日變動的調查數字，而且分母是「被 W3Techs 辨識出來的網站」，不是整個網路的戶口普查。市占高不代表「最適合每個專案」，但代表：主機支援、外掛、教學、接案需求都還在。

主機與上線成本

許多虛擬主機提供 PHP 與資料庫服務，部署傳統網站時不必先組一整套應用程式平台。Node.js 與 Python 當然也能部署到託管平台；只是不同供應商的支援方式、設定與成本不同，選之前要看清楚方案。延伸：免費 SSL、Herd 本機環境。

現代 PHP 已不是「把 HTML 跟邏輯攪在一起」

PHP 8 系列加入許多現代語法與型別功能，也持續改善錯誤處理。主流框架（Laravel、Symfony）搭配 Composer 依賴管理，讓大型專案比較容易維持結構；「比較容易」很重要，因為再好的工具也擋不住把所有程式塞進同一個檔案的熱情。

什麼時候不該硬選 PHP

即時協作、WebSocket 重度應用 → 可優先評估 Node.js 等事件驅動堆疊
資料科學、機器學習主力 → 通常會優先評估 Python 生態
純靜態內容、極致效能與維護單純 → 可考慮靜態網站生成器／11ty

3. PHP vs Node.js vs Python：怎麼選

面向	PHP	Node.js	Python（Django／Flask）
架站／CMS	WordPress 生態成熟	常需自組或採 Headless	可，常見於 Django 等框架
共享主機支援	常見	取決於主機商	取決於主機商
即時應用	可做，非傳統強項	強	中
AI／資料分析	弱	中	強
學習曲線（網站）	低～中	中（非同步思維）	中
常見使用情境	CMS、傳統網站、後端	JavaScript 全端、即時服務	資料處理、後端、AI 原型

實務建議：

要維護或客製 WordPress、接中小企業站 → 學 PHP
要做 SPA + API、即時功能 → Node.js（或 PHP API + 前端框架）
要做資料管線、AI 原型 → Python，網站可另選

語言可以並存：很多團隊用 PHP 管內容站、用 Node／Python 管其他服務。

4. PHP 8.x 你該知道的新特性（含 8.5）

不必一次背完；先知道「現代 PHP 長什麼樣」。

PHP 8.0–8.3 的代表性功能

Named arguments、union types、match、attributes
Constructor property promotion
Readonly properties／classes
#[\Override]（8.3）：覆寫父類方法時更安全
型別化 class constants（8.3）

PHP 8.4–8.5 值得關注

依 PHP 8.5 官方發布公告：

Pipe operator |>：把巢狀呼叫改成由左到右的資料流，可讀性更好
內建 URI extension：依 RFC 3986／WHATWG 解析與正規化 URL，減少脆弱的 parse_url() 用法
clone() 搭配屬性更新：方便 readonly／value object 的 with-er 模式
#[\NoDiscard]：提醒呼叫端不要忽略重要回傳值

範例（PHP 8.5）：

<?php
$result = $input
	|> trim(...)
	|> strtolower(...)
	|> htmlspecialchars(...);

正式環境升級前，請對照框架支援（例如 Laravel／Symfony 版本說明）與測試套件。也要查看 PHP 官方支援版本表，不要只因為版本號看起來很新就直接升級；程式碼不是牛奶，卻同樣有保存期限。

5. 怎麼開始：環境、第一支程式、學習路徑

本機環境（建議）

平台	建議
macOS	Herd（最省事）或 Homebrew `brew install php`
Windows	Herd for Windows 或 Chocolatey
只要試玩	官方二進位 + `php -S`

Herd 教學：用 Herd 架 WordPress。

五分鐘最小範例

<?php
declare(strict_types=1);

$name = $_GET['name'] ?? '訪客';
?>
<!DOCTYPE html>
<html lang="zh-Hant">
<head>
	<meta charset="UTF-8">
	<title>Hello</title>
</head>
<body>
	<h1>你好，<?= htmlspecialchars($name, ENT_QUOTES, 'UTF-8') ?></h1>
</body>
</html>

重點習慣：

開啟 declare(strict_types=1);
輸出到 HTML 前做跳脫（防 XSS）
密碼用 password_hash()／password_verify()，不要自己發明雜湊

建議學習順序

語法與陣列 → PHP 新手入門練習
類別與物件 → Class／Object、存取修飾符
例外處理 → Exception
依賴管理 → Composer
設計原則 → SOLID
選一條產品路：WordPress 外掛／主題，或 Laravel 專案

編輯器推薦 VS Code；字型可搭配 Fira Code。

PHP 工程師在做什麼？就業怎麼看

典型工作內容：後端邏輯、資料庫、API、效能與安全、與前端協作、維護 CMS／電商。

技能組合（實務向）：

PHP 8 + Composer
SQL（MySQL／MariaDB／PostgreSQL）
HTTP、REST、基本資安（XSS、CSRF、SQL Injection）
Git
至少一種框架或 CMS（Laravel 或 WordPress）

職涯方向： 資深後端、全端、技術主管、接案／維護站、或轉架構。薪資取決於能力與產業，不取決於「會不會喊某語言已死」。台灣職缺可在 104 等平台搜「PHP」「Laravel」「WordPress」自行比對當下行情；本文不引用易過期的截圖數字。

知名產品與站點生態中仍可見 PHP（例如 WordPress.org、Wikipedia 等）；企業內部是否採用，要以職缺與專案為準，而非迷思。

常見問題

Q：現在才學 PHP 會不會過時？
A：若目標是架站、WordPress、中小企業維護或 Laravel，PHP 仍是合理選項。若目標是 AI 研究，通常應以 Python 為主、PHP 為輔；最後仍要看你要解決的問題，而不是語言排行榜。

Q：一定要先學完 OOP 才能碰 WordPress 嗎？
A：不必。可先做主題／小外掛建立回饋，再回頭補物件導向與安全觀念。

Q：PHP 7 還能用嗎？
A：PHP 7 已不在 PHP 官方支援版本清單內，正式環境不應把它當成仍受支援的版本。請先確認相依套件與主機相容性，再規劃升級到仍受支援的 PHP 8.x；主機若卡在舊版，優先處理升級路徑，而不是繼續累積技術債。

Q：和靜態站怎麼選？
A：內容少、更新不頻繁、要極致速度與低維護 → 靜態站（本站即 11ty）。要後台、會員、大量編輯者 → PHP／CMS 仍合理。

結語

學 PHP 的理由很務實：生態還在、主機選擇多、WordPress／Laravel 仍有大量使用情境，語言本身也持續更新到 8.5。先掌握「伺服器端動態網頁」這個心智模型，再依目標選 CMS 或框架，比糾結「哪種語言最潮」有用。

下一步：

裝好環境（Herd 或 Homebrew）
跑完 10 個 PHP 練習
決定路線：WordPress 實戰，或 Laravel 入門

這世界只有兩種程式語言，一種是大家都在抱怨的，一種是沒人在用的。
— Bjarne Stroustrup

有人抱怨，通常代表還有人在用——重點是你能不能用它把問題解決好。

參考資料

PHP 官方手冊：Introduction：PHP 的定位、伺服器端執行方式與常見用途。
PHP 8.5.0 官方發布公告：PHP 8.5 的新功能總覽。
PHP 官方手冊：PHP 8.5 新功能：Pipe operator、URI extension、clone() 與 #[\NoDiscard] 的細節。
PHP 官方支援版本：目前仍接受錯誤修正與資安更新的版本分支。
W3Techs：PHP 使用統計：PHP 在可辨識伺服器端語言網站中的每日使用比例。
W3Techs：WordPress 使用統計：WordPress 在全站與已知 CMS 網站中的使用比例。

TypeScript 入門教學：5 分鐘零基礎快速上手

2026-08-29T00:00:00Z

歡迎來到 TypeScript 的世界。它不是把 JavaScript 重新煮一遍，而是在你寫程式時加上型別檢查，讓錯誤更早被發現。這篇文章會帶你在 macOS 建立基本環境、用 tsc 編譯第一支程式，也會簡單比較幾種常見的執行方式。準備好咖啡——型別錯誤通常比咖啡更早提醒你醒來。

TypeScript 是什麼？

TypeScript 是 JavaScript 的語法超集。換句話說，合法的 JavaScript 通常也能放進 TypeScript 專案；而 TypeScript 額外提供型別系統與編譯期檢查。

瀏覽器和多數 JavaScript 執行環境最終仍然需要 JavaScript。因此，TypeScript 原始碼通常會先經過 TypeScript 編譯器（tsc）或其他工具處理，再交給 JavaScript 執行環境。型別主要服務於開發階段，不會原封不動地留在輸出的 JavaScript 裡。

建立 TypeScript 開發環境

先準備 Node.js，再在專案裡安裝 TypeScript。把依賴裝在專案中，比全域安裝更容易固定版本，也比較不會出現「在我電腦明明可以」的經典劇情。

安裝 Node.js

你可以從 Node.js 官方網站下載適合 macOS 的版本，也可以使用 Homebrew：

brew install node

確認 Node.js 與 npm 已經可以使用：

node --version
npm --version

建立專案並安裝 TypeScript

先建立一個專案目錄，接著初始化 package.json：

mkdir typescript-demo
cd typescript-demo
npm init -y

把 TypeScript 安裝成開發依賴：

npm install --save-dev typescript

如果你習慣使用 pnpm，也可以把最後一步改成：

pnpm add --save-dev typescript

安裝在專案裡的 tsc 不會直接成為全域命令。執行它時，可以透過 npx（或 pnpm 的 pnpm exec）使用目前專案的版本：

npx tsc --version

初始化 `tsconfig.json`

tsconfig.json 是 TypeScript 專案的設定檔，會告訴編譯器要處理哪些檔案，以及要輸出什麼形式的 JavaScript。執行以下命令建立初始設定：

npx tsc --init

你可以先使用一份精簡設定：

{
	"compilerOptions": {
		"target": "ES2022",
		"module": "NodeNext",
		"moduleResolution": "NodeNext",
		"strict": true,
		"outDir": "dist"
	},
	"include": ["src/**/*.ts"]
}

這裡的重點有三個：

target 指定輸出的 JavaScript 目標語法。
module 與 moduleResolution 讓 TypeScript 依照 Node.js 的現代模組規則解析程式。
strict: true 開啟一組較嚴格的型別檢查選項，能在編譯階段抓出更多問題。

實際專案的設定會依 Node.js 版本、模組格式與建置工具而不同；上面這份設定適合作為使用現代 Node.js 的入門起點，不是所有專案的萬用答案。

寫出並編譯第一支 TypeScript 程式

建立 src/hello.ts：

const message: string = 'Hello, TypeScript!';

console.log(message);

接著執行編譯：

npx tsc

編譯器會依照 tsconfig.json 的設定，把輸出放到 dist 目錄。你可以執行產生的 JavaScript：

node dist/hello.js

tsc 不只是把副檔名換掉。它會根據設定檢查型別，並把 TypeScript 語法轉換成目標環境能理解的 JavaScript。假設你把字串傳給需要數字的函式，編譯時就可能收到錯誤，而不是等到使用者按下按鈕後才一起尖叫。

`tsc` 常用功能

編譯並檢查

直接執行 npx tsc 會依照專案的 tsconfig.json 編譯。若只想檢查型別、不產生輸出，可以使用：

npx tsc --noEmit

這很適合放在提交程式碼前或持續整合流程中。

指定單一檔案

你也可以直接指定檔案：

npx tsc src/hello.ts

不過要注意，命令列直接指定輸入檔案時，可能不會按照你預期使用專案完整的檔案清單與設定。正式專案通常讓 tsconfig.json 管理編譯範圍，再執行不帶檔名的 npx tsc，行為會比較一致。

執行 TypeScript 的幾種方式

完成編譯後，最單純的方法是用 Node.js 執行輸出的 JavaScript。除此之外，也有適合不同情境的工具。它們各有個性，像咖啡豆一樣；重點不是哪一種最潮，而是哪一種適合你的專案。

使用 Node.js

Node.js 執行的是 JavaScript。為了讓行為跨版本、跨設定更容易理解，入門時建議先用 tsc 編譯，再執行輸出的檔案：

npx tsc
node dist/hello.js

使用 ts-node

ts-node 是一個常見的 TypeScript 執行工具，能在開發時協助你直接執行 .ts 檔案。它適合快速測試與腳本，但正式部署仍要依專案的建置方式決定。

在專案中安裝 ts-node 與 TypeScript：

npm install --save-dev ts-node typescript

使用專案內的執行檔：

npx ts-node src/hello.ts

TypeScript Playground

如果你暫時不想安裝任何東西，TypeScript Playground 是很方便的線上沙盒。你可以貼上程式碼，查看型別錯誤與編譯後的 JavaScript，適合用來驗證小範例。

它不是完整的本機專案環境，但用來試驗語法很夠用。先在 Playground 把概念煮熟，再搬回專案，通常比直接在正式環境亂加鹽安全。

Deno

Deno 是另一個 JavaScript 與 TypeScript 執行環境，提供自己的工具鏈。請依照 Deno 官方安裝文件安裝，不要把 deno 當成一般 npm 套件用 pnpm add -g 安裝。

建立 hello.ts：

// hello.ts
console.log('Hello from Deno!');

接著執行：

deno run hello.ts

Bun

Bun 是另一個 JavaScript 執行環境，也提供執行 TypeScript、套件管理與建置等工具。請依照 Bun 官方安裝文件安裝；它是獨立的執行環境，不是用 pnpm add bun -g 取得的 npm 套件。

建立 hello.ts：

// hello.ts
console.log('Hello from Bun!');

使用 Bun 執行：

bun run hello.ts

接下來可以學什麼？

現在你已經走過基本流程：

安裝 Node.js 與專案內的 TypeScript。
用 tsconfig.json 設定編譯行為。
用 tsc 檢查並輸出 JavaScript。
視情境選擇 Node.js、ts-node、Deno 或 Bun。

下一步可以學習基本型別、函式型別、物件型別、泛型，以及如何在實際 JavaScript 專案中逐步加入 TypeScript。先從能讓程式更容易理解的型別開始，不必一口氣把整本手冊吞下去——那樣連編譯器都會替你噎到。

參考資料

TypeScript 官方網站：TypeScript 的語言介紹與最新文件入口。
TypeScript Handbook：型別系統、編譯器與語言功能的正式教學。
TypeScript tsconfig.json 參考：查詢編譯器選項與設定方式。
Node.js 官方下載頁：取得 Node.js 與查看支援的安裝方式。
Deno 安裝文件：Deno 執行環境的官方安裝指引。
Bun 安裝文件：Bun 執行環境的官方安裝指引。

文章目錄 TOC 怎麼做？SEO 最佳實踐 + WordPress／11ty 三種做法

2026-08-29T00:00:00Z

長文沒有目錄，讀者就得一路往下捲，像在網頁裡玩「找不同」：不同的是重點到底藏在哪裡。Table of Contents（TOC，文章目錄） 能把章節標題變成頁內連結，讓讀者先看地圖，再決定要走哪條路。

這篇讀完，你會知道 TOC 對閱讀體驗與 SEO 能幫多少、如何用原生 HTML 做出穩定錨點，以及靜態網站、JavaScript 和 WordPress 各自適合什麼情境。也會看到本站用 [[toc]] 時，建置流程實際做了什麼。

TOC 到底解決什麼問題

先解決讀者的問題

一份好的 TOC 至少有三個用途：

讓讀者快速掃過文章範圍，判斷內容是否值得讀
讓讀者直接跳到需要的章節，少滑幾個螢幕
讓讀者複製頁面網址後面的 #錨點，把特定段落分享給別人

這些是使用者體驗上的好處，不是「放上 TOC，排名立刻升天」的魔法。SEO 沒有魔法按鈕，不然大家早就把鍵盤換成水晶球了。

SEO 能幫多少：務實版

Google 並沒有保證「加入 TOC 就會排名更高」。比較可靠的做法，是把 TOC 做成一般 HTML 連結，並讓文章有清楚的標題結構：

用一個主要標題，再用 H2、H3 分出章節與小節
使用真正的 <a href="#section-id">，而不是只有 JavaScript 點擊事件
讓連結文字描述目標內容，不要全部都叫「點這裡」

Google 的文件指出，通常需要有 href 的 <a> 元素，搜尋系統才容易擷取連結；至於搜尋結果是否顯示頁內跳轉連結，仍由搜尋系統自動判斷，不能手動保證。

另外，別把頁內跳轉（jump link）和網站導覽列裡的 sitelinks 混在一起。Google 已宣布從 2024 年 11 月 21 日起移除搜尋結果中的 sitelinks search box 視覺元素，但這不等於一般 sitelinks 或頁內錨點消失。

先把標題和錨點做好

TOC 只是導航，不會替混亂的內容結構打掃房間。實作前先確認：

一篇文章有一個主要 H1；本站的版型會處理文章標題。
大章節用 H2，小節用 H3，層級不要從 H2 突然跳到 H4。
每個目標標題都有唯一且穩定的 id。
TOC 的 href 必須和目標標題的 id 完全相同。

最小 HTML 例子如下：

<article>
	<h1>文章標題</h1>
	<nav aria-label="文章目錄">
		<ol>
			<li><a href="#intro">簡介</a></li>
			<li><a href="#setup">開始實作</a></li>
		</ol>
	</nav>
	<section id="intro">
		<h2>簡介</h2>
		<p>這裡是文章簡介。</p>
	</section>
	<section id="setup">
		<h2>開始實作</h2>
		<p>這裡是實作內容。</p>
	</section>
</article>

id 不能在同一頁重複。若兩個標題都叫「結語」，產生器就需要處理碰撞，例如輸出 結語 和 結語-1。手動指定 ID 時也一樣：改了標題後，要一起檢查既有連結，否則讀者只會被送到一個很有禮貌的 404——它什麼都沒做，但態度很好。

三種 TOC 實作方式

A. 建置時產生靜態 TOC

靜態網站最適合這種方式。Markdown 內文放一個標記：

[[toc]]

建置工具讀取標題，輸出一般 HTML 清單與錨點。這種做法不需要額外的前端 JavaScript，HTML 載入時就有內容，通常也比較容易處理無 JavaScript、無障礙和版面穩定性。

本站的 [[toc]] 由 markdown-it-table-of-contents 處理，而且目前設定只列出 H2。換句話說，這篇文章的 H3 會出現在正文裡，但不會自動列進本站的目錄；這是目前建置設定的結果，不是 Markdown 的宇宙定律。

B. 用 JavaScript 動態掃描標題

如果頁面內容是執行後才出現，或需要摺疊目錄、標示目前章節，JavaScript 就很有用。不過它最好是「增強功能」，不要成為唯一的導航來源。

下面是一個不使用 innerHTML 的簡化範例。使用 textContent 和 createElement，可以避免把標題文字直接當成 HTML 解析：

<nav id="table-of-contents" aria-label="文章目錄">
	<h2>目錄</h2>
	<ol id="toc-list"></ol>
</nav>

const tocList = document.querySelector('#toc-list');
const headings = document.querySelectorAll('article h2');
const usedIds = new Set();

headings.forEach((heading, index) => {
	let id = heading.id || `section-${index + 1}`;
	let suffix = 1;

	while (usedIds.has(id)) {
		id = `${heading.id || `section-${index + 1}`}-${suffix}`;
		suffix += 1;
	}

	heading.id = id;
	usedIds.add(id);

	const item = document.createElement('li');
	const link = document.createElement('a');
	link.href = `#${id}`;
	link.textContent = heading.textContent;
	item.append(link);
	tocList.append(item);
});

這段程式的重點不是「看到 H2 就開心地生一堆 <li>」，而是確保每個連結都有 href，每個目標都有唯一 ID。若頁面內容在這段程式執行後才載入，就需要把建立目錄的時機放到內容完成後；不要只在 DOMContentLoaded 時猜測內容已經全部出現。

C. 使用 WordPress 外掛或區塊

WordPress 可以使用 TOC 外掛，或由佈景主題／編輯器提供目錄區塊。選擇時先看這些條件：

能否排除不想出現的標題，例如「參考資料」
輸出的連結是否是真正的 <a href="#...">
是否能處理重複標題並產生唯一 ID
手機版是否容易操作，且不會載入不必要的腳本與樣式

外掛功能越多不代表越適合。若只需要一份簡單目錄，卻順便載入一套動畫、三個 CSS 檔和一位不知道在做什麼的 JavaScript，這就有點像為了煮咖啡買了一台工業鍋爐。

一個可直接測試的完整範例

你也可以開啟 CSS Counter 列表示範頁，查看實際的列表編號效果。下面則是一個不依賴框架的最小頁面：

<!doctype html>
<html lang="zh-Hant">
<head>
	<meta charset="utf-8">
	<meta name="viewport" content="width=device-width, initial-scale=1">
	<title>TOC 示範</title>
</head>
<body>
	<article>
		<h1>TOC 示範文章</h1>
		<nav aria-label="文章目錄">
			<h2>目錄</h2>
			<ol>
				<li><a href="#intro">簡介</a></li>
				<li><a href="#practice">實作</a></li>
			</ol>
		</nav>
		<section id="intro">
			<h2>簡介</h2>
			<p>TOC 先提供路線圖，讀者再決定要不要出發。</p>
		</section>
		<section id="practice">
			<h2>實作</h2>
			<p>點擊目錄連結，應該會跳到這個段落。</p>
		</section>
	</article>
</body>
</html>

2026 年實務檢查清單

發布前可以逐項確認：

[ ] H1、H2、H3 層級符合內容結構，沒有為了字體大小亂用標題
[ ] 每個 TOC 連結都有 href="#..."，目標標題有對應且唯一的 id
[ ] 目錄文字和目標標題一致，讀者不需要玩猜謎遊戲
[ ] 靜態網站優先在建置時輸出；JavaScript 只負責互動增強
[ ] 目錄容器有 nav 和 aria-label，讓輔助科技知道它是導航
[ ] 手機版容易收合或掃讀，不會比文章本身還有存在感
[ ] 已實際點過每個連結，也測過重新整理後的 #錨點

結構化資料可以協助搜尋系統理解頁面，但不能取代清楚的標題、內文和可操作的連結。最實際的 SEO 策略通常不華麗：先讓人找得到、讀得懂、跳得準，再期待搜尋系統看懂。

常見問題

TOC 一定要放在文章最前面嗎？

長文通常放在引言後最方便讀者掃描；如果是桌面版側欄，也可以固定在旁邊。重點是目錄要在 HTML 中真實存在，且連結能直接跳到內容。

中文標題的 `id` 應該怎麼產生？

可以使用可讀的中文 ID、拼音，或其他穩定的 slug。選哪一種不是重點，重點是產生規則要穩定、結果不能重複，而且 TOC 和標題必須使用同一套規則。本站允許中文 slug，並讓 TOC 與標題 ID 共用自訂 slugify。

要不要把 H3 也放進目錄？

看文章長度與目錄深度。小節很多時，H3 會讓目錄變成另一篇文章；小節較少時，列出 H3 則能幫助讀者定位。本站目前只輸出 H2，因此若需要 H3 目錄，必須先調整建置設定，再同步檢查樣式與行動版體驗。

TOC 會不會和其他外掛衝突？

可能會。最常見的問題是兩個工具同時替標題產生 ID，結果一個工具改完，另一個工具的連結就失效。建議由單一工具負責 ID，並在建置後檢查 HTML 中是否有重複 ID 或找不到的 href。

結語

TOC 的核心價值很簡單：讓讀者更快找到重點，也讓頁面結構更容易被理解。靜態站通常優先選建置時產生的原生 HTML；需要高亮、摺疊或動態內容時，再讓 JavaScript 上場；WordPress 則要慎選外掛，別讓目錄為了五行功能背上一整個工具箱。

如果你正在走靜態網站路線，可以接著閱讀：11ty 入門和 PageSpeed 與 Core Web Vitals。文章審完、錨點點完，再來一杯咖啡——這次不必讓咖啡也建立一個 TOC。

參考資料

Google Search Central：SEO Starter Guide：說明可讀、分段並使用標題組織內容的基本原則。
Google Search Central：Make your links crawlable：說明搜尋系統如何擷取帶有 href 的原生連結，以及描述性連結文字的重要性。
Google Search Central：Farewell, Sitelinks Search Box：說明 sitelinks search box 於 2024 年 11 月 21 日起移除，以及這項變更不影響一般 sitelinks。
MDN：HTML id global attribute：說明 id 的唯一性與在頁面內建立片段識別字的用途。
11ty 文件：Markdown：說明 Eleventy 如何處理 Markdown，以及建置流程在靜態網站中的角色。

Tab Manager Plus 教學：Chrome 分頁管理終極指南

2026-08-29T00:00:00Z

你是不是也有過這種經驗：只是想找一個分頁，卻得在分頁列裡滑到天荒地老，最後連自己要找什麼都忘了？分頁開太多時，瀏覽器的工作列看起來就像咖啡店打烊前的桌面——每一杯都像重要的，但沒人知道哪一杯是你的。

這篇會介紹兩款 Chrome 分頁管理擴充功能：Tab Manager Plus 與 Tab Manager Auto。讀完後，你會知道它們各自適合什麼情境、能處理哪些工作，以及如何選擇；不必再用「關掉全部分頁，靠記憶重新開始」這種有點悲壯的整理法。

先認識 Chrome 的分頁整理方式

在開始比較擴充功能前，先釐清問題會比較好。Chrome 本身已經支援分頁群組，可以替群組命名、選顏色、收合分頁，也能把分頁拖進群組。若你只需要偶爾整理幾個主題，內建功能可能已經夠用。

但當你同時開著工作、研究、購物和一堆「等等再看」的分頁時，手動拖曳就會變成另一種工作。這時，擴充功能的價值在於幫你快速找到分頁，或按照規則自動整理。

Tab Manager Plus for Chrome：快速找回分頁

它適合什麼情境？

Tab Manager Plus 的核心工作很直接：把目前開啟的分頁與視窗集中列出，讓你用標題或網址搜尋，而不是一直在分頁列裡左右滑。Chrome Web Store 的說明也把「快速尋找分頁、查看所有視窗、找出重複分頁、限制每個視窗的分頁數」列為主要功能。

換句話說，它比較像一個「分頁搜尋器」，而不是替你決定所有分頁要怎麼生活。這種工具很適合習慣自己分類、但不想自己找分頁的人。

主要功能

集中查看：一次查看目前視窗中的分頁與視窗，少一點盲目搜尋。
搜尋標題與網址：開啟管理介面後直接輸入關鍵字，縮小結果範圍。
標記重複分頁：找出重複頁面後，再決定要保留、移動或關閉哪些分頁。
批次管理：依商店說明，可選取多個分頁，進行移動、建立或刪除等操作。
限制分頁數量：可以設定每個視窗的分頁上限；達到限制後，擴充功能會依其設定處理後續分頁。
隱身模式支援：這不是安裝後就自動開啟的功能。需要到 Chrome 的擴充功能管理頁，針對該擴充功能開啟「允許在無痕模式中使用」。

如果你的痛點是「我明明開過，但它現在在哪裡」，Tab Manager Plus 通常比自動分組更對症。它不會替你安排人生，只負責把分頁叫到你面前——這已經比很多會議主持人可靠了。

Tab Manager Auto：讓分頁按網域自動分組

它的整理方式

Tab Manager Auto 的方向不同。根據 Chrome Web Store 的功能說明，它會依分頁的來源網域自動分組，也能把最近使用的分頁排到該群組較前面的位置，並允許使用者自訂分組。

想像你開了 GitHub、文件網站和幾個測試頁面。你不必每次都手動拖曳，工具會嘗試依照網域把相關分頁集合起來。分頁終於學會排隊了，只是它不會幫你買咖啡。

主要功能

依網域分組：相同來源網域的分頁會被安排到同一組。
依最近使用狀態排序：商店說明指出，最後使用的分頁會被移到所屬群組較前的位置。
自訂群組：除了自動整理，也可以建立自己的分頁群組。

這款工具適合「我不想每天整理，但希望分頁至少不要散落各處」的人。不過，自動化不代表永遠符合你的工作習慣；如果不同專案使用同一個網域，最後仍可能需要手動調整。

Tab Manager Plus 與 Tab Manager Auto 怎麼選？

兩款工具不是誰一定比較強，而是解決的問題不同。先問自己：「我最常浪費時間在找分頁，還是整理分頁？」

需要搜尋與控制：選 Tab Manager Plus

分頁很多，常常找不到某一頁。
需要跨多個視窗搜尋與移動分頁。
想自己決定哪些分頁要保留或關閉。
偶爾才整理一次，不希望工具一直改變分頁配置。

需要自動分組：選 Tab Manager Auto

你常同時開啟同一網站的多個分頁。
希望分頁依網域自動集合。
可以接受偶爾檢查自動分組結果。
想把手動拖曳的時間交給工具處理。

兩者一起用可以嗎？

技術上可以同時安裝，但不代表一定要同時啟用所有自動功能。Tab Manager Auto 負責按規則整理，Tab Manager Plus 負責搜尋與批次管理；如果兩者同時修改分頁位置，結果可能和你的預期不同。

建議先安裝一款，使用幾天後再決定是否需要另一款。擴充功能越多不一定越有效率，瀏覽器不是自助餐盤，拿太多最後只會端不穩。

使用前的兩個提醒

第一，安裝擴充功能前，請查看它要求的權限與開發者資訊，只安裝你信任的工具。Chrome 官方也提醒，擴充功能可能需要讀取或變更你造訪網站上的資料，因此權限不是可以一路按「同意」帶過的小字。

第二，若要在無痕模式使用擴充功能，請開啟 chrome://extensions，找到擴充功能並進入「詳細資料」，再打開「允許在無痕模式中使用」。無痕模式不會讓擴充功能自動獲得這項權限；而且無痕視窗的工作階段資料也有不同的保存規則，別把它當成普通視窗的隱形斗篷。

結語

如果你最常說的是「那個分頁到底在哪裡」，先試 Tab Manager Plus；如果你更想要「分頁自己按網域排好」，可以試 Tab Manager Auto。也可以先使用 Chrome 內建的分頁群組，確認自己的整理習慣後，再決定是否需要擴充功能。

分頁管理的目標不是把分頁列整理得像樣品屋，而是讓你下一次找資料時，真的找得到。整理完記得喝口咖啡——分頁可以自動分組，咖啡目前還不會。

參考資料

Tab Manager Plus for Chrome｜Chrome Web Store：查閱擴充功能列出的搜尋分頁、重複分頁、視窗管理與分頁限制等功能。
Tab Manager Auto｜Chrome Web Store：查閱依來源網域自動分組、最近使用分頁排序與自訂分組的功能說明。
安裝及管理擴充功能｜Google Chrome 說明：查閱安裝擴充功能、檢查權限，以及開啟無痕模式使用權限的步驟。
管理 Chrome 中的分頁｜Google Chrome 說明：查閱 Chrome 內建分頁群組、命名、收合與同步等功能。

Statamic 教學：Flat-file CMS 入門 vs WordPress／11ty

2026-08-29T00:00:00Z

WordPress 功能很多，這是優點，也是有時讓人打開後台就先想泡咖啡的原因。如果你想要一個能用控制面板管理內容、又能把內容和模板放進 Git 的 CMS，Statamic 值得認真看一眼。它把 CMS 的方便，和檔案型工作流程放在同一張桌上——咖啡則放旁邊，避免灑到 YAML。

這篇會帶你認識 Statamic 的 flat-file 模式、用 Laravel Herd 建立本機環境，接著做出首頁、文章集合、文章列表與可重複使用的模板片段。讀完後，你也會知道它和 WordPress、11ty 的定位差在哪裡，以及什麼情況適合選它。

Statamic 是什麼？

Statamic 是建立在 Laravel 上的內容管理系統。它預設使用 flat-file 模式：內容、設定與模板可以用 YAML、Markdown、Antlers 模板等檔案管理，而不是一開始就要求你準備資料庫。

「檔案型」不代表它只有編輯器。Statamic 仍然提供控制面板、內容集合、欄位藍圖、路由和模板系統；需要時，也能改用資料庫儲存。這種設計的重點，是先讓專案保持簡單，等需求真的長大再決定資料儲存方式。

換句話說，Statamic 不是把 CMS 藏在資料庫裡，而是讓你可以在控制面板和程式碼編輯器之間自由切換。內容可以給編輯者管理，結構和模板則可以交給 Git 追蹤。這比在資料庫裡尋找某段設定，少一點考古，多一點開發。

外掛與 Starter Kits

Statamic 有外掛與 Marketplace，可以依專案需求增加功能。不過，選外掛前仍然要先確認相容版本、維護狀態和授權方式；「有外掛」不等於「所有外掛都該裝」。外掛裝太多，網站會像咖啡加了十種糖漿：不是不能喝，但已經忘記原本是什麼味道。

Starter Kits 是什麼？

Starter Kits 是預先準備好的網站起點，通常包含內容結構、模板、樣式和功能。它們比較像「可以繼續修改的專案骨架」，不是 WordPress 那種套上去就結束的主題。每個 Kit 可以有自己的內容模型與設計，因此使用前要先看清楚它包含哪些檔案和功能。

第一次使用時，建議先從空白專案開始。你會比較清楚每一個集合、欄位和模板從哪裡來；熟悉後，再用 Starter Kit 加速重複性高的專案。

先準備本機開發環境

Statamic 的官方文件把 Laravel Herd 列為 macOS 和 Windows 初學者的推薦路徑。Herd 會協助準備 PHP、Composer 和本機 Web 伺服器，省下手動拼裝開發環境的步驟。

如果你已經有 PHP 和 Composer，也可以直接使用 Statamic CLI。這篇先採 Herd 路線，因為少一點環境設定，就多一點時間看網站真的跑起來。

使用 Laravel Herd

安裝 Herd 後，把專案放進 Herd 管理的目錄，再安裝 Statamic CLI：

composer global require statamic/cli

接著建立一個新專案。這個指令會啟動設定精靈，讓你選擇空白網站或 Starter Kit，並建立第一位管理者：

cd ~/Herd
statamic new try-statamic

完成後，Herd 會把專案提供在類似以下的本機網址：

http://try-statamic.test

控制面板則位於 /cp：

http://try-statamic.test/cp

看到首頁和登入畫面，就代表基本環境完成。接下來不急著安裝十個套件，我們先做一個最小的內容流程。

認識首頁與 Antlers 模板

Statamic 的預設首頁模板位於 resources/views/home.antlers.html。副檔名中的 .antlers.html 很重要：它告訴 Statamic 這是一個要由 Antlers 解析的模板，不是原封不動送出的 HTML。

最小的首頁可以先這樣寫：

<h1>歡迎光臨我的 Statamic 實驗站！</h1>

{{ content }}

{{ content }} 會放入目前頁面的內容。模板儲存後重新整理頁面，就能看到結果。Antlers 使用雙大括號，看起來像鬍子；如果模板開始長出真的鬍子，通常是熬夜太久，不是語法功能。

Layout 負責共同外框

網站的共同結構通常放在 resources/views/layout.antlers.html，例如 HTML 外框、導覽列、頁尾和資產引用。頁面模板產生的內容，會插入 {{ template_content }} 的位置：

<!doctype html>
<html lang="{{ site:short_locale }}">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>{{ title ?? site:name }}</title>
</head>
<body>
    {{ template_content }}
</body>
</html>

你可以把 Layout 想成相框：每一頁的內容會變，外框則可以共用。這樣修改頁尾時，不必逐頁複製貼上，少一次複製，也少一次「為什麼只有這頁沒有更新」的偵探劇。

建立部落格的內容集合

在 Statamic 裡，Collection 是一組有共同結構的內容，例如文章、產品或作品集。建立 blog 集合後，文章項目會依集合設定儲存；flat-file 模式下，你可以在專案內直接找到並編輯這些 Markdown 檔案。

先規劃一個簡單的部落格：

title：文章標題
date：發布日期
author：作者
content：正文
featured_image：精選圖片

欄位不是越多越專業。先從讀者真的需要的資料開始，之後再透過 Blueprint 增加欄位。

產生文章模板

建立集合時，Statamic 可以協助產生基本模板，例如：

resources/views/blog/index.antlers.html
resources/views/blog/show.antlers.html

前者用來顯示文章列表，後者用來顯示單篇文章。若你的專案版本或設定產生了不同的檔案名稱，請以實際產生的檔案為準；模板路徑是專案設定的一部分，不要只靠截圖猜路徑。

設定日期與網址

發布日期不是每個網站都必須顯示的欄位，但部落格通常需要它來排序和呈現文章資訊。網址則由 Collection 的 route 設定決定，建議一開始保持簡單，確定內容模型後再設計更複雜的 URL。

顯示文章列表

建立第一篇文章後，就可以用 Collection Tag 讀取 blog 集合。下面的例子把最多五篇文章列在首頁：

<h1>{{ title }}</h1>
{{ content }}

<ul>
    {{ collection:blog limit="5" }}
        <li>
            <a href="{{ url }}">
                <span>{{ title }}</span>
                <time>{{ date }}</time>
            </a>
        </li>
    {{ /collection:blog }}
</ul>

collection:blog 會讀取 blog 集合，limit="5" 則限制輸出數量。這裡的 blog 是集合 handle，不是隨便取的裝飾文字；handle 打錯時，模板通常不會替你把咖啡端過來。

部落格索引頁

在 Pages 集合建立一個部落格頁面，將它設為文章列表使用的模板。resources/views/blog/index.antlers.html 可以重用前面的 Collection Tag：

<h1>{{ title }}</h1>
{{ content }}

{{ collection:blog limit="5" }}
    <a href="{{ url }}">{{ title }}</a>
{{ /collection:blog }}

單篇文章頁

單篇文章模板則負責顯示標題、日期、作者與正文：

<article>
    <h1>{{ title }}</h1>
    <p>Published on {{ date }} by {{ author:name }}</p>
    {{ content }}
</article>

{{ content }} 是文章正文，{{ author:name }} 則是讀取作者資料的寫法之一；實際欄位名稱要和你的 Blueprint 一致。

把重複內容抽成 Partial

文章列表會同時出現在首頁和索引頁。若兩邊都直接複製同一段模板，日後改一個 HTML class 就要改兩次，久了會養出兩份長得很像、脾氣卻不同的程式碼。

在 resources/views/blog/ 建立 _listing.antlers.html，底線是常見的 partial 命名約定：

<ul>
    {{ collection:blog limit="5" }}
        <li>
            <a href="{{ url }}">{{ title }}</a>
        </li>
    {{ /collection:blog }}
</ul>

頁面中再引用它：

{{ partial:blog/_listing }}

Partial 是可重用的模板片段，不是完整頁面。把列表集中管理後，首頁和索引頁就能共享同一份輸出邏輯。

加上導覽列

如果網站有 Pages 集合，可以使用 Nav Tag 產生導覽：

<nav>
    {{ nav from="pages" include_home="true" }}
        <a href="{{ url }}">{{ title }}</a>
    {{ /nav }}
</nav>

把這段放進 Layout，所有套用該 Layout 的頁面就能共用導覽列。樣式可以之後再加，先讓資料流動起來；CSS 不會因為等五分鐘而生氣，但你可能會。

用 Blueprint 增加精選圖片

Blueprint 用來定義集合或頁面的欄位。你可以在 blog 集合的 Blueprint 增加 featured_image，選擇適合圖片資產的欄位型別，並限制單篇文章的圖片數量。

設定欄位時，請分清楚「顯示名稱」和「Handle」。模板會使用 Handle，例如 featured_image。圖片的替代文字也應該在內容編輯時填好，讓無法看見圖片的讀者仍然知道它代表什麼。

在文章模板中輸出圖片時，欄位的實際回傳格式會受 Blueprint 和資產設定影響。最基本的概念如下：

<img src="{{ featured_image }}" alt="{{ featured_image:alt }}">

如果專案使用資產陣列或需要圖片轉換，請依官方 Assets 文件和實際欄位輸出調整模板，不要直接照抄一段不符合資料格式的範例。

Statamic、WordPress 與 11ty 怎麼選？

三者都能拿來做網站，但解決的問題不同：

Statamic：適合需要控制面板、內容集合、欄位藍圖，又希望內容與設定能以檔案管理的團隊。它建立在 Laravel 上，前端可以使用 Antlers，也能依專案選擇其他做法。
WordPress：適合想快速使用成熟後台、佈景主題和外掛生態的使用者。彈性很高，但網站的實際行為會取決於佈景主題、外掛和主機環境。
11ty：適合偏好 Markdown、Git 和靜態輸出的開發者。它是靜態網站產生器，不是內建內容編輯控制面的 CMS；需要多人後台時，通常要另外整合服務。

Statamic 的 flat-file 模式和 11ty 都重視檔案與版本控制，但使用感不同：11ty 偏向建置時把內容產生為靜態檔案；Statamic 則保留 CMS 的管理介面和動態應用程式能力。選擇時先問自己：編輯者需要後台嗎？內容是否需要複雜欄位？部署流程和團隊習慣是哪一種？

適合誰使用？

Statamic 適合以下情境：

內容團隊需要控制面板，但開發團隊想用 Git 管理內容結構和模板。
專案需要自訂 Collection、Blueprint、路由和前端設計。
團隊熟悉 Laravel、PHP 或希望沿用 Laravel 的開發方式。
想從 flat-file 開始，未來再依規模評估資料庫或 Headless 架構。

如果你只想寫幾篇 Markdown，並且不需要後台，11ty 可能更直接。如果你希望安裝主題、調整設定後立即上線，WordPress 的現成生態可能更省力。Statamic 的自由度很高，但自由度也代表你需要自己做一些決定；它不是「完全不用想」的 CMS，而是「可以決定要怎麼想」的 CMS。

結語

Statamic 的核心魅力，不只是「不用資料庫」這一句話，而是把 CMS、檔案型內容、版本控制和 Laravel 開發流程接在一起。從 CLI 建立專案，設定 Collection，再用 Antlers 和 Partial 組出頁面，你可以逐步理解每一層，而不是一次吞下一整套黑盒子。

先做一個小部落格，確認內容模型和模板邏輯，再考慮外掛、Starter Kit、圖片處理或部署。網站開發像手沖咖啡：水溫、比例和流程都重要，但第一杯先喝得下去，比研究半天濾杯角度更重要。

參考資料

Statamic Quick Start Guide：官方快速入門流程，涵蓋安裝、首頁、Collection 與模板。
Install Statamic with the CLI：官方 CLI 安裝需求與 statamic new 建站流程。
Install Statamic with Laravel Herd：官方 Herd 本機環境安裝說明。
Core Concepts：官方說明 flat-file 模式、內容管理與架構取捨。
Collections：官方說明 Collection、Entry 儲存方式與路由。
Antlers Templates：官方 Antlers 模板語法、檔案位置與 Layout 說明。
Starter Kits Overview：官方說明 Starter Kits 和 WordPress themes 的差異。

SOLID 原則 PHP 實戰：五大設計原則速查 + 設計模式對照

2026-08-29T00:00:00Z

寫程式不難，難的是半年後回頭看，還敢不敢改自己的程式碼。當一個類別同時算薪水、寫資料庫、寄信，甚至順便幫你煮咖啡，需求一變就會像耳機線一樣打結。這時候，SOLID 原則可以當一張設計地圖。

這篇會用 PHP 範例帶你理解 SOLID 的五個原則：它們各自想解決什麼問題、怎麼拆出比較健康的設計，以及什麼時候不必硬套。讀完後，你應該能看出程式碼「哪裡開始變胖」，也知道該從哪裡下刀。

SOLID 速查表

字母	原則	白話	違反時的症狀
S	Single Responsibility	一個類別只有一個改變的理由	改 A 功能卻壞 B 功能
O	Open/Closed	對擴充開放、對修改封閉	每加需求就改核心類別
L	Liskov Substitution	子類別可替換父類別	繼承後行為不一致
I	Interface Segregation	介面要小而專	被迫實作用不到的方法
D	Dependency Inversion	依賴抽象，不依賴具體	高層直接 new 低層實作

延伸閱讀：PHP 類別入門 · PHP 設計模式系列

SOLID 是什麼？

SOLID 是五個物件導向設計原則英文名稱的首字母：

S — Single Responsibility Principle（單一職責原則）
O — Open/Closed Principle（開放封閉原則）
L — Liskov Substitution Principle（里氏替換原則）
I — Interface Segregation Principle（介面隔離原則）
D — Dependency Inversion Principle（依賴反轉原則）

它們不是 PHP 的語法，也不是一份「照著做就永遠正確」的檢查表，而是幫助你降低耦合、控制變動範圍的思考工具。換句話說，SOLID 的重點不是把類別拆到像樂高散落一地，而是讓每個變動有比較清楚的落點。

S：單一職責原則（SRP）

單一職責原則常被簡化成「一個類別只做一件事」。這句話方向沒錯，但還不夠精準。Robert C. Martin 對 SRP 的經典說法是：一個模組應該只有一個「改變的理由」。

這裡的「職責」不是方法數量，而是誰會要求它改變。薪資規則由人資提出修改、資料庫格式由後端提出修改、畫面格式由前端提出修改；如果三種需求都集中在 Employee，它就背了太多不同的改變理由。

容易失控的寫法

class EmployeeService
{
	public function calculateSalary(Employee $employee): int
	{
		return $employee->baseSalary() + $employee->bonus();
	}

	public function save(Employee $employee): void
	{
		// 寫入資料庫
	}

	public function renderProfile(Employee $employee): string
	{
		// 組合 HTML
		return '<p>' . $employee->name() . '</p>';
	}
}

這個類別現在知道薪資規則、資料儲存和 HTML。任何一項需求變更，都可能碰到同一個檔案。類別不是不能有三個方法，而是這三個方法的變動原因彼此無關。

讓職責各就各位

class SalaryCalculator
{
	public function calculate(Employee $employee): int
	{
		return $employee->baseSalary() + $employee->bonus();
	}
}

class EmployeeRepository
{
	public function save(Employee $employee): void
	{
		// 將員工資料寫入資料庫
	}
}

class EmployeeProfileRenderer
{
	public function render(Employee $employee): string
	{
		return '<p>' . $employee->name() . '</p>';
	}
}

拆開後，薪資規則、儲存方式與顯示格式各自有清楚的責任邊界，也比較容易單獨測試。SRP 不是「每個類別只能有一個 public method」，而是「不要把不同的變動原因綁在一起」。

O：開放封閉原則（OCP）

開放封閉原則是：軟體實體應該對擴充開放，對修改封閉。意思不是原始碼永遠不能改，而是當你新增一種行為時，最好能透過新增實作來完成，避免反覆修改已經穩定的核心流程。

`if` 越長，咖啡越苦

假設結帳服務用條件判斷處理每種折扣：

function discountFor(string $memberType, int $amount): int
{
	if ($memberType === 'regular') {
		return 0;
	}

	if ($memberType === 'vip') {
		return (int) ($amount * 0.1);
	}

	if ($memberType === 'staff') {
		return (int) ($amount * 0.3);
	}

	return 0;
}

剛開始只有兩種會員，看起來很方便。等到加入生日折扣、活動折扣、合作夥伴折扣，這個函式就會變成一條需要小心穿越的 if 迷宮。迷宮本身沒有錯，但維護它通常不會讓人心情變好。

將變動的規則抽成策略

interface DiscountPolicy
{
	public function discountFor(int $amount): int;
}

final class VipDiscount implements DiscountPolicy
{
	public function discountFor(int $amount): int
	{
		return (int) ($amount * 0.1);
	}
}

final class StaffDiscount implements DiscountPolicy
{
	public function discountFor(int $amount): int
	{
		return (int) ($amount * 0.3);
	}
}

final class Checkout
{
	public function __construct(
		private DiscountPolicy $discountPolicy,
	) {
	}

	public function total(int $amount): int
	{
		return $amount - $this->discountPolicy->discountFor($amount);
	}
}

新增折扣規則時，可以新增另一個 DiscountPolicy 實作，Checkout 不必跟著修改。這就是常見的 Strategy（策略）做法，也是 OCP 的一種實現方式。

不過，OCP 不代表每一個小函式都要先抽介面。尚未出現變動點時過度抽象，反而會增加理解成本。先觀察真正會變的地方，再決定要不要抽象，通常比較務實。

L：里氏替換原則（LSP）

里氏替換原則要求：如果程式碼期待的是某個父型別或介面，那麼換成它的子型別或實作後，原本的正確性與使用方式仍然成立。

重點不是「有 extends 就算繼承成功」，而是子類別必須遵守父類別對外做出的契約。若父類別承諾「呼叫 withdraw() 會扣款」，子類別就不能突然改成「遇到某種帳戶就丟出不支援例外」，否則呼叫端就得先猜對方是哪一種物件。

會讓呼叫端踩雷的繼承

class Bird
{
	public function fly(): void
	{
		// 飛行
	}
}

class Penguin extends Bird
{
	public function fly(): void
	{
		throw new LogicException('企鵝不會飛');
	}
}

function letBirdFly(Bird $bird): void
{
	$bird->fly();
}

letBirdFly() 接受 Bird，照它的契約自然會呼叫 fly()。傳入 Penguin 後卻必定失敗，代表這個繼承關係只是在語法上成立，在行為上卻不成立。

讓抽象符合真正能力

class Animal
{
}

interface Flyable
{
	public function fly(): void;
}

class Sparrow extends Animal implements Flyable
{
	public function fly(): void
	{
		// 飛行
	}
}

class Penguin extends Animal
{
	// 企鵝是動物，但不是 Flyable
}

這裡不是把企鵝排除在鳥類之外，而是避免對「會飛」做出錯誤承諾。設計抽象時，先問「這個型別真的能保證什麼行為？」比先問「它是不是某某的子類別？」更重要。

I：介面隔離原則（ISP）

介面隔離原則主張：不要讓使用者依賴它用不到的方法。這裡的使用者可以是實作介面的類別，也可以是呼叫該介面的其他程式碼。

一個什麼都管的介面

interface Worker
{
	public function code(): void;

	public function test(): void;

	public function cook(): void;

	public function clean(): void;
}

如果 Developer 只需要寫程式與測試，卻被迫實作 cook() 和 clean()，介面就太胖了。更麻煩的是，介面新增一個方法時，所有實作者都可能被迫同步修改。

拆成能組合的小介面

interface Coder
{
	public function code(): void;
}

interface Tester
{
	public function test(): void;
}

final class Developer implements Coder, Tester
{
	public function code(): void
	{
		// 寫程式
	}

	public function test(): void
	{
		// 執行測試
	}
}

小介面讓依賴關係更精準，也讓類別可以用組合表達能力。介面不是自助餐，不需要把所有方法都端上桌；端太多，最後通常只會剩下沒人想吃的抽象。

D：依賴反轉原則（DIP）

依賴反轉原則有兩層意思：

高層模組不應直接依賴低層模組；兩者都應依賴抽象。
抽象不應依賴細節；細節應依賴抽象。

高層模組是業務規則，例如「註冊使用者」；低層模組則可能是 MySQL、檔案系統或第三方 API。業務規則不需要知道資料是存在哪一台資料庫，才能完成自己的工作。

把具體資料庫寫死

class MySqlUserRepository
{
	public function save(string $email): void
	{
		// 寫入 MySQL
	}
}

class RegisterUser
{
	private MySqlUserRepository $repository;

	public function __construct()
	{
		$this->repository = new MySqlUserRepository();
	}

	public function handle(string $email): void
	{
		$this->repository->save($email);
	}
}

RegisterUser 自己建立 MySqlUserRepository，所以測試時很難替換成記憶體版本，未來改用其他儲存方式也得修改業務類別。

讓高層依賴抽象

interface UserRepository
{
	public function save(string $email): void;
}

final class MySqlUserRepository implements UserRepository
{
	public function save(string $email): void
	{
		// 寫入 MySQL
	}
}

final class RegisterUser
{
	public function __construct(
		private UserRepository $repository,
	) {
	}

	public function handle(string $email): void
	{
		$this->repository->save($email);
	}
}

現在 RegisterUser 只依賴 UserRepository 這個抽象，具體實作透過建構子注入。測試時可以傳入一個測試用 repository；正式環境則傳入 MySqlUserRepository。這通常也被稱為依賴注入，但要注意：依賴注入是達成解耦的一種手法，DIP 是設計原則，兩者不是同義詞。

SOLID 與設計模式怎麼分？

SOLID 是設計時的原則；設計模式則是針對常見問題整理出的解法。兩者可以互相呼應，但不是一對一的配對表。

原則	常見呼應方式	重點
SRP	Facade、Repository	把不同變動原因分開
OCP	Strategy、Decorator	新增行為時減少修改核心
LSP	多型、合約測試	子型別遵守抽象契約
ISP	小型角色介面	只依賴真正需要的能力
DIP	Dependency Injection、Factory	高層依賴抽象

例如，Factory 解決的是「物件怎麼建立」，Singleton 解決的是「限制實例數量」。它們都可能出現在某個遵循 DIP 的設計裡，但使用 Singleton 不會自動讓程式變得 SOLID；全域狀態該難測，還是會難測。

實務上怎麼使用 SOLID？

SOLID 最適合拿來處理「已經看見的變動」與「正在造成痛苦的耦合」，不適合當成開工前的儀式。你可以用下面幾個問題做快速檢查：

這個類別是否同時受到不同角色的需求影響？如果是，回頭看 SRP。
每次新增類型都要修改同一串條件判斷嗎？如果是，考慮 OCP。
子類別是否需要丟出「這個方法我不支援」的例外？如果是，檢查 LSP。
類別是否被迫實作或依賴一大堆用不到的方法？如果是，看看 ISP。
業務邏輯是否直接 new 出資料庫、郵件服務或第三方 SDK？如果是，考慮 DIP。

最後也別忘了 YAGNI：還沒有需求、沒有變動跡象時，先寫清楚簡單的程式碼，通常比預先蓋一座抽象城堡更好維護。SOLID 的目標是降低變更成本，不是增加類別數量。類別多到需要地圖才能找到入口，那就不是 SOLID，是迷宮設計。

總結

SOLID 五原則可以濃縮成一句話：讓程式碼的責任清楚、變動可控、依賴可替換，並且讓抽象真正符合它承諾的行為。

你不需要一次重寫整個專案。下一次看到超長類別、巨型 if、不自然的繼承，先挑一個最痛的地方改善，跑測試，再觀察設計是否更容易理解。好的設計通常不是一杯咖啡喝完突然出現，而是每次修改少一點心驚膽跳。

常見 FAQ

SOLID 一定要五個全用嗎？

不用。SOLID 是思考工具，不是開工 checklist。先從最痛的地方（通常是 SRP 或 DIP）下手即可。

SOLID 和設計模式衝突嗎？

不衝突。設計模式是具體解法，SOLID 是設計方向。例如 Factory 常配合 DIP 使用，但 Singleton 濫用可能違反 SRP。

小專案也要 SOLID 嗎？

小腳本、一次性工具不必。當程式碼會被多人維護、需求會持續變動時，SOLID 的投報才明顯。

參考資料

The Single Responsibility Principle — Robert C. Martin：說明 SRP 的「一個改變理由」觀點。
The Open Closed Principle — Robert C. Martin：介紹 OCP 與擴充、修改之間的取捨。
Liskov Substitution Principle — Wikipedia：整理里氏替換原則的正式定義與背景。
PHP 手冊：物件介面：查閱 PHP 介面的宣告與實作規則。
PHP 手冊：建構子與解構子：查閱範例中建構子注入所使用的 PHP 物件語法。

PHP 類別與物件入門：Class／Object 完全指南

2026-08-29T00:00:00Z

如果你曾經寫過一串「先宣告資料、再呼叫函式、最後祈禱不要改壞其他地方」的 PHP，歡迎來到物件導向的世界。這裡會把資料和相關行為放在一起，讓程式不必像咖啡店的桌面一樣，什麼東西都堆在同一區。

這篇會用簡單的 PHP 範例帶你理解類別（Class）、物件（Object）、屬性、方法、$this 與 new，也會說明封裝和物件之間的組合。讀完後，你應該能看懂基本的 OOP 程式，並開始自己設計小型類別。

為什麼要學 PHP 物件導向

物件導向程式設計（Object-Oriented Programming，OOP）不是把每個變數都改名成物件，也不是看到 class 就要立刻召開架構會議。它是一種組織程式的方式：把相關的資料和操作資料的程式碼放在同一個類別裡。

這樣做有幾個實際好處：

更容易組織：一個類別可以集中描述某種事物的資料與行為。
減少重複：同一個類別可以建立多個物件，不必複製一整套程式碼。
比較容易維護：需求改變時，通常可以先從相關類別下手，不必在整個專案裡玩尋寶。
方便協作：大型專案可以依照責任拆分不同類別，讓程式碼邊界更清楚。
支援封裝：可以限制外部直接修改資料的方式，降低資料被亂改的機會。

OOP 不會自動讓所有程式變漂亮；類別設計得不好，仍然可能長成一團義大利麵，只是現在義大利麵住進了 class 裡。

類別與物件是什麼

先用一個生活化的比喻：類別像設計圖，物件像依照設計圖做出來的成品。

例如，Cake 類別可以描述蛋糕有哪些資料（口味、尺寸），以及可以做什麼事（烘烤）。依照這個類別建立出來的巧克力蛋糕和草莓蛋糕，就是兩個不同的物件。

換句話說：

類別（Class）：定義物件應該有哪些屬性和方法。
物件（Object）：類別建立出來的實例，擁有自己的資料。
實例化（Instantiation）：使用 new，依照類別建立物件的過程。

類別本身比較像規格，物件才是程式執行時真正拿來工作的東西。設計圖不能自己吃蛋糕，這點 PHP 也沒有打算替它開例外。

用 PHP 建立第一個類別

類別包含屬性與方法

以下建立一個簡單的 Cake 類別：

<?php

class Cake
{
	public $flavor;
	public $size;

	public function bake()
	{
		echo '正在烘烤 ' . $this->flavor . ' 口味的蛋糕。';
	}
}

這段程式有兩種成員：

flavor 和 size 是屬性（Property），用來保存物件的資料。
bake() 是方法（Method），用來描述物件可以執行的行為。

方法裡的 $this 代表「目前正在呼叫這個方法的物件」。因此，$this->flavor 讀取的是目前這個蛋糕自己的口味，而不是某個神秘的全域蛋糕。

使用 `new` 建立物件

有了類別之後，可以用 new 建立物件，再設定它的屬性：

$chocolateCake = new Cake();
$chocolateCake->flavor = '巧克力';
$chocolateCake->size = '大';

$chocolateCake->bake();

$chocolateCake 是 Cake 的一個物件。箭頭運算子 -> 用來存取物件的屬性或方法，所以：

$chocolateCake->flavor 代表這個物件的 flavor 屬性。
$chocolateCake->bake() 代表呼叫這個物件的 bake() 方法。

同一個類別也能建立多個彼此獨立的物件：

$chocolateCake = new Cake();
$chocolateCake->flavor = '巧克力';

$strawberryCake = new Cake();
$strawberryCake->flavor = '草莓';

$chocolateCake->bake();
$strawberryCake->bake();

兩個物件都來自 Cake 類別，但各自保存不同的 flavor。類別像食譜，物件則是不同口味的成品；PHP 沒有規定所有蛋糕都得是巧克力，算是對甜點界的基本尊重。

用類別管理書籍

接著把概念放進一個比較完整的例子。假設我們要描述一本書，可以把書名和作者放進屬性，再提供一個方法顯示書籍資訊：

class Book
{
	public $title;
	public $author;

	public function describe()
	{
		return $this->title . '，作者：' . $this->author;
	}
}

建立物件並使用它：

$book = new Book();
$book->title = '哈比人';
$book->author = 'J. R. R. 托爾金';

echo $book->describe();

這裡的 Book 是類別，$book 是物件。describe() 不需要另外接收 $book，因為它透過 $this 就能取得目前物件的資料。

把多個物件放在一起

物件也可以成為另一個物件的資料。像書架可以保存多本 Book：

class Bookshelf
{
	public $books = [];

	public function addBook(Book $book)
	{
		$this->books[] = $book;
	}

	public function listBooks()
	{
		foreach ($this->books as $book) {
			echo $book->describe() . PHP_EOL;
		}
	}
}

使用 Bookshelf：

$firstBook = new Book();
$firstBook->title = '哈比人';
$firstBook->author = 'J. R. R. 托爾金';

$secondBook = new Book();
$secondBook->title = '傲慢與偏見';
$secondBook->author = '珍・奧斯汀';

$bookshelf = new Bookshelf();
$bookshelf->addBook($firstBook);
$bookshelf->addBook($secondBook);
$bookshelf->listBooks();

Bookshelf 的 books 屬性是一個陣列，裡面放著多個 Book 物件。這種「一個物件管理其他物件」的做法，就是物件組合（composition）的簡單例子。

封裝與可見性

前面的屬性使用 public，代表類別外部也能直接讀寫。這對示範很方便，但在實際程式裡，未必希望任何地方都能隨意修改資料。

PHP 提供三種常見的可見性：

public：類別內外都可以存取。
protected：類別本身和繼承它的子類別可以存取。
private：只有宣告該成員的類別本身可以存取。

例如，把書名設為私有，並透過方法控制修改方式：

class Book
{
	private $title;

	public function setTitle($title)
	{
		$this->title = $title;
	}

	public function getTitle()
	{
		return $this->title;
	}
}

$book = new Book();
$book->setTitle('哈比人');

echo $book->getTitle();

這就是封裝（Encapsulation）：把資料和操作資料的方法放在一起，並限制外部直接碰觸內部狀態的方式。日後如果需要檢查書名是否為空白，可以在 setTitle() 裡加入規則，而不必搜尋整個專案的每一個賦值動作。

這篇的重點整理

到這裡，你已經掌握 PHP OOP 的基本詞彙：

類別是建立物件的定義，描述屬性與方法。
物件是類別的實例，保存自己的資料。
屬性代表物件的狀態，例如書名或作者。
方法代表物件的行為，例如列出書籍資訊。
new 用來依照類別建立物件。
$this 在物件方法中代表目前的物件。
封裝透過可見性與方法，控制資料如何被使用。
物件組合可以讓一個物件管理其他物件，例如書架管理書籍。

當你開始看到程式裡有許多互相關聯的資料和函式時，可以問自己：「這些東西是不是其實屬於同一種事物？」如果答案是，那就可能是設計類別的好時機。先把責任分清楚，再來喝咖啡；不然最後連咖啡都要被迫繼承 Everything 類別。

參考資料

PHP 官方文件：Classes and Objects：查閱 PHP 類別與物件的完整說明。
PHP 官方文件：The Basics：了解類別宣告、物件建立與 $this 的基本用法。
PHP 官方文件：Visibility：查閱 public、protected 與 private 的存取規則。
PHP 官方文件：Properties：了解類別屬性的宣告與物件屬性存取方式。

PHP try catch 教學：例外處理完整指南（含 finally）

2026-08-29T00:00:00Z

例外處理有點像替程式準備安全網：希望它永遠用不到，但真的出事時，總不能只對著錯誤畫面喝咖啡。這篇會用白話說明 PHP 的 try、catch、finally、Throwable 與自訂例外，讓你知道該在哪裡接住問題，也知道哪些問題根本不是同一種球。

讀完後，你應該能寫出基本的例外處理、依例外類型採取不同策略，並在資料庫操作中保留原始錯誤脈絡，而不是把所有錯誤都包成一句「好像哪裡怪怪的」。

語法速查

try {
	// 可能拋出例外的程式碼
} catch (SpecificException $e) {
	// 處理特定例外
} catch (Throwable $e) {
	// 兜底：任何 Error 或 Exception
} finally {
	// 無論成功失敗都會執行（關連線、釋放資源）
}

關鍵字	用途
`throw new Exception('msg')`	主動拋出例外
`catch (Type $e)`	依類型接住
`finally`	清理資源（可省略）
`Throwable`	PHP 7+ 同時涵蓋 Error 與 Exception

先分清楚：例外、錯誤與 `Throwable`

PHP 中可以被 throw 拋出、再由 catch 接住的物件，必須實作 Throwable 介面。內建的 Exception 與 Error 都屬於這個家族，但兩者的繼承關係不同：

Exception 通常代表應用程式或函式庫預期可以處理的例外。
Error 代表 PHP 執行期間發現的錯誤，例如部分型別或算術錯誤。
Throwable 是兩者共同的上層介面。

因此，catch (Exception $e) 不會接住 Error。如果你確實需要同時處理兩者，可以捕獲 Throwable；不過，這不代表所有錯誤都適合被吃掉。語法錯誤、設定問題或程式設計錯誤，通常應該在開發與記錄階段被找出，而不是在生產環境偷偷假裝沒事。

`try`、`catch` 與 `finally` 怎麼合作？

這三個關鍵字各自負責一件事：

try：放入可能拋出例外的程式碼。
catch：接住符合指定類型的 Throwable，並決定如何回應。
finally：不論是否發生例外，都在流程離開 try／catch 前執行清理工作。

一個最小但完整的例子如下：

<?php

function divide(int $dividend, int $divisor): float
{
	if ($divisor === 0) {
		throw new InvalidArgumentException('除數不能是 0。');
	}

	return $dividend / $divisor;
}

try {
	echo divide(10, 2);
} catch (InvalidArgumentException $exception) {
	echo '輸入無效：' . $exception->getMessage();
} finally {
	echo PHP_EOL . '這段清理流程一定會執行。';
}

throw 之後，同一個區塊中尚未執行的程式碼會被跳過，PHP 會往外尋找第一個符合類型的 catch。如果一路找不到，例外就會繼續往呼叫堆疊上層傳遞，最後可能成為未捕獲例外。

另外，finally 不是「錯誤發生時才執行」的區塊；成功與失敗都會走到它。它很適合放關閉檔案、釋放鎖定或還原暫存狀態等清理工作。清理區塊也不要再次拋出無關例外，否則可能覆蓋原本更重要的錯誤——錯誤會排隊，但不保證乖乖排隊。

檔案操作不一定會自動拋出例外

這是初學者很容易踩到的坑：並非所有 PHP 函式失敗時都會拋出 Exception。例如 fopen() 找不到檔案時，通常會回傳 false 並產生警告；單純把它放進 try，不會自動變成可捕獲的例外。

如果你的程式需要用例外流程處理這種失敗，就要明確檢查回傳值，再自行拋出例外：

<?php

function openFile(string $path)
{
	$handle = fopen($path, 'r');

	if ($handle === false) {
		throw new RuntimeException('無法開啟檔案：' . $path);
	}

	return $handle;
}

$handle = null;

try {
	$handle = openFile(__DIR__ . '/example.txt');
	$content = stream_get_contents($handle);
} catch (RuntimeException $exception) {
	echo '檔案處理失敗：' . $exception->getMessage();
} finally {
	if (is_resource($handle)) {
		fclose($handle);
	}
}

這裡的重點不是把每個警告都硬轉成例外，而是先確認你使用的 API 如何回報失敗，再選擇一致的處理方式。

建立自訂例外

當程式只丟出一個通用的 Exception，呼叫端往往只能看訊息猜發生什麼事。建立有語意的例外類別，可以讓 catch 更精準，也讓日後搜尋記錄檔容易很多。

自訂例外通常只要繼承 Exception 或它的子類別即可：

<?php

class FileNotFoundException extends RuntimeException
{
}

function readConfig(string $path): string
{
	if (!is_file($path)) {
		throw new FileNotFoundException('找不到設定檔：' . $path);
	}

	$config = file_get_contents($path);

	if ($config === false) {
		throw new RuntimeException('無法讀取設定檔：' . $path);
	}

	return $config;
}

try {
	$config = readConfig(__DIR__ . '/config.php');
} catch (FileNotFoundException $exception) {
	echo '設定檔不存在，請檢查部署內容。';
}

類別名稱本身就是文件。與其在每個地方解析一長串錯誤訊息，不如讓 FileNotFoundException 直接說明「是哪一類問題」。

如果需要保留較低層的原因，可以在建立新例外時傳入上一個例外。這種做法稱為例外鏈結：

<?php

class DatabaseException extends RuntimeException
{
}

try {
	// 這裡假設資料庫函式庫拋出了 PDOException。
	throw new PDOException('連線被拒絕');
} catch (PDOException $exception) {
	throw new DatabaseException('無法完成資料庫操作。', 0, $exception);
}

上層可以用 getMessage() 取得對使用者較安全的訊息，也可以用 getPrevious() 追查原始原因。請避免直接把資料庫帳號、密碼、完整 SQL 或堆疊資訊顯示給使用者；這些內容比較適合寫入受保護的伺服器記錄。

多個 `catch`：順序就是優先權

一個 try 後面可以接多個 catch。PHP 會從上到下比對，執行第一個符合的區塊。因此，具體的例外要放前面，較一般的類型放後面：

<?php

try {
	// 可能拋出不同類型的 Throwable。
} catch (FileNotFoundException $exception) {
	echo '找不到檔案。';
} catch (RuntimeException $exception) {
	echo '執行時發生可預期的問題。';
} catch (Throwable $exception) {
	echo '發生未預期的錯誤。';
}

反過來，如果先寫 catch (Throwable $exception)，後面的區塊就永遠沒有機會接手。這就像先在門口安排一個「所有人都進來」的保全，後面再安排「只接待 PHP 開發者」的櫃檯，後者自然會失業。

若不同例外需要完全相同的處理方式，也可以使用聯合捕獲語法：

<?php

try {
	// 可能拋出這兩類例外。
} catch (InvalidArgumentException | UnexpectedValueException $exception) {
	echo '收到無效的資料。';
}

`finally` 的實務用法

finally 適合處理「無論成功或失敗都要做」的事情，例如關閉檔案、釋放鎖或還原狀態。它不適合拿來掩蓋錯誤，也不建議在裡面寫 return，因為那可能覆蓋 try 或 catch 原本要回傳的值，讓除錯難度直接升級。

需要注意的是，finally 不是萬能清潔工。若程式直接結束，或清理本身拋出新的例外，流程可能不會照你預想的方式完成。因此，清理程式應該保持簡單、可預期。

實用案例：包裝 PDO 例外

以下用新增書籍的流程示範例外分層。範例明確設定 PDO 使用例外模式，避免把不同的錯誤回報方式混在一起：

<?php

class DatabaseException extends RuntimeException
{
}

function addBook(PDO $db, string $title, string $author): void
{
	try {
		$statement = $db->prepare(
			'INSERT INTO books (title, author) VALUES (:title, :author)'
		);
		$statement->execute([
			'title' => $title,
			'author' => $author,
		]);
	} catch (PDOException $exception) {
		throw new DatabaseException('新增書籍失敗。', 0, $exception);
	}
}

try {
	$db = new PDO(
		'mysql:host=localhost;dbname=library;charset=utf8mb4',
		$username,
		$password,
		[
			PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
		]
	);

	addBook($db, '1984', 'George Orwell');
	echo '書籍新增成功。';
} catch (DatabaseException $exception) {
	echo '目前無法新增書籍，請稍後再試。';
	// 實務上可在這裡記錄 $exception 與 getPrevious() 的資訊。
}

這個範例有三個值得保留的設計：

addBook() 將底層的 PDOException 包裝成應用程式看得懂的 DatabaseException。
throw new DatabaseException(..., 0, $exception) 保留原始例外，方便記錄與除錯。
對外只顯示安全、友善的訊息，不把資料庫細節直接送到瀏覽器。

資料庫連線的生命週期也不必硬塞進 finally。當 $db 離開作用域且沒有其他參照時，PHP 會回收物件；真正需要 finally 的情境，應該是你有明確的資源或狀態需要無條件清理。

常見問題

`catch (Exception $exception)` 能接住所有錯誤嗎？

不能。Error 不繼承 Exception。若需要同時接住實作 Throwable 的 Exception 與 Error，可以使用 catch (Throwable $exception)，但應先確認這樣做符合你的錯誤處理策略。

所有 PHP 函式失敗時都會拋出例外嗎？

不會。不同函式的行為不同，有些會回傳 false、null 或錯誤碼，有些才會拋出例外。請先查閱該函式的文件，再決定是否需要檢查回傳值或設定錯誤模式。

`finally` 一定會執行嗎？

在正常離開 try／catch 的流程中，finally 會執行，包括 try 或 catch 中遇到 return 的情況。但若程式直接終止，或 finally 自己拋出例外，就可能改變原本的流程與結果。

什麼時候該捕獲 `Throwable`？

在應用程式邊界、記錄未預期錯誤或建立統一錯誤回應時，Throwable 可能有用。一般業務邏輯則應優先捕獲具體類型，否則很容易把真正的程式錯誤當成正常流程處理。

總結

PHP 例外處理的核心不是「把所有錯誤抓起來」，而是讓錯誤在合適的邊界被辨識、記錄與回應。先分清楚 Exception、Error 與 Throwable，再用具體的自訂例外表達意圖；需要清理時使用 finally，需要跨層轉換時保留 getPrevious() 的原始脈絡。

當你開始這樣設計，錯誤就不再只是紅色畫面，而會變成可以追蹤、可以處理的訊號。咖啡可以繼續喝，例外則交給正確的 catch。

參考資料

PHP 官方文件：Exceptions：說明 try、catch、finally、例外傳遞與 Throwable。
PHP 官方文件：Errors in PHP 7：說明 Error 與 Exception 的差異，以及 Throwable 的角色。
PHP 官方文件：PDO — Errors and error handling：說明 PDO 的錯誤模式與 PDOException。

PHP Composer 教學：依賴管理入門到實戰

2026-08-29T00:00:00Z

PHP 專案一大，手動 require 檔案就像點餐時每道菜都要自己去廚房端：不是做不到，只是很快就會想喝咖啡冷靜一下。這篇會用一個小型流程，帶你理解 Composer 如何管理依賴、產生自動載入器，以及 composer.json、composer.lock 該怎麼分工。

看完之後，你應該能完成以下事情：

安裝 Composer，建立一個 Composer 專案。
使用 require、install、update 等日常指令。
讀懂 composer.json 的常見欄位。
用 PSR-4 設定自己的類別自動載入。
判斷什麼時候應該提交 composer.lock。

Composer 是什麼

Composer 是 PHP 的依賴管理工具。你可以在專案裡宣告需要哪些函式庫，以及允許使用哪些版本範圍；Composer 會解析這些依賴，下載套件與它們需要的其他套件，並把檔案放在專案的 vendor/ 目錄。

這裡有一個容易搞混的地方：Composer 管理的是「每個專案自己的依賴」，不是像作業系統套件管理器那樣，預設把函式庫裝成全機共用。不同專案可以因此使用不同版本，彼此不必為了搶同一杯咖啡而吵架。

Composer 也會產生自動載入器。PHP 程式只要載入 vendor/autoload.php，就能使用已安裝套件提供的類別，不必逐一 require 每個檔案。

安裝 Composer

請先確認電腦已經有 PHP，再依照 Composer 官方的安裝說明操作。macOS 使用 Homebrew 時，可以執行：

brew install composer

安裝完成後，用版本指令確認 Composer 可用：

composer --version

不同作業系統的安裝方式和前置需求可能不同，請以 Composer 官方安裝說明為準。macOS 的 Homebrew 尚未安裝？可以先看看站內的 Homebrew 安裝教學。

建立第一個 Composer 專案

初始化 `composer.json`

在專案根目錄執行：

composer init

Composer 會以互動問答引導你建立 composer.json。這個檔案是專案的依賴與設定描述，通常放在版本庫的根目錄。

你也可以直接新增套件，讓 Composer 在需要時建立或更新 composer.json：

composer require monolog/monolog

monolog/monolog 是 Packagist 上實際存在的套件名稱；如果你要安裝其他套件，請先確認套件名稱與它支援的 PHP 版本。執行 require 後，Composer 會更新 composer.json、解析依賴、建立或更新 composer.lock，並把套件安裝到 vendor/。

在 PHP 程式中載入套件

在程式的入口檔案載入 Composer 自動載入器：

<?php

require __DIR__ . '/vendor/autoload.php';

接著就能使用套件提供的類別。__DIR__ 代表目前 PHP 檔案所在的目錄，比依賴目前工作目錄更穩定；換句話說，程式從哪裡被執行，不會影響它尋找 vendor/ 的位置。

`composer.json` 常見欄位

一個專案的設定可以像這樣：

{
    "name": "vendor/project",
    "description": "專案描述",
    "type": "project",
    "require": {
        "monolog/monolog": "*"
    },
    "require-dev": {
        "phpunit/phpunit": "*"
    },
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    },
    "scripts": {
        "test": "phpunit"
    }
}

這段是示意結構，不代表你應該在正式專案中使用 *。實務上應根據套件相容性選擇合適的版本約束，並讓 Composer 寫入 lock 檔來固定實際解析出的版本。

常見欄位如下：

name：套件名稱，通常使用 廠商或組織名稱/專案名稱 格式。
description：專案或套件的簡短說明。
type：套件類型；應用程式與可重複使用的函式庫用途不同。
require：正式執行需要的依賴。
require-dev：開發、測試或靜態分析需要的依賴。
autoload：正式程式碼的自動載入規則。
autoload-dev：只在開發情境使用的自動載入規則。
scripts：把常用工作包成 Composer 指令，例如 composer test。

完整欄位和格式請查閱 Composer 的 composer.json schema，不要把網路文章裡的範例直接當成最新規格。

Composer 與 PSR-4 自動載入

Composer 是工具；PSR-4 是 PHP-FIG 制定的自動載入規範。PSR-4 描述命名空間如何對應到檔案路徑，Composer 則可以讀取這項設定並產生自動載入器。兩者不是同一件事，就像咖啡機和咖啡豆：常常一起出現，但職責不同。

設定 PSR-4

假設專案結構如下：

project/
├── composer.json
├── src/
│   └── Controllers/
│       └── UserController.php
└── public/
    └── index.php

在 composer.json 加入：

{
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    }
}

在這個映射下，App\Controllers\UserController 會對應到 src/Controllers/UserController.php。類別的命名空間、類別名稱與檔案路徑要一致：

<?php

namespace App\Controllers;

class UserController
{
    public function index(): string
    {
        return 'Hello, Composer!';
    }
}

設定或新增自動載入規則後，重新產生自動載入檔：

composer dump-autoload

然後在入口檔載入 vendor/autoload.php，就可以使用 new UserController()。PSR-4 的重點不是魔法，而是大家遵守同一套「命名空間對應路徑」的規則；規則一致，檔案就不用到處報到。

日常最常用的 Composer 指令

`composer require`

新增正式依賴：

composer require vendor/package

若套件只在測試或開發時使用，可加入 --dev：

composer require --dev vendor/package

這個指令會修改 composer.json，並重新解析與安裝依賴。

`composer install`

依照目前的 composer.lock 安裝依賴：

composer install

在拉下專案原始碼、CI 或部署環境中，通常應優先使用 install。有 lock 檔時，Composer 會使用其中記錄的精確版本；沒有 lock 檔時，則會先解析依賴並建立它。

`composer update`

依照 composer.json 允許的版本範圍重新解析依賴：

composer update

這會更新 composer.lock。它不是「每次安裝都該執行」的按鈕，而是你有意識地要更新依賴時才使用。否則一個看似平凡的更新，可能讓整個專案一起喝雙倍濃縮。

只更新單一套件及其必要依賴時，可以指定套件名稱：

composer update vendor/package

`composer remove`

移除依賴：

composer remove vendor/package

Composer 會同步更新 composer.json、composer.lock 與 vendor/。

`composer dump-autoload`

重新產生自動載入檔，但不負責重新解析依賴：

composer dump-autoload

如果只是修改 autoload 設定或需要重建 autoloader，使用這個指令即可，不必為了重建自動載入器而更新所有套件。

正式環境也可以使用 Composer 文件描述的最佳化選項，例如：

composer dump-autoload --optimize

是否使用最佳化，以及要不要採用更嚴格的 classmap 選項，應依專案的部署方式測試後決定。

`composer show` 與 `composer validate`

查看已安裝套件：

composer show

檢查 composer.json 與 lock 檔：

composer validate

當你接手別人的專案，這兩個指令很適合當作快速健康檢查：先看有哪些依賴，再確認設定檔是否合理。

`composer.lock` 要不要提交

composer.lock 記錄 Composer 解析出的精確依賴版本。它讓團隊成員、CI 和部署環境能安裝同一組版本，避免「我這裡可以跑」成為專案最常見的考古謎題。

一般可依專案類型判斷：

應用程式：通常應提交 composer.lock，讓每次安裝都使用經過確認的依賴版本。
可供其他專案安裝的函式庫：lock 檔對使用者安裝你的函式庫不會產生同樣的鎖定效果，因此是否提交可依團隊測試流程決定；Composer 官方文件也說明，函式庫可以不提交 lock 檔。

不論哪一種專案，都不要把 vendor/ 當成依賴版本的主要紀錄。版本與相容性約束寫在 composer.json，精確解析結果則由 composer.lock 保存。

一個實用的工作流程

新專案可以依這個順序開始：

composer init
composer require vendor/package
composer install

日後從版本庫取得程式碼時：

composer install

需要有計畫地更新依賴時：

composer update
composer validate

如果新增了自己的 PSR-4 類別映射，再執行：

composer dump-autoload

掌握這個分工後，Composer 就不再像一個只會吐出紅字的黑盒子：composer.json 描述需求，composer.lock 固定結果，vendor/autoload.php 負責把類別帶進來。剩下的問題，先讓 Composer 解；解不出來，再泡一杯咖啡一起看錯誤訊息。

參考資料

Composer Introduction：Composer 的定位、安裝方式與基本概念。
Composer Basic usage：composer.json、依賴安裝、lock 檔與自動載入流程。
Composer Command-line interface / Commands：require、install、update、dump-autoload 等指令的官方說明。
The composer.json schema：設定檔欄位、版本約束與 PSR-4 映射格式。
PSR-4: Autoloader：PHP-FIG 的 PSR-4 自動載入規範。

光輝咖碼

Eleventy 怎麼顯示流程圖，Mermaid 的顯示和優化

目錄

先講結論：固定圖在 build 時匯出

SVG、PNG，還是瀏覽器端 Mermaid？

第一步：準備 Mermaid 原始檔

第二步：用 Mermaid CLI 匯出 SVG 或 PNG

第三步：讓 Eleventy 複製圖檔

第四步：讓圖片在手機上不拆台

alt 不要只寫「Mermaid 圖」

Vite 顯示 chunk 過大，應該怎麼判斷？

上線前檢查清單

推薦工具／資源

結語：先把固定圖搬到 build 時間

參考資料

PHP 架站全指南：開發者必知的 5 個核心概念

5 個核心概念（TL;DR）

目錄

1. PHP 是什麼：伺服器端腳本語言

2. 為什麼還有人用 PHP

市占與生態

主機與上線成本

現代 PHP 已不是「把 HTML 跟邏輯攪在一起」

什麼時候不該硬選 PHP

3. PHP vs Node.js vs Python：怎麼選

4. PHP 8.x 你該知道的新特性（含 8.5）

PHP 8.0–8.3 的代表性功能

PHP 8.4–8.5 值得關注

5. 怎麼開始：環境、第一支程式、學習路徑

本機環境（建議）

五分鐘最小範例

建議學習順序

PHP 工程師在做什麼？就業怎麼看

常見問題

結語

參考資料

TypeScript 入門教學：5 分鐘零基礎快速上手

目錄

TypeScript 是什麼？

建立 TypeScript 開發環境

安裝 Node.js

建立專案並安裝 TypeScript

初始化 tsconfig.json

寫出並編譯第一支 TypeScript 程式

tsc 常用功能

編譯並檢查

指定單一檔案

執行 TypeScript 的幾種方式

使用 Node.js

使用 ts-node

TypeScript Playground

Deno

Bun

接下來可以學什麼？

參考資料

文章目錄 TOC 怎麼做？SEO 最佳實踐 + WordPress／11ty 三種做法

目錄

TOC 到底解決什麼問題

先解決讀者的問題

SEO 能幫多少：務實版

先把標題和錨點做好

三種 TOC 實作方式

A. 建置時產生靜態 TOC

B. 用 JavaScript 動態掃描標題

C. 使用 WordPress 外掛或區塊

一個可直接測試的完整範例

2026 年實務檢查清單

常見問題

TOC 一定要放在文章最前面嗎？

中文標題的 id 應該怎麼產生？

要不要把 H3 也放進目錄？

TOC 會不會和其他外掛衝突？

結語

參考資料

Tab Manager Plus 教學：Chrome 分頁管理終極指南

目錄

先認識 Chrome 的分頁整理方式

Tab Manager Plus for Chrome：快速找回分頁

它適合什麼情境？

主要功能

`alt` 不要只寫「Mermaid 圖」

初始化 `tsconfig.json`

`tsc` 常用功能

中文標題的 `id` 應該怎麼產生？

`if` 越長，咖啡越苦

使用 `new` 建立物件