零基礎搭建 Hexo 博客：從本地到 GitHub Pages 全流程指南

Hexo 是一個快速、簡潔且高效的博客框架，支持使用 Markdown 來編寫文章，并能快速生成靜態網頁，非常適合想要搭建個人博客的同學。本文將帶你從零開始，本地搭建 Hexo 博客，并部署到 GitHub Pages。

---

1. 安裝 Hexo 框架

首先需要安裝 Node.js，確保已經配置好環境變量。
接著打開命令行工具（cmd / PowerShell / Terminal），運行以下命令全局安裝 Hexo：

npm install -g hexo-cli

安裝完成后，你可以通過以下命令驗證是否安裝成功：

hexo -v

如果能看到版本號，就說明安裝完成。

---

2. 初始化博客項目

新建一個文件夾，例如 Hexo-blog，然后進入該文件夾：

mkdir Hexo-blog
cd Hexo-blog

接著運行初始化命令：

hexo init

這會自動生成 Hexo 的基礎目錄結構和默認配置。

---

3. 安裝依賴

進入到博客目錄后，執行以下命令安裝依賴：

npm install

至此，博客的主體框架就已經準備好了。

---

4. 本地啟動博客

運行以下命令啟動本地服務：

hexo server

然后在瀏覽器中訪問 http://localhost:4000，就可以看到默認生成的 Hexo 博客頁面啦！

按下 Ctrl + C 可以停止服務。

---

5. 創建第一篇文章

接下來，我們來寫一篇屬于自己的第一篇博客文章。

執行以下命令：

hexo new "我的第一篇文章"

這時會在 source/_posts/ 目錄下生成一個名為 我的第一篇文章.md 的 Markdown 文件。

你可以用任意 Markdown 編輯器（如 Typora、VS Code）打開并編輯它，例如：

---
title: 我的第一篇文章
date: 2025-09-09 14:00:00
tags: [Hexo, 博客]
---# Hello Hexo這是我的第一篇 Hexo 博客文章！

編輯完成后，保存文件，再次啟動本地服務：

hexo server

刷新瀏覽器頁面，就能看到你寫的第一篇博客文章啦 🎉

---

6. 常用 Hexo 命令速查

命令	作用
hexo new "標題"	新建一篇文章
hexo server	本地啟動博客（默認端口 4000）
hexo generate 或 hexo g	生成靜態文件
hexo clean	清理緩存和生成的文件
hexo deploy 或 hexo d	部署到遠程（如 GitHub Pages）

---

到這里，你已經成功在本地搭建并運行了 Hexo 博客，并寫好了第一篇 Markdown 文章。
下一步就是把它 部署到 GitHub Pages，讓別人也能訪問到。

---

7. 部署 Hexo 博客到 GitHub Pages

7.1 創建 GitHub 倉庫

1. 打開 GitHub，登錄賬號。
2. 點擊右上角 New repository 新建倉庫。
3. 倉庫名字必須設置為：

用戶名.github.io

例如：如果你的 GitHub 用戶名是 hexo-user，那么倉庫名就必須是：

hexo-user.github.io

這是 GitHub Pages 的默認規則。

4. 選擇 Public（公開），點擊 Create repository 完成創建。

👉 詳情可以參考這篇文章：從零開始搭建你的個人博客：使用 GitHub Pages 免費部署靜態網站

---

7.2 安裝部署插件

回到本地博客項目目錄，運行以下命令安裝 Hexo 部署工具：

npm install hexo-deployer-git --save

---

7.3 配置 _config.yml

打開博客根目錄下的 _config.yml 文件，找到 deploy 部分。

修改為：

deploy:type: gitrepo: https://github.com/你的用戶名/你的用戶名.github.io.gitbranch: master

注意：

• 如果你的 GitHub 默認分支是 main，這里就寫 branch: main。
• repo 一定要寫成你自己的倉庫地址。

---

7.4 部署博客

先生成靜態文件：

hexo generate

然后執行部署：

hexo deploy

第一次運行時，可能會提示輸入 GitHub 的用戶名和密碼。
如果你開啟了雙重驗證，需要使用 Personal Access Token（個人訪問令牌） 代替密碼。

---

7.5 訪問你的博客

部署完成后，稍等片刻，打開瀏覽器訪問：

https://用戶名.github.io

你也可以嘗試訪問我的主頁：Hexo

就能看到你剛剛寫的博客啦 🎉

---

7.6 常見問題

1. Git 未安裝
   如果提示 git: command not found，說明沒有安裝 Git，需要先到 Git 官網 下載并安裝。

2. 權限錯誤
   如果提示 Permission denied，可能是 SSH/Token 沒有配置好。推薦使用 HTTPS 倉庫地址，并使用 Token 部署。

3. 分支不對
   部署后訪問不到，檢查 _config.yml 里的 branch 是否和 GitHub 倉庫的默認分支一致。

---

總結

到這里，你已經完成了：

• ? 本地搭建 Hexo 博客
• ? 寫下第一篇 Markdown 文章
• ? 部署到 GitHub Pages，讓全世界都能訪問

接下來你可以嘗試：

• 更換 Hexo 主題，讓博客更漂亮
• 配置 自定義域名，讓博客網址更個性化
• 使用 標簽、分類，整理文章內容