🎯 靜態網站生成器選擇: 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 隱私保護
• ✅ 介面簡單易用
• ✅ 沒有隱藏費用

購買流程​

1. 前往 Porkbun.com
2. 搜尋你想要的網域名稱
3. 加入購物車並結帳
4. 完成！（DNS 設定稍後處理）

🚀 第四步：部署到 Vercel​

為什麼選擇 Vercel？​

GitHub Pages vs Vercel 比較：

這裡我選擇 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

1. 前往 Vercel.com
2. 使用 GitHub 帳號登入
3. 點擊「New Project」
4. 選擇你的 GitHub 倉庫
5. 點擊「Deploy」

就這樣！Vercel 會自動：

• 偵測到這是 Docusaurus 專案
• 執行 npm run build
• 部署到全球 CDN
• 給你一個網址（例如 my-blog.vercel.app）

🔗 第五步：設定自訂網域​

在 Vercel 設定網域​

1. 進入專案的「Settings」→「Domains」
2. 輸入你的網域名稱：chiayang.blog
3. 點擊「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. 完成！

就這麼簡單！

💰 成本分析​

讓我計算一下總成本：

一年只需要約台幣 60 元！相比其他平台（例如 WordPress 主機一個月就要幾百元）。

📊 功能清單​

我的部落格現在有這些功能：

• ✅ 響應式設計（手機、平板、電腦都好看）
• ✅ 深色/亮色模式切換
• ✅ RSS 訂閱 (/blog/rss.xml)
• ✅ 標籤分類
• ✅ 文章搜尋
• ✅ 閱讀時間估算
• ✅ 程式碼語法高亮
• ✅ 自訂網域 + HTTPS
• ✅ 全球 CDN

🎓 我學到了什麼​

技術方面​

1. React 基礎：Docusaurus 基於 React，讓我更熟悉 JSX 語法
2. Markdown：學會用 Markdown 寫作，比 Word 效率高多了
3. Git 工作流程：習慣了用 Git 管理版本
4. DNS 設定：了解網域名稱如何運作
5. CSS 客製化：學會覆蓋預設樣式

心得體會​

1. 選對工具很重要：Docusaurus 讓整個過程變得很簡單
2. 文件是最好的老師：遇到問題先看官方文件
3. 不要怕踩坑：每個錯誤都是學習機會
4. 自己的網站自己掌控：不用擔心平台倒閉或改規則

📚 推薦資源​

官方文件​

• Docusaurus 官方文件
• Vercel 文件
• Markdown 語法指南

靈感來源​

• Wiwi.Blog ─ 被推坑成功?

最後更新：2026 年 2 月 16 日

test123! Docusaurus 支援 React 元件，例如： 點我試試