0 元博客搭建教程

Fri, 13 Mar 2026 16:46:47 +0800

一、安装 hugo

# 1. 创建新站点（文件夹名随便取，比如 myblog）
hugo new site myblog
cd myblog

# 2. 初始化 Git 仓库
git init

# 3. 安装 Stack 主题 (作为 submodule 安装，方便后续更新)
git submodule add https://github.com/CaiJimmy/hugo-theme-stack/ themes/hugo-theme-stack

# 4. 复制示例配置 (这是最关键的一步，Stack 的配置比较复杂，直接抄作业)
# 注意：新版 Stack 使用 hugo.yaml，旧版是 config.toml，这里以 yaml 为准
cp themes/hugo-theme-stack/exampleSite/hugo.yaml .
cp -r themes/hugo-theme-stack/exampleSite/content/* content/
# 如果是 Windows，请手动在文件管理器里把 exampleSite 里的 hugo.yaml 复制到根目录替换，content 里的内容也复制过去

此时，运行 hugo server，访问 http://localhost:1313，应该能看到一个漂亮的 Stack 主题演示站了。

报错：

原因：

日志里有一行： Watching for config changes in .../hugo.toml

但是之前从主题里复制过来的是 hugo.yaml。 Hugo 会优先读取默认生成的 hugo.toml（它是空的），从而忽略复制过来的 hugo.yaml（它是配置好的）。 这会导致网站打开后是一片空白或者排版混乱。

解决：rm hugo.toml

重新启动 hugo server：

浏览器效果：

二、部署 Waline 评论系统 (服务端)

需要先搞定评论系统的后端，拿到那个 Server URL。然后使用 Vercel + LeanCloud (国际版) 的方案，免费且无需备案。

1. 注册/登录 LeanCloud 国际版

访问 LeanCloud 国际版 (不需要手机号实名，邮箱即可)。
创建一个应用，名字叫 waline-blog。
进入应用 -> Settings (设置) -> App Keys (应用凭证)。
记下这三个值：App ID, App Key, Master Key。

2. 一键部署到 Vercel

点击这个 Waline 一键部署链接 (这是 Waline 官方提供的模板)。
登录 GitHub 授权 Vercel。
在 Create Git Repository 页面，直接点 Create。

关键步骤：Configure Project (配置环境变量)
- 在部署页面会让你填 Environment Variables。
- 填入刚才在 LeanCloud 获取的三个值：
  - LEAN_ID: 对应 App ID
  - LEAN_KEY: 对应 App Key
  - LEAN_MASTER_KEY: 对应 Master Key

点击 Deploy。等待几分钟。

3. 获取 Server URL

部署完成后，点击 Go to Dashboard。
在 Vercel 给你的项目分配的域名中，找到类似 waline-xxxxx.vercel.app 的地址。
复制这个地址，这就是你的 serverURL。

三、配置 Hugo 并上传到 GitHub

回到本地代码。

1. 修改 `hugo.yaml` 配置 Waline

打开根目录下的 hugo.yaml，找到 params.comments 部分，修改如下：

params:
  # ... 其他配置 ...
  
  comments:
    enabled: true
    provider: waline

    waline:
      # 粘贴刚才在 Vercel 获得的地址，注意没有最后的斜杠
      serverURL: "https://项目名.vercel.app"
      lang: zh-CN
      pageview: true # 开启阅读量
      emoji: 
        - https://unpkg.com/@waline/emojis@1.1.0/weibo

同时，记得修改最顶部的 baseURL（先空着或者填个临时的，等下 Cloudflare 分配了域名再回来改，不改也没大问题，Cloudflare 会处理）。

2. 推送到 GitHub

在 GitHub 上新建一个 Public 仓库（比如叫 my-tech-blog）。

# 回到本地终端
git add .
git commit -m "Initial commit with Stack theme and Waline config"
git branch -M main
git remote add origin https://github.com/用户名/my-tech-blog.git
git push -u origin main

四、Cloudflare Pages 部署 (前端)

最后一步，把 GitHub 上的静态页面通过 Cloudflare 发布到互联网。

登录 Cloudflare Dashboard。
左侧菜单选择 Workers & Pages -> Create application -> Connect to Github。

查看 GitHub 账号右上角有个绿点表示认证成功，点击底部的 Get started。

构建配置 (Build settings) - 关键！
- Project name: 随便填（这将决定默认域名，如 myblog-demo.pages.dev）。
- Production branch:main
- Framework preset (框架预设): 选择 Hugo。
- Build command: 默认应该是 hugo (如果它没自动填，就手填 hugo)。
- Build output directory:public
点击 Save and Deploy。

Cloudflare 会自动拉取代码、安装 Hugo、构建网站。几秒钟后，你会看到一个绿色的 Success。点击分配给的 xxx-blog.pages.dev 域名，博客就上线了！

五、最后的验证与日常使用

验证评论： 打开博客任意一篇文章，拉到底部，看看 Waline 评论框是否出现，试着发一条评论。如果不显示，检查一下 Vercel 那个链接是否能直接访问，或者 F12 看控制台有没有报错。

日常写文章流程：
- 本地终端：hugo new post/my-first-tech-article.md
- 在 content/post/ 目录下找到文件进行写作。
- 注意： 记得把文件头部的 draft: true 改为 draft: false，否则发布后看不到。写完后提交：

1
2
3

git add .
git commit -m "Add new article"
git push

Cloudflare 感知到 GitHub 有更新，会自动触发构建，几十秒后线上就更新了。

六、Markdown 头部配置

Hugo 的 Markdown 头部配置（学名叫 Front Matter ）确实有很多参数，但不需要全部都记住。

1. 基础必填项（最常用的）

这些是每篇文章必须有的，控制文章的基本显示。

---
title: "我的第一篇 Python 爬虫实战"      # 文章标题
date: 2025-12-13T18:00:00+08:00      # 发布时间 (Hugo 根据这个排序)
draft: false                         # 是否为草稿 (true=只有本地能看，false=发布上线)
slug: "python-scrapy-tutorial"       # 自定义 URL 尾缀 (强烈建议设置，比默认的中文拼音/乱码 URL 更好看)
---

2. 分类与标签（用于组织文章）

Stack 主题会在侧边栏和文章卡片上显示这些信息。

categories:     # 分类（建议每篇文章只写 1 个，类似文件夹）
    - "后端开发"
tags:           # 标签（可以写多个，类似关键词）
    - "Python"
    - "Scrapy"
    - "教程"

3. Stack 主题特别优化的参数（推荐）

主题 hugo-theme-stack 对以下参数有很好的支持，建议用上，会让博客看起来更精致：

description: "这篇文章详细介绍了如何使用 Scrapy 绕过反爬机制..."  # 文章摘要 (显示在主页卡片上，不写会默认截取正文前几个字)
image: "cover.jpg"      # 封面图 (Stack 是卡片式布局，有图会好看很多。默认读取同目录下的图片)
comments: true          # 是否开启评论 (如果你配置了评论系统，某篇不想让人评论可以设为 false)
license: "CC-BY-NC-4.0" # 版权协议 (Stack 会在文章底部显示版权信息)

4. 进阶控制（偶尔用到）

weight: 1       # 置顶权重 (数字越小越靠前，想置顶某篇文章时用)
aliases:        # 重定向 (如果你改了 URL，想让旧链接跳转到新链接时用)
    - /posts/old-url/
hidden: true    # 在首页列表中隐藏 (但可以通过链接直接访问)

💡 偷懒技巧：VS Code 代码片段 (User Snippets)

配置太麻烦了，作为程序员，我们肯定要 自动化 。可以利用 VS Code 的“用户代码片段”功能，输入 header 然后按 Tab 键，瞬间生成这一大坨配置。

操作方法：

VS Code 中点击左下角齿轮 -> 用户代码片段 (User Snippets)。
搜索 markdown，选择 markdown.json。
把下面的 JSON 粘贴进去：

{
  "Hugo Front Matter": {
    "prefix": "header",
    "body": [
      "---",
      "title: \"$1\"",
      "date: $CURRENT_YEAR-$CURRENT_MONTH-$CURRENT_DATE",
      "slug: \"$2\"",
      "image: \"$3\"",
      "categories:",
      "    - $4",
      "tags:",
      "    - $5",
      "draft: true",
      "---",
      "",
      "$0"
    ],
    "description": "Insert Hugo Front Matter"
  }
}

以后写博客：

只需要在一个空白 .md 文件里输入 header 然后回车，它就会自动填好今天的日期，光标会自动跳到 title 等待你输入。

注意！如果装了预览插件发现输入 header 后没有提示自动生成，点击“Edit in VSCode”。

slug (URL 尾缀) 的命名规范：（对以后博客的 SEO - 搜索引擎收录比较重要）

slug: "英文-关键词-全小写-用横杠连接"

总结

这套方案：

域名： Cloudflare 送的 .pages.dev (无需备案，海外访问极快)。
服务器： Cloudflare (前端) + Vercel (后端)。
数据库： LeanCloud (国际版)。
费用： 全程 $0。

博客搭建 on Nanzet