想从零搭一套个人博客系统最容易出现的情况不是在写代码而是在选型上反复横跳——今天看框架明天看内容管理系统后天又想直接套模板。我前前后后给多个朋友做过类似的博客前端最后留在我个人项目里的是一套没有任何框架依赖的实现HTML、CSS、JavaScript 三件套加一个几十行的构建脚本就能完成从文章列表到详情页、代码高亮、响应式适配、静态部署的全部流程。这篇文章我会把整套前端实现的完整代码和思路拆开讲清楚适合刚接触博客搭建、想理解博客系统前端到底是怎么工作的人也适合有前端基础但不希望被框架束缚的朋友直接参考复现。1. 动手之前先把博客前端的需求拆清楚1.1 为什么我放弃了前端框架个人博客系统的前端本质上就三件事管理文章入口、展示文章列表、渲染文章正文。附带一些标签、归档、关于页这类补充页面。它没有复杂的用户交互不需要数据双向绑定不需要服务端渲染来支撑高并发绝大多数时候就是一个人写、一群人读。为这个场景引入前端框架换来的往往是几百 MB 的 node_modules、看不懂的抽象层和升级依赖时的不确定感。我用表格整理过原生方案和框架方案的差异放在这里供参考对比维度原生三件套前端框架方案初始门槛浏览器直接运行无需构建需要熟悉工程化工具链运行依赖几乎为零必须引入框架运行时代码体积可控按需编写即使摇树优化也有基础体积长期维护几年后打开仍能修改依赖升级频繁可能出现兼容问题适用场景内容型网站、小型工具复杂交互应用、后台系统、大型协作项目并不是说框架不好而是要看场景是否匹配。博客系统作为一个以内容为核心的站点用户真正关心的是文章能不能快速打开、排版是否舒服、在手机上阅读是否流畅。这些目标用原生三件套完全可以达成。如果你后续计划加入很复杂的编辑器、实时协作评论、复杂标签筛选系统那再引入框架也不迟一开始就上框架反而妨碍你把精力放在内容与阅读体验上。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 文件方案。我在项目开发初期也是这么做的先跑通再优化避免过度设计。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结果通过无障碍检测时被扣了分后来才改回语义化结构。导航里的链接统一用href#/这种形式配合后面的 hash 路由使用。这样做的好处是任何静态托管平台都不需要额外配置服务器回退规则用户刷新页面不会出现 404。2.2 文章列表的数据结构文章列表页面核心是一组元信息标题、发布时间、摘要、标签、唯一标识。我在js/data.js里用一个数组保存结构像这样window.ARTICLES [ { id: how-to-build-blog, title: 从零搭建个人博客系统的前端实现, date: 2025-01-18, excerpt: 本文记录了一套不依赖框架的前端实现方案内容包括路由、渲染、代码高亮与响应式适配。, tags: [前端, 博客, 教程], cover: }, { id: markdown-renderer-basics, title: 自己写一个够用的 Markdown 渲染器, date: 2025-01-05, excerpt: 很多人第一时间会去引入现成的解析库但理解分块解析的原理能让问题定位更容易。, tags: [Markdown, 原理] } ];id字段是文章的稳定标识不能使用数组下标。因为后续你可能会删除、排序或筛选文章一旦下标变化浏览器里的历史链接就失效了。我一开始也偷懒用0、1、2当下标后来删了两篇文章收藏夹里的旧链接全部指向错位内容才老老实实给每篇文章起了独立的字符串 id。摘要字段excerpt是从正文开头手动提取的。配合标题渲染列表卡片时摘要可以让列表页有呼吸感也能让访客在点击前判断文章是否值得读。如果你希望减少维护成本也可以在构建脚本里自动截取正文前 200 个字符作为摘要。2.3 列表渲染一次性插入而非循环拼接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)是每次切换页面后自动回到顶部这个细节不做的话从长文章底部点回首页浏览器会停留在原来的滚动位置观感非常差。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示例代码会被浏览器当成真实标签执行。代码块内容尤其要小心我在函数里单独维护了一个inCodeBlock状态遇到代码块就原样收集、整体转义不做 markdown 语法解析这样可以避免代码里的#被误解析成标题。如果你觉得自研解析器太粗糙生产环境中接一个成熟的开源 Markdown 解析库完全合理。关键不是“自己写”或“用库”而是你要理解解析的基本原理这样当渲染结果出现异常时你能快速判断问题在解析器、转义还是 CSS。3.4 目录生成与阅读进度长文章的阅读体验里目录和进度提示是两个加分项。目录可以基于渲染后的标题生成在renderMarkdown返回的 HTML 里找出所有h2、h3提取文本和锚点然后渲染到侧边栏或文章顶部。锚点可以利用标题文本的哈希值实现不过更稳妥的方式是在生成标题时写入稳定的 id。阅读进度条实现起来也更简单监听页面滚动读取当前的滚动位置和文档总高度计算百分比后更新进度条宽度。代码不超过二十行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阅读时能带来一点“我在推进”的仪式感。不过要注意监听滚动事件时没必要在每次滚动回调里做复杂计算上面这种轻量更新完全够用不需要引入节流函数。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 // 在页面文章渲染完成后执行 function highlightCode() { document.querySelectorAll(pre code).forEach(function(block) { hljs.highlightElement(block); }); } /script如果你的代码高亮 CDN 访问不稳定也可以把高亮脚本下载到本地静态资源目录构建时一并输出到dist。对于访问量不大的个人博客我并不推荐把所有语言包都打进去按需加载你常用的几种语言即可。如果博客里贴的都是 JavaScript、CSS 和 bash 片段没必要为几十种语言包多付出几倍体积。高亮样式要注意适配深色模式。很多高亮主题默认底色是白色一旦页面切换深色主题代码块会变成一块亮晃晃的白板。我自己用过一种做法是浅色模式用默认亮色主题深色模式覆盖pre的background-color同时把文字亮度稍微压低保证不刺眼。4.2 正文排版比宽窄更重要的是节奏代码高亮解决的是“代码好不好看”而正文排版决定整篇文章读起来舒不舒服。我总结出的博客排版参数大致是这样一组.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 给文字留出足够呼吸空间。正文里的行内代码和独立代码块要区分开行内代码用小圆角浅色背景独立代码块则用深色背景横向滚动。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 移动端导航与触摸体验移动端最需要处理的是导航菜单。桌面端一行显示的导航在手机上必须变成可以收起的抽屉菜单。我用一个按钮切换菜单的展开状态配合 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在部分移动浏览器上会把地址栏算进去导致页面底部被遮挡或滚动异常。我的处理方式是优先使用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保证页面主体不横向滚动用户只在表格区域内滑动。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 部署到静态托管的注意事项构建产物就是dist/下的静态文件一个 HTML、几个 CSS、几个 JS以及图片资源。部署到任何静态托管平台都很简单本质是把文件夹上传上去。部署时我踩过一个看起来不大但很影响体验的坑资源路径必须使用相对路径或与部署路径完全匹配的绝对路径。如果博客部署在域名子路径下比如example.com/blog/而 HTML 里写成link relstylesheet href/css/home.css那浏览器会去域名根目录找资源大概率 404。用./css/home.css这类相对路径能规避这个问题但要注意 hash 路由切换页面后相对路径依然基于 HTML 文件位置解析所以静态资源相对路径在 hash 模式里不会出问题。自定义域名和 HTTPS 证书这类设置不同平台有不同操作入口但思路一致把 DNS 解析指向托管平台提供的目标地址然后在平台侧完成域名绑定和证书配置。证书配置一般只要点开“启用 HTTPS”按钮剩下由平台处理。6.3 还可以继续完善的方向基础版博客上线之后有几个高性价比功能值得继续加文章页独立设置document.title避免所有页面都是同一个站点名文章列表加loadinglazy实现图片懒加载做一个简单的站内搜索用关键词在文章标题和摘要里做匹配标签归档页点击标签筛选出相关文章生成按日期的归档索引这些不会改变博客系统的整体架构都是在现有数据结构上追加渲染逻辑。内容型站点的优势就在这里——核心功能保持稳定外围功能按需叠加不会因为一个小功能就推翻重建。整套博客前端实现写下来我最想对后来者说的是博客系统的前端没有想象中那么复杂真正需要用心的地方是内容组织、阅读体验和长期可维护性。不要被“全栈”“工程化”这些词吓住原生三件套先把最小的闭环跑通后续有需要再优化再扩展。最后分享两个实操小技巧。一是渲染列表时永远先拼字符串再一次插入 DOM我在第 2 节已经反复强调过这在高频切换视图时能明显降低卡顿二是每次构建前先清空dist/再写入新产物否则删除的文章会残留在旧文件中导致线上出现失效链接。尝试把文章从一个平台搬到这套系统中时你会直观感受到纯静态方案在迁移自由度上的好处。按这套流程走一遍属于你自己的博客前端很快就能跑起来。