想從零搭一套個人博客系統(tǒng)最容易出現的情況不是在寫代碼而是在選型上反復橫跳——今天看框架明天看內容管理系統(tǒng)后天又想直接套模板。我前前后后給多個朋友做過類似的博客前端最后留在我個人項目里的是一套沒有任何框架依賴的實現HTML、CSS、JavaScript 三件套加一個幾十行的構建腳本就能完成從文章列表到詳情頁、代碼高亮、響應式適配、靜態(tài)部署的全部流程。這篇文章我會把整套前端實現的完整代碼和思路拆開講清楚適合剛接觸博客搭建、想理解博客系統(tǒng)前端到底是怎么工作的人也適合有前端基礎但不希望被框架束縛的朋友直接參考復現。1. 動手之前先把博客前端的需求拆清楚1.1 為什么我放棄了前端框架個人博客系統(tǒng)的前端本質上就三件事管理文章入口、展示文章列表、渲染文章正文。附帶一些標簽、歸檔、關于頁這類補充頁面。它沒有復雜的用戶交互不需要數據雙向綁定不需要服務端渲染來支撐高并發(fā)絕大多數時候就是一個人寫、一群人讀。為這個場景引入前端框架換來的往往是幾百 MB 的 node_modules、看不懂的抽象層和升級依賴時的不確定感。我用表格整理過原生方案和框架方案的差異放在這里供參考對比維度原生三件套前端框架方案初始門檻瀏覽器直接運行無需構建需要熟悉工程化工具鏈運行依賴幾乎為零必須引入框架運行時代碼體積可控按需編寫即使搖樹優(yōu)化也有基礎體積長期維護幾年后打開仍能修改依賴升級頻繁可能出現兼容問題適用場景內容型網站、小型工具復雜交互應用、后臺系統(tǒng)、大型協(xié)作項目并不是說框架不好而是要看場景是否匹配。博客系統(tǒng)作為一個以內容為核心的站點用戶真正關心的是文章能不能快速打開、排版是否舒服、在手機上閱讀是否流暢。這些目標用原生三件套完全可以達成。如果你后續(xù)計劃加入很復雜的編輯器、實時協(xié)作評論、復雜標簽篩選系統(tǒng)那再引入框架也不遲一開始就上框架反而妨礙你把精力放在內容與閱讀體驗上。1.2 目錄設計把數據和展示分開從零動手之前先把目錄想清楚。好的目錄結構應該一眼能看出什么東西放哪里。我目前維護的這套博客前端使用下面的結構blog-front/ index.html # 首頁入口 css/ base.css # 全局樣式、變量、排版基礎 home.css # 首頁文章列表樣式 post.css # 文章詳情頁樣式 js/ data.js # 文章元信息數據構建時生成 markdown.js # 輕量 markdown 渲染函數 router.js # hash 路由 home.js # 首頁渲染邏輯 post.js # 詳情頁渲染邏輯 posts/ # 原始文章目錄每篇一個 md 文件 hello-world.md ... scripts/ build.js # 構建腳本把 md 轉成前端要用的數據 dist/ # 構建產物最終部署這個目錄這個結構的關鍵點是數據和展示分離。文章正文以 markdown 文件放在posts/里構建腳本負責把 md 轉成文章數據最終給前端的是一個干凈的 JSON 或 JS 模塊。寫新文章的人只需要關心posts/里的文件完全不需要碰前端邏輯。如果你暫時不想引入構建腳本也可以直接把文章數據寫在js/data.js里等文章多到管理不過來再遷移到 md 文件方案。我在項目開發(fā)初期也是這么做的先跑通再優(yōu)化避免過度設計。2. 首頁骨架與文章列表先把內容鋪出來2.1 語義化布局首頁的骨架結構博客首頁的職責不是炫技而是讓訪客快速看到最新文章列表。我用的 HTML 骨架很簡單但每一個標簽都是有意圖的!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 title我的個人博客/title link relstylesheet hrefcss/base.css link relstylesheet hrefcss/home.css /head body header classsite-header div classcontainer header-inner a classlogo href#/我的博客/a nav classmain-nav ul lia href#/首頁/a/li lia href#/about關于/a/li lia href#/archive歸檔/a/li /ul /nav /div /header main classcontainer main-content section classpost-list idpostList !-- 文章列表由 JS 渲染 -- /section /main footer classsite-footer div classcontainer footer-inner p由我手工維護文章內容采用知識共享方式分享。/p /div /footer script srcjs/data.js/script script srcjs/router.js/script script srcjs/home.js/script /body /html語義化標簽不是寫給別人看的裝飾。header、main、section、footer這些標簽能幫助屏幕閱讀器正確識別頁面結構也有利于搜索引擎理解內容層級。我在早期重構時曾把這些全換成div結果通過無障礙檢測時被扣了分后來才改回語義化結構。導航里的鏈接統(tǒng)一用href#/這種形式配合后面的 hash 路由使用。這樣做的好處是任何靜態(tài)托管平臺都不需要額外配置服務器回退規(guī)則用戶刷新頁面不會出現 404。2.2 文章列表的數據結構文章列表頁面核心是一組元信息標題、發(fā)布時間、摘要、標簽、唯一標識。我在js/data.js里用一個數組保存結構像這樣window.ARTICLES [ { id: how-to-build-blog, title: 從零搭建個人博客系統(tǒng)的前端實現, date: 2025-01-18, excerpt: 本文記錄了一套不依賴框架的前端實現方案內容包括路由、渲染、代碼高亮與響應式適配。, tags: [前端, 博客, 教程], cover: }, { id: markdown-renderer-basics, title: 自己寫一個夠用的 Markdown 渲染器, date: 2025-01-05, excerpt: 很多人第一時間會去引入現成的解析庫但理解分塊解析的原理能讓問題定位更容易。, tags: [Markdown, 原理] } ];id字段是文章的穩(wěn)定標識不能使用數組下標。因為后續(xù)你可能會刪除、排序或篩選文章一旦下標變化瀏覽器里的歷史鏈接就失效了。我一開始也偷懶用0、1、2當下標后來刪了兩篇文章收藏夾里的舊鏈接全部指向錯位內容才老老實實給每篇文章起了獨立的字符串 id。摘要字段excerpt是從正文開頭手動提取的。配合標題渲染列表卡片時摘要可以讓列表頁有呼吸感也能讓訪客在點擊前判斷文章是否值得讀。如果你希望減少維護成本也可以在構建腳本里自動截取正文前 200 個字符作為摘要。2.3 列表渲染一次性插入而非循環(huán)拼接home.js里面做的事情是把ARTICLES數組渲染成 DOM 結構。這里有一個非常重要的性能習慣不要每遍歷一條數據就操作一次 DOM。頻繁操作 DOM 會引起瀏覽器重排重繪文章數量少時感覺不明顯上到上百篇就會明顯卡頓。function renderArticleList() { const container document.getElementById(postList); if (!container || !window.ARTICLES) return; const html window.ARTICLES.map(function(article) { const tagHtml article.tags.map(function(tag) { return span classtag escapeHtml(tag) /span; }).join(); return ( article classpost-card>function parseHash() { const hash location.hash || #/; if (hash.indexOf(#/post/) 0) { const id decodeURIComponent(hash.replace(#/post/, )); return { name: post, params: { id: id } }; } if (hash.indexOf(#/about) 0) { return { name: about }; } return { name: home }; } window.addEventListener(hashchange, handleRoute); window.addEventListener(DOMContentLoaded, handleRoute); function handleRoute() { const route parseHash(); if (route.name post) { renderPostPage(route.params.id); } else if (route.name about) { renderAboutPage(); } else { renderHomePage(); } window.scrollTo(0, 0); }parseHash把#/post/hello-world解析成{ name: post, params: { id: hello-world } }handleRoute根據路由名稱調動對應的渲染函數。scrollTo(0, 0)是每次切換頁面后自動回到頂部這個細節(jié)不做的話從長文章底部點回首頁瀏覽器會停留在原來的滾動位置觀感非常差。3.3 Markdown 渲染先轉義再解析詳情頁最核心的工作是把 markdown 轉成 HTML。很多人第一反應就是引入大而全的解析庫但博客場景里其實只需要處理標題、段落、列表、引用、代碼塊和加粗斜體這些常見語法。我自己維護了一個輕量渲染器核心思路是逐行掃描并按塊處理。下面是我在項目里使用的簡化版本省略了嵌套列表等邊界情況但足夠覆蓋日常寫作function renderMarkdown(markdownText) { const lines markdownText.split(\n); let html ; let inCodeBlock false; let codeLang ; let codeLines []; function flushCode() { if (codeLines.length 0) return; const codeHtml codeLines.map(escapeHtml).join(\n); html precode classlanguage- codeLang codeHtml /code/pre; codeLines []; codeLang ; } for (let i 0; i lines.length; i) { const line lines[i]; if (line.indexOf() 0) { if (!inCodeBlock) { inCodeBlock true; codeLang line.replace(, ).trim(); } else { inCodeBlock false; flushCode(); } continue; } if (inCodeBlock) { codeLines.push(line); continue; } if (line.indexOf(### ) 0) { html h3 escapeHtml(line.slice(4)) /h3; } else if (line.indexOf(## ) 0) { html h2 escapeHtml(line.slice(3)) /h2; } else if (line.indexOf(# ) 0) { html h1 escapeHtml(line.slice(2)) /h1; } else if (line.indexOf(- ) 0) { html li escapeHtml(line.slice(2)) /li; } else if (line.trim() ) { html /li/ul; } else { html p escapeHtml(line) /p; } } if (inCodeBlock) { flushCode(); } // 把孤立的 li 包裹進 ul html html.replace(/li/g, ulli); html html.replace(/\/li\/ululli/g, /lili); html html.replace(/\/liul/g, /li); // 鏈接轉換 html convertLinks(html); return html; }這段代碼里最容易出錯的地方是轉義順序。必須先對文本內容做escapeHtml再去解析 markdown 語法標記否則員工寫的script示例代碼會被瀏覽器當成真實標簽執(zhí)行。代碼塊內容尤其要小心我在函數里單獨維護了一個inCodeBlock狀態(tài)遇到代碼塊就原樣收集、整體轉義不做 markdown 語法解析這樣可以避免代碼里的#被誤解析成標題。如果你覺得自研解析器太粗糙生產環(huán)境中接一個成熟的開源 Markdown 解析庫完全合理。關鍵不是“自己寫”或“用庫”而是你要理解解析的基本原理這樣當渲染結果出現異常時你能快速判斷問題在解析器、轉義還是 CSS。3.4 目錄生成與閱讀進度長文章的閱讀體驗里目錄和進度提示是兩個加分項。目錄可以基于渲染后的標題生成在renderMarkdown返回的 HTML 里找出所有h2、h3提取文本和錨點然后渲染到側邊欄或文章頂部。錨點可以利用標題文本的哈希值實現不過更穩(wěn)妥的方式是在生成標題時寫入穩(wěn)定的 id。閱讀進度條實現起來也更簡單監(jiān)聽頁面滾動讀取當前的滾動位置和文檔總高度計算百分比后更新進度條寬度。代碼不超過二十行window.addEventListener(scroll, function() { const progressBar document.getElementById(readingProgress); if (!progressBar) return; const scrollTop window.scrollY; const docHeight document.documentElement.scrollHeight - window.innerHeight; const progress docHeight 0 ? Math.min(scrollTop / docHeight, 1) : 0; const percent Math.round(progress * 100); progressBar.style.width percent %; });進度條顏色用主題色漸變寬度變化加上transition閱讀時能帶來一點“我在推進”的儀式感。不過要注意監(jiān)聽滾動事件時沒必要在每次滾動回調里做復雜計算上面這種輕量更新完全夠用不需要引入節(jié)流函數。4. 代碼高亮與閱讀排版決定博客質感的分水嶺4.1 代碼高亮的接入時機技術類博客里代碼塊是絕對的主角。代碼高亮方案我選的是開源代碼高亮腳本語言包按需加載體積可控。接入時有一個關鍵順序必須在 markdown 渲染完成、HTML 已經插入頁面之后再調用高亮函數否則高亮腳本找不到需要處理的代碼塊。link relstylesheet hrefhttps://cdn.example.com/highlight/styles/default.min.css script srchttps://cdn.example.com/highlight/highlight.min.js/script script // 在頁面文章渲染完成后執(zhí)行 function highlightCode() { document.querySelectorAll(pre code).forEach(function(block) { hljs.highlightElement(block); }); } /script如果你的代碼高亮 CDN 訪問不穩(wěn)定也可以把高亮腳本下載到本地靜態(tài)資源目錄構建時一并輸出到dist。對于訪問量不大的個人博客我并不推薦把所有語言包都打進去按需加載你常用的幾種語言即可。如果博客里貼的都是 JavaScript、CSS 和 bash 片段沒必要為幾十種語言包多付出幾倍體積。高亮樣式要注意適配深色模式。很多高亮主題默認底色是白色一旦頁面切換深色主題代碼塊會變成一塊亮晃晃的白板。我自己用過一種做法是淺色模式用默認亮色主題深色模式覆蓋pre的background-color同時把文字亮度稍微壓低保證不刺眼。4.2 正文排版比寬窄更重要的是節(jié)奏代碼高亮解決的是“代碼好不好看”而正文排版決定整篇文章讀起來舒不舒服。我總結出的博客排版參數大致是這樣一組.post-content { max-width: 42rem; margin: 0 auto; font-size: 1.0625rem; line-height: 1.8; color: #2d3748; } .post-content h2 { font-size: 1.5rem; margin-top: 2rem; margin-bottom: 1rem; } .post-content h3 { font-size: 1.25rem; margin-top: 1.5rem; margin-bottom: 0.75rem; } .post-content p { margin-bottom: 1.25rem; } .post-content code { font-family: JetBrains Mono, Fira Code, Consolas, monospace; font-size: 0.9em; padding: 0.15em 0.4em; background: rgba(0, 0, 0, 0.06); border-radius: 4px; } .post-content pre code { display: block; padding: 1rem 1.25rem; overflow-x: auto; background: #1e1e2e; color: #cdd6f4; border-radius: 8px; }max-width: 42rem是我反復試出來的舒適閱讀寬度。太窄時每行字數太少眼睛來回跳動頻繁太寬時視線容易串行。行高 1.8 給文字留出足夠呼吸空間。正文里的行內代碼和獨立代碼塊要區(qū)分開行內代碼用小圓角淺色背景獨立代碼塊則用深色背景橫向滾動。4.3 深色模式不要搞顏色災難深色模式的實現不需要引入任何插件用 CSS 變量就能干凈地完成。定義一組語義變量通過>:root { --bg-color: #ffffff; --text-color: #2d3748; --card-bg: #f7fafc; --border-color: #e2e8f0; } [data-themedark] { --bg-color: #1a1b26; --text-color: #cbd5e1; --card-bg: #24283b; --border-color: #334155; } body { background: var(--bg-color); color: var(--text-color); }切換按鈕綁定一個點擊事件修改document.documentElement的>.container { width: 100%; max-width: 1200px; margin: 0 auto; padding: 0 1rem; } .main-content { display: grid; grid-template-columns: 1fr; gap: 2rem; } media (min-width: 768px) { .main-content { grid-template-columns: 1fr 260px; } } media (min-width: 1024px) { .main-content { grid-template-columns: 1fr 320px; } }網格布局讓側邊欄在窄屏自動掉到下方不需要額外調整 HTML 結構。側邊欄的內容通常是標簽云、最近文章列表、關于博主的一句話。移動端訪問時這些東西應該放在主內容之后避免讓讀者先看到一堆輔助信息再看到文章。5.2 移動端導航與觸摸體驗移動端最需要處理的是導航菜單。桌面端一行顯示的導航在手機上必須變成可以收起的抽屜菜單。我用一個按鈕切換菜單的展開狀態(tài)配合 CSS 類名控制顯隱button classmenu-toggle idmenuToggle aria-label打開導航菜單 span/spanspan/spanspan/span /button nav classmain-nav idmainNav ul lia href#/首頁/a/li lia href#/about關于/a/li lia href#/archive歸檔/a/li /ul /nav.main-nav { display: none; } .main-nav.open { display: block; } media (min-width: 768px) { .main-nav { display: block; } .menu-toggle { display: none; } }document.getElementById(menuToggle).addEventListener(click, function() { const nav document.getElementById(mainNav); nav.classList.toggle(open); });移動端還有一個移動端特有的坑min-height: 100vh在部分移動瀏覽器上會把地址欄算進去導致頁面底部被遮擋或滾動異常。我的處理方式是優(yōu)先使用min-height: 100dvh同時保留100vh作為不支持dvh單位時的回退值。另外導航按鈕和文章卡片里的點擊目標都盡量做到至少 44 像素見方這是手指點擊舒適度的最低要求。5.3 圖片和表格別讓頁面橫向滾動文章里插入圖片是常見需求響應式布局下圖片要能隨容器寬度縮放不能撐破父容器.post-content img { max-width: 100%; height: auto; display: block; margin: 1.5rem auto; }如果文章里有表格寬表格會泡到容器外面導致整個頁面出現橫向滾動條這個問題在手機上尤其明顯。一個簡單的處理是把表格包進可橫向滾動的容器或者給table設置display: block; overflow-x: auto保證頁面主體不橫向滾動用戶只在表格區(qū)域內滑動。6. 構建與部署把博客前端變成線上項目6.1 本地構建腳本自動生成文章數據當博客多了用手維護data.js不現實。我在scripts/build.js里做了一個小工具遍歷posts/目錄下所有 md 文件解析出標題、日期、標簽和正文輸出成前端使用的js/data.js和js/posts.js。const fs require(fs); const path require(path); const postsDir path.join(__dirname, ../posts); const outputDir path.join(__dirname, ../dist); function parseFrontMatter(content) { const match content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/); if (!match) return { meta: {}, body: content }; const meta {}; match[1].split(\n).forEach(function(line) { const idx line.indexOf(:); if (idx -1) { meta[line.slice(0, idx).trim()] line.slice(idx 1).trim(); } }); return { meta, body: match[2] }; } const articles []; const files fs.readdirSync(postsDir).filter(function(file) { return file.endsWith(.md); }); files.forEach(function(file) { const content fs.readFileSync(path.join(postsDir, file), utf8); const { meta, body } parseFrontMatter(content); articles.push({ id: file.replace(/\.md$/, ), title: meta.title || 未命名文章, date: meta.date || 2025-01-01, excerpt: meta.excerpt || body.slice(0, 200), tags: meta.tags ? meta.tags.split(,).map(function(s) { return s.trim(); }) : [], content: body }); }); const dataJs window.ARTICLES JSON.stringify(articles, null, 2) ;; fs.writeFileSync(path.join(outputDir, data.js), dataJs, utf8); console.log(構建完成共處理 articles.length 篇文章);文章頭部用 YAML 格式維護元信息構建腳本讀取時做一次解析。這樣新文章只需要新建一個 md 文件在文件最頂部寫上標題、日期、標簽運行構建腳本就能刷新整個站點數據。6.2 部署到靜態(tài)托管的注意事項構建產物就是dist/下的靜態(tài)文件一個 HTML、幾個 CSS、幾個 JS以及圖片資源。部署到任何靜態(tài)托管平臺都很簡單本質是把文件夾上傳上去。部署時我踩過一個看起來不大但很影響體驗的坑資源路徑必須使用相對路徑或與部署路徑完全匹配的絕對路徑。如果博客部署在域名子路徑下比如example.com/blog/而 HTML 里寫成link relstylesheet href/css/home.css那瀏覽器會去域名根目錄找資源大概率 404。用./css/home.css這類相對路徑能規(guī)避這個問題但要注意 hash 路由切換頁面后相對路徑依然基于 HTML 文件位置解析所以靜態(tài)資源相對路徑在 hash 模式里不會出問題。自定義域名和 HTTPS 證書這類設置不同平臺有不同操作入口但思路一致把 DNS 解析指向托管平臺提供的目標地址然后在平臺側完成域名綁定和證書配置。證書配置一般只要點開“啟用 HTTPS”按鈕剩下由平臺處理。6.3 還可以繼續(xù)完善的方向基礎版博客上線之后有幾個高性價比功能值得繼續(xù)加文章頁獨立設置document.title避免所有頁面都是同一個站點名文章列表加loadinglazy實現圖片懶加載做一個簡單的站內搜索用關鍵詞在文章標題和摘要里做匹配標簽歸檔頁點擊標簽篩選出相關文章生成按日期的歸檔索引這些不會改變博客系統(tǒng)的整體架構都是在現有數據結構上追加渲染邏輯。內容型站點的優(yōu)勢就在這里——核心功能保持穩(wěn)定外圍功能按需疊加不會因為一個小功能就推翻重建。整套博客前端實現寫下來我最想對后來者說的是博客系統(tǒng)的前端沒有想象中那么復雜真正需要用心的地方是內容組織、閱讀體驗和長期可維護性。不要被“全?！薄肮こ袒边@些詞嚇住原生三件套先把最小的閉環(huán)跑通后續(xù)有需要再優(yōu)化再擴展。最后分享兩個實操小技巧。一是渲染列表時永遠先拼字符串再一次插入 DOM我在第 2 節(jié)已經反復強調過這在高頻切換視圖時能明顯降低卡頓二是每次構建前先清空dist/再寫入新產物否則刪除的文章會殘留在舊文件中導致線上出現失效鏈接。嘗試把文章從一個平臺搬到這套系統(tǒng)中時你會直觀感受到純靜態(tài)方案在遷移自由度上的好處。按這套流程走一遍屬于你自己的博客前端很快就能跑起來。