前言
架設完成至今,一直想著第一篇文章到底要寫什麼,突然!一個念頭閃過!
決定分享我是如何從零到一架設起個人網站的吧 XDDDDDDDD
如題,本篇將以懶人包方式敘述如何使用Github Pages+Hexo成功架設個人網站
並分享架設後的個人踩坑紀錄,將列出十個 修復Bug / 增加功能 的問題與解法
希望這篇懶人包與踩坑實錄 作為WriteUp 幫助也想擁有自己數位小天地的你 🧸
— 記於首篇撰寫的文章 HeyMrSalt
為何使用 GitHub Pages + Hexo
在開始動手前你也許會想
架設網站的選擇這麼多,為什麼是 GitHub Pages + Hexo 這個組合?
( 若沒興趣 [Chick] 點我跳過)
簡單來說,因為這組合
提供了 完全免費、建置速度快、高度安全、客製化彈性高 的 Solution
對於個人部落格或網站來說,應該算是非常不錯的方案吧我想!
WHY GitHub Pages
FREE & EASY 理由就是這麼簡單粗暴 XDDDDD
不過 GitHub Pages 其實還是存在一些限制

你可以點擊這裡看見官方對 Github Pages 一些限制的聲明
- 每個 GitHub 帳號只能建立一個使用者網站(username.github.io)
- 網站大小不能超過 1 GB
- 部署過程若超過 10 分鐘將會失敗
- 網站流量每月 100 GB 的限制
- 若過於頻繁請求將會收到 HTTP 429 狀態碼 被限制速率
總結來說 就算有上述這些限制
對於大部分使用者的基本需求來說 還是非常夠用的
且 GitHub 的知名度與高品質 其極高的可用性
要遇到網站服務掛掉應該還是不太容易
最後一個限制就是 GitHub Pages 只能託管靜態網站
若需動態網頁功能 就得向外部 API/資料庫 發送請求 並從 GitHub 以外的地方進行管理
🤔 動態 vs. 靜態? (點擊展開比較 以WordPress為例)
動態網站 (如 WordPress): 像一間「現點現做的餐廳」。當客人(使用者)來訪時,廚房(伺服器)才開始從冰箱(資料庫)拿出食材,現場烹飪,最後才把菜(網頁)端給客人。這個過程比較慢,而且廚房需要隨時待命,也相較容易被攻擊這部分就不多詳談。
靜態網站 (如 Hexo): 像一間「麵包店」。開店前,就已經把所有麵包(網頁)都好了。客人(使用者)來時,可以直接從架上取下,速度快。
WHY Hexo
高效率 & 簡易更換主題風格
其實常見的框架除了 Hexo 還有 Jekyll、Hugo,在這邊就不詳細比較
有興趣可以參考 這裡 Ray 寫的 靜態網站產生器大比拚
本篇會介紹 GitHub Pages + Hexo 框架 的使用流程
環境建置可以參考 官方文件,裡面有詳細的教學流程
我已將必要步驟整理為 懶人包:五步驟快速上線
懶人包:五步驟快速上線
- 環境準備: 在你的電腦上安裝 Git 和 Node.js。
- Hexo 初始化: 透過指令建立你的本地部落格專案。
- 主題套用與預覽: 挑選外觀,並在自己電腦上預覽成果。
- GitHub 設定與部署: 建立 GitHub 倉庫並將個人網站上傳。
- 基礎 SEO 設定: 讓 Google 知道你的網站存在。
接下來 本文提供了兩種閱讀體驗
- 如果你是老手:請直接看下面的「指令懶人包」,五分鐘就能完成部署。
- 如果你是新手:請跳過指令包,從「五步驟的拆解與指令」開始
1 | # Step1 : 環境準備 (macOS with Homebrew) |
五步驟的拆解與指令
下列五步驟 依序跟上應該都能輕鬆部署
但在這還是提供給新手專用的 詳細導覽 只要你看到 Toggle List (就是一個三角形 圖如下

我會用 Toggle List 搭配白話文 帶你走完每一步 新手卡住可以打開
甚至如果我的 Toggle List 不清楚 或是補充不足
網路上的資源很多 再幫我直接 GOOGLE 吧
且還有強大的 AI 可以當你的 Debug 夥伴 若有不足還請多包涵
第一步:環境準備 (安裝 Git & Node.js)
這是所有開始前的基礎
Hexo 是基於 Node.js 的框架,而我們需要 Git 來將網站推送到 GitHub
- macOS 使用者: 推薦使用 Homebrew 安裝。
1
2brew install git
brew install node - Windows 使用者: 請前往 Git 官網 和 Node.js 官網下載並安裝 LTS 版本。
新手點擊這裡,展開詳細敘述 👉 安裝後 打開「終端機」檢查是否成功
打開「終端機」或「CMD」輸入 git --version 和 node --version 檢查是否成功
第二步:Hexo 初始化
環境備妥後,就可以透過 npm (安裝 Node.js 時會一併安裝) 來安裝 Hexo 並建立專案。
1 | # 1. 全域安裝 Hexo 命令列工具 |

第三步:主題套用與預覽
一個網頁的靈魂在於它的外觀。
而 Hexo 有提供許多豐富的主題庫,讓我們可以輕鬆地為網站「換衣服」。
- 挑選主題: 前往 Hexo Themes 挑選你喜歡的模板。
- 安裝主題: 根據主題說明,通常是透過
git clone指令,將主題下載到你的themes資料夾中。 - 設定主題: 打開專案根目錄的
_config.yml,修改theme:欄位。 - 本地預覽: 執行
hexo server,在瀏覽器打開http://localhost:4000查看新外觀。
👉 新手跟著做:從零安裝一個主題 (以 Maple 為例)
如果你對於「根目錄」、「git clone」這些名詞感到陌生,別擔心!跟著下面的詳細步驟,一步步來操作。
A. 什麼是「專案根目錄」?
「根目錄」指的就是你專案最外層的那個資料夾,也就是我們之前建立的 my-blog 資料夾。
當你在終端機裡,路徑顯示在 my-blog 時,你就可以看到 _config.yml、source、themes 這些檔案和資料夾,這裡就是「根目錄」。

B. 安裝 Maple 主題
確認位置: 首先,請打開你的「終端機」,並 cd 到你的專案根目錄。
1
cd path/to/your/my-blog
執行 git clone 指令:
git clone 這個指令就像是「影印」
會把網路上的主題,完整地複製一份到你電腦的指定位置。
請複製並執行以下完整指令:
1
git clone https://github.com/xbmlz/hexo-theme-maple.git themes/maple
git clone https://...maple.git:這是「影印」的來源,也就是 Maple 主題在 GitHub 上的地址。themes/maple:這是「影印」後要存放的位置。指令會自動在themes資料夾裡,建立一個叫做maple的新資料夾來存放主題。


C. 修改設定檔,啟用新主題
打開設定檔: 在你的專案根目錄,找到並打開
_config.yml這個檔案。找到
theme欄位: 在檔案中,你會找到一行theme: landscape(landscape 是 Hexo 的預設主題)。修改主題名稱: 將
landscape改成我們剛剛安裝的主題資料夾名稱maple。修改前:
1
2
3
4# _config.yml
...
theme: landscape
...修改後:
1
2
3
4# _config.yml
...
theme: maple
...
D. 預覽你的新網站!
儲存你修改好的
_config.yml。回到終端機,執行預覽指令:
1
hexo clean && hexo s
在瀏覽器中打開
http://localhost:4000。
恭喜!你現在應該能看到你的網站已經成功換上了 Maple 主題的全新外觀了!
第四步:GitHub 設定與部署
這一步的目標是將我們在電腦上建好的網站,「發布」到網際網路上,讓全世界都能看到。
A. 在 GitHub 建立一個新倉庫 (Repository)
- 登入你的 GitHub
- 點擊右上角的「+」號,選擇「New repository」
- 關鍵 Repository name 必須符合 你的 GitHub使用者名稱.github.io 這個格式
- 將倉庫設定為 Public (公開) #需有 Free 以上會員等級才可免費設 Private (不公開)
- 完成!點擊「Create repository」

B. 安裝 Hexo 部署外掛 在你的終端機 (專案根目錄 my-blog 中),執行以下指令:
1 | npm install hexo-deployer-git --save |
C. 設定部署資訊 打開專案根目錄的 _config.yml 檔案,滑到檔案最底部,找到或新增 deploy: 區塊,填上你剛剛建立的倉庫資訊
1 | deploy: |
像我就是輸入
1 | deploy: |
D. 部署上線! 回到終端機,執行這行神奇的指令:
1 | hexo clean && hexo g && hexo d |
🤔 clean, g, d 是什麼意思? (點擊展開細節)
這是一套「三合一」的自動化流程:
- hexo clean: 大掃除。刪掉上次產生的舊網站檔案 (/public 資料夾),確保這次是全新的開始
- hexo g (generate): 打包。把你的 Markdown 文章和主題樣式,編譯成瀏覽器看得懂的靜態 HTML, CSS, JS 檔案
- hexo d (deploy): 寄送。把打包好的所有檔案,透過我們安裝的 hexo-deployer-git 外掛,推送到 GitHub Pages 上
第五步:基礎 SEO 設定
為了讓 Google 等搜尋引擎能找到並正確收錄你的網站,我們需要做幾項基礎的 SEO 設定。
A. 安裝網站地圖 (Sitemap) 與爬蟲規則 (robots.txt) 外掛 在終端機 (專案根目錄 my-blog 中) 執行以下指令來安裝:
1 | npm install hexo-generator-sitemap hexo-generator-robotstxt --save |
B. 修改 _config.yml 設定 打開專案根目錄的 _config.yml,確認 url 欄位已經填寫成你完整的網址,並新增 sitemap 和 robotstxt 的設定
1 | # _config.yml |
C. 提交到 Google Search Console (GSC)
設定完後,你需要主動去 Google Search Console 登記你的網站,並提交你的網站地圖
這個步驟就就像是去戶政事務所報戶口一樣 應該很貼切吧 ? xd
https://search.google.com/search-console/about

雖然有許多方法來建立 SEO 但如果像我們是使用 GitHub Pages + Hexo 的話
用這方法即可 快又方便 對於初次使用 SEO 來說 實在是新手友善 🥹
一切順利之後 進到頁面 點選左側 Sitemap
然後看到 新增 Sitemap 內的輸入框
輸入 sitemap.xml

當然你也能到 https://你的使用者名稱.github.io/sitemap.xml 去檢查看看
是不是有順利出現 XML file
當然初次在提交時,「狀態」欄位一開始可能會顯示「無法擷取」
這是正常的 要等待一陣子 讓 Google 吃到
但是過幾天沒看到就要記得 Debug 了
可能出錯在 robots.txt 可能出錯在 _config.yml 都不太一定
若以上一切順利的話
那麼你的 SEO 基礎就打好了!恭喜老爺賀喜老爺 🎉🎉🎉
提早結語
做到這 就算是已經部署完最基本的功能了
可以開始玩你的個人網站瞜 (興奮到模糊 wwwwwww
但當然了 這充其量 也只是個 “開始”
你可以想像成 你正在打造一個實體店面
我們終於辛苦搞好 地點 合約 租金/買地
但現在這些步驟都只是 前菜 現在才是真正要發揮創意了
我們要弄水電 要顧及人力 要粉刷牆壁 倉庫要有貨 等等等
所以 接下來的創意之路 還等著你發揮了
不過在開始之前 我記錄了 十大 我個人認為的冤望路/踩坑
不仿看看 或許也會遇上你即將碰到的問題
希望這份心得能幫助你少走一些冤枉路 享受創造的樂趣
(除了這提早結語 後面還有另一個結語
我的踩坑實錄之十大經典問題與解法
Hum… 就是各種部署完後 發現各種小問題 以及亂魔改遇到的踩坑經驗 給各位參考
我會用 ★☆☆ 來表示坑洞的程度 一星為小問題 三星為相較難處理
以下整理 這次部署過程中 印象最深刻的 10個 個人遭遇大坑洞XDDDDD 請服用
一、為何文章加了 tags,標籤頁卻一片空白? [★☆☆]
本來我認為只要在文章開頭的 Front-matter 裡 加上 tags: [心得]
就會自動幫我建標籤頁
但實際遇到的問題是:
點進標籤頁連結後 除了標題頁面一片空白!
我直接 ✌️ 原地嚇到 ✌️
後來我的解決方案是:手動安裝額外的「產生器」外掛來處理標籤、分類等彙整頁面
在終端機執行 才恢復了正常
1 | npm install hexo-generator-tag hexo-generator-category --save |
非常推薦使用
二、文章和「關於我」頁面的圖片路徑問題 [★☆☆]
我本以為 同圖片 放至該文章同資料夾 撰寫.md檔 就簡單 在/後面 寫檔名
但不確定是該主題問題 還是我真的太菜
我似乎碰上 _posts 這個資料夾 圖片一直會進不來會破圖
所以我另外開了一個圖片的資料夾(/images) 用 ../ 或絕對路徑 處理所有部落格的圖
在用不同的文章 url 建立不同的子資料夾 做管理
我查到的問題 post_asset_folder 只對 _posts 裡的「文章」有效
所以對於關於我頁面 也是另外建新的資料夾(如 source/about/)底下
直接放入圖片 並使用絕對路徑引用
三、為何本地刪除的文章,線上版本還陰魂不散? [★★☆]
也是好笑 腦袋真的冒出 Jacky Wu 那句 見鬼啦 👻
反正就如標題 我在本地電腦上把 .md 檔案刪了 部署上去 網站自然就會更新
但結果 無論我怎麼部署 那篇文章 一直像幽靈一樣 留在線上的網站裡 XDD
後來研究下 就發現 可以手動刪除專案根目錄下的 .deploy_git 隱藏資料夾
然後再全部重來一次 它會強制進行一次比對
1 | rm -rf .deploy_git |
四、一篇文章,兩種日期?我的網站有時差? [★★☆]
我有在文章的日期,也就是我在 Front-matter 裡寫的那個 date
但首頁列表顯示一個日期 點進文章內頁卻又變成另一個日期 …
最後發現是 原來主題在不同地方,分別顯示了 date (發布日期) 和 updated (更新日期)
而 updated 日期又因為 _config.yml 裡的 updated_option: ‘mtime’ 設定
它會在你每次儲存檔案時自動更新
最後我打算直接統一 以 .md 檔案裡的 date 值為主 不啟用自動更新 才解決了這詭異現象
五、手機的深色模式下,為何看不清楚? [★★☆]
👉 不知道 CSS 嗎?
核心概念:HTML 是骨架,CSS 是外觀
如果把製作一個網頁想像成 「蓋房子」 或 「穿搭」- HTML (結構):
房子的鋼筋水泥,或是人的骨架。
它決定了哪裡有標題、哪裡有圖片、哪裡有按鈕。
雖然功能都在,但看起來很陽春(像是白底黑字但網頁有功能)。 - CSS (樣式):
房子的油漆裝潢,或是人的衣服化妝。
它決定了牆壁要漆成什麼顏色、字體要多大、圖片要放左邊還是右邊。
簡單來說 CSS 負責讓網頁「變漂亮」和「排版」

就像下面是一個 CSS 的內容 備注是我個人常用的風格可忽略
1 | /* --- 字體顏色 大小 位置 --- */ |
加了上段 CSS 之後 我們就能把這個標題變成 紅色 且字體 變大
這也讓我多一個認知 原來瀏覽器設定好 手機也可以順便檢查
可能本來我以為 所有瀏覽器上看起來都應該一樣 現在多了這個知覺/思維了
- 我實際遇到的問題是:
在 iPhone 的 Safari 開啟深色模式 展開的選單文字是淺色 背景也是淺色 根本看不見 - 最後我的解決方案是:
變更我規則裡的「權重 (Specificity)」
在 custom.css 中 撰寫一個條件更明確的 html.dark
並加上 !important 大絕招 強制覆蓋主題的樣式
附上我的寫法 備注是我個人常用的風格可忽略
1 | /* --- 手機在深色模式下的文字顏色 --- */ |
六、為何 Safari 看不到網站小圖示 (Favicon)? [★★☆]
當我用 iPhone 的 Safari 檢查 發現看不到網站圖示
明明設定好 favicon.ico 所有瀏覽器就都會顯示我的網站圖示
結果 我的鹽巴罐 Logo 在所有電腦瀏覽器上都正常 換成 iPhone 就變回了預設圖示
這個經驗 同踩坑五 也是讓我多一個認知
Apple 生態系有自己的圖示規範
需要提供一個名為 apple-touch-icon.png 的檔案 並在網頁
這邊推薦使用 RealFaviconGenerator.net 這樣的專業工具
可以一次性產生所有平台所需的圖示和程式碼 一勞由逸 蘇胡辣 (❁´ω`❁)
附上傳送門 https://realfavicongenerator.net/
七、GitHub Pages 只能用公開 Repo?[★★★]
先羞愧地說 下面有部分是錯的 XDDDD 留著自己鞭自己 讓下次多注意
要使用免費的 GitHub Pages 服務
我的網站原始碼 Repo(倉庫)就必須設定成「公開 (Public)」
但這樣也會讓全世界都看得到我的程式碼…
其實!!! 現在倉庫已經可以設定為 Private 不公開 了
在 2019 年以前,免費版的 GitHub 會員
確實規定只有「公開」的倉庫才能使用 GitHub Pages 功能
很多人(包括很多舊的網路教學)的記憶還停留在那個時候
這個政策在 2019 年 4 月 2 日 發生了重大的改變
GitHub 官方宣布將這個原本屬於付費方案的功能,全面開放給所有使用者
官方來源 (Official Source) 如下https://github.blog/2019-04-02-new-github-pages-for-private-repositories/
如果公開 我怕有些人就把 API Key 放上去也有可能 (你懂的 XDDDDD)
這樣就等於是把家裡的鑰匙掛在大門口,任何人都可以拿去亂用,非常危險
我也差點陷入這個困難 索性查了一下 我就大辣辣改為不公開了
若你也為公開 步驟為至該 repo 然後點 setting 滑到下面將 Public 改成 Private
= = = = 2025.11.14 Updated = = = =
這邊感謝 BoBo 大佬 的回饋
先講結論 以上我敘述的資訊是有誤的
GitHub Free 的使用者將會看到如下圖

而我之所以能自由切換 是因為我本身就是 GitHub Pro 版本
誤以為大家都可以 也將文章解讀錯誤

2019 年那篇部落格文章確實存在 但它的功能是針對付費方案
如 GitHub Pro / Team / Enterprise 等方案的增強功能
而不是開放給 GitHub Free 會員
明明測試過 沒想到自己撰寫上有盲點 不夠客觀有些忽略
向讀者深感抱歉… 也非常感謝回饋 造成不便還請各位海涵與留情
八、鬼打牆的首頁縮圖路徑[★★★]
小雷同 二、圖片路徑 但目的不同 解決方案也有小差異
本來我只要在文章的 Front-matter 裡 將cover: 欄位填上圖片檔名 就會自動顯示縮圖
但無論 我填寫 圖片.png 或是 /_posts/文章/圖片.png
圖片在首頁上永遠是個破碎的圖示
最後發現到問題出在「主題不知道如何組合路徑」
直接修改首頁樣板 archive.ejs 將 <img> 標籤的 src
從 <%- url_for(post.cover) %> 改成 <%- url_for(post.path + post.cover) %>
手動把 文章的地址 (post.path) 和 圖片 (post.cover) 拼接起來 才終於解決
九、從零打造首頁縮圖功能[★★★]
現代很多主題 部落格首頁 會顯示縮圖應該是基本功能吧?
但我選的該主題 主打簡約 所以並沒有這樣的視覺功能 哭了
想簡約 但又想要有縮圖 只好自己魔改了 wwwwww
首先 回到前面遇到的問題
在文章 Front-matter 加入 cover 屬性後
首頁列表完全沒反應 QAQ
這跟 八、鬼打牆的首頁縮圖路徑 是接續的組合拳問題
這邊我的解決方案:
打開檔案 archive.ejs 在文章迴圈中(在theme > maple > layout裡面
手動加入 <% if (post.cover) { %> ... <img src="..."> ... <% } %>
的 EJS 判斷式 讓它去讀取 cover 屬性並顯示圖片
接著,再去 custom.css 裡為這個縮圖加上 width, height, object-fit: cover 等樣式讓它美觀
這樣就完成了 第八個坑 跟 第九個坑 是連貫的
雖然如果當初沒有選這個主題 就不用這麼麻煩了…
但往好處想 XDDDD 這是最有成就感的一個修改!學會修改樣板的邏輯
十、主題更新大炸彈 = = 💣 [★★★★★]
這是全部裡面最慘痛的
痛到需要客製化外科手術 ( ROOM…
我當初 clone 主題樣式 後 少做了 更新 這動作
我早已經把 custom.css 寫爆、版面 (.ejs) 改成我想要的樣子…
殊不知後來才發現 作者有持續更新 我 clone 完的是 0.0.0 版本
而當時作者已經更新到 0.0.7 了
但我改了不少要我全部蓋掉要我命 XDDDDD
目前知道的方法 好像就真的只能人工一個一個檢查… 像是動大手術一樣…
三個字 超級可悲
目前我都還沒升級
有去看主題的作者發布了一個超棒的新版本,修正了 Bug 還加了新功能
如果當初 開始亂裝潢之前 就先升級 就不怕這些魔改很多的地方會灰飛煙滅…
目前尚未升級 找個好時間來動大刀
我是預計 先安全複製一份 然後開始魔改 clone & update
然後用一些軟體的「檔案比對」功能
再將新版的功能「移植」到我現有的檔案中
怎麼想都覺得是超可怕的外科手術 - -
有可能我就不弄了 就這樣…
這是這次建網站學到最重要(痛)的一課 誠心建議大家都有看到這條 不跟我一樣
結語
感謝你看完所有內容
你的實體店面打造的怎麼樣了?
架設個人網站的過程 實在遠比想像中更有趣
它不僅是打幾個指令 很像是真的打造一個店面
過程中會一直想增加東西 像充滿挑戰的遊戲
每增加一個功能 每解決一個 Bug
都代表你對網站的底層運作原理有加強一步的理解
也因此我才記錄了十大我個人認為的冤望路/踩坑
願你也能一同享受這創造的樂趣( 但 我懂 BUG 有時候出現真的很躁很不有趣 XD
希望這份心得能幫助你少走一些冤枉路 並享受創造的樂趣! 謝謝你的觀看
如果這份充滿眼淚的踩坑實錄對你有所幫助,幫我點個 ❤️ 吧!
🚀 點我快速回到頂部按讚
🎧 今日我想分享的音樂是這首...
Wanting(曲婉婷)《Everything In The World》 ☺️ 希望你也會喜歡
參考資料
[1] medium@JackChen89
[2] https://ed521.github.io/2019/07/hexo-install/
[3] https://hackmd.io/@Heidi-Liu/note-hexo-github
[4] https://raychiutw.github.io/2019/Static-Site-Generator-Comparison/