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