Astro 從零開始：完整初學者指南

版本：2026年 9月 15日

若你初次接觸 Astro，看到以下檔案：

index.astro
[...slug].astro
src/pages/
src/content/
src/components/
src/layouts/

感到困惑是很正常的。

其核心概念並不複雜。請先理解：

Astro 如何將一堆檔案轉換成瀏覽器中的網頁。

一旦理解這一點，index.astro、[...slug].astro、Markdown、版面（layout）與元件（component）就會容易許多。

1. 用一句話理解 Astro

Astro 是一種將內容、模板與程式碼轉換成 HTML 網頁的工具。

例如：

src/pages/about.astro  →  /about

瀏覽器主要收到 HTML、CSS，以及真正需要的 JavaScript。

你的原始檔案
       │
       ▼
     Astro
       │
       ▼
HTML / CSS / JavaScript
       │
       ▼
   瀏覽器

Astro 不是瀏覽器，而是在建置階段準備網站的工具。

2. Astro 專案的主要部分

my-site/
├── public/
├── src/
│   ├── pages/
│   ├── components/
│   ├── layouts/
│   ├── content/
│   └── styles/
├── astro.config.mjs
├── package.json
└── tsconfig.json

位置	用途
`src/pages/`	定義 URL
`src/content/`	文章內容
`src/components/`	可重複使用的 UI 元件
`src/layouts/`	共用的頁面外框
`src/styles/`	CSS
`public/`	靜態檔案（圖片、favicon）
`astro.config.mjs`	全站 Astro 設定

最先需要理解的是 src/pages/。

3. `src/pages`：URL 如何產生

Astro 使用檔案式路由：

src/pages 下的資料夾與檔案結構，通常決定 URL。

src/pages/index.astro   → /
src/pages/about.astro   → /about
src/pages/en/index.astro → /en/
src/pages/en/home-lab/firewall.astro → /en/home-lab/firewall

與 Angular 不同，通常不需要另外撰寫路由設定檔，檔案位置即為路由。

4. `index.astro` 為何重要

index.astro 是該資料夾的首頁：

src/pages/index.astro        → /
src/pages/en/index.astro     → /en/
src/pages/en/home-lab/index.astro → /en/home-lab/

5. `.astro` 檔案裡有什麼？

---
const name = "Harry";
---

<h1>Hello {name}</h1>

上方 --- 區塊：匯入、資料、建置時邏輯
下方：HTML 模板

6. `components`：可重複使用的積木

不必在每個頁面重複寫相同的頁首，只需建立一次 Header.astro 並在各處匯入。

修改一次頁首，所有頁面同步更新。

7. `layouts`：共用的頁面外框

版面（layout）包裝共同的結構：

Header
Main content
Footer

例如：在自訂 Astro 網站中，ContentLayout.astro 可包裝每篇文章頁面。

8. `<slot />` 是什麼？

<slot /> 是版面中插入內容的位置。

可理解為：「把頁面主體放在這裡。」

9. Markdown 為何適合寫部落格

Markdown 專注於內容，而非版面，適合部落格、教學與技術筆記。

10. `src/content` 與 `src/pages` 的差別

	`src/content`	`src/pages`
用途	文章資料	路由與頁面組裝
範例	`home-lab/firewall.md`	`en/[...slug].astro`

src/content 本身不會自動產生 URL。

11. 最重要的一句話

Content 是文章，Pages 是 URL。

Markdown 內容 → Astro 路由 → 版面 → HTML → 瀏覽器

12. 動態路由（Dynamic Route）是什麼？

不必為每篇文章建立一個 .astro 檔案，可用一個模板處理多個 URL。

13. `[slug].astro` 是什麼？

處理單一可變路徑段：

/products/apple
/products/orange

14. `[...slug].astro` 是什麼？

處理多段路徑：

/en/home-lab
/en/home-lab/firewall
/en/home-lab/network/vlan

這是純 Astro 網站中常見的模式：一個 catch-all 路由檔案可服務多個巢狀文章 URL。

15. `getStaticPaths()` 為何存在？

靜態網站在建置時必須知道所有 URL。

getStaticPaths() 回傳要預先渲染的 slug 清單。

16. Markdown 如何變成 URL

在純 Astro 網站中：

firewall.md
    │ 讀取 frontmatter：slug = home-lab/firewall
    ▼
[...slug].astro
    │ 套用 ContentLayout
    ▼
/en/home-lab/firewall

Markdown 不會自己產生 URL，而是由路由讀取並建置頁面。

17. 純 Astro 與 Astro + Starlight

許多 Astro 教學會介紹純 Astro 的做法：

Markdown
    ↓
Content Collection
    ↓
[...slug].astro
    ↓
getStaticPaths()
    ↓
Layout
    ↓
Page

若需要完全掌控路由、版面、側邊欄與語言切換，這種方式很適合。

Astro + Starlight 是建置在 Astro 之上的文件站方案。你在 src/content/docs/ 撰寫 Markdown，Starlight 提供文件站外殼：

Markdown
    ↓
src/content/docs/
    ↓
Starlight
    ↓
側邊欄 + 目錄 + 搜尋 + 頁面

	純 Astro	Astro + Starlight
路由	自行建立 `[...slug].astro` 與 `getStaticPaths()`	`src/content/docs/` 下的檔案路徑即為 URL
側邊欄	自訂元件或設定	依資料夾與 frontmatter 自動產生
本頁目錄	自訂或手動	依標題自動產生
搜尋	自行整合（如 Pagefind）	內建 Pagefind
多語系	自訂配對邏輯	內建語系資料夾（`en/`、`zh/`）

兩者都合理。純 Astro 有助理解路由原理；Starlight 適合不想自行重建導覽、目錄與搜尋的文件站。

18. 套用到目前的 harrylo.com

目前 harrylo.com 技術站使用 Astro + Starlight，而非自訂的 [...slug].astro 路由。

/en/                          → 英文首頁
/zh/                          → 中文首頁
/en/astro/astro-from-zero/    → 本指南（英文）
/zh/astro/astro-from-zero/    → 本指南（中文）

內容結構如下：

src/content/docs/
├── en/
│   ├── index.md
│   └── astro/
│       └── astro-from-zero.md
└── zh/
    ├── index.md
    └── astro/
        └── astro-from-zero.md

新增頁面時，在 en/ 與 zh/ 下加入相同相對路徑的 Markdown 檔案即可，不需要新增 .astro 路由檔。

本站曾有使用 src/pages/en/[...slug].astro 與自訂版面的純 Astro 原型，該做法仍值得學習，但不是本 Starlight 網站的建置方式。

19. 英文與中文頁面如何配對

在 Starlight 中，每種語言有各自的資料夾，且相對路徑一致：

src/content/docs/en/astro/astro-from-zero.md
src/content/docs/zh/astro/astro-from-zero.md

語言切換會保留相同路徑，只替換語系前缀：

/en/astro/astro-from-zero/  ↔  /zh/astro/astro-from-zero/

不需要自訂的 id 或 slug frontmatter 欄位來配對，資料夾結構即可完成對應。

20. 如何新增一篇文章

在 src/content/docs/en/... 建立英文 Markdown
在 src/content/docs/zh/... 建立相同相對路徑的中文 Markdown
加入 Starlight frontmatter（title、description，可選 sidebar 的 label/order）
執行 npm run dev 或 npm run build

Starlight 會自動發現新檔案並更新側邊欄。

21. 圖片放在哪裡？

public/images/astro/example.webp

在 Markdown 中：

![說明文字](/images/astro/example.webp)

22. `npm run build` 時發生什麼事？

讀取設定 → 讀取內容 → 產生路由 → 渲染 → 輸出至 dist/

src/ 用於開發，dist/ 用於部署。

搜尋索引（Pagefind）也在正式建置時執行。

23. Astro 與 Angular 的差別

	Angular	Astro
最適合	應用程式、儀表板、SPA	內容站、部落格、文件站
預設模式	客戶端應用	建置時產生 HTML

Astro 預設向瀏覽器傳送的 JavaScript 較少。

24. 初學者常見誤解

以為 src/content 中的 Markdown 會自動有 URL — 必須有機制將內容對應到路由（純 Astro 自行處理，或 Starlight 處理文件）
在純 Astro 中為每篇文章建立一個 .astro 檔 — 通常 [...slug].astro 更合適
把 [...slug].astro 當成一篇文章 — 它是模板
混淆 index.astro 與 [...slug].astro — index 是資料夾首頁
混淆純 Astro 與 Starlight — 在 Starlight 中，文件 URL 來自 src/content/docs/ 路徑，而非自訂 slug frontmatter

25. 整體架構

純 Astro：

Markdown 內容（src/content/）
       │
       ▼
動態路由（[...slug].astro）
       │
       ▼
版面（ContentLayout）
       │
       ▼
HTML → 瀏覽器

本站（Starlight）：

Markdown（src/content/docs/）
       │
       ▼
Starlight（路由 + 文件版面）
       │
       ▼
HTML → 瀏覽器

26. 初學階段應記住的十句話

Astro 將原始檔建置成網站。
純 Astro 中 src/pages 定義 URL；Starlight 文件使用 src/content/docs/。
index.astro 是資料夾首頁。
.astro 檔結合邏輯與 HTML。
元件是可重複使用的 UI 積木。
版面是共用的頁面外框（或 Starlight 內建文件版面）。
自訂版面中 <slot /> 是頁面內容的插入點。
src/content 或 src/content/docs 存放文章資料。
純 Astro 中 [...slug].astro 可用一個模板處理多個文章 URL。
Content 是文章，路由（或 Starlight 路徑）是 URL。

27. 下一步建議

在實際網站上追蹤本指南：

src/content/docs/zh/astro/astro-from-zero.md
       │
       ▼
Starlight 文件路由
       │
       ▼
側邊欄 + 本頁目錄 + 文章內容
       │
       ▼
/zh/astro/astro-from-zero/

能完整追蹤一次後，Astro 與 Starlight 就不會再顯得抽象。

小測驗

Q1. src/pages/zh/index.astro 對應哪個 URL？ → /zh/

Q2. [...slug].astro 是一篇文章還是模板？ → 模板

Q3. 在 Starlight 中，本指南的 Markdown 檔在哪裡？ → src/content/docs/zh/astro/astro-from-zero.md

Q4. 該檔案產生哪個 URL？ → /zh/astro/astro-from-zero/

Q5. 哪一句最重要？ → Content 是文章，路由是 URL。

結語

Astro 看似複雜，是因為多個概念同時出現。請沿著這條線思考：

文章在哪裡？
URL 由誰產生？
版面由誰控制？
Astro 如何建置？

把每個部分放在正確位置，整個系統就會清晰：

內容 + 路由 + 版面 = 網站

對 harrylo.com 而言，Starlight 已處理大部分文件站外殼，讓你可以專心撰寫 Markdown。