手把手搭建技术博客：从零到部署的完整避坑指南

作者： /

先别急着买服务器，我们得先想清楚：你的博客是给谁看的？如果是给技术同行的，那就要快、要干净、要支持代码高亮。如果是给客户的，那就要好看、要支持 SEO。我选择的是前者，因为踩坑经验最好的观众就是开发者。

（开篇配图：一个开发者站在一排服务器前，表情是“我悟了”的苦笑）

第一步：选框架，别选 WordPress
WordPress 太重了，而且安全漏洞多得像筛子。我推荐用 Hugo 或 Hexo，这两个都是静态博客生成器，生成的是纯 HTML，部署在 CDN 上，几乎不用管安全。我选 Hugo，因为它编译速度快，从 Markdown 到 HTML 只要 0.3 秒。

配置 Hugo 其实很简单，但官方文档那段配置说明文档不够清晰，我来给你翻译成人话：

“`bash
# 安装 Hugo（Mac 用户用 Homebrew）
brew install hugo

# 创建新站点
hugo new site my-blog

# 初始化 Git 仓库（这步很重要，不然没法部署）
cd my-blog
git init

# 安装一个主题（我推荐 loveit，干净又支持代码高亮）
git submodule add https://github.com/dillonzq/LoveIt.git themes/LoveIt
“`

这里有个坑：如果你用 `git clone` 而不是 `git submodule`，以后更新主题会非常痛苦。我第一周就因为这个重装了两次。

第二步：写配置，别被默认模板骗了
默认的 `config.toml` 文件基本是废的，你得自己写。这是我最常用的配置模板：

“`toml
baseURL = “https://yourdomain.com”
languageCode = “zh-CN”
title = “你的博客名字”
theme = “LoveIt”

[params]
# 开启代码高亮
enableCodeCopy = true
# 开启评论（用 Giscus，基于 GitHub Discussions，免费且无广告）
[params.page.comment.giscus]
enable = true
repo = “你的GitHub用户名/博客仓库名”
repoID = “从Giscus官网获取”
category = “Announcements”
categoryID = “从Giscus官网获取”
“`

为什么要这么写？因为这是最稳的配置，开启代码高亮可以让你的技术文章看起来专业，评论系统用 Giscus 不用 Disqus（Disqus 太慢，而且有广告，用户体验很差）。

（核心配图：Hugo 生成的博客首页截图，干净、无广告、代码高亮）

另一个坑：图片资源管理
如果你直接把图片放在 `content` 目录下，Hugo 会把它当成页面来处理，导致生成多个无用的 HTML。正确做法是建一个 `assets/images` 目录，然后在文章里用相对路径引用：

“`markdown
![Hugo 配置界面](images/hugo-config.png)
“`

这样 Hugo 只会把图片原样复制到 `public` 目录，不会生成垃圾文件。

第三步：写文章，别用富文本编辑器
我建议直接用 Markdown 写，在 VS Code 里装一个 `Markdown Preview Enhanced` 插件，实时预览。写文章时注意三点：

  • 文件名用英文，用 `-` 分隔，比如 `build-blog-tutorial.md`
  • 头部信息（Front Matter）要写全：

    • “`yaml
    —
    title: “手把手搭建技术博客”
    date: 2024-01-15
    draft: false
    tags: [“博客”, “Hugo”, “教程”]
    —
    “`

  • 每篇文章至少放两个代码块，因为读者（尤其是开发者）更信任代码而不是文字。

    • 第四步：部署，别用传统服务器
    传统的 VPS 方案太落后了，你要自己配 Nginx、装证书、处理备份。我用的是 Netlify 或 Vercel，这两个平台都支持从 GitHub 自动部署，而且免费额度足够了。

    部署步骤：

  • 把博客仓库推到 GitHub
  • 在 Netlify 上选择“从 Git 仓库创建站点”
  • 配置构建命令：`hugo`，输出目录：`public`
  • 绑定自定义域名，自动签发 SSL 证书

    • 这样，你每次往 GitHub 推送代码，Netlify 会自动重新构建并部署。从推送代码到上线，不到 30 秒。

    还有个技巧：开启 Netlify 的“部署预览”功能，这样你可以先在分支上测试文章效果，确认无误后再合并到主分支。我因为这个功能避免了好几次“文章排版车祸现场”。

    第五步：备份，别等丢了才后悔
    静态博客最大的风险是本地写的内容没备份。我的方案是：所有内容都保存在 GitHub 仓库里，同时在本地和云端各存一份。

    在 `config.toml` 里加一个参数，开启 Hugo 的构建优化：

    “`bash
    # 在项目根目录执行
    hugo –gc –minify
    “`

    这个命令会生成一个压缩后的 `public` 目录，直接部署就行。但注意，这不会自动备份——真正的备份要靠 Git 推送。建议每次写完文章后执行：

    “`bash
    git add .
    git commit -m “更新文章”
    git push origin main
    “`

    这样你的内容就安全地存在 GitHub 上了，永不丢失。

    总结一下，你可以立刻用的三个点：

  • 选 Hugo 加 Netlify，维护成本最低，速度最快
  • 用 Giscus 做评论，免费、无广告、支持 Markdown
  • 所有内容放 GitHub，自动备份，永不丢失

    • （结尾配图：一个开发者坐在电脑前，背景是 GitHub 和 Netlify 的图标，表情是“搞定”的轻松）

    滚动至顶部