写技术博客这件事我断断续续坚持了好几年。最早总在第三方平台上写后来慢慢发现内容都不是自己的平台改个版、关个模块文章可能就没了。所以后来我下定决心从零搭建个人技术博客把内容、域名、部署方式全部攥在自己手里。今天这篇就把我摸索下来的完整路线写出来从方案选型到最终上线再到日常维护和问题排查尽量把每一步都讲透让你照着做就能跑起来。这篇文章适合几类人刚入行、想通过写博客沉淀知识的开发者已经写了段时间内容、想摆脱平台束缚的博主还有想做个人品牌、需要一块自己阵地的朋友。整体思路是本地写 Markdown静态站点生成器渲染成网站部署到服务器或托管平台再绑定自己的域名。整套方案搭建成本很低后续维护也基本不费劲。下面我开始拆解。1. 动笔之前先定方案为什么静态博客更适合个人沉淀1.1 动态博客和静态博客的取舍很多人一开始纠结到底用 WordPress 这类动态博客还是用静态站点生成器。我两个体系都用过先说说它们本质上的区别。动态博客有后台管理有数据库写文章就像用记事本一样在网页里编辑点发布就生效。好处是上手门槛低插件也多想加什么功能直接装一个插件就行。但问题不少服务器要跑数据库和脚本资源占用高安全问题复杂插件、主题、核心程序都需要不断更新数据迁移麻烦哪天想搬家导出导入都很折腾。最要命的是速度动态页面每次请求都要查数据库、执行脚本优化不好就会卡。静态博客完全不同。所有文章在本地用 Markdown 写好构建工具把内容和模板渲染成纯静态的 HTML 文件服务器做的事就是把这些文件发给访问者。没有数据库没有后端脚本速度快、安全性高、维护成本低。部署的时候就是把文件放上服务器甚至可以放到对象存储或托管平台基本不花钱。我的结论很明确如果只是写技术文章、做个人沉淀静态博客是更优解。动态博客适合做复杂的业务站点对个人内容输出来说属于杀鸡用牛刀。1.2 主流静态站点生成器怎么选静态博客生态里工具很多常见的有 Hexo、Hugo、VuePress、Jekyll还有最近流行的 Astro 等。我画个表把关键差异列清楚生成器基于语言构建速度主题生态适合人群HexoNode.js中等文章多会慢很丰富喜欢 Node 生态、想要花哨主题的人HugoGo极快几千篇文章秒级构建较丰富追求速度、想简化部署的人VuePressVue/Node中等偏文档风格喜欢 Vue、需要文档站的人JekyllRuby较慢经典老牌早期博客用户、熟悉 Ruby 的人AstroNode.js较快快速增长喜欢新工具、想要组件化的人我自己最终用的 Hugo。原因有几个第一Hugo 是编译好的单个二进制文件不依赖 Node 环境机器上随便装一下就能用第二构建速度真的快几百篇文章也是毫秒级后面文章多了完全不用焦虑第三主题系统成熟找一个好看的主题改一改就很出效果第四部署极其简单构建后就是一个 public 目录扔到任何静态托管地方都能跑。如果你已经熟悉 Node.js选 Hexo 也完全可以毕竟主题多、中文资料多遇到问题容易搜到解决方案。关键是别频繁换工具写东西才是核心工具顺手就好。1.3 动手前的关键决策清单在真正搭之前有几个问题要先想清楚我踩过不少坑内容放哪里我建议所有源文件用 Git 管理本地一份、远程仓库备份一份换电脑或者误删都能恢复。域名用什么如果将来想长期经营最好注册一个自己的域名不要用带平台前缀的免费域名因为那等于把品牌寄托在别人身上。服务器选哪家没有唯一答案。看你的目标读者在什么区域、预算多少、要不要折腾 HTTPS 和 CDN。预算低可以先从托管平台起步后面再上服务器。评论系统怎么处理静态博客天然没有评论功能需要接入第三方评论服务或者自己做一套。这个问题可以后面再加初期不用纠结。这几件事想明白了后面的搭建过程会顺畅很多。不要一上来就找教程、下主题先把大方向定下来省得后面反复推翻。2. 本地环境准备与站点初始化先把博客跑在电脑上2.1 安装基础工具链以 Hugo 为例第一步是把环境配好。需要三样东西Git、Hugo 本体、一个趁手的代码编辑器。Git 是必备的用来管理博客源文件和主题更新。Windows 下直接安装 Git 客户端macOS 可以用 homebrew 装Linux 用系统包管理器装。装完确认一下git versionHugo 的安装也很简单。macOS 用户brew install hugoLinux 用户看发行版比如基于 Debian 的可以直接sudo apt install hugoWindows 用户可以从官方发布页下载安装包或者用包管理器。安装完运行hugo version能输出版本号就说明装好了。编辑器我常用 VS Code免费而且插件生态丰富写 Markdown 有实时预览配个markdownlint插件还能帮你规范格式。这里有个最容易忽略的点Hugo 区分普通版和 extended 版。如果你打算用 SCSS 编译功能或者使用某些依赖 Sass 的主题一定要装 extended 版否则构建的时候会报错。我第一次就栽在这上面普通版编译到一半提示找不到编译器换成 extended 版就好了。2.2 创建站点并让它在本地跑起来环境准备好之后创建站点只需要一条命令hugo new site myblog这条命令会生成一个名为myblog的目录里面有基础骨架。接下来选择一个主题。主题是静态博客的门面直接决定读者打开网站时的第一印象。挑主题的时候我建议看几个点是否响应式、是否支持暗色模式、是否内置搜索、代码高亮效果如何、导航结构是否清晰。不要只看演示站好看还要看主题的文档全不全作者更新勤不勤。选好主题后把主题克隆到themes目录cd myblog git clone https://example.com/path/to/theme.git themes/my-theme然后把主题名字写进配置文件新建第一篇文章hugo new posts/first-post.md这里生成的 Markdown 文件会自动带一段 Front Matter是 Hugo 识别文章信息的关键。给个典型例子--- title: 我的第一篇博客 date: 2025-01-15T10:00:0008:00 draft: true tags: [随笔] categories: [生活] ---draft: true表示草稿本地预览时能看到正式构建默认不会发布。等文章写完了把draft改成false或者直接删掉这行。写完保存在博客根目录执行hugo server -D这个命令会在本地启动一个服务打开浏览器访问http://localhost:1313就能看到你的博客了。-D参数表示预览草稿文章写初稿阶段非常实用不用每次刷新都手动改状态。2.3 站点配置文件里的关键字段配置文件的路径一般是config.yaml或者config.toml取决于你用的主题和 Hugo 默认配置。我习惯用 YAML可读性更好。一份基础配置长这样baseURL: https://example.com/ title: 我的技术博客 theme: my-theme languageCode: zh-CN paginate: 10 enableRobotsTXT: true这里需要注意baseURL很多新手栽跟头都是因为它。baseURL是整个站点的根地址本地预览时是http://localhost:1313部署到线上就要改成最终访问的域名比如https://example.com/。如果这个字段不填或者填错构建出来的页面里所有链接都会出问题表现就是首页能看到点进文章后样式全丢、图片加载不出来实际上就是因为相对路径和绝对路径错乱了。paginate控制列表页每页显示多少篇文章languageCode标注语言对 SEO 有帮助。配置好之后本地看一眼效果如果没问题就可以进入部署环节了。3. 部署上线把博客从本地搬到公网3.1 常见的部署路线对比博客构建完成之后会生成一个public目录里面是纯静态文件。部署的本质就是把这堆文件放上一个能通过公网访问的地方。主流路线有三条部署方式成本难度可控性适合场景代码托管平台的静态页面服务免费低一般刚开始写、不想花钱维护云服务器 Nginx按需付费中高想完全控制、未来要扩展功能对象存储静态网站托管按量付费低中只想快速上线、访问量不大三条路我都走过。最初用的是托管平台零成本push 代码到仓库就自动构建爽归爽但自定义能力有限比如想加服务器端脚本、自定义缓存规则就做不了。后来换成云服务器加 Nginx自由度完全不一样可以任意折腾也顺便把 Linux 命令、Nginx 配置、SSL 证书这些技能都练会了。如果你刚开始我建议先选熟悉的路线。预算敏感就先用托管平台想一次性到位就直接上服务器。下面重点讲云服务器加 Nginx 的完整流程这是最通用的方案理解之后其他路线基本一目了然。3.2 云服务器加 Nginx 的完整部署首先你需要一台云服务器和一个域名。服务器买最低配的即可2核2G内存足够跑一个纯静态博客Nginx 对资源的消耗非常低。部署过程我把每一步拆开讲。第一步安装 Nginx。登录服务器后执行sudo apt update sudo apt install nginx -y装好后访问服务器 IP如果看到 Nginx 的默认欢迎页说明安装成功。第二步在本地构建博客hugo --minify--minify参数会对 HTML、CSS、JS 做压缩减少体积对加载速度有帮助。构建完成后public目录里就是最终要发布的文件。第三步把构建产物上传到服务器。最直接的方式是rsync它比scp好用的地方在于支持增量同步而且能删除服务器上的多余文件保证线上和本地完全一致rsync -avz --delete public/ rootyour-server-ip:/var/www/myblog如果没有rsync先手动建目录再用scp上传ssh rootyour-server-ip mkdir -p /var/www/myblog scp -r public/* rootyour-server-ip:/var/www/myblog/第四步配置 Nginx 站点。在服务器上新建一个配置文件sudo vim /etc/nginx/sites-available/myblog写入内容server { listen 80; server_name example.com www.example.com; root /var/www/myblog; index index.html; location / { try_files $uri $uri/ 404; } location ~* \.(css|js|jpg|jpeg|png|gif|ico|svg|webp)$ { expires 7d; add_header Cache-Control public, max-age604800; } error_page 404 /404.html; }try_files $uri $uri/ 404是 Nginx 处理静态文件比较推荐的方式先尝试直接匹配文件再匹配目录都没有就返回 404。静态资源设置expires 7d可以给浏览器缓存减少重复请求。第五步把站点软链接到启用目录测试配置然后重载 Nginxsudo ln -s /etc/nginx/sites-available/myblog /etc/nginx/sites-enabled/ sudo nginx -t sudo systemctl reload nginxnginx -t用来检查配置文件有没有语法错误这一步一定要做不然改坏了会导致整个服务起不来。第六步申请 HTTPS 证书。现在浏览器对 HTTP 站点越来越不友好而且没有 HTTPS有些浏览器会直接报警告。我用 Certbot 申请免费证书两条命令搞定sudo apt install certbot python3-certbot-nginx -y sudo certbot --nginx -d example.com -d www.example.com运行后按提示输入邮箱、同意协议Certbot 会自动修改 Nginx 配置并配置证书续期。证书快到期时会自动续基本不用管。申请之前确保域名解析已经指向服务器 IP否则验证流程会失败。最后重新加载 Nginxsudo systemctl reload nginx然后用浏览器访问你的域名看到博客正常打开并且地址栏带锁图标部署就成功了。3.3 托管平台部署的捷径如果不想买服务器用托管平台部署更省心。大致流程是先把博客源码推到代码仓库然后在托管平台新建项目关联仓库平台会自动识别静态站点生成器执行构建命令最终分配给你一个子域名。平时更新博客只需要hugo构建出public目录再 push 到仓库。如果平台支持自动构建push 完就自动上线了。域名绑定也很简单在平台后台添加你的域名按提示配置一条 CNAME 解析即可。托管平台的问题在于如果平台访问不畅或者服务调整你的站点会受影响。所以我后来还是把主力博客搬到了自己服务器上托管平台只用来跑一些临时 demo。如果你刚开始折腾完全可以用托管平台练练手等熟悉了再迁移。4. 日常维护与写作体验优化把心思放回内容上4.1 一条命令完成的自动发布流程博客上线后最烦的事情是每次写文章都要手动走一遍构建、上传、刷新。其实这个流程完全可以自动化。我在本地写了一个deploy.sh脚本核心内容大致是#!/bin/bash set -e echo 开始构建... hugo --minify echo 同步到服务器... rsync -avz --delete public/ rootyour-server-ip:/var/www/myblog echo 部署完成保存后给脚本加执行权限chmod x deploy.sh以后更新博客就两步写好文章然后执行./deploy.sh。就是这么简单。同样的思路也可以放到云服务器上配置一个 Git 仓库本地 push 代码后服务器的钩子脚本自动拉取并构建。但对个人博客来说脚本方案够用且容易排查问题避免引入过多环节。这里有个小教训写自动化脚本时rsync的--delete参数要慎用。它会删除服务器上构建目录中本地不存在的文件。如果服务器上的目录里还有其他内容比如手动上传的页面或者临时文件会被一并清掉。确保/var/www/myblog里放的全部是 Hugo 构建产物再使用--delete。4.2 图片资源管理策略技术博客最离不开的就是图片。截图、流程图、架构图一篇文章下来少说也要放五六张。图片管理不好博客会越写越臃肿页面加载也越来越慢。我现在的做法是图片统一放在static/images/目录下按文章或主题分子目录。比如static/images/reverse-proxy/nginx-conf.png路径清晰找起来方便。图片上传前必做三件事压缩。随便一张截图可能几百 KB用工具压缩一下能降到几十 KB对加载速度的提升非常明显。裁剪。只保留文章需要展示的区域不要整屏截图读者看不清楚重点文件也大。重命名。用英文描述性文件名比如hugo-config-yaml.png既好记又对 SEO 友好。如果文章特别多图片存储可以考虑对象存储服务把图片上传到对象存储然后通过 CDN 加速分发。这样做的好处是减轻服务器带宽压力坏处是多了一笔 OSS 费用和多一个管理环节。初期直接用服务器目录存放完全够用等流量大了再迁移也行。4.3 SEO 和阅读体验的基础配置静态博客在 SEO 上有天然优势页面结构干净、加载速度快、内容都是纯文本。但有一些基础配置做了会更好。第一开启站点地图。Hugo 默认会生成sitemap.xml不用额外插件。确保配置里开启enableRobotsTXT: true生成robots.txt可以让搜索引擎更规范地抓取你的站点。第二配置文章摘要。在 Front Matter 里写description字段控制搜索引擎展示的摘要内容。不写的话搜索引擎会自己截取正文前几句话效果往往不理想。我每篇文章都会手写一段六七十字的描述既点出文章核心又带上一两个关键词。第三开启 RSS 订阅。Hugo 默认就支持 RSS 输出。老读者可能喜欢用订阅器看更新RSS 是博客的标配能力不需要额外配置。第四配好代码高亮。技术博客最关键的就是代码显示效果。Hugo 自带highlight短代码支持多种主题风格。我一般配置为markup: highlight: style: github lineNos: true lineNumbersInTable: true行号能帮助读者定位代码位置尤其在讨论报错信息时非常有用。我在浅色主题下用github风格在暗色主题下会换一套深色系风格保证代码块可读性。第五阅读体验不能忽视。段落行高、正文字号、内容区最大宽度都要细心调一调。很多主题默认的内容宽度太宽一行文字过长读起来容易串行。我会在自定义 CSS 里限制正文最大宽度在 720px 左右这个宽度下中英文混排的阅读体验都比较好。另外给文章页面加上上一篇、下一篇的导航让读者看完一篇可以自然地跳到相邻文章能明显提升停留时长和阅读深度。5. 常见问题与排查经验5.1 部署后样式丢失、图片不显示这个是我见过最多的问题十次里有八次是baseURL配置错误。症状是首页能打开点进文章后页面变成了“裸奔”状态没有 CSS图片也裂开。排查思路右键查看网页源代码看引用的 CSS 地址是绝对路径还是相对路径。如果是http://localhost:1313/css/main.css这种地址说明线上页面里的baseURL还是本地地址。检查config.yaml里的baseURL是否改成了正式域名且末尾带斜杠。构建前执行hugo --cleanDestinationDir清掉旧构建产物再重新生成避免残留文件干扰。这个问题的本质是静态站点构建时就把所有资源地址写死了配置里是什么地址出来的页面就是用什么地址。所以每次部署前养成习惯先看一眼配置。5.2 文章更新后线上不变化我遇到过好多次本地改好了执行部署脚本刷新浏览器还是旧内容。排除掉服务器实在太慢的情况后基本就是两个原因。一个是浏览器缓存。你访问过旧页面浏览器把 HTML、CSS 存在本地了。新版本文件名如果没变浏览器会直接用旧缓存。解决办法是强制刷新Mac 用CmdShiftRWindows 用CtrlF5或者用无痕窗口打开。如果部署了 CDN还需要刷新 CDN 缓存。另一个是服务器上的旧文件没有清干净。有些部署脚本只上传新增文件不删除旧文件导致旧版本文件残留。确保你的脚本带了--delete以及本地构建目录是全新生成的。还有一个细节Nginx 配置了静态资源缓存规则后如果文章改了但图片、CSS 文件名没变浏览器可能还会命中旧缓存。解决方法是 Hugo 构建时自动给静态资源加内容哈希或者改缓存策略把expires设短一些。个人博客访问量不大我一般把 CSS 和 JS 的缓存设为一小时HTML 不设缓存既保证速度又保证更新及时。5.3 评论功能不显示静态博客没有原生评论区我接入过第三方评论服务踩过的坑主要有两类。第一类是配置项不对。很多评论服务需要在后台配置站点地址如果后台填的域名和你线上实际用的不一致会拒绝加载。常见的是从https://example.com访问但后台配置里写成了example.com没带协议导致匹配失败。第二类是初始化脚本时机问题。评论组件通常在页面底部加载如果页面脚本存在加载顺序冲突评论框就不出现。排查时打开浏览器开发者工具看控制台有没有报错信息有报错直接定位到具体脚本。大多数情况下是评论脚本加载出错而不是你的配置有问题。如果不想依赖第三方评论服务也可以自己做一套简单的评论方案给每篇文章结尾放一个“关于本文的问题欢迎联系我”的提示附上个人邮箱或社交账号。对个人博客来说评论不是最核心的功能把内容和阅读体验做好比什么都重要。5.4 域名解析生效慢域名解析有一个传播过程。修改解析记录之后不同地区的 DNS 服务器更新时间不一样快则几分钟慢则几小时。检查域名是否解析成功用系统自带的命令就能看nslookup example.com也可以直接输入域名访问试试看是否打开自己的博客。解析没生效时通常会有两种表现打开的是其他网站或者提示域名无法访问。前者说明解析记录配置错了后者说明还没生效。如果已经等了一段时间还没生效去域名管理后台检查两条记录A 记录是否指向服务器 IP记录值是否填写正确。另外如果同时配置了 CNAME 和 A 记录可能互相冲突。一般情况下主域名用 A 记录子域名用 CNAME 记录就行。最后分享两个实际经验写技术博客这几年我最大的感受是工具永远是次要的内容和记录本身才值钱。很多人搭建博客花了大量精力折腾主题、折腾服务器最后真正开始写文章却坚持不下来。所以我后来给自己定了一个规矩每周至少写一篇哪怕只是几百字的问题记录。Blog 本质上是给自己积累知识库写下来以后回头看能省下大量重复搜索的时间。再分享一个实用小技巧博客源的 Markdown 文件我全部备份在 Git 仓库里每次写改文章都提交一次。有一次服务器数据全丢了我一点不慌拉回源码重新构建三分钟就把站点恢复了。把源文件和构建产物分开管理这可能是你搭建博客后最值得养成的一个习惯。如果你正打算从零搭建个人技术博客别追求一步到位。第一天先在电脑上跑通本地预览第二周再部署上线第三周再优化域名、评论、SEO。一步一步来你会发现技术博客真正带给你的不是流量和关注而是对自己知识体系的不断整理和审视。