1. 為什么選擇 GitHub Pages Hexo 這條路如果你正在看這篇文章大概率是厭倦了在各大平臺寫博客時被各種廣告、審核和格式限制所困擾。想擁有一個完全屬于自己的、干凈利落的寫作空間但又不想在服務器、域名和運維上投入太多金錢和精力。那么GitHub Pages 配合 Hexo 靜態博客框架幾乎是為你量身定制的方案。我自己的技術博客和幾個項目文檔站都跑在這套組合上穩定運行了四五年幾乎零成本訪問速度也完全夠用。簡單來說GitHub Pages 是 GitHub 提供的免費靜態網站托管服務你只需要有一個 GitHub 賬號就能獲得一個username.github.io的域名和服務器空間。而 Hexo 是一個基于 Node.js 的快速、簡潔且高效的博客框架它能把我們用 Markdown 寫的文章瞬間轉換成漂亮的靜態網頁。這兩者結合意味著你可以在本地用你最順手的編輯器寫文章然后用幾條命令就能發布到互聯網上整個過程優雅得像在本地保存文件一樣自然。這套方案的核心優勢在于“靜態”。你的網站只是一堆 HTML、CSS、JS 文件沒有數據庫沒有后端邏輯。這帶來了極致的安全性和穩定性——幾乎沒有被黑客攻擊的漏洞也幾乎不會因為流量突增而宕機。同時它完全免費如果你使用 GitHub 的免費套餐并且天生支持版本控制你的每一篇文章、每一次主題修改都像代碼一樣被 Git 完整記錄隨時可以回滾到任意歷史版本。網上相關的教程很多但要么過于簡略跳過了關鍵的配置細節讓新手卡在某個步驟不知所措要么就是信息陳舊提到的插件或主題已經不再維護。這篇教程我會結合我這些年搭建、維護以及遷移了不下十個 Hexo 博客的經驗從最基礎的環境安裝到深度自定義再到部署和優化手把手帶你走通每一個環節并重點分享那些官方文檔不會寫、但實際操作中一定會遇到的“坑”和技巧。我們的目標是讓你看完就能擁有一個既美觀又實用的個人博客。2. 環境準備別在第一步就踩坑萬事開頭難但對于 Hexo 來說開頭只要把環境裝對后面就一馬平川。這里需要的核心是 Node.js 和 Git。2.1 安裝 Node.js版本選擇有講究Hexo 運行在 Node.js 環境下。很多教程會直接讓你去官網下載最新版但這其實是個潛在的坑。Node.js 的某些新版本可能會與 Hexo 或其插件存在兼容性問題。我的建議是選擇長期支持版本。訪問 Node.js 官網找到標有LTS的版本進行下載安裝。目前以撰寫時為例v18.x 或 v20.x 都是穩定的 LTS 版本。安裝過程很簡單一路“下一步”即可。但請注意安裝界面上的一個選項“Automatically install the necessary tools”或類似選項。務必勾選它。這會自動安裝npmNode.js 的包管理器以及一些編譯工具對于后續安裝某些需要本地編譯的 Hexo 插件至關重要。安裝完成后打開命令行工具Windows 用 Cmd 或 PowerShellMac 用終端。驗證安裝是否成功node -v npm -v如果兩行命令分別輸出了版本號如v20.11.0和10.2.4說明安裝成功。注意如果你之前安裝過舊版本最好先卸載干凈再安裝新版本避免環境變量沖突。在 Windows 上可以使用專門的卸載工具在 Mac 上如果通過 Homebrew 安裝則用brew uninstall node進行卸載。2.2 安裝與配置 Git你的內容“時光機”Git 是版本控制工具也是我們連接本地和 GitHub 的橋梁。下載安裝前往 Git 官網下載對應系統的安裝包。安裝時在“Adjusting your PATH environment”這一步建議選擇“Git from the command line and also from 3rd-party software”這樣可以在任何命令行窗口中使用 Git。關鍵配置安裝完成后需要進行全局配置這關系到你后續提交代碼的“身份標識”。git config --global user.name 你的GitHub用戶名 git config --global user.email 你的GitHub注冊郵箱這個配置非常重要user.name最好和 GitHub 用戶名保持一致user.email必須是注冊 GitHub 時使用的郵箱。這樣你在本地做的每一次提交GitHub 都能正確識別出是你。可選但推薦配置 SSH 密鑰。使用 HTTPS 鏈接每次推送都需要輸入賬號密碼而 SSH 密鑰可以實現免密操作更安全便捷。生成密鑰ssh-keygen -t rsa -C 你的GitHub注冊郵箱一路回車使用默認路徑和空密碼。查看公鑰cat ~/.ssh/id_rsa.pub復制輸出的全部內容。登錄 GitHub進入Settings - SSH and GPG keys - New SSH key將復制的公鑰內容粘貼進去Title 可以自擬如“My Laptop”。2.3 安裝 Hexo 腳手架環境就緒后就可以安裝 Hexo 的命令行工具了。這個工具能幫你快速創建博客項目骨架。打開命令行執行以下命令進行全局安裝npm install -g hexo-cli安裝完成后可以通過hexo -v來驗證。如果看到 Hexo 的版本信息說明一切順利。至此所有前置的、底層的工具都已準備完畢。接下來我們將進入激動人心的環節——創建你的第一個博客項目。3. 初始化你的第一個 Hexo 博客項目現在讓我們在本地創建一個專屬的博客文件夾并讓 Hexo 為我們生成初始結構。選擇并創建項目目錄在你電腦上找一個合適的位置比如D:\Blog或~/Documents/Blog。打開命令行進入這個目錄。cd /path/to/your/blog-folder初始化博客執行 Hexo 初始化命令。hexo init my-blog # “my-blog”是你的項目文件夾名可以自定義 cd my-blog這個命令會創建一個名為my-blog的文件夾并在其中下載 Hexo 框架、默認主題landscape和基礎配置文件。安裝依賴包進入項目文件夾后需要安裝項目運行所必需的 Node.js 模塊。npm install這個過程會讀取package.json文件下載所有列出的依賴。完成后你的博客項目骨架就搭建好了。讓我們快速瀏覽一下生成的關鍵目錄和文件_config.yml站點的核心配置文件博客的名稱、描述、URL、部署設置等都在這里。themes/主題目錄。默認里面有一個landscape主題。你下載的其他主題也會放在這里。source/源文件目錄。你寫的 Markdown 文章在_posts/子目錄下、關于頁、標簽頁等都在這里。public/這是執行生成命令后Hexo 將 Markdown 轉換成的靜態 HTML 文件存放處。這個文件夾的內容就是最終要部署到 GitHub Pages 上的。scaffolds/模板文件夾。當你用hexo new命令創建新文章時會依據這里的模板生成文件。本地預覽讓我們先看看默認博客長什么樣。hexo clean # 清除緩存和舊文件 hexo generate # 生成靜態文件可簡寫為 hexo g hexo server # 啟動本地服務器可簡寫為 hexo s執行hexo s后命令行會提示服務已啟動通常訪問http://localhost:4000就能看到你的博客了這是一個本地預覽只有你能看到。你可以試著點擊一下感受一下默認主題的樣式。至此一個最基礎的 Hexo 博客已經在你的本地機器上運行起來了。但這只是開始默認的主題和配置遠不能滿足個性化需求。接下來我們要對它進行“大改造”。4. 核心配置詳解讓博客擁有你的DNA_config.yml這個文件是 Hexo 博客的大腦所有全局設置都在這里。直接用文本編輯器打開它推薦使用 VS Code、Sublime Text 等代碼編輯器。里面的配置項很多我們聚焦最關鍵的幾個部分。4.1 站點信息配置你是誰你的博客叫什么找到Site部分進行修改title: 我的技術漫談 # 博客標題 subtitle: 記錄、思考與分享 # 副標題 description: 一個專注于后端開發、系統架構與個人成長的博客 # 站點描述對SEO很重要 keywords: 技術,博客,編程,Java,Spring # 關鍵詞用英文逗號分隔 author: 你的名字 # 作者名 language: zh-CN # 語言中文設為 zh-CN timezone: Asia/Shanghai # 時區這些信息會顯示在博客的頁眉、頁腳以及生成的 HTML 元數據中是博客的“名片”。4.2 網址配置為部署到 GitHub Pages 做準備URL部分至關重要它決定了生成頁面中鏈接的根路徑。url: https://你的GitHub用戶名.github.io # 你的 GitHub Pages 地址 root: / # 如果部署到非根目錄如 username.github.io/project則改為 /project/ permalink: :year/:month/:day/:title/ # 文章永久鏈接格式 permalink_defaults: pretty_urls: trailing_index: false # 移除鏈接末尾的 index.html對于最基本的個人主頁型 GitHub Pages (username.github.io)url就按上面填寫root保持為/。permalink定義了你的文章鏈接樣式:year/:month/:day/:title/是一種常見且清晰的結構。4.3 部署配置一鍵上線的魔法這是連接本地和 GitHub 的關鍵。找到Deployment部分修改如下deploy: type: git # 部署類型 repo: github: gitgithub.com:你的GitHub用戶名/你的GitHub用戶名.github.io.git # 推薦SSH地址 # 或者使用HTTPS地址https://github.com/你的GitHub用戶名/你的GitHub用戶名.github.io.git branch: main # 部署到的分支GitHub默認主分支現在是 main message: Site updated: {{ now(YYYY-MM-DD HH:mm:ss) }} # 可選的提交信息這里解釋一下repo的兩種地址SSH地址(gitgithub.com:...): 如果你配置了 SSH 密鑰就用這個以后部署不需要輸密碼。HTTPS地址(https://github.com/...): 如果沒配 SSH 密鑰就用這個每次部署需要輸入 GitHub 賬號密碼或 Personal Access Token。實操心得強烈建議使用 SSH 方式一勞永逸。確保你的 SSH 密鑰已添加到 GitHub并在命令行中用ssh -T gitgithub.com測試連接是否成功看到歡迎信息即成功。配置好后你需要安裝 Hexo 的 Git 部署插件npm install hexo-deployer-git --save這個插件會讀取上面的配置并幫你完成將public文件夾推送到 GitHub 倉庫的復雜操作。4.4 其他實用配置new_post_name: :title.md 新建文章的文件名格式保持默認即可。default_layout: post 默認布局新建文章時使用。highlight: 代碼高亮設置。建議啟用并選擇一個喜歡的主題例如highlight: enable: true line_number: true auto_detect: true tab_replace: wrap: true hljs: false這樣你的代碼塊就會有行號和語法高亮了。修改完_config.yml后建議執行hexo clean hexo g重新生成然后用hexo s在本地查看配置是否生效。配置文件是靜態博客的基石花點時間理解它后續的定制化會順利很多。5. 主題選擇與深度定制打造獨一無二的視覺風格Hexo 默認的landscape主題功能簡單顏值一般。社區有大量優秀的第三方主題比如 NexT、Butterfly、Matery 等它們提供了豐富的功能和現代化的設計。這里我以目前非常流行且功能強大的Butterfly主題為例講解如何安裝和配置。5.1 安裝 Butterfly 主題在你的博客項目根目錄下執行git clone -b master https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly這會將 Butterfly 主題的代碼克隆到themes/butterfly目錄下。5.2 啟用主題打開根目錄的_config.yml找到theme字段將其修改為theme: butterfly5.3 主題配置復制與覆蓋Butterfly 主題有自己獨立的配置文件themes/butterfly/_config.yml。但是最佳實踐不是直接修改這個文件因為主題更新時你的修改會被覆蓋。正確做法是在博客根目錄下創建一個名為_config.butterfly.yml的文件如果使用 NexT 主題則是_config.next.yml然后將主題原配置文件中你需要修改的部分復制到這個新文件里進行修改。例如你想修改導航菜單和網站圖標從themes/butterfly/_config.yml中找到menu和favicon相關配置。將其復制到根目錄的_config.butterfly.yml中。在_config.butterfly.yml里進行修改# 導航菜單 menu: 首頁: / || fas fa-home 歸檔: /archives/ || fas fa-archive 標簽: /tags/ || fas fa-tags 分類: /categories/ || fas fa-folder-open 關于: /about/ || fas fa-user-circle # 你可以添加更多如友鏈 # 友鏈: /link/ || fas fa-link # 網站圖標 favicon: /img/favicon.ico # 將你的 favicon.ico 圖片放在 source/img/ 目錄下Hexo 在生成時會優先使用根目錄下這些_config.[theme].yml文件中的配置來覆蓋主題默認配置。這樣就實現了配置與主題代碼的分離便于管理和升級。5.4 常見功能配置示例側邊欄頭像與社交鏈接# _config.butterfly.yml avatar: img: /img/avatar.jpg # 頭像路徑 effect: true # 是否開啟旋轉效果 social: fa-github: https://github.com/你的用戶名 || fab fa-github fa-envelope: mailto:你的郵箱 || fas fa-envelope # 更多圖標參考 Font Awesome文章打賞reward: enable: true QR_code: - img: /img/wechatpay.png link: text: 微信 - img: /img/alipay.png link: text: 支付寶評論系統Butterfly 支持多種評論插件如 Valine、Waline、Gitalk 等。以 Waline 為例你需要先在 Vercel 等平臺部署 Waline 服務端獲取服務端地址。waline: serverURL: https://your-waline-domain.vercel.app # Waline 服務端地址 lang: zh-CN visitor: true # 文章閱讀量統計 commentCount: true # 顯示評論數搜索功能安裝hexo-generator-search插件。npm install hexo-generator-search --save在根目錄_config.yml中添加search: path: search.xml field: post format: html limit: 10000然后在_config.butterfly.yml中啟用本地搜索。主題的配置項極其豐富包括動畫效果、字體、代碼高亮樣式、頁腳信息等等。建議你訪問 Butterfly 主題的官方文檔對照文檔逐一探索和配置。這個過程就像裝修自己的房子雖然繁瑣但成就感十足。配置完成后執行hexo clean hexo g hexo s在本地仔細檢查每一個頁面的效果確保一切如你所愿。6. 寫作與管理讓創作流程化博客的核心是內容。Hexo 讓寫作和內容管理變得非常高效。6.1 創建一篇新文章使用一條簡單的命令hexo new 我的第一篇文章Hexo 會在source/_posts目錄下生成一個 Markdown 文件文件名通常是我的第一篇文章.md。文件開頭是“Front-matter”這是用三條短橫線包裹的 YAML 區域用于設置文章的元數據。6.2 理解 Front-matter打開新生成的文章你會看到類似這樣的結構--- title: 我的第一篇文章 date: 2024-05-27 14:00:00 tags: - 教程 - Hexo categories: 建站 ---這是文章的“頭信息”Hexo 根據它來處理文章。你可以添加更多字段title: 文章標題。date: 發布時間可手動修改。updated: 更新時間可選。tags: 標簽支持多個用數組表示[標簽1, 標簽2]或列表形式。categories: 分類。可以是字符串建站也可以是層級分類[建站, 教程]。permalink: 覆蓋全局的永久鏈接可選。cover: 文章封面圖路徑主題支持時。toc: 是否顯示文章目錄Table of Contents。mathjax: 是否啟用數學公式渲染。6.3 編寫文章內容在 Front-matter 下方就可以用 Markdown 語法暢快書寫了。Hexo 支持所有標準 Markdown 語法并擴展了一些有用的標簽插件例如引用站內文章{% post_link 文章文件名不含.md ‘文章標題’ %}插入圖片{% asset_img 圖片文件名.jpg 圖片描述 %}圖片需放在source/_posts同名的文章資源文件夾內通過hexo new時加--path參數創建代碼塊使用三個反引號包裹并指定語言。我的寫作流程通常是用 VS Code 打開博客項目在_posts里新建文件用 Markdown 寫作配合 Paste Image 等插件直接粘貼截圖圖片會自動保存到對應目錄。寫完一段就用hexo s實時預覽非常方便。6.4 創建獨立頁面除了文章你還可以創建“關于”、“友鏈”、“標簽云”等獨立頁面。創建頁面hexo new page about這會在source目錄下生成一個about文件夾里面包含index.md文件。編輯頁面像寫文章一樣編輯這個index.md文件。它的 Front-matter 可以更簡單通常只需要title和layout如果主題支持特殊的頁面布局。在導航中顯示記得去主題配置文件如_config.butterfly.yml的menu部分添加這個頁面的鏈接如關于: /about/ || fas fa-user-circle。7. 部署到 GitHub Pages讓全世界看到你的博客當你在本地把博客打磨得差不多了就可以部署到 GitHub Pages讓它公之于眾。7.1 創建 GitHub 倉庫這個倉庫的名字有嚴格規定如果你想使用https://你的用戶名.github.io這樣的頂級域名那么倉庫名必須是你的用戶名.github.io。如果你想使用https://你的用戶名.github.io/倉庫名這樣的項目頁面那么倉庫名可以任意。對于個人博客我們通常選擇第一種。登錄 GitHub點擊右上角“”選擇“New repository”。在 Repository name 中填入你的用戶名.github.io選擇 Public公開然后創建倉庫。7.2 配置 SSH 密鑰并測試連接如果你在環境準備階段沒有配置 SSH 密鑰請返回 2.2 節完成。配置后在命令行測試ssh -T gitgithub.com如果看到Hi 你的用戶名! Youve successfully authenticated...的提示說明連接成功。7.3 一鍵部署這是最激動人心的時刻。確保你的_config.yml中部署配置已正確填寫見 4.3 節并且已安裝hexo-deployer-git插件。在博客項目根目錄下執行部署命令hexo clean hexo deploy -g # 或者分步執行 hexo clean # 清理 hexo generate # 生成靜態文件 hexo deploy # 部署hexo deploy -g是generate和deploy的合并操作。命令執行過程中會提示你輸入 GitHub 的用戶名和密碼如果使用 HTTPS 方式。如果使用 SSH 且配置正確則會直接開始推送。推送完成后稍等1-2分鐘訪問https://你的用戶名.github.io你的博客就應該在線了7.4 自動化部署的進階思路每次寫文章都要執行hexo clean hexo deploy -g有點麻煩。更優雅的方式是利用 GitHub Actions 實現自動化。其原理是你將博客的源碼包括 Markdown 文章、主題、配置文件推送到一個倉庫比如blog-source然后 GitHub Actions 會自動在云端執行生成和部署命令將生成的public文件夾內容推送到你的用戶名.github.io這個倉庫。這需要編寫一個.github/workflows/deploy.yml工作流文件。雖然初次設置稍復雜但一勞永逸。網上有大量現成的 Hexo 部署 Action 模板搜索“Hexo GitHub Actions”即可找到。這能讓你從任何設備只需推送 Markdown 文件就完成博客更新。8. 高級技巧與疑難排坑即使按照教程一步步來也可能會遇到一些奇怪的問題。這里分享幾個我踩過的坑和對應的解決方案。8.1 圖片加載失敗問題這是最常見的問題之一。本地預覽正常部署后圖片不顯示。原因1路徑錯誤。Markdown 中引用圖片的路徑是相對于最終生成頁面的。最穩妥的方式是使用 Hexo 的標簽插件{% asset_img %}或{% img %}取決于主題并將圖片放在文章對應的資源文件夾內。解決方案使用“文章資源文件夾”功能。在根目錄_config.yml中設置post_asset_folder: true之后使用hexo new命令創建文章時會自動生成一個與文章同名的文件夾。你可以把文章用到的圖片都放進去。在文章中引用圖片時使用{% asset_img 圖片文件名.jpg 圖片描述 %}Hexo 在生成時會正確處理路徑。原因2圖床問題。如果你引用的是網絡圖片圖床請確保鏈接是 HTTPS 且穩定。8.2 主題樣式或功能不生效檢查配置覆蓋確認你是否在正確的配置文件_config.butterfly.yml中修改了設置并且修改的格式縮進、冒號后的空格符合 YAML 語法。清除緩存每次修改主題配置后務必執行hexo clean再重新生成。Hexo 有緩存機制清理能避免很多詭異問題。查看主題文檔確認你使用的功能是否需要額外安裝插件或進行特定配置。例如某些主題的搜索功能需要單獨安裝hexo-generator-searchdb插件。8.3 部署失敗報錯“Permission denied (publickey)”這通常是 SSH 密鑰問題。檢查密鑰是否添加確保~/.ssh/id_rsa.pub的內容已完整添加到 GitHub 的 SSH Keys 設置中。測試連接再次運行ssh -T gitgithub.com看是否成功。檢查倉庫地址確認_config.yml中的repo地址是 SSH 格式 (gitgithub.com:...)并且用戶名和倉庫名正確。檢查本地密鑰加載在 Windows 上可以嘗試啟動ssh-agent并添加密鑰ssh-add ~/.ssh/id_rsa。8.4 自定義域名與 HTTPS想讓博客擁有像blog.yourname.com這樣的專屬域名購買一個域名在阿里云、GoDaddy等平臺。在域名管理后臺添加兩條 CNAME 記錄記錄類型CNAME主機記錄記錄值你的用戶名.github.io記錄類型CNAME主機記錄www記錄值你的用戶名.github.io在你的博客項目source目錄下創建一個名為CNAME的文件無后綴里面只寫一行你的域名例如blog.yourname.com。重新部署博客 (hexo clean hexo deploy -g)。等待 DNS 生效可能需要幾分鐘到幾小時。生效后GitHub Pages 會自動為你的域名啟用 HTTPS。8.5 備份你的博客源碼你的_config.yml、主題配置文件、Markdown 源文件這些才是你最寶貴的資產。一定要做好備份本地備份定期將整個博客項目文件夾除了node_modules和public這類可生成的目錄壓縮存檔。云端備份在 GitHub 上創建一個私有倉庫例如my-hexo-blog-source將你的源碼推送到這個倉庫。這樣既實現了版本控制也完成了異地備份。.gitignore文件需要忽略node_modules、public、.deploy_git等目錄。搭建博客是一個持續學習和打磨的過程。從最初的功能實現到后來的樣式調整、性能優化、SEO 設置每一步都能學到新東西。最重要的是開始寫堅持寫。這個完全由你掌控的數字角落會成為你技術成長最好的見證。如果在實踐中遇到任何教程未覆蓋的問題善用搜索引擎Hexo 和各大主題的官方文檔、GitHub Issues 區通常都能找到答案。祝你搭建順利寫作愉快