從 0 建設個人網站
2026 Astro 網站加上部落格:用 Markdown 寫文章
在 Astro 個人網站加上部落格,只要一個放 Markdown 檔的資料夾、一個 content collection 設定檔和兩個頁面(文章列表、文章內頁),不用資料庫。附完整程式碼、RSS 設定,以及我的網站從資料庫搬回檔案的經過。
Kelvin Wang · · 8 分鐘閱讀
在 Astro 網站加上部落格,要做的事只有四件:建一個資料夾放 Markdown 文章、寫一個 src/content.config.ts 告訴 Astro 文章長什麼樣子、做一個文章列表頁、做一個文章內頁。不用資料庫,也不用後台。寫新文章就是新增一個 .md 檔,推到 GitHub,網站重新建置後文章就上線了。每一步都附可以直接貼上的程式碼,用的是 Astro 目前的 content collections 寫法(2026 年 11 月查過官方文件)1。
我的網站 kelvinwang.info 現在有 26 篇中文、26 篇英文舊文,加上這陣子新寫的文章,全部都是 repo 裡的檔案。這套做法我繞了一圈才回來,原因寫在最後一節。
開始之前:你需要一個 Astro 網站
還沒有網站的話,先裝好 Node.js(官方要求 v22.23.4 以上,v23 這類奇數版不支援)2,在終端機執行:
npm create astro@latest my-site
cd my-site
npm run dev
安裝程式問你要哪種範本時選最基本的就好。跑起來之後打開瀏覽器的 http://localhost:4321,看到首頁就代表成功。
如果想跳過這些步驟直接拿一個做好的部落格,Astro 官方有部落格範本:npm create astro@latest -- --template blog5。範本功能齊全,但檔案多,新手不容易看懂哪個檔案在做什麼。自己一步一步做,你會知道每個檔案的用途,之後要改也知道從哪裡改。
第一步:建資料夾,寫第一篇文章
在專案裡建立 src/content/blog/ 資料夾,新增一個檔案 hello-world.md:
---
title: 我的第一篇文章
description: 用一兩句話說這篇在講什麼,搜尋結果會顯示這段。
pubDate: 2026-11-07
tags: [隨筆]
---
這是內文。Markdown 的寫法:
## 小標題
- 清單用減號
- **粗體**用兩個星號
- [連結](https://example.com) 用中括號加小括號
上下兩條 --- 之間叫 frontmatter,放文章的資料(標題、摘要、日期)。下面才是內文。
檔名會變成網址:hello-world.md 的網址是 /blog/hello-world/。檔名用英文小寫和連字號,發布之後就不要改,改了網址就變,搜尋引擎和別人貼的連結都會失效。
第二步:寫 content collection 設定檔
在 src/ 底下新增 content.config.ts:
import { defineCollection } from 'astro:content';
import { glob } from 'astro/loaders';
import { z } from 'astro/zod';
const blog = defineCollection({
// 讀 src/content/blog 底下所有 .md 和 .mdx 檔
loader: glob({ base: './src/content/blog', pattern: '**/*.{md,mdx}' }),
// 每篇文章的 frontmatter 必須長這樣,少了或打錯,建置就會失敗
schema: z.object({
title: z.string(),
description: z.string(),
pubDate: z.coerce.date(),
tags: z.array(z.string()).default([]),
draft: z.boolean().default(false),
}),
});
export const collections = { blog };
schema 是這個檔案最有用的地方。哪一篇文章忘了寫 description、日期格式寫錯,npm run build 會直接失敗並告訴你是哪個檔案,錯的文章不會悄悄上線。用 AI 寫文章時這條特別有用,AI 偶爾會漏欄位。
第三步:文章列表頁
新增 src/pages/blog/index.astro:
---
import { getCollection } from 'astro:content';
const posts = (await getCollection('blog', ({ data }) => !data.draft))
.sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf());
---
<html lang="zh-Hant">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>文章</title>
</head>
<body>
<h1>文章</h1>
<ul>
{posts.map((post) => (
<li>
<a href={`/blog/${post.id}/`}>{post.data.title}</a>
<time datetime={post.data.pubDate.toISOString()}>
{post.data.pubDate.toLocaleDateString('zh-TW')}
</time>
</li>
))}
</ul>
</body>
</html>
兩個重點:
getCollection的第二個參數是篩選條件,這裡把draft: true的草稿排除。- 一定要自己排序。官方文件寫明
getCollection回傳的順序不固定,不排序的話文章順序可能每次建置都不同。
第四步:文章內頁
新增 src/pages/blog/[id].astro。檔名的中括號代表這是一個「每篇文章各產生一頁」的範本:
---
import { getCollection, render } from 'astro:content';
export async function getStaticPaths() {
const posts = await getCollection('blog', ({ data }) => !data.draft);
return posts.map((post) => ({
params: { id: post.id },
props: { post },
}));
}
const { post } = Astro.props;
const { Content } = await render(post);
---
<html lang="zh-Hant">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>{post.data.title}</title>
<meta name="description" content={post.data.description} />
</head>
<body>
<article>
<h1>{post.data.title}</h1>
<Content />
</article>
</body>
</html>
getStaticPaths 在建置時跑一次,列出所有要產生的頁面;render(post) 把 Markdown 轉成 HTML,<Content /> 就是內文。這裡也要排除草稿,只在列表頁排除的話,草稿雖然不會出現在列表,網址還是打得開。
存檔後打開 http://localhost:4321/blog/,應該會看到第一篇文章的標題,點進去就是內文。
兩個頁面裡的 <html>、<head> 是重複的。網站已經有共用版面(layout)的話,換成你的 layout 元件,把標題和摘要傳進去就好。
第五步(選用):用 MDX 在文章裡放元件
一般 Markdown 只能寫文字、圖片、表格。想在文章裡放互動元件或自訂的提示框,就改用 MDX3:
npx astro add mdx
先做一個元件。最簡單的提示框 src/components/Note.astro:
<aside style="border-left: 4px solid #888; padding: 0.5rem 1rem;">
<slot />
</aside>
<slot /> 會換成你寫在 <Note> 和 </Note> 中間的內容。接著把文章副檔名改成 .mdx,在 frontmatter 下面 import 這個元件:
---
title: 用 MDX 寫的文章
description: 文章裡可以放元件。
pubDate: 2026-11-07
---
import Note from '../../components/Note.astro';
一般的 Markdown 內文。
<Note>這是一個自訂的提示框。</Note>
第二步的 pattern 已經包含 .mdx,不用再改設定檔。
第六步(選用):加上 RSS
RSS 讓讀者用閱讀器訂閱你的文章。先在 astro.config.mjs 設好網站網址(site: 'https://你的網域'),再安裝官方套件4:
npm install @astrojs/rss
新增 src/pages/rss.xml.js:
import rss from '@astrojs/rss';
import { getCollection } from 'astro:content';
export async function GET(context) {
const posts = await getCollection('blog', ({ data }) => !data.draft);
return rss({
title: '我的部落格',
description: '文章的 RSS',
site: context.site,
items: posts.map((post) => ({
title: post.data.title,
pubDate: post.data.pubDate,
description: post.data.description,
link: `/blog/${post.id}/`,
})),
});
}
建置之後 /rss.xml 就是訂閱網址。
第七步:發布
寫完文章後:
git add src/content/blog/hello-world.md
git commit -m "post: hello world"
git push
網站如果已經接好自動部署(Cloudflare Workers Builds、Vercel、Netlify 都可以設定成 push 就建置),幾分鐘後文章就上線。沒有接自動部署的話,照你平常部署的方式重新建置一次。
想深入 Cloudflare Workers 教學 2026:Astro 部署與 wrangler 設定 把 Astro 網站部署到 Cloudflare,並設定 push 就自動上線。用 AI 寫文章時
文章是檔案,AI 寫程式工具可以直接新增和修改。我會在 AI 工具讀的專案說明檔(Claude Code 讀 CLAUDE.md,Codex 讀 AGENTS.md)寫一行文章放在哪裡、檔名規則是什麼,AI 每次就知道要寫到哪個資料夾。schema 會擋掉缺欄位的文章;我的網站另外規定 MDX 文章一定要有 description,沒有就讓建置失敗,因為沒有摘要時頁面會從 MDX 原始碼截一段當搜尋摘要,截出來的可能是 import 語句。
發布前一樣要自己看過。檔案化讓 AI 寫得很快,但 push 之後就是公開的,我的規則是寫稿可以自動,commit、push 之前要我點頭。
我的網站怎麼做(給已經會的人)
我的網站在 2026 年 6 月 10 日加上部落格時,用的就是上面這套:glob() loader 加一篇 hello-world.mdx。隔天(6 月 11 日)我把文章搬進 Supabase 資料庫,建置時從資料庫讀,用自己寫的編輯器發布。
用了五個月之後,2026 年 11 月 5 日又搬回檔案。原因有兩個:
- 編輯器存的是 HTML,只能放段落、標題、清單、表格和圖片。像交易所事件頁那種需要時間軸、數字卡的文章,編輯器做不到。
- 我不在後台編輯器裡改文章。AI 起草,我把內容全部看過,確認後說可以發布,剩下的上線工作交給 AI。編輯器用不到,只帶來限制,還讓每篇文章多一份要同步的副本。
搬家時把 52 篇已發布的文章(中英各 26 篇)匯出成檔案,再比對搬家前後建出來的網站:199 個檔案裡 198 個逐位元組相同,唯一的差別是後台程式的一個檔名雜湊。
現在的結構比入門版多了幾層,因為網站有中英兩種語言,還有從資料庫搬來的舊文:
| 項目 | 入門版 | 我的網站 |
|---|---|---|
| 文章位置 | src/content/blog/<slug>.md | src/content/posts/<slug>/<lang>.mdx |
| loader | 官方 glob() | 自己寫的 loader,同時讀 .mdx 和搬家來的 .html |
| 網址 | /blog/<id>/ | /zh-hant/blog/<slug>/、/en/blog/<slug>/ |
| 文章裡的元件 | 自己做 | 時間軸、數字卡、表格、提示框、資料來源、延伸閱讀卡 |
| 草稿 | draft: true | draft: true,建置時完全不讀 |
如果你的網站只有一種語言,入門版就夠用很久。
新手常踩的坑
- 改了檔名,舊網址就 404。 網址來自檔名。要改就加轉址,或乾脆不改。
- 忘了排序。
getCollection不保證順序,列表和 RSS 都要自己排。 - 只在列表排除草稿。
getStaticPaths裡也要排除,不然草稿的網址還是打得開。 - 文章放在子資料夾。
glob()產生的 id 會包含資料夾路徑(例如2026/hello),id 有斜線時頁面檔名要改成[...id].astro。 - 圖片路徑。 最簡單的做法是把圖片放在
public/images/,文章裡用/images/xxx.webp引用。
資料來源