想從零搭一套個人博客系統(tǒng)最容易出現(xiàn)的情況不是在寫代碼而是在選型上反復(fù)橫跳——今天看框架明天看內(nèi)容管理系統(tǒng)后天又想直接套模板。我前前后后給多個朋友做過類似的博客前端最后留在我個人項目里的是一套沒有任何框架依賴的實現(xiàn)HTML、CSS、JavaScript 三件套加一個幾十行的構(gòu)建腳本就能完成從文章列表到詳情頁、代碼高亮、響應(yīng)式適配、靜態(tài)部署的全部流程。這篇文章我會把整套前端實現(xiàn)的完整代碼和思路拆開講清楚適合剛接觸博客搭建、想理解博客系統(tǒng)前端到底是怎么工作的人也適合有前端基礎(chǔ)但不希望被框架束縛的朋友直接參考復(fù)現(xiàn)。1. 動手之前先把博客前端的需求拆清楚1.1 為什么我放棄了前端框架個人博客系統(tǒng)的前端本質(zhì)上就三件事管理文章入口、展示文章列表、渲染文章正文。附帶一些標(biāo)簽、歸檔、關(guān)于頁這類補(bǔ)充頁面。它沒有復(fù)雜的用戶交互不需要數(shù)據(jù)雙向綁定不需要服務(wù)端渲染來支撐高并發(fā)絕大多數(shù)時候就是一個人寫、一群人讀。為這個場景引入前端框架換來的往往是幾百 MB 的 node_modules、看不懂的抽象層和升級依賴時的不確定感。我用表格整理過原生方案和框架方案的差異放在這里供參考對比維度原生三件套前端框架方案初始門檻瀏覽器直接運行無需構(gòu)建需要熟悉工程化工具鏈運行依賴幾乎為零必須引入框架運行時代碼體積可控按需編寫即使搖樹優(yōu)化也有基礎(chǔ)體積長期維護(hù)幾年后打開仍能修改依賴升級頻繁可能出現(xiàn)兼容問題適用場景內(nèi)容型網(wǎng)站、小型工具復(fù)雜交互應(yīng)用、后臺系統(tǒng)、大型協(xié)作項目并不是說框架不好而是要看場景是否匹配。博客系統(tǒng)作為一個以內(nèi)容為核心的站點用戶真正關(guān)心的是文章能不能快速打開、排版是否舒服、在手機(jī)上閱讀是否流暢。這些目標(biāo)用原生三件套完全可以達(dá)成。如果你后續(xù)計劃加入很復(fù)雜的編輯器、實時協(xié)作評論、復(fù)雜標(biāo)簽篩選系統(tǒng)那再引入框架也不遲一開始就上框架反而妨礙你把精力放在內(nèi)容與閱讀體驗上。1.2 目錄設(shè)計把數(shù)據(jù)和展示分開從零動手之前先把目錄想清楚。好的目錄結(jié)構(gòu)應(yīng)該一眼能看出什么東西放哪里。我目前維護(hù)的這套博客前端使用下面的結(jié)構(gòu)blog-front/ index.html # 首頁入口 css/ base.css # 全局樣式、變量、排版基礎(chǔ) home.css # 首頁文章列表樣式 post.css # 文章詳情頁樣式 js/ data.js # 文章元信息數(shù)據(jù)構(gòu)建時生成 markdown.js # 輕量 markdown 渲染函數(shù) router.js # hash 路由 home.js # 首頁渲染邏輯 post.js # 詳情頁渲染邏輯 posts/ # 原始文章目錄每篇一個 md 文件 hello-world.md ... scripts/ build.js # 構(gòu)建腳本把 md 轉(zhuǎn)成前端要用的數(shù)據(jù) dist/ # 構(gòu)建產(chǎn)物最終部署這個目錄這個結(jié)構(gòu)的關(guān)鍵點是數(shù)據(jù)和展示分離。文章正文以 markdown 文件放在posts/里構(gòu)建腳本負(fù)責(zé)把 md 轉(zhuǎn)成文章數(shù)據(jù)最終給前端的是一個干凈的 JSON 或 JS 模塊。寫新文章的人只需要關(guān)心posts/里的文件完全不需要碰前端邏輯。如果你暫時不想引入構(gòu)建腳本也可以直接把文章數(shù)據(jù)寫在js/data.js里等文章多到管理不過來再遷移到 md 文件方案。我在項目開發(fā)初期也是這么做的先跑通再優(yōu)化避免過度設(shè)計。2. 首頁骨架與文章列表先把內(nèi)容鋪出來2.1 語義化布局首頁的骨架結(jié)構(gòu)博客首頁的職責(zé)不是炫技而是讓訪客快速看到最新文章列表。我用的 HTML 骨架很簡單但每一個標(biāo)簽都是有意圖的!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關(guān)于/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由我手工維護(hù)文章內(nèi)容采用知識共享方式分享。/p /div /footer script srcjs/data.js/script script srcjs/router.js/script script srcjs/home.js/script /body /html語義化標(biāo)簽不是寫給別人看的裝飾。header、main、section、footer這些標(biāo)簽?zāi)軒椭聊婚喿x器正確識別頁面結(jié)構(gòu)也有利于搜索引擎理解內(nèi)容層級。我在早期重構(gòu)時曾把這些全換成div結(jié)果通過無障礙檢測時被扣了分后來才改回語義化結(jié)構(gòu)。導(dǎo)航里的鏈接統(tǒng)一用href#/這種形式配合后面的 hash 路由使用。這樣做的好處是任何靜態(tài)托管平臺都不需要額外配置服務(wù)器回退規(guī)則用戶刷新頁面不會出現(xiàn) 404。2.2 文章列表的數(shù)據(jù)結(jié)構(gòu)文章列表頁面核心是一組元信息標(biāo)題、發(fā)布時間、摘要、標(biāo)簽、唯一標(biāo)識。我在js/data.js里用一個數(shù)組保存結(jié)構(gòu)像這樣window.ARTICLES [ { id: how-to-build-blog, title: 從零搭建個人博客系統(tǒng)的前端實現(xiàn), date: 2025-01-18, excerpt: 本文記錄了一套不依賴框架的前端實現(xiàn)方案內(nèi)容包括路由、渲染、代碼高亮與響應(yīng)式適配。, tags: [前端, 博客, 教程], cover: }, { id: markdown-renderer-basics, title: 自己寫一個夠用的 Markdown 渲染器, date: 2025-01-05, excerpt: 很多人第一時間會去引入現(xiàn)成的解析庫但理解分塊解析的原理能讓問題定位更容易。, tags: [Markdown, 原理] } ];id字段是文章的穩(wěn)定標(biāo)識不能使用數(shù)組下標(biāo)。因為后續(xù)你可能會刪除、排序或篩選文章一旦下標(biāo)變化瀏覽器里的歷史鏈接就失效了。我一開始也偷懶用0、1、2當(dāng)下標(biāo)后來刪了兩篇文章收藏夾里的舊鏈接全部指向錯位內(nèi)容才老老實實給每篇文章起了獨立的字符串 id。摘要字段excerpt是從正文開頭手動提取的。配合標(biāo)題渲染列表卡片時摘要可以讓列表頁有呼吸感也能讓訪客在點擊前判斷文章是否值得讀。如果你希望減少維護(hù)成本也可以在構(gòu)建腳本里自動截取正文前 200 個字符作為摘要。2.3 列表渲染一次性插入而非循環(huán)拼接home.js里面做的事情是把ARTICLES數(shù)組渲染成 DOM 結(jié)構(gòu)。這里有一個非常重要的性能習(xí)慣不要每遍歷一條數(shù)據(jù)就操作一次 DOM。頻繁操作 DOM 會引起瀏覽器重排重繪文章數(shù)量少時感覺不明顯上到上百篇就會明顯卡頓。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根據(jù)路由名稱調(diào)動對應(yīng)的渲染函數(shù)。scrollTo(0, 0)是每次切換頁面后自動回到頂部這個細(xì)節(jié)不做的話從長文章底部點回首頁瀏覽器會停留在原來的滾動位置觀感非常差。3.3 Markdown 渲染先轉(zhuǎn)義再解析詳情頁最核心的工作是把 markdown 轉(zhuǎn)成 HTML。很多人第一反應(yīng)就是引入大而全的解析庫但博客場景里其實只需要處理標(biāo)題、段落、列表、引用、代碼塊和加粗斜體這些常見語法。我自己維護(hù)了一個輕量渲染器核心思路是逐行掃描并按塊處理。下面是我在項目里使用的簡化版本省略了嵌套列表等邊界情況但足夠覆蓋日常寫作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 包裹進(jìn) ul html html.replace(/li/g, ulli); html html.replace(/\/li\/ululli/g, /lili); html html.replace(/\/liul/g, /li); // 鏈接轉(zhuǎn)換 html convertLinks(html); return html; }這段代碼里最容易出錯的地方是轉(zhuǎn)義順序。必須先對文本內(nèi)容做escapeHtml再去解析 markdown 語法標(biāo)記否則員工寫的script示例代碼會被瀏覽器當(dāng)成真實標(biāo)簽執(zhí)行。代碼塊內(nèi)容尤其要小心我在函數(shù)里單獨維護(hù)了一個inCodeBlock狀態(tài)遇到代碼塊就原樣收集、整體轉(zhuǎn)義不做 markdown 語法解析這樣可以避免代碼里的#被誤解析成標(biāo)題。如果你覺得自研解析器太粗糙生產(chǎn)環(huán)境中接一個成熟的開源 Markdown 解析庫完全合理。關(guān)鍵不是“自己寫”或“用庫”而是你要理解解析的基本原理這樣當(dāng)渲染結(jié)果出現(xiàn)異常時你能快速判斷問題在解析器、轉(zhuǎn)義還是 CSS。3.4 目錄生成與閱讀進(jìn)度長文章的閱讀體驗里目錄和進(jìn)度提示是兩個加分項。目錄可以基于渲染后的標(biāo)題生成在renderMarkdown返回的 HTML 里找出所有h2、h3提取文本和錨點然后渲染到側(cè)邊欄或文章頂部。錨點可以利用標(biāo)題文本的哈希值實現(xiàn)不過更穩(wěn)妥的方式是在生成標(biāo)題時寫入穩(wěn)定的 id。閱讀進(jìn)度條實現(xiàn)起來也更簡單監(jiān)聽頁面滾動讀取當(dāng)前的滾動位置和文檔總高度計算百分比后更新進(jì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 %; });進(jìn)度條顏色用主題色漸變寬度變化加上transition閱讀時能帶來一點“我在推進(jìn)”的儀式感。不過要注意監(jiān)聽滾動事件時沒必要在每次滾動回調(diào)里做復(fù)雜計算上面這種輕量更新完全夠用不需要引入節(jié)流函數(shù)。4. 代碼高亮與閱讀排版決定博客質(zhì)感的分水嶺4.1 代碼高亮的接入時機(jī)技術(shù)類博客里代碼塊是絕對的主角。代碼高亮方案我選的是開源代碼高亮腳本語言包按需加載體積可控。接入時有一個關(guān)鍵順序必須在 markdown 渲染完成、HTML 已經(jīng)插入頁面之后再調(diào)用高亮函數(shù)否則高亮腳本找不到需要處理的代碼塊。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)資源目錄構(gòu)建時一并輸出到dist。對于訪問量不大的個人博客我并不推薦把所有語言包都打進(jìn)去按需加載你常用的幾種語言即可。如果博客里貼的都是 JavaScript、CSS 和 bash 片段沒必要為幾十種語言包多付出幾倍體積。高亮樣式要注意適配深色模式。很多高亮主題默認(rèn)底色是白色一旦頁面切換深色主題代碼塊會變成一塊亮晃晃的白板。我自己用過一種做法是淺色模式用默認(rèn)亮色主題深色模式覆蓋pre的background-color同時把文字亮度稍微壓低保證不刺眼。4.2 正文排版比寬窄更重要的是節(jié)奏代碼高亮解決的是“代碼好不好看”而正文排版決定整篇文章讀起來舒不舒服。我總結(jié)出的博客排版參數(shù)大致是這樣一組.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是我反復(fù)試出來的舒適閱讀寬度。太窄時每行字?jǐn)?shù)太少眼睛來回跳動頻繁太寬時視線容易串行。行高 1.8 給文字留出足夠呼吸空間。正文里的行內(nèi)代碼和獨立代碼塊要區(qū)分開行內(nèi)代碼用小圓角淺色背景獨立代碼塊則用深色背景橫向滾動。4.3 深色模式不要搞顏色災(zāi)難深色模式的實現(xiàn)不需要引入任何插件用 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; } }網(wǎng)格布局讓側(cè)邊欄在窄屏自動掉到下方不需要額外調(diào)整 HTML 結(jié)構(gòu)。側(cè)邊欄的內(nèi)容通常是標(biāo)簽云、最近文章列表、關(guān)于博主的一句話。移動端訪問時這些東西應(yīng)該放在主內(nèi)容之后避免讓讀者先看到一堆輔助信息再看到文章。5.2 移動端導(dǎo)航與觸摸體驗移動端最需要處理的是導(dǎo)航菜單。桌面端一行顯示的導(dǎo)航在手機(jī)上必須變成可以收起的抽屜菜單。我用一個按鈕切換菜單的展開狀態(tài)配合 CSS 類名控制顯隱button classmenu-toggle idmenuToggle aria-label打開導(dǎo)航菜單 span/spanspan/spanspan/span /button nav classmain-nav idmainNav ul lia href#/首頁/a/li lia href#/about關(guān)于/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在部分移動瀏覽器上會把地址欄算進(jìn)去導(dǎo)致頁面底部被遮擋或滾動異常。我的處理方式是優(yōu)先使用min-height: 100dvh同時保留100vh作為不支持dvh單位時的回退值。另外導(dǎo)航按鈕和文章卡片里的點擊目標(biāo)都盡量做到至少 44 像素見方這是手指點擊舒適度的最低要求。5.3 圖片和表格別讓頁面橫向滾動文章里插入圖片是常見需求響應(yīng)式布局下圖片要能隨容器寬度縮放不能撐破父容器.post-content img { max-width: 100%; height: auto; display: block; margin: 1.5rem auto; }如果文章里有表格寬表格會泡到容器外面導(dǎo)致整個頁面出現(xiàn)橫向滾動條這個問題在手機(jī)上尤其明顯。一個簡單的處理是把表格包進(jìn)可橫向滾動的容器或者給table設(shè)置display: block; overflow-x: auto保證頁面主體不橫向滾動用戶只在表格區(qū)域內(nèi)滑動。6. 構(gòu)建與部署把博客前端變成線上項目6.1 本地構(gòu)建腳本自動生成文章數(shù)據(jù)當(dāng)博客多了用手維護(hù)data.js不現(xiàn)實。我在scripts/build.js里做了一個小工具遍歷posts/目錄下所有 md 文件解析出標(biāo)題、日期、標(biāo)簽和正文輸出成前端使用的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(構(gòu)建完成共處理 articles.length 篇文章);文章頭部用 YAML 格式維護(hù)元信息構(gòu)建腳本讀取時做一次解析。這樣新文章只需要新建一個 md 文件在文件最頂部寫上標(biāo)題、日期、標(biāo)簽運行構(gòu)建腳本就能刷新整個站點數(shù)據(jù)。6.2 部署到靜態(tài)托管的注意事項構(gòu)建產(chǎn)物就是dist/下的靜態(tài)文件一個 HTML、幾個 CSS、幾個 JS以及圖片資源。部署到任何靜態(tài)托管平臺都很簡單本質(zhì)是把文件夾上傳上去。部署時我踩過一個看起來不大但很影響體驗的坑資源路徑必須使用相對路徑或與部署路徑完全匹配的絕對路徑。如果博客部署在域名子路徑下比如example.com/blog/而 HTML 里寫成link relstylesheet href/css/home.css那瀏覽器會去域名根目錄找資源大概率 404。用./css/home.css這類相對路徑能規(guī)避這個問題但要注意 hash 路由切換頁面后相對路徑依然基于 HTML 文件位置解析所以靜態(tài)資源相對路徑在 hash 模式里不會出問題。自定義域名和 HTTPS 證書這類設(shè)置不同平臺有不同操作入口但思路一致把 DNS 解析指向托管平臺提供的目標(biāo)地址然后在平臺側(cè)完成域名綁定和證書配置。證書配置一般只要點開“啟用 HTTPS”按鈕剩下由平臺處理。6.3 還可以繼續(xù)完善的方向基礎(chǔ)版博客上線之后有幾個高性價比功能值得繼續(xù)加文章頁獨立設(shè)置document.title避免所有頁面都是同一個站點名文章列表加loadinglazy實現(xiàn)圖片懶加載做一個簡單的站內(nèi)搜索用關(guān)鍵詞在文章標(biāo)題和摘要里做匹配標(biāo)簽歸檔頁點擊標(biāo)簽篩選出相關(guān)文章生成按日期的歸檔索引這些不會改變博客系統(tǒng)的整體架構(gòu)都是在現(xiàn)有數(shù)據(jù)結(jié)構(gòu)上追加渲染邏輯。內(nèi)容型站點的優(yōu)勢就在這里——核心功能保持穩(wěn)定外圍功能按需疊加不會因為一個小功能就推翻重建。整套博客前端實現(xiàn)寫下來我最想對后來者說的是博客系統(tǒng)的前端沒有想象中那么復(fù)雜真正需要用心的地方是內(nèi)容組織、閱讀體驗和長期可維護(hù)性。不要被“全棧”“工程化”這些詞嚇住原生三件套先把最小的閉環(huán)跑通后續(xù)有需要再優(yōu)化再擴(kuò)展。最后分享兩個實操小技巧。一是渲染列表時永遠(yuǎn)先拼字符串再一次插入 DOM我在第 2 節(jié)已經(jīng)反復(fù)強(qiáng)調(diào)過這在高頻切換視圖時能明顯降低卡頓二是每次構(gòu)建前先清空dist/再寫入新產(chǎn)物否則刪除的文章會殘留在舊文件中導(dǎo)致線上出現(xiàn)失效鏈接。嘗試把文章從一個平臺搬到這套系統(tǒng)中時你會直觀感受到純靜態(tài)方案在遷移自由度上的好處。按這套流程走一遍屬于你自己的博客前端很快就能跑起來。