從零開始：我如何用 Docusaurus 建立自己的部落格
· 閱讀時間約 7 分鐘
這裡記錄了我是如何建立這個網頁的!
🎯 靜態網站生成器選擇: Docusaurus
在建立部落格時，我考慮了幾個選項：WordPress、Medium、Jekyll、Hugo、Docusaurus。
最後我選擇了 Docusaurus。
📦 第一步：安裝與初始化
環境需求
# 確認 Node.js 版本（需要 18.0 或更高）
node -v
# 我的版本：v24.13.0
npm -v
# 我的版本：11.0.0
建立專案
# 使用官方腳手架建立專案
npx create-docusaurus@latest my-blog classic --typescript
# 進入專案目錄
cd my-blog
# 啟動開發伺服器
npm start
執行 npm start 後，瀏覽器會自動開啟 http://localhost:3000，你會看到 Docusaurus 的預設範本。
🔧 第二步：設定為純部落格模式
預設的 Docusaurus 包含文件區和部落格區，但我只想要一個純部落格，所以需要調整設定。
修改 docusaurus.config.js
export default {
// ... 其他設定
presets: [
[
'classic',
{
docs: false, // ← 關閉文件功能
blog: {
routeBasePath: 'blog', // ← 部落格路徑
showReadingTime: true,
feedOptions: {
type: ['rss', 'atom'],
xslt: true,
},
},
},
],
],
};
刪除不需要的檔案
# 刪除文件相關資料夾
rm -rf docs
🌍 第三步：購買網域名稱
我決定使用自己的網域名稱，而不是 Vercel 的預設網址。
為什麼選擇 Porkbun？
我在 Porkbun 購買了 chiayang.blog 網域，原因是：
- ✅ 價格便宜（比 GoDaddy 便宜很多）
- ✅ 免費的 WHOIS 隱私保護
- ✅ 介面簡單易用
- ✅ 沒有隱藏費用
購買流程
- 前往 Porkbun.com
- 搜尋你想要的網域名稱
- 加入購物車並結帳
- 完成！（DNS 設定稍後處理）
🚀 第四步：部署到 Vercel
為什麼選擇 Vercel？
GitHub Pages vs Vercel 比較：
| 項目 | GitHub Pages | Vercel |
|---|---|---|
| 速度 | 普通 | 超快（全球 CDN） |
| 自動部署 | 需要設定 GitHub Actions | 自動 |
| 自訂網域 | 支援但設定較複雜 | 超簡單 |
| HTTPS | 支援 | 自動設定 |
| 價格 | 免費 | 免費（個人專案） |
這裡我選擇 Vercel。
部署步驟
1. 將專案推送到 GitHub
# 初始化 Git
git init
# 加入所有檔案
git add .
# 提交
git commit -m "Initial commit"
# 建立 GitHub 倉庫（在 GitHub 網站上操作）
# 然後連結遠端倉庫
git remote add origin https://github.com/你的帳號/my-blog.git
# 推送
git push -u origin main
2. 連結 Vercel
- 前往 Vercel.com
- 使用 GitHub 帳號登入
- 點擊「New Project」
- 選擇你的 GitHub 倉庫
- 點擊「Deploy」
就這樣！Vercel 會自動：
- 偵測到這是 Docusaurus 專案
- 執行
npm run build - 部署到全球 CDN
- 給你一個網址（例如
my-blog.vercel.app）
🔗 第五步：設定自訂網域
在 Vercel 設定網域
- 進入專案的「Settings」→「Domains」
- 輸入你的網域名稱：
chiayang.blog - 點擊「Add」
Vercel 會告訴你需要設定的 DNS 記錄。
在 Porkbun 設定 DNS
前往 Porkbun 的 DNS 管理頁面，設定 DNS：
等待生效
DNS 通常需要 5-30 分鐘生效。你可以用這個指令檢查：
# 檢查 DNS 是否已更新
nslookup chiayang.blog
# 或使用線上工具
# https://www.whatsmydns.net/
生效後，Vercel 會自動設定 HTTPS！
🎨 第六步：客製化部落格
現在網站已經上線了，接下來是讓它變得更有個人特色。
1. 更換 Logo
準備圖片
- Logo: 512 x 512 px，PNG 格式（透明背景）
- Favicon: 同一張圖片即可
放置檔案
static/
└── img/
├── logo-transparent.png # 導航欄 Logo
└── favicon-transparent.png # 瀏覽器圖示
更新設定（docusaurus.config.js）
export default {
title: 'ChiaYang Blog',
favicon: 'img/favicon-transparent.png',
themeConfig: {
navbar: {
logo: {
alt: 'ChiaYang Blog Logo',
src: 'img/logo-transparent.png',
},
},
},
};
2. 自訂首頁
我想要一個有橫幅圖片的首頁，所以建立了 src/pages/index.md：
---
title: ChiaYang Blog
description: 歡迎來到 ChiaYang 的部落格
hide_table_of_contents: true
---
<div style={{position: 'relative', marginBottom: '3rem'}}>
<img
src="/img/welcome-banner.jpg"
alt="歡迎來到 ChiaYang Blog"
style={{
width: '100%',
maxHeight: '500px',
objectFit: 'cover',
borderRadius: '15px',
}}
/>
<div className="hero-banner-text" style={{
position: 'absolute',
bottom: '30px',
left: '50%',
transform: 'translateX(-50%)',
background: 'rgba(0,0,0,0.6)',
padding: '1rem 2rem',
borderRadius: '10px',
}}>
<h1 className="hero-title" style={{margin: 0}}>ChiaYang Blog</h1>
<p className="hero-subtitle">紀錄與分享</p>
</div>
</div>
## 👋 歡迎
哈囉！歡迎來到我的部落格...
3. 調整樣式（CSS）
在 src/css/custom.css 中自訂樣式：
/* 縮小文章標題 */
h1, h2 {
font-size: 1.5rem !important;
}
/* 確保文字在深色導航欄上清晰可見 */
.navbar__title,
.navbar__toggle,
.hero-title,
.hero-subtitle {
color: #ffffff !important;
}
/* 隱藏作者資訊（如果你不想顯示） */
.avatar {
display: none !important;
}
🐛 遇到的問題與解決方法
問題 1：部署時出現 "Broken Links" 錯誤
錯誤訊息：
Error: Docusaurus found broken links!
- linking to /tags
- linking to /archive
原因：
我把部落格設為 routeBasePath: 'blog'，所以路徑變成了 /blog/tags 而不是 /tags。
解決方法：
修改 docusaurus.config.js 中所有連結：
navbar: {
items: [
{to: '/blog/tags', label: '標籤'}, // 加上 /blog 前綴
{to: '/blog/archive', label: '歷史文章'},
],
},
問題 2：文章標題太大
解決方法：
在 custom.css 中強制縮小：
h1, h2 {
font-size: 1.5rem !important;
line-height: 1.3 !important;
}
問題 3：亮色模式下文字看不清楚
某些文字（例如導航欄、首頁橫幅）在切換主題時會看不清楚。
解決方法： 因為我的導航欄背景是深色，所以強制文字為白色：
.navbar__title,
.navbar__toggle svg,
.hero-title,
.hero-subtitle,
.footer__copyright {
color: #ffffff !important;
}
問題 4：主題切換按鈕看不到
解決方法： 同樣強制按鈕和圖示為白色：
.navbar__toggle,
.navbar__toggle svg {
color: #ffffff !important;
fill: #ffffff !important;
}
📝 寫第一篇文章
在 blog/ 資料夾建立新文章：
blog/
└── 2026-02-16-my-first-post.md
文章格式：
---
title: 我的第一篇文章
description: 這是摘要，會顯示在列表頁
authors: yang
tags: [Hello, Test]
---
這是摘要，會顯示在列表頁。
<!-- truncate -->
這裡開始是完整內容，只有在文章詳細頁才會顯示。
## 小標題
可以用 Markdown 語法寫作...
推送到 GitHub 後，Vercel 會自動重新部署！
🔄 日常更新流程
現在網站已經建立完成，以後要發文只需要：
# 1. 建立新文章
echo "---
title: 新文章標題
authors: yang
tags: [標籤]
---
文章內容...
" > blog/2026-02-16-new-post.md
# 2. 提交並推送
git add .
git commit -m "新增文章：標題"
git push
# 3. Vercel 自動部署（1-2 分鐘）
# 4. 完成！
就這麼簡單！
💰 成本分析
讓我計算一下總成本：
| 項目 | 費用 |
|---|---|
| Docusaurus | 免費 |
| GitHub | 免費 |
| Vercel | 免費 |
| 網域名稱（chiayang.blog） | 約 $2 USD/年 |
| 總計 | 約 $2 USD/年 |
一年只需要約台幣 60 元！相比其他平台（例如 WordPress 主機一個月就要幾百元）。
📊 功能清單
我的部落格現在有這些功能：
- ✅ 響應式設計（手機、平板、電腦都好看）
- ✅ 深色/亮色模式切換
- ✅ RSS 訂閱 (
/blog/rss.xml) - ✅ 標籤分類
- ✅ 文章搜尋
- ✅ 閱讀時間估算
- ✅ 程式碼語法高亮
- ✅ 自訂網域 + HTTPS
- ✅ 全球 CDN
🎓 我學到了什麼
技術方面
- React 基礎：Docusaurus 基於 React，讓我更熟悉 JSX 語法
- Markdown：學會用 Markdown 寫作，比 Word 效率高多了
- Git 工作流程：習慣了用 Git 管理版本
- DNS 設定：了解網域名稱如何運作
- CSS 客製化：學會覆蓋預設樣式
心得體會
- 選對工具很重要：Docusaurus 讓整個過程變得很簡單
- 文件是最好的老師：遇到問題先看官方文件
- 不要怕踩坑：每個錯誤都是學習機會
- 自己的網站自己掌控：不用擔心平台倒閉或改規則
📚 推薦資源
官方文件
靈感來源
- Wiwi.Blog ─
被推坑成功?
最後更新：2026 年 2 月 16 日