從零開始建立個人部落格 (Hexo + Github Pages)

發表於 2025-04-16 更新於 2025-04-18 分類於技術筆記

從零開始建立個人部落格

這篇文章將詳細記錄如何使用 Hexo 和 GitHub Pages 建立一個個人部落格的完整過程。從環境設置到部署上線，一步一步帶你了解整個流程。

1. 環境準備

1.1 安裝必要工具

首先，我們需要安裝以下工具：

Node.js（包含 npm）
Git

在 macOS 上，可以使用 Homebrew 安裝：

# 安裝 Homebrew（如果還沒安裝的話）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安裝 Node.js
brew install node

# 安裝 Git
brew install git

安裝完成後，確認版本：

node -v  # 應該顯示 v16 或更高版本
npm -v   # 應該顯示 7.0 或更高版本
git --version

注意事項：

如果已經安裝過這些工具，可以跳過安裝步驟

如果版本不符合要求，需要先卸載舊版本再安裝新版本

1.2 安裝 Hexo

安裝 Hexo 命令行工具（全局安裝）：

npm install -g hexo-cli

安裝完成後，確認安裝成功：

hexo -v

2. 創建部落格

2.1 初始化專案

# 創建部落格目錄
hexo init my-blog
cd my-blog

# 初始化 npm 專案
npm init -y

# 安裝依賴
npm install

執行 hexo init 後，會創建以下文件結構：

my-blog/
├── _config.yml       # 網站配置文件
├── package.json      # 專案依賴配置
├── scaffolds/        # 文章模板目錄
│   ├── draft.md     # 草稿模板
│   ├── page.md      # 頁面模板
│   └── post.md      # 文章模板
├── source/           # 源文件目錄
│   ├── _posts/      # 文章目錄
│   └── _drafts/     # 草稿目錄
├── themes/           # 主題目錄
│   └── landscape/   # 默認主題
└── node_modules/    # 依賴包目錄

各目錄的用途：

_config.yml：網站的配置文件，包含網站標題、描述、作者等基本資訊
package.json：記錄專案依賴的 npm 包
scaffolds/：存放文章模板，用於快速創建新文章
source/：存放源文件，包括文章、頁面、圖片等
themes/：存放主題文件，可以安裝多個主題
node_modules/：存放安裝的 npm 包

2.1.1 db.json 文件

當你執行 hexo generate 或 hexo g 命令時，Hexo 會生成一個 db.json 文件。這個文件位於部落格的根目錄，是 Hexo 的資料庫文件，用於存儲所有文章的元數據。

db.json 的生成過程：

當你執行 hexo generate 時：
- Hexo 會掃描 source/_posts/ 目錄下的所有文章
- 讀取每篇文章的 front-matter（文章頭部的 YAML 配置）
- 將這些資訊整理成結構化的數據
- 生成 db.json 文件
db.json 的內容包括：
- 所有文章的標題、日期、標籤、分類等元數據
- 文章之間的關聯關係
- 網站的基本配置資訊
用途：
- 用於生成靜態網站的導航、分類、標籤等頁面
- 提供文章搜索功能
- 用於生成 RSS feed
- 用於生成網站地圖

注意事項：

npm init -y 會創建一個默認的 package.json 文件

如果 npm install 過程中出現錯誤，可以嘗試使用 npm install --force

確保在執行這些命令時有足夠的權限

所有安裝的套件都會保存在專案的 node_modules 目錄中

不要直接修改 themes/ 目錄下的主題文件，應該複製到 source/ 目錄下修改

source/ 目錄下的文件會被編譯到 public/ 目錄

_drafts/ 目錄下的文件不會被編譯，用於存放草稿

db.json 是自動生成的，不需要手動編輯

如果修改了文章或配置，需要重新執行 hexo generate 來更新 db.json

執行 hexo clean 會刪除 db.json，下次生成時會重新創建

如果 db.json 損壞，可以執行 hexo clean && hexo generate 重新生成

2.2 安裝必要的插件

# 安裝 Git 部署插件（安裝到專案中）
npm install hexo-deployer-git --save

# 安裝其他有用的插件（安裝到專案中）
npm install hexo-generator-feed --save  # RSS feed
npm install hexo-generator-sitemap --save  # 網站地圖

注意事項：

使用 --save 參數會將套件添加到 package.json 的 dependencies 中

這些套件只會安裝在當前專案的 node_modules 目錄中

如果需要全局安裝套件，使用 -g 參數，例如：npm install -g 套件名稱

3. 配置部落格

3.1 基本配置

編輯 _config.yml 文件，設置基本信息。以下是配置前後的對比：

配置前：

# Site
title: Hexo
subtitle: ''
description: ''
keywords:
author: John Doe
language: en
timezone: ''

# URL
url: http://example.com
root: /

配置後：

# 網站資訊
title: 我的旅行部落格  # 修改為你的部落格標題
subtitle: '探索世界的腳步'  # 修改為你的部落格副標題
description: '分享旅行故事和經驗'  # 修改為你的部落格描述
keywords: 旅行,攝影,美食,文化  # 修改為你的部落格關鍵字
author: 你的名字  # 修改為你的名字
language: zh-TW
timezone: 'Asia/Taipei'

# URL 設定
url: https://你的用戶名.github.io/你的部落格名.github.io  # 修改為你的 GitHub 用戶名和部落格名稱
root: /你的部落格名.github.io/  # 修改為你的部落格名稱
permalink: :year/:month/:day/:title/

# 目錄設定
source_dir: source
public_dir: public
tag_dir: tags
archive_dir: archives
category_dir: categories

注意事項：

確保 url 和 root 設置正確，這會影響到部署後的訪問地址

建議使用 zh-TW 作為語言設置，以確保中文顯示正常

所有標記為「修改為…」的部分都需要根據你的個人資訊進行修改

3.2 主題設置

我們使用了 Next 主題：

# 安裝 Next 主題
git clone https://github.com/theme-next/hexo-theme-next themes/next

在 _config.yml 中設置主題：

theme: next

4. GitHub 設置

4.1 創建 GitHub Repository

在 GitHub 上創建一個新的 repository：
- 名稱格式必須為：你的部落格名.github.io
- 例如：my_blog.github.io
- 設置 repository 為 public
- 不要初始化 README 文件
設置 GitHub Pages：
- 進入 repository 的 Settings
- 找到 Pages 選項
- 在 Source 部分選擇 “Deploy from a branch”
- 在 Branch 部分選擇 “gh-pages” 分支
- 點擊 Save

注意事項：

Repository 名稱必須完全匹配 你的部落格名.github.io

確保 repository 設置為 public

不要選擇任何初始化選項

4.2 配置部署設置

在 _config.yml 中添加部署配置：

deploy:
  type: git
  repo: git@github.com:你的用戶名/你的部落格名.github.io.git  # 修改為你的 GitHub 用戶名跟你的部落格名
  branch: gh-pages

注意事項：

建議使用 SSH 格式的 URL，避免每次部署都要輸入密碼

如果使用 HTTPS 格式的 URL，每次部署都需要輸入 GitHub 的用戶名和密碼

4.3 設置 SSH 金鑰

生成 SSH 金鑰：

ssh-keygen -t ed25519 -C "你的電子郵件"  # 修改為你的 GitHub 註冊郵箱

查看公鑰：

cat ~/.ssh/id_ed25519.pub

複製顯示的整個內容，包括開頭的 ssh-ed25519 和結尾的郵件地址

將公鑰添加到 GitHub：
- 進入 GitHub 設置
- 找到 SSH and GPG keys
- 點擊 New SSH key
- Title: 可以隨意命名（例如：My Blog）
- Key: 貼上剛才複製的公鑰內容
- 點擊 Add SSH key
測試 SSH 連接：

ssh -T git@github.com

如果看到 “Hi 你的用戶名!” 的歡迎信息，表示設置成功

5. 創建內容

5.1 創建新文章

# 創建新文章
hexo new "文章標題"

文章模板位於 scaffolds/post.md，包含以下內容：

---
title: {{ title }}
date: {{ date }}
categories:
tags:
---

5.2 創建關於頁面

# 創建關於頁面
hexo new page about

這會創建一個新的頁面檔案 source/about/index.md。編輯這個檔案，加入你的自我介紹。以下是一個範例：

---
title: 關於我
date: 2024-04-16 14:00:00
---

嗨！我是 Test User，一個熱愛旅行的部落客。

在這個部落格中，我會分享：
- 旅行故事
- 景點介紹
- 旅遊攻略
- 美食推薦

歡迎追蹤我的社群媒體，一起探索世界的美好！

5.3 編輯文章內容

使用 Markdown 語法編輯你的文章。以下是一個範例：

---
title: 我的第一次日本之旅
date: 2024-04-16 14:00:00
tags:
  - 旅行
  - 日本
categories: 旅遊
---

# 我的第一次日本之旅

這是我第一次去日本旅行的故事...

## 第一天：抵達東京

早上抵達成田機場，搭乘 Skyliner 前往市區...

## 第二天：淺草寺

參觀了著名的淺草寺，品嚐了當地的美食...

## 心得分享

這次旅行讓我收穫滿滿，期待下次再訪！

注意事項：

每篇文章都需要包含 front-matter（文章頭部信息）

front-matter 必須使用 --- 包圍

至少需要包含 title 和 date 兩個欄位

可以根據需要添加 tags 和 categories

6. 本地預覽

# 啟動本地服務器
hexo server

訪問 http://localhost:4000 預覽部落格。

注意事項：

如果 4000 端口被占用，可以使用 hexo server -p 5000 指定其他端口

按 Ctrl+C 可以停止服務器

7. 部署流程

每次更新內容後，執行以下命令部署到 GitHub Pages：

# 清理舊的生成文件
hexo clean

# 生成新的靜態文件
hexo generate

# 部署到 GitHub Pages
hexo deploy

或者使用簡寫形式：

hexo clean && hexo g && hexo d

注意事項：

如果使用 HTTPS 格式的 repository URL，每次部署都需要輸入 GitHub 的用戶名和密碼

建議使用 SSH 格式的 URL，避免每次部署都要輸入密碼

7.1 故障排除指南

如果在部署過程中遇到問題，請參考以下解決方法：

部署失敗：無法連接到 GitHub
- 檢查 SSH 金鑰是否正確設置
- 執行 ssh -T git@github.com 測試連接
- 如果提示 “Permission denied”，重新生成 SSH 金鑰
部署失敗：找不到 repository
- 檢查 repository 名稱是否正確
- 確認 repository 是否設置為 public
- 確認你有權限訪問該 repository
部署成功但網站顯示 404
- 等待幾分鐘讓 GitHub Pages 完成部署
- 檢查 URL 是否正確
- 在 GitHub repository 的 Settings > Pages 中確認部署狀態
本地預覽正常但部署後樣式錯誤
- 執行 hexo clean 清理緩存
- 重新執行 hexo g 生成文件
- 檢查 _config.yml 中的 URL 設置
部署時出現權限錯誤
- 確認使用的是 SSH 格式的 URL
- 檢查 GitHub 的 SSH 設置
- 嘗試重新生成 SSH 金鑰
部署時出現文件衝突
- 執行 git pull 更新本地文件
- 解決衝突後重新部署
- 如果問題持續，可以嘗試刪除 public/ 目錄後重新部署

部署完成後，訪問 https://你的用戶名.github.io/你的部落格名.github.io 查看你的部落格。例如：https://nivek-yang.github.io/test_blog.github.io

8. 自定義設置

8.1 導航菜單

在 Next 主題的 _config.yml 中設置導航菜單：

menu:
  home: / || fa fa-home
  archives: /archives/ || fa fa-archive
  about: /about/ || fa fa-user

8.2 社交鏈接

social:
  GitHub: https://github.com/你的用戶名 || fab fa-github
  E-Mail: mailto:你的電子郵件 || fa fa-envelope

9. 維護和更新

9.1 日常維護

定期更新 Hexo 和主題：

npm update

備份源文件：
- 將 source 目錄下的文件定期備份
- 可以使用 Git 進行版本控制

9.2 故障排除

常見問題的解決方法：

部署失敗：
- 檢查 GitHub 設置
- 確認 SSH key 設置正確
- 檢查部署配置
- 嘗試重新生成 SSH key
本地預覽問題：
- 清理緩存：hexo clean
- 重新安裝依賴：npm install
- 檢查端口是否被占用
主題顯示問題：
- 確認主題文件是否完整
- 檢查主題配置是否正確
- 嘗試重新安裝主題

10. 結語

通過以上步驟，我們成功建立了一個個人部落格。這個部落格具有以下特點：

使用 Hexo 靜態網站生成器
採用 Next 主題，簡潔美觀
部署在 GitHub Pages，無需額外伺服器
支持 Markdown 寫作
具有分類、標籤等功能
響應式設計，支持多設備訪問

持續更新和維護這個部落格，它將成為記錄生活和分享知識的好平台。如果遇到任何問題，可以參考：

希望這篇教學對你建立自己的部落格有所幫助！

11. 更新和部署文章

11.1 更新現有文章

編輯現有文章：
- 在 source/_posts/ 目錄下找到要修改的文章
- 使用編輯器修改文章內容
- 保存修改
本地預覽修改：

# 啟動本地服務器
hexo server

訪問 http://localhost:4000 查看修改效果
確認修改符合預期後，按 Ctrl+C 停止服務器

11.2 新增文章

創建新文章：

# 創建新文章
hexo new "新文章標題"

這會在 source/_posts/ 目錄下創建一個新的 Markdown 文件
文件名格式為：年-月-日-新文章標題.md

編輯新文章：
- 使用編輯器打開新創建的文章文件
- 添加文章內容
- 設置適當的標籤和分類
- 保存文件
本地預覽新文章：

# 啟動本地服務器
hexo server

訪問 http://localhost:4000 查看新文章效果
確認文章顯示正常後，按 Ctrl+C 停止服務器

11.3 部署更新

完成文章修改或新增後，執行以下命令部署到 GitHub Pages：

# 清理舊的生成文件
hexo clean

# 生成新的靜態文件
hexo generate

# 部署到 GitHub Pages
hexo deploy

或者使用簡寫形式：

hexo clean && hexo g && hexo d

注意事項：

部署後需要等待幾分鐘讓 GitHub Pages 完成更新

如果看到 404 頁面，請等待幾分鐘後重新整理

可以使用 hexo clean && hexo g && hexo d 命令快速部署

部署前建議先在本地預覽，確認內容正確

11.4 檢查部署狀態

在 GitHub 上檢查：
- 進入你的 repository
- 點擊 Actions 標籤
- 查看最新的部署狀態
- 等待部署完成（顯示綠色勾號）
訪問你的部落格：
- 訪問 https://你的用戶名.github.io/你的部落格名.github.io
- 檢查新文章或修改是否正確顯示
- 如果內容未更新，請等待幾分鐘後重新整理

11.5 常見問題

部署後內容未更新
- 等待幾分鐘讓 GitHub Pages 完成更新
- 執行 hexo clean 清理緩存
- 重新執行部署命令
新文章未顯示
- 檢查文章文件名格式是否正確
- 確認文章是否包含正確的 front-matter
- 檢查 _config.yml 中的 URL 設置
修改未生效
- 確認修改已保存
- 執行 hexo clean 清理緩存
- 重新執行部署命令
部署失敗
- 檢查 GitHub 設置
- 確認 SSH key 設置正確
- 檢查部署配置
- 嘗試重新生成 SSH key

部署完成後，訪問 https://你的用戶名.github.io/你的部落格名.github.io 查看你的部落格。例如：https://nivek-yang.github.io/test_blog.github.io

12. 自定義設置

12.1 導航菜單

在 Next 主題的 _config.yml 中設置導航菜單：

menu:
  home: / || fa fa-home
  archives: /archives/ || fa fa-archive
  about: /about/ || fa fa-user

12.2 社交鏈接

social:
  GitHub: https://github.com/你的用戶名 || fab fa-github
  E-Mail: mailto:你的電子郵件 || fa fa-envelope

13. 維護和更新

13.1 日常維護

定期更新 Hexo 和主題：

npm update

備份源文件：
- 將 source 目錄下的文件定期備份
- 可以使用 Git 進行版本控制

13.2 故障排除

常見問題的解決方法：

部署失敗：
- 檢查 GitHub 設置
- 確認 SSH key 設置正確
- 檢查部署配置
- 嘗試重新生成 SSH key
本地預覽問題：
- 清理緩存：hexo clean
- 重新安裝依賴：npm install
- 檢查端口是否被占用
主題顯示問題：
- 確認主題文件是否完整
- 檢查主題配置是否正確
- 嘗試重新安裝主題

14. 結語

通過以上步驟，我們成功建立了一個個人部落格。這個部落格具有以下特點：

使用 Hexo 靜態網站生成器
採用 Next 主題，簡潔美觀
部署在 GitHub Pages，無需額外伺服器
支持 Markdown 寫作
具有分類、標籤等功能
響應式設計，支持多設備訪問

持續更新和維護這個部落格，它將成為記錄生活和分享知識的好平台。如果遇到任何問題，可以參考：

希望這篇教學對你建立自己的部落格有所幫助！

15. 部署後的後續工作

15.1 檢查網站功能

部署完成後，需要檢查以下功能是否正常：

基本功能檢查：
- 首頁是否能正常訪問
- 文章列表是否正確顯示
- 文章內容是否完整
- 圖片是否正常顯示
- 導航菜單是否正常運作
互動功能檢查：
- 分類頁面是否正常
- 標籤頁面是否正常
- 搜索功能是否正常
- 評論功能（如果有的話）是否正常
響應式設計檢查：
- 在手機上訪問是否正常
- 在不同瀏覽器中訪問是否正常
- 頁面縮放是否正常

15.2 優化網站性能

圖片優化：
- 使用適當的圖片格式（WebP、JPEG、PNG）
- 壓縮圖片大小
- 使用延遲加載（lazy loading）
SEO 優化：
- 確保每篇文章都有適當的標題和描述
- 添加適當的 meta 標籤
- 提交網站地圖到搜索引擎
性能監控：
- 使用 Google Analytics 或類似工具監控訪問量
- 使用 PageSpeed Insights 檢查網站性能
- 定期檢查網站加載速度

15.3 定期維護

內容更新：
- 定期發布新文章
- 更新舊文章的內容
- 維護分類和標籤
技術維護：
- 定期更新 Hexo 和主題
- 更新依賴包
- 備份源文件
安全維護：
- 定期檢查 GitHub 設置
- 更新 SSH 金鑰
- 檢查訪問權限

15.4 推廣和互動

社群媒體推廣：
- 在社群媒體上分享文章
- 與讀者互動
- 收集反饋
SEO 優化：
- 使用適當的關鍵字
- 建立外部連結
- 優化文章結構
內容策略：
- 制定發布計劃
- 分析讀者反饋
- 調整內容方向

15.5 備份策略

源文件備份：
- 定期備份 source 目錄
- 使用 Git 進行版本控制
- 保存到雲端存儲
配置備份：
- 備份 _config.yml 文件
- 備份主題配置
- 記錄重要的修改
恢復計劃：
- 制定網站恢復流程
- 測試備份文件
- 準備應急方案

15.6 持續學習

技術學習：
- 學習新的 Markdown 技巧
- 了解 Hexo 的新功能
- 學習前端開發知識
內容創作：
- 提高寫作技巧
- 學習攝影技巧
- 研究 SEO 最佳實踐
社群參與：
- 參與 Hexo 社群
- 分享經驗
- 學習他人經驗

通過這些後續工作，你可以不斷優化和改進你的部落格，提供更好的閱讀體驗，吸引更多讀者。記住，建立部落格只是一個開始，持續的維護和改進才是關鍵。