[hexo] Hexo 基本設置

Hexo 基本設定指南

這份指南將帶您了解如何在本機環境中安裝和設定 Hexo，以便開始建立您的靜態部落格網站。本篇文章適合初學者，也包含一些實用的指令與維護方式。

Hexo 的優勢

在深入學習之前，讓我們先了解 Hexo 的幾個主要優勢：

1. 快速與高效：Hexo 使用靜態檔案，能夠快速生成並部署網站，運行時無需伺服器處理請求，速度快且安全。
2. 靈活性強：支援高度自定義的主題和插件，讓您能打造出符合自己需求的部落格。
3. 社群活躍：擁有豐富的主題和插件，社群資源豐富，可以輕鬆擴展網站功能。
4. 適合 SEO：靜態網站天然適合搜尋引擎收錄，結合 Hexo 的 SEO 插件，能進一步提升網站可見性。

總覽

本文將涵蓋以下內容：

1. 先決條件：必須安裝的軟體
2. 安裝與初始化 Hexo
3. 基本配置與網站部署
4. 常用指令
5. 基本維護邏輯

先決條件

在開始之前，請確認您已安裝以下軟體：

• Node.js（建議使用最新的 LTS 版本）
• pnpm（Node.js 套件管理工具）

安裝 Hexo

1. 安裝 Node.js 和 pnpm

如果您還未安裝 Node.js 和 pnpm，請使用以下指令安裝：

# 使用 Homebrew 安裝 Node.js
brew install node

# 安裝 pnpm
brew install pnpm

2. 全域安裝 Hexo CLI

使用 pnpm 全域安裝 Hexo CLI：

pnpm add -g hexo-cli

3. 初始化 Hexo 專案

選擇一個目錄來存放您的部落格專案，然後使用以下指令初始化 Hexo 專案：

mkdir my-blog
cd my-blog
hexo init

接下來，安裝專案所需的依賴：

pnpm install

基本配置

Hexo 的基本配置檔案是根目錄下的 _config.yml，以下是一些常見的設定：

網站基本信息

在 _config.yml 中設定網站的基本信息：

title: My Blog
subtitle: Welcome to my blog
description: 這是一個使用 Hexo 建立的部落格
author: 您的名稱
language: zh-TW

設定網址

設定部落格的 URL：

url: https://您的域名.com
root: /
permalink: :year/:month/:day/:title/

常用指令

以下是一些常用的 Hexo 指令，幫助您在開發過程中更有效率：

• 清理檔案

清除暫存檔和生成的檔案：

hexo clean
# 或使用簡寫
hexo c

• 生成靜態檔案

生成網站的靜態檔案：

hexo generate
# 或使用簡寫
hexo g

• 啟動本地開發伺服器

啟動本地伺服器以預覽網站：

hexo server
# 或使用簡寫
hexo s

現在，您可以在瀏覽器中造訪 http://localhost:4000。

• 部署網站

部署網站到遠端伺服器：

hexo deploy
# 或使用簡寫
hexo d

• 新增文章

新增一篇新文章：

hexo new "文章標題"
# 或使用簡寫
hexo n "文章標題"

部署網站

Hexo 支援多種部署方式，這裡以 GitHub Pages 為例，詳細介紹如何將您的 Hexo 部落格部署到 GitHub Pages。

1. 創建 GitHub Repository

首先，登入您的 GitHub 帳號，創建一個新的倉庫（repository）。倉庫名稱可以是：

• 用戶名.github.io：如果您希望使用 GitHub 提供的個人主頁功能，倉庫名稱必須與您的 GitHub 用戶名一致，後面加上 .github.io。
• 自定義名稱：如果您想要部署在自定義的路徑下，可以使用任意倉庫名稱。

2. 安裝部署插件

安裝 hexo-deployer-git 插件，這個插件可以將生成的靜態檔案推送到 GitHub：

pnpm add hexo-deployer-git

3. 配置 _config.yml

在 Hexo 根目錄下的 _config.yml 中，找到或添加 deploy 配置，並進行如下設定：

deploy:
    type: git
    repo: git@github.com:<YOUR_USERNAME>/<YOUR_REPO>.git
    branch: gh-pages

• <YOUR_USERNAME>：替換為您的 GitHub 使用者名稱。
• <YOUR_REPO>：替換為您的倉庫名稱。

注意：

• 如果您的倉庫名稱是 <YOUR_USERNAME>.github.io，那麼部署分支應該是 main 或 master，具體取決於您的默認分支名稱。
• 如果使用自定義倉庫名稱，建議將部署分支設為 gh-pages，這是 GitHub Pages 的專用分支。

4. 生成 SSH 金鑰（可選）

如果您還未在本機生成 SSH 金鑰，或者未將其添加到 GitHub，請執行以下步驟：

# 生成新的 SSH 金鑰
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

# 啟動 ssh-agent 並添加金鑰
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_rsa

然後，將生成的公鑰內容（~/.ssh/id_rsa.pub）添加到 GitHub 的 SSH Keys 中。

5. 部署網站

執行以下指令以生成並部署網站：

hexo clean
hexo generate
hexo deploy
# 或者簡寫為
hexo clean && hexo g -d

這將執行以下操作：

1. 清理：刪除之前生成的靜態檔案，避免舊檔案干擾。
2. 生成：根據您的內容和配置，重新生成最新的靜態網站。
3. 部署：將生成的靜態檔案推送到您在 _config.yml 中設定的 GitHub 倉庫和分支。

6. 驗證部署結果

部署完成後，您可以在瀏覽器中訪問：

• 如果倉庫名稱是 <YOUR_USERNAME>.github.io，那麼您的網站地址為：

  https://<YOUR_USERNAME>.github.io/

• 如果倉庫名稱是自定義的，並且部署在 gh-pages 分支，則訪問地址為：

  https://<YOUR_USERNAME>.github.io/<YOUR_REPO>/

注意： GitHub Pages 部署可能需要幾分鐘的時間才能生效。如果在訪問時看不到更新，請稍等片刻並刷新頁面。

7. 常見問題排查

• 部署後網站顯示空白或 404 錯誤：

  • 確認您的部署分支和路徑是否正確。
  • 檢查 _config.yml 中的 url 和 root 設置是否匹配。

• 無法推送到 GitHub，提示權限錯誤：

  • 確認您的 SSH 金鑰已正確添加到 GitHub。
  • 檢查 repo 地址是否正確，可以嘗試使用 HTTPS 方式：

  repo: https://github.com/<YOUR_USERNAME>/<YOUR_REPO>.git

• 部署命令失敗，提示缺少插件：

  • 確認已安裝 hexo-deployer-git 插件，並且在 package.json 的依賴中。

8. 自動化部署（可選）

如果您希望在每次提交內容更新後自動部署，可以考慮使用 GitHub Actions、自建 CI/CD 流水線，或在本機腳本中添加部署命令。

基本維護邏輯

Hexo 的維護過程相對簡單，這是它作為靜態網站生成器的其中一個優勢。以下是一些日常維護的步驟與注意事項：

• 清理與重新生成：在每次修改完配置或安裝新的插件後，建議使用 hexo clean 清理舊的暫存檔，再執行 hexo generate 重新生成靜態網站。
• 檔案同步：Hexo 的內容基於檔案管理，您只需要確保源碼版本控制（如 Git）一致，並定期備份 _config.yml 及其他重要配置檔案。
• 定期檢查插件更新：通過 pnpm update 可以檢查並更新 Hexo 及其相關插件，保持部落格穩定性。

總結與下一步行動

這篇文章介紹了 Hexo 的安裝、基本設定、部署方法、常用指令以及基本維護邏輯。Hexo 的操作簡單，特別適合想要建立個人部落格的開發者。

接下來，我們將在[第二篇進階設定指南]深入探討如何進一步自定義您的 Hexo 部落格，包括主題設定、插件安裝、以及 SEO 優化等。