先说一个我观察到的现象大部分人的技术博客死在第 7 天而不是死在第 700 天。搭建本身只花了两个晚上第三次更新之后就再也没有打开过那个仓库。原因通常不是懒而是搭建阶段做了一堆当时觉得很专业、事后全变成阻力的决定——主题改了三遍、评论系统接了两套、部署流程要手动传文件、想改个标题得翻五个配置文件。这篇文章聊的是从零搭建技术博客的完整链路但重点不在于给你一套抄完就完的配置而是把每个环节的选择逻辑摊开域名和托管怎么配、静态站点生成器怎么选、内容目录怎么组织、性能与收录要做哪几件真正有用的事、上线之后怎么不被依赖升级拖死。适合已经写过几篇笔记、准备把东西正式放出去的人也适合已经搭好但一直没更新的朋友对照着检查一下自己卡在哪一步。1. 动手前先想清楚技术博客到底写给谁看我见过太多人把顺序搞反了先花两周调主题配色写到第一篇正文时忽然发现自己不知道该用什么语气说话。定位这件事听起来虚但它实实在在决定了后面所有技术选型——要不要评论、要不要多语言、要不要统计、目录结构按年份还是按主题全都从这里推导。1.1 三种定位对技术栈的真实影响技术博客大致分三类各自的诉求差别很大。个人知识库型主要读者是三个月后的自己。这类站点对样式几乎没要求但对检索要求极高——全站搜索、标签聚合、按时间倒序归档必须有。你可能还会有大量半成品笔记所以草稿机制和不发布但也不删除的状态要设计好。这类站点我建议直接上最轻的方案构建越快越好因为你会频繁本地预览。作品展示型读者是面试官、合作方、潜在客户。这类站点对首屏观感和页面质量要求高文章数量反而不重要五篇写得扎实的深度文章顶过五十篇周记。它需要的是精心设计的首页、清晰的项目说明页、稳定的访问速度以及一个不会突然挂掉的域名。评论系统在这类站点上基本是负资产噪音大于价值。话题输出型面向社区持续输出靠订阅和搜索流量获得反馈。这类才真正需要 RSS、站点地图、结构化数据、社交卡片、访问统计这一整套东西也最需要关注收录情况。如果你属于这一类第 5 章的内容要认真看。先把这三类分清楚再去看工具对比表你会发现很多功能其实跟你无关。我见过有人给一个纯知识库站点接了三种评论插件最后因为垃圾评论太多全删了白折腾。1.2 用三个月后还在更吗做一次冷静自检判断自己属于哪一类有个很土但很准的方法问自己三个月后这个站还在更新吗。如果答案是应该会那你可以放心投入时间做完整的基建如果答案是看情况那就把搭建时间压到 4 小时以内剩下的精力全留给写第一篇。这里有个经验值从想法到发布一篇新文章的操作步骤超过 5 步断更概率会显著上升。理想状态是在编辑器里写完 Markdown保存执行一条提交命令剩下的交给自动化。任何需要你打开浏览器登录后台、复制粘贴、手动上传文件的环节都是未来的断更理由。顺带说一句别急着买域名。先用托管平台给的免费二级域名把站点跑起来写满五篇再决定要不要绑定自己的域名。域名一年几十块不贵但绑定域名之后你会开始在意这站得拿得出手然后陷入无限期的主题打磨第一篇文章永远发不出去。2. 静态站点生成器怎么选把需求翻译成选型清单技术博客九成以上是静态站点原因是它没有数据库、没有运行时、每次访问都是读文件速度快、成本低、几乎不会挂。剩下的问题就是用哪个工具把 Markdown 变成 HTML。2.1 从写作习惯倒推工具链选型别从哪个最火开始从你的写作习惯倒推。我列几个真正影响长期体验的问题你可以逐条对照你主要在本地编辑器写还是希望有个网页后台如果坚持本地写纯静态生成器完全够用如果希望随时在手机或别的电脑上写那要考虑内容仓库和构建流程能不能在浏览器里完成。文章里会不会有数学公式、流程图、交互式组件数学公式需要渲染器支持交互组件意味着你要么用支持组件化的框架要么接受用内嵌页面绕过去。预计文章规模是多少五十篇和一千篇是两个世界。纯静态生成器生成一千篇通常在几十秒量级但如果每篇文章都带图片处理压缩、生成多尺寸缩略图构建时间会成倍增长这时候增量构建能力就很关键。有没有人跟你一起写多人协作时模板语法的学习成本和代码评审的友好度就变得重要。把这四个问题答完备选方案通常就只剩一两个了。剩下的差异都是个人偏好选哪个都不会错。2.2 四类常见方案的横向对照按实现语言和设计思路市面上主流方案可以归成四类。我用功能描述代替具体名称你对照特性就能认出它们分别是谁。类型构建速度模板学习曲线插件生态增量构建适合人群编译型生成器Go 系极快千篇级别常在一秒内中等模板语法自成一套中等支持文章多、追求构建速度脚本型生成器Node 系中等百篇级别几秒到几十秒低接近普通模板语法丰富部分支持想快速上手、插件控组件框架型现代前端框架驱动偏慢但可做增量较高需要懂组件化思维很丰富支持良好前端背景、想深度定制文档型生成器快极低偏少支持只想要干净排版、不想折腾几个补充说明这些是表格里塞不下的构建速度的实际影响比想象中大。我做过一个对比同一批约 400 篇带代码块的文章编译型生成器全量构建 1.2 秒左右脚本型大约 12 秒组件框架型冷启动接近 40 秒。单看数字都还能忍但本地写作时你每改一个标点就要等一次热更新40 秒的反馈延迟会实打实地磨掉写作欲望。如果你有前端背景并且确实需要组件化能力那值得如果只是想写文章别为了技术栈先进支付这个成本。插件生态是一把双刃剑。插件多的方案上手快但插件质量参差不齐很多插件长期不维护升级主版本时集体报错。我的做法是核心功能用官方能力非核心功能比如阅读时长估算自己写十几行脚本反而更稳。增量构建不是万能药。它解决的是改了文章 A 却要重新生成全站的问题但如果你的瓶颈在图片处理或语法高亮增量构建帮不上忙得从流程上分开处理。2.3 我为什么最终落在Markdown Git这条路上说一个我自己的选择过程。早期我用过带数据库的方案好处是有后台、能在线编辑、评论和统计一体化坏处是三年后我想换主题发现所有文章都躺在数据库里导出成 Markdown 之后格式乱得一塌糊涂代码块的缩进全丢了图片链接指向的还是旧域名的绝对路径。那次迁移花了我两个周末。后来我把所有内容统一成纯 Markdown 文件放进 Git 仓库这件事带来的收益远超预期版本可回滚。改错一个参数把站点搞崩了回退一个提交就行不用回忆我到底改了哪。diff 可读。文章修订历史是逐行的能清楚看到某段话是什么时候改的、为什么改。不绑定平台。内容就是一堆文本文件今天用这个生成器明天换另一个正文一个字都不用动只需要处理 front matter 字段名和模板。离线写作无障碍。飞机上、断网时照常写写完提交等有网再推。备份天然存在。每推一次就是一份异地副本。代价也要说清楚你需要熟悉命令行需要理解 Git 的基本操作多人协作时要处理冲突不过博客这种场景冲突极少。图片放在仓库里会让仓库体积膨胀超过几百 MB 之后克隆会变慢这时候要么用 Git 的大文件扩展要么把图片挪到对象存储。这个取舍后面第 4 章会细说。3. 域名解析、HTTPS 与托管链路把站点真正推到公网本地能跑和公网能访问之间隔着一段最容易出错的链路。这一段的坑普遍很低级但排查起来很费时间因为出错时的表现往往只是打不开或404没有任何提示。3.1 域名和 DNS 记录怎么配才不会踩空先把记录类型搞清楚这决定了你后面能不能正确绑定。记录类型用途填什么常见误区A域名指向 IPv4 地址托管方给的 IP填了旧 IP 忘了改AAAA域名指向 IPv6 地址托管方给的 IPv6本地网络不支持 IPv6 时访问异常CNAME域名指向另一个域名托管方给的别名用在根域名上导致解析失败TXT验证所有权、邮件安全平台给的一串字符串复制时多了空格或引号MX邮件收发邮件服务商地址与博客无关别乱动这里有个必须知道的基础限制CNAME 记录不能直接用在根域名上。根域名也就是不带 www 的那一截按 DNS 规范必须能同时承载其他记录类型而 CNAME 要求该名字下不能存在其他记录两者冲突。所以你会看到两种常见做法一是根域名用 A 记录指向托管方的固定 IPwww子域用 CNAME 指向托管方域名然后在托管侧配置把www重定向到根域名或反过来。二是使用支持别名记录的解析服务它能在根域名上模拟 CNAME 的行为这样托管方换 IP 时你不用手动跟。我的建议是统一到一个主域名上另一个做 301 永久重定向不要两个域名都能直接访问。原因很实际两个地址都能打开会造成重复内容收录时会分散权重也是第 5 章要讲的收录问题的常见来源。还有一个小技巧值得提前做改解析之前把 TTL 调低。TTL 是记录的缓存时间常见默认值是 3600 秒甚至更长。如果你要更换托管方提前一天把 TTL 调到 300 秒切换时全球生效只需要几分钟如果不调改完之后可能有一小时的时间一部分用户看到新站、一部分看到旧站你会以为是自己配错了反复折腾。3.2 自动部署流水线的搭建与常见报错手动上传文件这件事第一次做觉得没什么做到第十次就会开始偷懒偷懒就会出错。自动部署的流程很简单往仓库推代码托管平台拉取代码、执行构建命令、把产物目录发布出去。配置文件通常是仓库根目录下的一个 YAML 文件写清楚环境版本和构建命令就够了。# 通用构建配置示意字段名按所用平台的实际规范调整 build: image: node:20 # 显式锁版本不要用 latest steps: - run: npm ci # 用 ci 而不是 install保证依赖与锁文件一致 cache: true - run: npm run build publish: dir: dist # 产物目录写错就是全站 404配置本身没什么难度坑都在环境差异上。下面这几类我全踩过大小写敏感问题。本地开发机常见的不区分大小写而构建环境通常是区分的。你在本地引用./Images/cover.png文件实际叫images/cover.png本地一切正常上线后图片全裂。这类问题排查起来特别费劲因为报错信息只会告诉你资源 404。解决办法只有一条文件名统一小写并且用连字符代替空格从源头掐死。环境版本不一致。本地用的是一个较新版本的运行时构建环境默认是老版本于是本地好好的构建在线上直接报语法错误。配置文件里把版本号写死别用latest这一条能省掉大量莫名其妙的报错。缓存导致的陈旧产物。依赖缓存能大幅缩短构建时间但偶尔会出现明明改了代码线上还是旧的。遇到这种情况先清缓存重跑一次如果仍然不对检查是不是产物目录被整体缓存了。子目录部署的路径问题。如果站点部署在example.com/blog/这样的子路径下而站点配置里的基础路径还是根路径/那所有 CSS、JS、图片链接都会指向错误位置表现为页面是白板只有裸文字。这个配置项名字各不相同有的叫 base有的叫 publicPath有的叫 pathPrefix但逻辑一样。构建时的时区问题。文章日期如果是未来时间有些生成器会默认跳过不生成。构建环境的时区和你本地不一致时可能出现某篇文章本地有、线上没有的诡异情况。统一用带时区的完整时间格式写日期这个坑就没了。3.3 HTTPS 证书与重定向的细节HTTPS 现在基本是托管平台自动处理的你不需要手动申请证书。但有三个细节要确认混合内容警告。站点是 HTTPS 了但文章里引用的图片还是http://开头浏览器会把整页标记为不安全某些环境下图片直接不显示。老文章迁移时最常出现这个问题建议在构建阶段加一条检查把正文里所有http://的资源链接揪出来。强制跳转要配。确认访问http://会自动跳到https://而不是两个都能打开。这同样是重复内容问题。HSTS 谨慎开启。HSTS 是告诉浏览器以后访问我这个域名一律走 HTTPS好处是安全坏处是它会记住这个设置且很难撤销——如果你开了 HSTS 之后证书出问题用户连手动点继续访问的机会都没有只能等证书修好。开启之前先确认证书续期是稳定的自动流程并且对子域名是否生效想清楚。4. 内容组织目录结构、写作流程与代码块规范前面都是基建这一章才是你未来几年每天都要打交道的东西。内容组织做得不好两年后你会面对一堆找不到、改不动、不敢删的文章。4.1 从文件夹即分类到标签体系的取舍分类和标签的区别用一句话说清楚分类是一对多的目录标签是多对多的关键词。一篇文章只能属于一个分类但可以打任意多个标签。很多人一开始只用文件夹分目录写到一百篇之后发现有些文章既属于A又属于B文件夹没法表达于是开始乱放。我的做法是分类只保留少数几个粗粒度的、稳定的维度比如后端、前端、工具、杂记数量控制在十个以内并且尽量不新增因为分类一旦变化就意味着 URL 变化。标签放开用反正标签页面是聚合视图改动不影响文章本身的地址。URL 结构上我强烈建议在文章地址里带上日期或固定 slug并且发布之后永不修改。文章标题可以改但 slug 一旦变动就必须配 301 重定向否则所有外部链接和搜索结果都会指向 404。这个规则我写进了自己的发布清单里改标题时先问一句slug 要不要动。front matter 字段也要一开始就定好后面加字段的成本比想象中高历史文章要批量补。我用的字段大致是这些字段作用注意点title文章标题可以带标点不要带换行date首次发布时间用带时区的完整格式避免构建跳过updated最后修改时间手动或脚本更新对读者是重要信号slugURL 路径段全小写、连字符分隔发布后冻结categories分类只填一个tags标签三到五个为宜太多等于没有summary摘要用于列表页和社交分享卡片两句话以内draft草稿标记草稿只在本地预览可见4.2 一套能坚持下来的写作流水线写作流水线的设计目标只有一个让想写到已发布之间的阻力尽可能小。我现在的流程是这样的从新建到上线全程不超过几分钟的额外开销。第一步用一个模板文件生成新文章的骨架。模板里预填了日期、分类、草稿标记我只需要改标题和 slug。这里建议把模板里的日期自动填成当前时间手动敲日期最容易写错格式。第二步文章放草稿状态写。草稿状态下本地预览能看到但构建产物里没有所以你可以放心地推送到仓库不用担心半成品被访问到。这解决了想在公司电脑上接着写的问题。第三步本地预览。热更新是必需品改完保存浏览器自动刷新比自己按 F5 强很多。预览时重点看三件事代码块有没有横向溢出、图片宽度是否撑破容器、长标题在列表页会不会换行错位。第四步发布前过一遍清单。我的清单一共六条每条都对应一次真实的翻车文章里所有外链能不能打开、代码块有没有标语言、图片 alt 有没有写、摘要填了没有、slug 有没有和已有文章冲突、日期是不是在未来的时区里。这六条检查下来不到两分钟但能挡掉大部分低级问题。第五步提交推送等自动化跑完。构建日志要养成看一眼的习惯很多警告比如内部链接指向不存在的页面不会让构建失败但会一直烂在那里。4.3 技术文章里的代码块、图片与图表规范代码块是技术博客的门面几个细节值得较真一定标语言。不标语言的代码块没有语法高亮读者阅读成本陡增。而且某些生成器会把它当纯文本处理长行直接溢出容器。控制单行长度。超过 90 个字符的行在中等宽度的屏幕上会触发横向滚动读者要左右拖动才能看完整体验很差。写代码示例时主动断行比事后怪主题宽度设置不合理有用。代码要能跑。我给自己定的规矩是示例代码必须是从实际能运行的版本里截出来的不能凭记忆手写。凭记忆写出来的代码经常少个引号、少个await读者复制过去报错然后就不再信任你的文章了。图片这块我现在的处理原则是截图宽度统一压到 1200 像素以内格式优先用 WebP质量 80 左右单张控制在 200KB 以下终端输出、配置片段这类内容用代码块而不是截图搜索得到、复制得了、体积还小图片放在仓库里还是对象存储取决于数量。两百张以内放仓库最省事再多就该往外挪了每张图都写 alt一方面是无障碍另一方面图片挂了的时候至少能看出这里原本是什么至于要不要在文章里放流程图和时序图我的看法是能用一段话讲清楚的就别画图。图维护成本高改一个分支就要重画而且很多图表工具的语法和渲染效果在不同主题下差异很大迁移时经常整块失效。真需要图优先选纯文本描述加表格。5. 打开速度与搜索可见度性能与 SEO 的实战处理项站点上线之后你会开始关心两个指标打开快不快、搜不搜得到。这两件事有大量看起来很专业但没什么用的操作我按投入产出比排一下。5.1 首屏性能图片、字体与第三方脚本性能优化最容易犯的错是没有测量就开始优化。先用浏览器自带的性能面板跑一次看最大内容元素的加载时间落在哪里再决定动哪里。经验上静态博客的性能瓶颈九成集中在三个地方图片。首屏大图是最常见的拖累项。处理方式是压缩、限制尺寸、首屏图不要懒加载、非首屏图全部加懒加载。一个常被忽略的点是给图片写死宽高属性否则图片加载过程中页面会跳动读者刚想点某篇文章页面一跳点到了别的这种体验损伤比慢一秒更严重。字体。中文字体文件动辄几 MB直接引入会让首屏白屏很久。解决办法是子集化——只保留你实际用到的字符通常能压到几百 KB 甚至更小再配合font-display: swap让文字先用系统字体显示字体加载完再替换。如果你的站点主要读者在国内还要考虑不要依赖境外字体服务加载失败时会长时间卡住。第三方脚本。访问统计、评论系统、分享按钮每一个都是外部请求。这些脚本全部改成延迟加载等页面主要内容渲染完再执行。评论系统尤其要注意它经常是页面上最重的部分而它恰恰是最不重要的部分——没人会因为评论区加载慢而离开但会因为你首屏白屏两秒而离开。顺便说一个反直觉的观察主题自带的性能优化开关经常是负优化。比如某些主题默认开启代码块行号、默认开启阅读进度条、默认内联所有 CSS这些在文章少的站点上没什么感觉文章一多就会显著增加单页体积。上线前把主题配置项过一遍把不认识的全关掉比装优化插件管用。5.2 站点地图、robots 与结构化数据基础三件套缺一不可站点地图sitemap.xml把所有文章地址列出来告诉搜索引擎有哪些页面。大部分生成器有现成插件一行配置就出来了。要注意的是它必须包含最终可访问的绝对地址如果域名配错了站点地图里全是错的链接提交上去反而有害。robots.txt放在根目录声明哪些可以抓、站点地图在哪。最简版本大概长这样User-agent: * Allow: / Sitemap: https://你的域名/sitemap.xmlcanonical 标签每篇文章声明自己的规范地址。这一条对防止重复收录特别重要尤其是你同时存在www和非www、或者带不带结尾斜杠两种地址都能访问的时候。所有内链统一用一种形式别一半带斜杠一半不带。结构化数据这块技术博客最值得加的是文章类型的数据标题、作者、发布时间、修改时间、封面图。加对了之后搜索结果里可能展示发布时间和缩略图点击率会有肉眼可见的提升。但别乱加——把不是文章的页面标成文章、把发布时间写成未来时间都会带来负面影响。社交分享卡片分享到聊天工具时显示的那张预览图也值得配一下一张 1200×630 的封面图就够成本很低。5.3 收录异常时的逐层排查链路文章发出去搜不到这是最高频的问题。我的排查顺序是这样基本能定位到九成情况第一层确认页面能不能被抓。打开 robots.txt 看有没有不小心写了Disallow: /。这个错误极其常见很多主题的默认配置里就带着一行屏蔽规则本地看不出任何异常。同时看一眼页面源码里有没有noindex的 meta 标签有些主题会把标签页、归档页默认设成不索引如果你误把文章页也归类进去了就永远搜不到。第二层确认页面在不在站点地图里。打开站点地图搜索你的文章标题不在的话说明构建时被跳过了最常见的原因是日期写成了未来时间或者草稿标记忘了去掉。这条我在第 3 章提过是真的高频。第三层确认规范地址指向哪里。打开页面源码找 canonical 那一行看看它指向的地址和你想收录的地址是不是同一个。如果指向了一个不存在的地址比如域名写错、路径多了个斜杠搜索引擎会认为这篇内容属于另一个页面你这篇就永远进不了索引。第四层确认内容能被解析。如果你用了大量客户端渲染抓取工具拿到的可能是个空壳。静态生成的站点一般没这个问题但如果是组件框架型方案且没做预渲染就要注意了。用抓取工具模拟看一下渲染后的 HTML 里有没有正文是最直接的验证。第五层才是等。前面四层都确认没问题那就只是时间问题。新站点从提交到被收录几天到几周都正常。这时候该做的是去几个相关社区把文章发一下让外链自然产生比反复刷新搜索结果的效率高得多。6. 上线之后备份、迁移与长期维护搭好只是开始。一个技术博客真正的成本在维护而维护的痛点在两三年后集中爆发依赖全部过时、主题作者弃坑、想换工具发现迁移成本高得离谱。6.1 备份不等于我推了 Git很多人的备份策略是代码在仓库里仓库在平台上平台有备份。这个链条有个明显缺口你的内容不全在代码里。评论数据、访问统计、图片如果放在对象存储、订阅用户列表这些都不在 Git 里。我的做法是每月做一次导出把三样东西打包存到本地和另一处Markdown 源文件全集、图片目录、各个外部服务的配置导出。整个操作五分钟但能救命。尤其是评论系统很多第三方服务的免费额度用完会把数据锁住等你发现的时候已经导不出来了。还有一个容易忽略的点备份要验证一次能恢复。我见过有人备份了三年真出问题时发现压缩包是空的。每年挑一次从备份里恢复一个测试站跑一次构建确认文章都在、图片都在、链接都对。6.2 依赖腐化与主题魔改的代价静态站点的依赖树通常不深但有两类东西会随着时间腐烂主题。开源主题的作者维护热情往往只有一两年。你基于某个主题做了大量定制两年后它不再更新新的运行时版本不兼容你就卡住了。我的应对方式是能通过配置项改的绝不改源码必须改的部分单独抽成一个覆盖层或自定义样式文件这样将来换主题时改动集中在一个文件里重写成本可控。插件和依赖。锁文件一定要提交保证每次构建结果一致。同时给自己定一个节奏比如每季度跑一次依赖升级小版本直接升大版本一次升一个升完立刻构建预览。我最惨的一次是把所有依赖一次性升到最新构建报错十七处排查了两天才逐个修完从那以后再也不批量升级了。运行时版本也要固定。配置文件里写死运行时的大版本号别用latest。不然某一天平台默认版本更新你的构建会突然挂掉而你可能一个月都没推过代码完全不知道发生了什么。6.3 换生成器的迁移成本与最小化路径说实话绝大多数人不会换生成器但如果哪天你想换迁移成本主要来自三件事提前预防能省掉大量时间URL 结构。这是最贵的。如果新旧方案的 URL 规则不一致你需要为每篇老文章配一条 301 重定向。几百篇文章手写重定向表不现实写个脚本从旧站点地图生成映射表一次性搞定。所以从一开始就让 URL 结构尽量简单且与工具无关比如年份/slug这种形式大多数方案都能配出来。front matter 字段名。不同方案对同一个概念叫法不同摘要有的叫 summary有的叫 description。写个脚本批量重写字段名就行十分钟的事。图片路径。如果你的图片引用写的是站点内的绝对路径换域名或换目录结构会全裂。建议正文里统一用相对路径引用同目录下的图片把所有资源放在和文章同级的位置迁移时整个目录搬走就行一个链接都不用改。最后再说个小技巧关于域名到期把域名到期提醒设在到期前 90 天而不是提前 7 天。域名过期之后有一个赎回期费用通常是正常续费的十倍以上而且期间站点会直接消失。我给自己所有重要域名都设了日历提醒这不是强迫症是真的有人因此丢掉过用了五年的域名。7. 我的建议顺序别把顺序搞反了如果让我重新走一遍顺序会是这样先用最轻的方案把站点跑通不为任何以后可能会用到的功能提前搭基建写满五篇文章之后再回头决定要不要绑定域名、要不要接评论、要不要做统计等文章超过二十篇、开始有人从搜索进来再认真处理性能和收录。这个顺序背后的逻辑很简单所有基建的价值都建立在你确实在写这个前提上。没有内容再快的构建速度也只是跑得快而已。我见过太多让人惋惜的站点配置挑不出毛病就是首页最新一篇停留在两年前。真要给一句最实在的建议那就是把第一篇写完发出去哪怕格式丑一点、主题用的是默认的、域名还是平台给的二级域名。等你写到第十篇的时候你会非常清楚地知道自己需要什么、不需要什么那时候再回来改基建改动量可能只有现在的一半而且改的都是真正用得上的地方。