我一直覺得個人博客最大的門檻不在寫作而在折騰。不少朋友一開始興致勃勃想搭個自己的博客一搜教程要么老到能考古要么零碎得連不上趟折騰幾天連本地預(yù)覽都沒跑起來熱情就涼了一半。如果你也有這種感覺那這篇文章應(yīng)該能幫你省下不少時間。這次我來完整過一遍Hexo部署加Sakura主題調(diào)教的流程從零開始把環(huán)境、配置、主題、發(fā)布、排錯一條龍捋清楚照著做就行。Hexo部署這件事聽起來有點技術(shù)門檻實際上就是把一套基于Node.js的靜態(tài)博客系統(tǒng)跑起來再通過Git推到代碼托管平臺的Pages服務(wù)上最終得到一個能通過域名訪問的個人站點。Sakura主題則是整個流程里最值得花心思的部分它默認(rèn)狀態(tài)下已經(jīng)很好看但真正好用的博客從來不是裝好主題就算完而是按照自己的寫作習(xí)慣和審美偏好把菜單、側(cè)欄、配色、評論、特效一點點調(diào)順。這個過程就是標(biāo)題里說的“調(diào)教”也是這篇文章的核心。這篇文章適合幾類人看剛接觸Hexo、想搭一個長期維護的個人博客的新手已經(jīng)跑通Hexo但不知道怎么把Sakura主題玩出花來的朋友還有那些被各種過時教程坑過、想系統(tǒng)梳理一遍部署和排錯思路的人。我會把每一步的“為什么”也講清楚而不只是丟命令這樣你以后遇到問題能自己判斷。1. 項目概述與核心價值1.1 為什么是Hexo而不是WordPress或Hugo先說一個很多人糾結(jié)的問題博客框架那么多為什么選Hexo。我個人的判斷標(biāo)準(zhǔn)是三條上手成本、折騰空間、社區(qū)資源。Hexo恰好是這三者平衡得比較好的那一個。動態(tài)博客方案比如WordPress功能確實全后臺管理、在線編輯、插件市場都很成熟但代價是你得租一臺有數(shù)據(jù)庫的服務(wù)器還要面對插件沖突、安全補丁、性能優(yōu)化這些沒完沒了的問題。很多人只是想安安靜靜寫文章結(jié)果變成了服務(wù)器管理員這就本末倒置了。靜態(tài)博客方案里Hexo和Hugo是最常被比較的兩個。Hugo用Go語言編寫構(gòu)建速度極快幾千篇文章也能秒級生成但它建立在Go模板體系上想改主題結(jié)構(gòu)得先學(xué)Go模板語法對大多數(shù)只有一點前端基礎(chǔ)的人來說門檻偏高。Hexo基于Node.js模板用的是EJS或Swig會一點HTML和CSS就能把主題翻個底朝天。再加上Hexo的中文社區(qū)非?；钴S插件、教程、主題數(shù)量都碾壓其他靜態(tài)框架遇到問題搜一下基本有現(xiàn)成答案。用生活類比來解釋就是Hugo像一輛出廠調(diào)校到極致的性能車拿來跑就很快但想改裝得懂機修Hexo更像一輛改裝文化豐富的家用車原廠夠用更重要的是滿大街都是改裝配件和改裝店你隨便折騰也不怕沒人幫你。Sakura主題就是這些“改裝配件”里口碑和視覺完成度都很高的一套方案。1.2 Sakura主題值得調(diào)教的理由Sakura主題在Hexo社區(qū)里屬于一眼就能認(rèn)出來的那種。它的默認(rèn)風(fēng)格偏向二次元審美色彩明亮圓角卡片多整體觀感很“活”不是那種性冷淡風(fēng)的極簡博客。喜歡的人會很喜歡的不喜歡的人可能會覺得花哨這完全看個人口味。但它能在眾多主題里被反復(fù)提起更多是因為它的功能密度響應(yīng)式布局、夜間模式、文章目錄、代碼高亮、側(cè)欄小組件、社交鏈接、背景特效幾乎開箱即得。不過主題默認(rèn)給的東西是“通用解”不是“最優(yōu)解”。每個人的寫作內(nèi)容不同有的博主主要發(fā)技術(shù)筆記有的主要發(fā)攝影日記還有的拿博客當(dāng)個人簡歷用。同一個主題不可能在所有場景下都完美適配所以調(diào)教是必然的。調(diào)教Sakura主題的核心思路可以總結(jié)成一句話先懂配置再捋模板最后動樣式。配置層面解決“有什么”的問題模板層面解決“放在哪”的問題樣式層面解決“長什么樣”的問題。按照這個順序來你會非常從容不會改一處崩一處。2. 部署環(huán)境與準(zhǔn)備工作2.1 Node.js安裝與npm換源Hexo是Node.js生態(tài)里的應(yīng)用所以第一步是把Node.js環(huán)境裝好。這里有一個常見的坑很多人習(xí)慣從官網(wǎng)直接下載最新版但最新版有時候不是穩(wěn)定版某些依賴編譯起來會有奇奇怪怪的問題。我個人建議選擇LTS長期支持版本穩(wěn)定壓倒一切Hexo的社區(qū)也主要在LTS版本上測試。環(huán)境裝好以后先用兩個命令確認(rèn)是否成功node -v npm -v能正常打印版本號說明Node.js和npm都可用。接下來要處理npm下載慢的問題。如果你直接npm install默認(rèn)走官方源速度可能在各種網(wǎng)絡(luò)環(huán)境下都不太樂觀尤其國內(nèi)網(wǎng)絡(luò)環(huán)境下往往慢得讓人懷疑人生。推薦把npm源切換到國內(nèi)鏡像npm config set registry https://registry.npmmirror.com切換之后再用npm config get registry確認(rèn)看到的是鏡像地址就說明生效了。這一步看著不起眼但后面裝Hexo和下載主題依賴的時候能幫你省出大量時間。2.2 Git安裝與SSH密鑰配置Hexo的部署流程依賴Git。原因很簡單靜態(tài)博客最終是通過Git把生成好的網(wǎng)頁文件推送到代碼托管平臺再由平臺的Pages服務(wù)對外提供訪問。所以你需要在本地裝好Git環(huán)境同時配置SSH密鑰讓平臺能認(rèn)出“是你”在推送代碼。裝好Git之后先設(shè)置用戶名和郵箱這兩個信息會嵌入到提交記錄里git config --global user.name 你的名字 git config --global user.email 你的郵箱接著生成SSH密鑰ssh-keygen -t rsa -b 4096 -C 你的郵箱一路回車即可。生成完成后用下面這個命令復(fù)制公鑰內(nèi)容cat ~/.ssh/id_rsa.pub把輸出的一整串內(nèi)容復(fù)制到代碼托管平臺的后臺設(shè)置里位置一般在“SSH公鑰”或“安全設(shè)置”這類菜單下。添加成功后可以拿下面的命令做一次連通性測試ssh -T git對應(yīng)平臺如果看到歡迎語說明SSH通道已經(jīng)打通。這一步有個新手很容易犯的錯以為配置了Git就完事了結(jié)果部署時平臺一直報權(quán)限錯誤實際上是SSH公鑰沒有添加或者添加的和本機生成的不是同一對。3. Hexo初始化與基礎(chǔ)配置3.1 初始化項目與目錄結(jié)構(gòu)Node.js和Git都就緒之后正式進入Hexo部署環(huán)節(jié)。首先是安裝Hexo的命令行工具npm install -g hexo-cli安裝完成后在一個你習(xí)慣存放項目的目錄里執(zhí)行初始化命令hexo init blog cd blog npm install這一步會自動生成一套完整的Hexo項目骨架包括node_modules、source、themes、scaffolds等關(guān)鍵目錄。很多第一次接觸Hexo的人會對這套結(jié)構(gòu)感到陌生其實理解起來不復(fù)雜source是你寫文章和放原始素材的地方themes是主題代碼的存放位置_config.yml是全局配置文件scaffolds是文章模板public則是每次執(zhí)行生成命令后被覆蓋的靜態(tài)網(wǎng)頁產(chǎn)物。初始化完成之后先跑一個本地預(yù)覽看看基礎(chǔ)效果hexo server瀏覽器訪問默認(rèn)地址正常情況下能看到一個Hexo默認(rèn)主題的空白頁面。我第一次跑通的時候雖然只是默認(rèn)頁但那種“我的博客活了”的感覺還是很強烈的。3.2 核心配置項詳解本地服務(wù)能跑起來之后先不急著換主題把根目錄下的_config.yml里的基礎(chǔ)信息梳理清楚。這個文件是Hexo全站的“總控臺”重要性怎么強調(diào)都不為過。幾個必改的配置項包括title站點標(biāo)題、subtitle副標(biāo)題、author作者名、language語言這里填zh-CN才能讓部分中文主題和插件正確渲染。還有個容易忽略的地方是url字段它應(yīng)該填最終要用的域名而不是本地地址否則后面生成站點地圖或者提交搜索引擎收錄時所有鏈接都會是錯的。另外theme字段要改成接下來準(zhǔn)備使用的主題名默認(rèn)是landscape后面裝好Sakura之后需要改成sakura。還有一個值得注意的配置是permalink它決定文章的URL格式。默認(rèn)是:year/:month/:day/:title/這種帶日期的結(jié)構(gòu)對歸檔友好但如果你更看重URL的簡潔性也可以改成:title/。我個人的習(xí)慣是保留帶日期的方式因為Hexo的文章文件名如果重了URL沖突的概率更低。3.3 寫第一篇測試文章配置好站點信息之后順手創(chuàng)建一篇測試文章方便后面驗證主題效果。Hexo創(chuàng)建文章的命令是hexo new post hello-world執(zhí)行后會在source/_posts目錄下生成一個Markdown文件。用編輯器打開你會看到開頭有一段被---包裹的內(nèi)容這就是Front-matterHexo通過這里聲明文章標(biāo)題、日期、標(biāo)簽和分類。踩過的坑要提醒一句categories和tags這兩個字段寫錯了格式會導(dǎo)致文章頁不顯示分類信息一定要用清單樣式即使只有一個分類也要寫成categories:加空格再加短橫線。測試文章里可以隨便寫幾段話再放一張本地圖片驗證圖片路徑是否正確。等這些都確認(rèn)過了再開始折騰主題也不遲。4. Sakura主題的安裝與調(diào)教4.1 下載主題并啟用Sakura主題的安裝方式和大多數(shù)Hexo主題一樣克隆到themes目錄下cd themes git clone 主題倉庫地址 sakura克隆完成后回根目錄打開_config.yml把theme字段改成sakura然后重新啟動本地服務(wù)。這一步如果順利你會看到博客外觀完全變成了Sakura的默認(rèn)樣式。這里必須提醒一個主題相關(guān)的版本匹配問題Sakura主題在社區(qū)里有多個分支或魔改版不同版本對Hexo版本的要求可能不一樣。如果你克隆下來之后本地服務(wù)報錯優(yōu)先檢查兩件事一是主題的說明文檔有沒有寫依賴的Hexo版本二是themes/sakura/package.json里有沒有額外的依賴需要單獨npm install。別一報錯就懷疑主題不好多數(shù)情況是版本不匹配。Sakura主題的配置入口在themes/sakura/_config.yml注意不要和根目錄的全局配置搞混。這個文件里的參數(shù)非常多我按重要程度分成幾類來講。4.2 主題核心參數(shù)調(diào)教先看菜單導(dǎo)航。Sakura默認(rèn)會顯示“首頁”“歸檔”“關(guān)于”這些菜單項對應(yīng)的配置區(qū)塊是menu。這里的分支邏輯是每個菜單項都會關(guān)聯(lián)一個頁面比如關(guān)于頁面如果你還沒創(chuàng)建點進去就是404。所以調(diào)教的第一步是先把要展示的頁面建好再配置菜單順序反了就會出現(xiàn)一堆死鏈。創(chuàng)建“關(guān)于”頁面的方式是執(zhí)行hexo new page about然后在source/about/index.md里寫內(nèi)容。菜單里的顯示名稱、跳轉(zhuǎn)鏈接都在主題配置里改你可以按自己的博客欄目來規(guī)劃比如把“歸檔”改成“索引”把“關(guān)于”改成“博主說”完全自定義。這個步驟最值得投入時間因為導(dǎo)航是訪客理解你博客結(jié)構(gòu)的核心入口。接下來是側(cè)欄。Sakura的側(cè)欄組件包括頭像、簡介、社交入口、文章目錄、最新文章、標(biāo)簽云等。側(cè)欄的展示與否可以在配置里打開或關(guān)閉但真正要調(diào)的是內(nèi)容的“顆粒度”比如社交鏈接要放哪些平臺昵稱顯示成什么這些都要逐項填不填的部分不會顯示也不會報錯。4.3 導(dǎo)航菜單與側(cè)欄使用體驗優(yōu)化很多人的博客看起來“沒調(diào)過”問題就出在側(cè)欄內(nèi)容太多但不可控。Sakura默認(rèn)會把很多組件一股腦打開結(jié)果就是你自己的博客看起來和別人的幾乎一樣完全沒有個人辨識度。我的建議是先明確你這個博客的核心功能然后砍掉所有不重要的側(cè)欄組件。舉個例子如果你主要發(fā)技術(shù)文章側(cè)欄保留“目錄”“最新文章”“標(biāo)簽”就夠了“隨機文章”“站點統(tǒng)計”這類裝飾性強的組件可以關(guān)掉降低視覺負(fù)擔(dān)。如果你主要做作品展示側(cè)欄放簡介和作品入口更有意義。這里還有個細(xì)節(jié)值得說Sakura的文章目錄需要文章里有足夠多的H2、H3標(biāo)題才會生成如果你發(fā)現(xiàn)某篇文章沒有目錄欄先檢查Markdown里是不是沒用子標(biāo)題。這是主題調(diào)教里非常容易出現(xiàn)“假故障”的一類問題但其實原因極其簡單。社交鏈接調(diào)教也屬于側(cè)欄范疇。主題默認(rèn)在側(cè)欄底部或菜單欄里提供社交圖標(biāo)入口一般需要你在主題配置里填寫對應(yīng)的鏈接。建議別貪多三五個常用平臺就夠了。我在實際使用中發(fā)現(xiàn)社交鏈接一旦超過七個側(cè)欄高度會變得很長反而擠壓了閱讀區(qū)域體驗并不好。4.4 全局樣式與配色方案調(diào)整配置層面的調(diào)教做完之后如果還想再進一步那就進入了風(fēng)格定制的階段。Sakura主題的樣式控制有一部分通過主題配置里的custom_css字段實現(xiàn)也有一部分需要直接改主題目錄下的CSS文件。改動CSS之前先搞清楚一件事主題更新時會覆蓋你改過的文件。所以如果你打算長期維護這個博客最好把自定義樣式統(tǒng)一放在一個不會被主題升級影響的文件里。Sakura通常支持在主題配置里引入自定義CSS文件路徑你可以在source目錄下建一個css/custom.css然后在主題配置中加一行引用。配色方面我的經(jīng)驗是從“主色調(diào)”和“背景色”兩個變量入手。找到樣式文件里定義顏色變量的位置比如$primary-color、$background-color這類變量替換成你想要的色值全站顏色就會跟著變。這個操作比挨個改樣式文件高效得多也是我最推薦的做法。還有一個小而美的調(diào)教方案是修改文章頁的正文寬度和行高。Sakura開源發(fā)布的默認(rèn)樣式里正文的版心寬度大約是適合短段落閱讀的但如果你需要放進比較長的代碼塊或者表格可以考慮適度調(diào)整內(nèi)容區(qū)域的寬度限制。調(diào)整時注意別把行高改得過疏否則手機端閱讀會很難受。5. 構(gòu)建、發(fā)布與域名綁定5.1 本地構(gòu)建與預(yù)覽檢查主題調(diào)教告一段落之后別急著部署先在本地把靜態(tài)文件完整構(gòu)建一遍hexo clean hexo generate hexo serverhexo clean清理的是public目錄和緩存這一步很關(guān)鍵尤其是你改過主題名稱、刪除過舊文件時不清理干凈可能導(dǎo)致線上出現(xiàn)你根本找不到來源的殘留頁面。hexo generate會根據(jù)當(dāng)前配置文件重新生成完整的靜態(tài)站點hexo server則啟動本地預(yù)覽。本地預(yù)覽的主要檢查項有三塊首頁是否能正常列出文章摘要文章頁是否完整渲染了標(biāo)題、目錄、標(biāo)簽和評論區(qū)域歸檔和分類頁面是否按預(yù)期展示。這一步千萬不要跳過因為部署上去之后發(fā)現(xiàn)問題再改雖然也不是大事但來回耗時總不如本地一鍵驗證來得快。5.2 代碼托管平臺Pages部署本地檢查無誤后就可以往線上部署了。部署的原理很簡單Hexo通過插件hexo-deployer-git把public目錄里的文件推送并覆蓋到代碼托管平臺倉庫中。這個插件需要先安裝npm install hexo-deployer-git --save然后在根目錄_config.yml中配置deploy區(qū)塊deploy: type: git repository: 你的倉庫SSH地址 branch: main倉庫地址務(wù)必用SSH格式不要用HTTPS格式因為前面配置的SSH密鑰在HTTPS方式下派不上用場。分支名根據(jù)平臺默認(rèn)分支調(diào)整有些平臺是main有些是master寫錯了推送會失敗。配置完成后一條命令完成部署hexo deploy執(zhí)行時會先構(gòu)建再推送等控制臺輸出Branch ... set up to track origin ...之類的信息就說明推送成功。之后到代碼托管平臺的后臺開啟Pages服務(wù)選擇好分支等一兩分鐘你的博客就上線了。5.3 域名綁定與HTTPS如果你有自己的域名可以在代碼托管平臺Pages服務(wù)的設(shè)置里綁定。綁定過程一般為填寫域名然后在域名服務(wù)商后臺解析一個CNAME別名到平臺分配的域名具體地址以平臺提示為準(zhǔn)。解析生效后再回到平臺提交綁定通常幾分鐘內(nèi)就可以通過自己的域名訪問。域名解析配置有一個常見問題有的平臺強制要求使用CNAME有的則要求同時配置A記錄指向具體IP而且不同區(qū)域也不同這完全取決于你用的托管平臺。我建議按平臺文檔來不要憑經(jīng)驗亂配因為這類配置一旦填錯連鎖反應(yīng)就是域名解析不生效但頁面報錯信息又很模糊排查起來很費勁。如果你綁定了自定義域名記得同時開啟HTTPS。平臺一般提供免費證書申請后自動續(xù)期不需要你手動管理。頁面訪問地址統(tǒng)一為https://你的域名這樣瀏覽器地址欄看起來才正式搜索引擎那邊也更友好。6. 常見問題與排查技巧實錄6.1 部署失敗Git認(rèn)證與遠(yuǎn)程倉庫權(quán)限錯誤部署過程中遇到最多的報錯是權(quán)限相關(guān)典型表現(xiàn)是控制臺輸出大段英文其中包含Permission denied (publickey)或者Could not read from remote repository。出現(xiàn)這類報錯先檢查SSH公鑰有沒有正確添加到平臺。很多人這里會犯一個隱蔽的錯在平臺添加的“密鑰”多了一個換行符或者復(fù)制的時候少了后半段導(dǎo)致平臺拿到的公鑰與本地私鑰不匹配。解決方法是重新查看一次本地公鑰確認(rèn)復(fù)制完整再重新添加。另外有些平臺還要求把本機的私鑰文件路徑明確告訴SSH客戶端你可以通過下面這個命令驗證SSH配置是否能正確對應(yīng)倉庫ssh -T git對應(yīng)平臺如果這條命令能輸出歡迎語而hexo deploy仍然報權(quán)限錯誤那基本可以確定是倉庫地址寫錯了。檢查一下deploy配置里的repository是不是用到了SSH格式別不小心填成HTTPS地址。6.2 主題樣式不生效或頁面布局錯亂換好Sakura主題后重新生成和部署但線上頁面看起來沒有變化或者樣式時好時壞。這個問題的根源通常是緩存和靜態(tài)文件殘留。解決思路是強制清理一次。本地執(zhí)行hexo clean這步會清除public目錄和.deploy_git緩存然后重新生成、重新部署。線上如果還是老樣子試試瀏覽器強制刷新或使用無痕窗口訪問因為瀏覽器側(cè)的緩存有時候也會把舊CSS死死記住。另外如果你改了主題的樣式文件后沒有重啟hexo server本地預(yù)覽也會一直停留在舊狀態(tài)這個細(xì)節(jié)也容易踩中。還有一種隱蔽情況是主題引用了外部CDN資源而這些資源在個別網(wǎng)絡(luò)環(huán)境下加載失敗導(dǎo)致頁面結(jié)構(gòu)變亂。排查辦法是打開瀏覽器開發(fā)者工具看控制臺和網(wǎng)絡(luò)面板凡是加載失敗的外部資源都有紅色報錯。解決方式要么換一個CDN源要么把資源下載到本地后放入source目錄。6.3 分類和標(biāo)簽不顯示頁面很多朋友調(diào)教完主題后點“分類”或“標(biāo)簽”菜單發(fā)現(xiàn)頁面一片空白或者只有一行“標(biāo)簽頁”但沒有內(nèi)容。這里有兩個常見原因。第一個原因是你在寫文章時沒有正確聲明Front-matter里的categories和tags字段或者聲明了但格式錯誤。第二個原因是創(chuàng)建“標(biāo)簽頁”和“分類頁”時沒有執(zhí)行正確的命令。只靠你在菜單里填一個鏈接是不夠的你必須在source目錄下手動生成對應(yīng)的頁面文件hexo new page tags hexo new page categories然后在對應(yīng)頁面的Front-matter里寫上type: tags或type: categoriesSakura主題才會識別這個頁面并注入標(biāo)簽聚合內(nèi)容。這一步新手非常容易漏掉漏掉之后頁面依然存在但就是一個純空白頁面毫無提示。6.4 常見問題速查表癥狀大概率原因排查順序本地預(yù)覽白屏依賴未安裝完整檢查npm install結(jié)果部署報權(quán)限錯誤SSH公鑰缺失或不匹配重新添加公鑰檢查倉庫地址格式線上樣式?jīng)]變化緩存未清理執(zhí)行hexo clean重新生成部署文章圖片打不開圖片路徑是絕對本地路徑改為相對路徑或外鏈圖床菜單點進去404對應(yīng)頁面未創(chuàng)建用hexo new page創(chuàng)建目標(biāo)頁面評論功能不顯示評論模塊參數(shù)未填寫檢查主題配置中評論服務(wù)的三方編號參數(shù)代碼高亮失效語言標(biāo)簽缺失確認(rèn)代碼塊圍欄后填寫了語言標(biāo)識這七類問題基本覆蓋了Hexo部署和Sakura主題調(diào)教里八成的新手故障。我每次幫人排錯都是按“配置檢查、緩存清理、頁面創(chuàng)建、資源路徑”這個順序去問的九成問題都出在這幾個環(huán)節(jié)上。最后再分享一個小技巧調(diào)教Sakura主題時建議把主題配置文件和自己的自定義CSS文件都用版本管理工具托管起來。這樣即使哪天主題改壞了或者想回退某個配置隨時可以回到之前的穩(wěn)定狀態(tài)。博客這個東西只要底子是好的后續(xù)維護會越來越輕松你也會越來越愿意在上面寫字。