很多人问我都2025年了各种写作平台既方便又有流量何必自己折腾一个博客我的回答一直是因为平台是别人的地盘而一个自建博客才是真正属于你的一亩三分地。这篇文章要分享的就是我搭建个人博客 my-blog 的完整过程——从技术选型、站点结构、写作流程到部署上线、日常维护所有踩过的坑都会摊开讲。它适合想拥有独立站点的开发者、写作者也适合纯粹厌倦了模板化个人主页的人。零基础也可以跟着做我的目标就是让你照着操作能真正把博客跑起来。1. 写博客这件事到底值不值得折腾1.1 为什么我劝你留一块自留地在做技术分享这件事上我算是折腾过不少地方。很早以前在各类内容平台写过后来也尝试过用现成的建站工具但总觉得不太对劲。原因其实很简单你在哪个平台写内容就住在哪个平台的服务器上。平台今天改版你的排版全乱明天调整推荐策略你辛苦写的东西可能根本没人看到哪天平台说关停就关停你甚至连数据都导不完整。自建博客解决的就是这个问题。域名是我的源码是我的文章就是一个个 Markdown 文件放在自己的 Git 仓库里。想换平台直接把内容打包带走想改样式所有代码都在手边哪怕某一天托管服务倒闭了我本地还有一份完整备份换个地方十分钟就能恢复。这种踏实的掌控感是任何一个第三方平台都给不了的。而且博客本身就是个不断积累的长期项目。刚开始你可能只会写一篇文章、搭一个页面但慢慢地你会去优化加载速度、处理不同设备的适配、搞一套自己的备份方案。每件事看着都不大合在一起就是一套完整的工程能力训练。哪怕你完全不懂技术把博客当作一个整理输出、积累作品集的工具也是稳赚不赔的。1.2 静态博客和动态博客如何选搭建博客之前面临的第一个方向性选择就是动态博客和静态博客。这两条路我都走过可以负责任地帮你梳理一下。动态博客的代表是 WordPress、Typecho 这类系统。它们的运行依赖服务器和数据库后台有可视化的管理界面发文章就像在后台敲字。好处是功能丰富、插件多、上手容易但坏处也很直接——你得养一台服务器要装环境、打补丁、处理安全问题稍不留神就会被攻击或者挂马。如果你只是为了专注输出这些运维琐事会非常消耗你的热情。静态博客的思路完全不同。它先把所有文章在本地编译成纯 HTML、CSS、JS 文件再把这些文件丢到托管平台。没有数据库没有后端程序页面全部是静态文件加载速度极快也不存在常见的注入攻击。代价就是发布流程偏“极客”一些需要适应命令行操作但这套流程一旦搭好反而比动态博客更省心。我个人的判断标准很简单如果你不想维护服务器又想拥有一个又快又安全的个人站点那就选静态博客。个人博客真正的瓶颈从来不是技术而是你能不能持续更新。把精力留给写作而不是熬夜修服务器这个选择基本不会错。1.3 生成器对比Hugo、Hexo、VuePress 谁更省心确定静态博客这个方向后接下来就是选生成器。市面上常见的主流方案有 Hugo、Hexo、VuePress、Jekyll 这几个我简单说说各自的情况。Hugo 是用 Go 语言写的核心优势是构建速度快几百篇文章也是瞬间完成。它发布时只要一个可执行文件几乎不需要额外安装依赖换电脑也一样能跑。主题生态很丰富配置虽然有点学习成本但文档很完善。Hexo 是 Node.js 生态下的老牌静态博客中文社区特别活跃教程满天飞。如果你完全没接触过命令行Hexo 的学习资料更好找。但文章数量上去之后构建速度会明显变慢而且需要先装 Node.js 环境偶尔还会碰到依赖版本冲突的问题。VuePress 本来是给 Vue 文档服务的虽然也能做博客但它的组织方式更偏向文档站。如果内容是以时间线、分类、标签为核心的博客VuePress 用起来会有点拧巴。Jekyll 则是 GitHub Pages 原生支持但 Ruby 环境在 Windows 上体验不太好我直接就没考虑。最后我选了 Hugo。除了速度更看重的是它产出的内容非常干净就是一个纯静态目录放到任何托管平台都能跑。接下来整个方案我都会基于 Hugo 来讲。2. 搭站点前的关键设计别急着写代码2.1 一个健康博客的目录结构长什么样用 Hugo 生成一个全新站点默认会得到下面这样的目录结构my-blog/ ├── archetypes/ # 文章模板 ├── assets/ # 需要构建处理的资源 ├── content/ # 所有 Markdown 内容 ├── layouts/ # 自定义模板 ├── static/ # 直接拷贝的静态文件 ├── themes/ # 主题代码 └── hugo.toml # 配置文件很多人刚开始只关注 content 和 themes其实其他目录同样关键。content 放所有文章是整个博客最核心的部分我会在里面再建一个 post 目录用来放博客正文其他独立页面如关于页、归档页也放在 content 下。static 是很多人容易忽略的一层它里面的文件不会被 Hugo 做任何处理构建时直接原封不动复制到根目录。比如网站图标 favicon、验证文件、CNAME 文件这类不需要编译的资源我都会放这里。如果你想给静态资源加哈希指纹让 CDN 缓存更高效那就放到 assets 里让 Hugo 统一处理而不是硬塞进 static。layouts 则是用来覆盖主题默认模板的。早期我喜欢直接在 themes 目录里改主题源码结果主题一升级所有改动全被覆盖了。正确做法是先复制要改的模板到 layouts 对应目录里再修改Hugo 会优先加载你自定义的文件。这个习惯能帮你省掉很多后悔操作。2.2 三个必改的配置项baseURL、语言和主题Hugo 新版本默认使用 hugo.toml 作为配置文件老教程里常见的 config.toml 也仍然有效只是命名不同。一个最小可用的配置长这样baseURL https://example.com/ title my-blog languageCode zh-cn defaultContentLanguage zh theme PaperMod这几个配置项里baseURL 是头号大坑。它决定生成页面里所有绝对链接的地址比如 CSS、JS、图片的引用路径。如果 baseURL 和你实际部署的地址不一致页面打开时所有资源都会指向错误的地址表现就是样式全丢、图片全裂。很多人第一次部署就遇到这个问题原因基本都是 baseURL 没改对。title 就是你博客的名字会出现在页面标题、导航和 RSS 里按自己喜好设置就行。languageCode 和 defaultContentLanguage 对中文博客很关键建议设置成 zh-cn 和 zh这样时间格式、语言标记和 RSS 输出都会更符合中文阅读习惯。theme 字段指定你用的主题。主题数量多不代表要眼花缭乱我选择了 PaperMod。它第一眼看起来很简单但细节很全面暗色模式、代码高亮、文章目录、内置搜索都有基本不用怎么折腾就能达到完整状态。博客的核心是内容不是让每个访客都觉得“哇这主题好炫”那样只会拖慢加载速度分散注意力。2.3 评论、访问统计、站内搜索怎么组合最舒服博客不是写给自己看的上线后绝大多数人关心的三件事就是读者怎么评论、我怎么知道有没有人看、别人能不能搜到我的文章。评论这块我建议使用第三方评论服务不要自建。常见的有基于 GitHub Discussions 的 Giscus、部署在云函数上的 Twikoo、以及早期的 Valine 等。我选用的是 Twikoo它支持按页面管理评论、邮件通知、自定义表情部署出来也挺清爽。不管选哪个注意它依赖的外部服务要相对稳定不要找那种已经没人维护的方案。访问统计方面比较省心的选择是 Cloudflare Analytics 或百度统计。Cloudflare Analytics 胜在脚本极轻不泄露访客隐私如果域名 DNS 本身就放在 Cloudflare直接在后台开启即可。百度统计在国内搜索引擎场景下能提供更多参考但脚本会更重一些我目前只接了一个避免给页面增加太多无谓的请求。站内搜索可以依赖主题自带能力PaperMod 默认集成了基于索引的搜索不需要额外服务。如果哪天文章量大到搜索吃力再考虑接入搜索引擎自定义 API。搜索优化还有一个前置动作就是确保每篇文章的标题、描述、关键词都写清楚这个是纯内容和元数据层面的工作比任何插件都重要。2.4 文章怎么写才规范front matter 与图片管理写作环节看似随意实际上“规范”决定了你后面能省多少事。我给自己定了几条硬规矩。第一每篇文章开头必须有完整的 front matter。这是 Markdown 文件最顶部的一小块 YAML 配置用来给 Hugo 和搜索引擎提供文章的基础信息--- title: 我的博客搭建之旅 date: 2025-01-18 tags: [博客, Hugo] categories: [技术] description: 从零到一搭建个人博客的完整过程 ---title 会在页面标题和文章列表里展示date 控制发布时间和排序tags 和 categories 帮你做内容归类description 最好手写一段简洁的页面描述让搜索引擎在搜索结果里展示更有吸引力的摘要。第二图片要统一管理。最简单的方案是把所有图片放在static/images下文章里用根路径引用比如。如果你图很多也可以把图片传到对象存储或图床但那样多了一个维护点也多了防盗链、跨域等问题所以我个人偏好还是和文章一起放仓库。第三图片必须压缩和规范命名。一张几 MB 的原图直接放进博客页面加载速度会非常感人。我习惯把图压到合适尺寸并转成 WebP文件名一律小写、用连字符分隔避免大小写混用导致线上路径对不上。这些小事看似繁琐但能在日后帮你避开很多莫名其妙的问题。3. 实操全流程把 my-blog 从零跑起来3.1 装好 Hugo五分钟生成第一个站点开始实操之前先把环境准备好。Hugo 是一个独立可执行文件安装非常简单不同系统的命令略有区别。macOS 用户可以用 Homebrewbrew install hugoLinux 用户可以去官方 GitHub Releases 页面下载对应架构的二进制解压后放入/usr/local/bin并赋予执行权限。Windows 用户推荐用 Scoopscoop install hugo安装完在终端执行hugo version能输出版本号就说明环境没问题。接着生成一个新站点hugo new site my-blog cd my-blog git init执行完目录里就是一份骨架代码。此时还没有主题直接打开页面也没法看所以先克隆一个主题进来git clone https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod然后在 hugo.toml 里把 theme 改成theme PaperMod启动本地预览hugo server -D浏览器访问http://localhost:1313能看到页面就说明整个链路通了。-D参数是让草稿文章也显示出来后续写草稿预览时很常用。3.2 写作、构建到发布的本地工作流站点跑通之后日常写作流程基本就是固定的三步。我每天打开终端进入博客目录执行hugo new post/文章名.md然后在编辑器里写正文。写完想预览效果就运行hugo server -D它会自动监听文件变化页面实时刷新。内容确认没问题后退出本地预览执行构建命令hugo --minify这条命令会把所有文章编译成最终的 HTML 页面输出到public目录。--minify会把 HTML 压缩去掉多余空白和注释减少文件体积。构建完成后把public目录里的文件部署到托管平台整站就更新了。如果每篇文章都要手动执行一遍构建、上传短期内还行时间久了绝对会烦。所以更合理的方案是让发布流程自动化这也是我下一步重点讲的。3.3 一次配置永久省心用 GitHub Actions 自动部署自动化部署我用的是 GitHub Actions方案直观且免费。核心逻辑一句话本地把 Markdown 源码推送到 GitHub云端自动执行 Hugo 构建再把生成的public目录发布到 GitHub Pages。以后你只要负责写和推发布这种重复劳动交给流水线完成。在仓库根目录创建.github/workflows/deploy.yml内容如下name: Deploy Hugo site on: push: branches: - main jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Install Hugo run: | HUGO_VERSION$(curl -s https://api.github.com/repos/gohugoio/hugo/releases/latest | grep tag_name | cut -d -f 4 | sed s/v//) wget -O hugo.tar.gz https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_${HUGO_VERSION}_linux-amd64.tar.gz tar -xzf hugo.tar.gz sudo mv hugo /usr/local/bin/ - name: Build site run: hugo --minify - name: Deploy to GitHub Pages uses: peaceiris/actions-gh-pagesv4 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./public这个工作流会在每次 push 到 main 分支时触发。它先自动下载最新版 Hugo然后构建站点最后把public文件夹推送到gh-pages分支。GITHUB_TOKEN是 GitHub 自动提供的不需要你自己创建密钥。第一次部署完成后进入仓库 Settings - Pages把发布源设置为 “Deploy from a branch”分支选择gh-pages保存后站点就能通过https://你的用户名.github.io/仓库名/访问了。如果你的仓库名就叫my-blog访问地址里就会带上/my-blog这个路径这也是我反复强调 baseURL 要和实际路径匹配的原因。3.4 绑定域名并搞定 HTTPS默认的用户名.github.io地址当临时预览没问题但想把博客当作品牌经营还是建议绑一个自己的域名。去域名服务商买一个合适的域名然后在 DNS 管理界面添加解析记录。如果你使用子域名比如blog.example.com添加一条 CNAME 记录主机记录blog记录值你的用户名.github.io如果你希望裸域名example.com也能直接访问需要按照托管平台的指引添加对应的 A 记录或 ALIAS 记录。如果 DNS 放在 Cloudflare还能顺便开启 CDN 和自动 HTTPS 证书访问速度和安全性都能得到一定改善。接着在博客仓库的static目录里新建一个CNAME文件内容填写你的自定义域名blog.example.com保存推送到 GitHubActions 会自动重新构建发布。这样每次构建后域名配置都会保留在产物里不会因为重新部署而丢失。HTTPS 证书方面GitHub Pages 和 Cloudflare 都能自动申请和续期你基本不用碰证书文件。4. 上线后我遇到的那些坑一个不落写给你4.1 页面样式全崩先检查 baseURL博客刚部署完打开页面发现没有任何样式类似纯文本堆在那里这是静态博客新手最常见的翻车现场九成以上都是 baseURL 配置问题。打个比方你本地写代码时 baseURL 是https://example.com但真正部署在https://username.github.io/my-blog生成的 HTML 里所有 CSS、JS 都按https://example.com/...去找线上自然什么都加载不出来。排查方法很简单。打开浏览器开发者工具切到 Console 或 Network 面板看看报错的资源请求地址是什么。如果它指向的域名和实际访问地址不一致就去 hugo.toml 改掉 baseURL重新构建发布。本地开发时保持http://localhost:1313不用管真正部署到哪个环境再把 baseURL 改成哪个环境的完整地址。4.2 图片本地正常线上却消失从三个方向排查本地预览一切正常部署完却发现图片全裂这个问题我遇到过太多次原因基本集中在三处。第一文件名大小写不一致。本地开发环境尤其在 macOS 和 Windows 上文件系统默认不区分大小写所以MyPic.png和mypic.png能正常显示。但线上 Linux 环境严格区分大小写路径对不上就直接 404。解决办法是从一开始就统一图片文件名全部小写用连字符。第二路径引用方式不对。文章里写但图片实际在static/images/my-pic.png目录层级对不上。建议统一使用根路径引用比如/images/my-pic.png并且先确认文件确实在对应目录里。第三用了图床或对象存储后图片地址本身不稳定或防盗链拦截。这种问题可以用无痕窗口直接打开图片地址验证如果图片能直接访问说明是引用路径或防盗链问题如果地址本身就打不开那就是图床那边的问题换一个托底方案解决。4.3 新文章迟迟不被搜索引擎收录怎么办搜索引擎收录是个慢过程尤其新站点急也没用但有几件事可以主动去做。首先是保证站点有 sitemap。Hugo 默认会生成/sitemap.xml里面列出了所有文章的地址。把它提交到 Google Search Console 和百度搜索资源平台是收录的基础动作。其次检查 robots.txt 是否存在且内容正确。绝大多数 Hugo 主题会自带如果没有就在 static 目录手动放一个User-agent: * Allow: / Sitemap: https://你的域名/sitemap.xml再次是文章自身的元数据。每篇文章写好 title 和 description内容本身有价值搜索引擎才会愿意收录和展示。最后是多渠道分发。发布后把文章链接分享出去社交平台、技术社区、邮件列表都可以。外链越多搜索引擎的爬虫越容易顺着链接找到你这是一个非常有效但常被忽略的收录加速手段。收录速度本身也很看运气通常几天到几周不等没必要一天刷三遍后台。4.4 写博客的头三个月我踩过的非技术坑技术坑其实是最好解决的搜一下基本都有答案。真正容易被忽视的反而是那些跟技术无关的习惯坑。第一个坑是主题更新把改动覆盖了。最开始我直接在themes目录里改主题源码主题作者一发新版我git pull之后所有定制全丢了。后来严格执行“改动放到 layouts 目录覆盖”的原则再没出现过这种问题。你要记住主题是别人家的代码我们能控制的只应该是自己的覆盖层。第二个坑是提交不勤。刚写博客时我经常脑袋一热写两三篇文章才想起来提交一次中间电脑出问题丢了差不多一周的稿子那种感觉真的很难受。现在我的习惯是每篇文章写完就提交一次commit message 尽量写清楚比如docs: add post about blog。Git 日志本身就是你的写作时间线回看特别方便。第三个坑是过度关注 SEO 导致内容变形。有一段时间我特别迷信关键词密度写文章时刻意堆词结果文章读起来生硬别扭搜索效果反而更差。后来彻底想通了搜索引擎只是工具真正留得住读者的是内容本身。回归正常写作之后博客的数据反而更稳了。最后再分享一个小心得。如果你打算长期维护一个博客请把它当成一个“作品集”而不是“炫技场”。技术方案可以简单域名可以不贵主题可以朴素真正决定这个博客价值的永远是你写下来的那些内容。我搭 my-blog 到现在换过主题、换过域名、换过部署流程唯一不变的就是写作这件事本身想清楚写明白发布出去不断迭代。希望读到这里的你也能尽早搭起属于自己的那一块自留地然后好好打理它。