Focus On Today
所有文章 系列 分类 标签
友链
导航
关于
Focus On Today

使用hugo搭建静态博客

FocusOnToday  收录于  类别 学习 和 系列 建立自己的博客
     约 3108 字   预计阅读 7 分钟    次阅读     条评论  
系列 - 建立自己的博客

最近打算建立一个自己的博客，在查阅一些资料后，决定采用静态博客这种方式，下面整理下自己的搭建过程。

需要准备的内容如下

  • 一个域名，托管在 cloudflare 上
  • 一个 github 账号。用于存放博客及其它相关服务的源文件。
  • 本地安装好 hugo。用来进行本地的静态博客调试。
  • 一个 vercel 账户，用于提供静态博客的在线访问以及相关在线服务的运行。

  1. 创建 github 私有仓库，用来存放博客相关文件，这里起名为 blog-hugo

  2. 在当前目录下创建本地博客文件

    hugo new site blog-hugo

  3. themes 文件夹中添加主题，我用的是 DoIt，文档地址

  4. 进行环境配置，可以把主题中 exampleSite/config 这个文件夹直接复制到博客根路径下，之后再根据需要进行部分调整

  5. 将博客资料纳入 git 版本管理，并推送给刚刚创建的 github 私有仓库，根路径下命令行执行

    git init
git add -A .
git commit -m "博客初始化"

git remote add origin 仓库地址
git branch -M main
git push -u origin main

  6. 关闭 git 中的 quotePath，可选步骤。如果以后希望用 github 提交时间作为文章的更新时间，不再手动编辑这个值，可以开启enableGitInfo=true，而关闭 quotePath 就是为了让这个设置生效。因为如果文章涉及到中文，路径会被 git 自动调整，结果导致最后 hugo 看不到相应的 git 提交信息。

    要让本地部署环境生效的话，命令是

    git config --local core.quotePath false

    要让 vercel 环境生效的话，则这么做

    项目主页 -> settings -> general -> Build & Development Settings

    在 INSTALL COMMAND 一栏中打开 OVERRIDE

    然后输入 git config core.quotePath false 并重新构建

主题官方的做法可参考文档，大致是

  1. 在 content 文件夹下创建 posts 文件夹

  2. posts 文件夹直接放入 md 文件，并且在文件内容开头处加入必要的前置参数，如下

    ---
title: "使用hugo搭建静态博客"
date: 2023-10-21
draft: false
authors: ["FocusOnToday"]
description: "使用 hugo 和 vercel 搭建静态博客服务"
featuredImage: "featured-image.webp"

categories: ["学习"]
tags: ["博客"]
series: ["建立自己的博客"]
series_weight: 1
lightgallery: true
---
<!--more-->
    • title: 博客标题
    • date: 创建日期
    • authors: 作者列表
    • description: 文章摘要，注意别漏加了<!--more-->，且保证前面除了前置参数外没有其它内容
    • featuredImage: 背景图片路径
    • categories: 归属分类
    • tags: 归属标签
    • series: 归属系列
    • series_weight: 在当前系列文章中的显示顺序
    • draft: 设置成 false 用来保证本地测试时文章正常渲染
    • lightgallery: 设置成 true，则文章中的图片将可以按照画廊形式呈现

但是测试下来有个问题，那就是主页的文章预览图加载失败，如果按照官方说的放在博客根路径下的 assets 目录中，那显示就没问题了，但是总感觉文章资源不该是这种放法。后来参考了 hugo 官方给出的一种结构，文档地址，换了另外一种目录结构，如下

  1. 在 content 文件夹下创建 posts 文件夹
  2. 对于每篇文章，专门建立一个同名文件夹来存放，且文章的文件名要改为 index.md
  3. 对于博客涉及到的背景图片，存放在该文件夹中，建议统一设置为 featured-image.webp
  4. 至于其它图片等资源，在当前文件夹下再建立一个文件夹用来存放，如果使用 typora 的话，那这一步可以自动化进行
  5. 在文件内容开头处加入前置参数，之前已提过，略过

如果在静态博客中要显示关于页面，可以在 content 文件夹下建立 about文件夹，其中放入的 markdown 内容即为关于页面所展示的，文件要命名为 index.md

下面是测试命令，博客根目录下进入命令行执行

hugo --environment production server

上述命令会开启所有功能，包括评论等，如果只想展示文章效果，可以用下面的命令

hugo server

  1. 在项目根路径下新建 vercel.json 文件，用于控制 hugo 版本，假设版本是 0.110.0，内容如下。然后推送下仓库

    {
  "build": {
    "env": {
      "HUGO_VERSION": "0.110.0"
    }
  }
}

  2. 注册 vercel

  3. 在 vercel 中导入之前创建的 github 私有仓库，并进行部署

  4. 处理 vercel 域名被屏蔽的问题。vercel 官方虽然会提供一个域名，但是大陆地区是无法连上的，解决方案是给这个项目加个自己的域名。做法是，项目 setting-domains 中，填入自己的域名，比如 hello.com，然后会提示你去配置 dns 解析记录，根据它提供的信息，在 cloudflare 对应域名中建立 dns 解析记录（记得关闭代理，即把 proxy status 设置为 dns only，这样后续才能看到访问者的来源信息），同时把 SSL/TSL 设置中的 encryption mode 改为 full

  5. 耐心等待 vercel 域名页面自动配置完毕，就可以通过该域名访问静态博客了

  6. 之后每推送一次内容到 github 仓库，vercel 都会自动帮我们构建部署

我选择的是 waline，DoIt 默认支持，使用它需要自己部署，需要一个后端和一个数据库，vercel 可以提供后端访问能力，数据库我用的是官方推荐的 leancloud 国际账号，都是免费滴

不过部署过程采用官方的 vercel 一键部署方式会出错，暂时没弄明白原因。那就换个思路，先配置好源代码部分，再让 vercel 去拉取构建部署，发现可行。

过程如下

  • 创建 leancloud 国际账号，再创建一个数据库服务
  • 新建一个 github 私有仓库，并把 waline 的 github 项目中的 example 下内容（排除 .env.example 文件）推送到这个仓库中
  • vercel 导入 github 私有仓库，框架类型选择 other，在环境变量中配置好 LEAN_ID、LEAN_KEY、LEAN_MASTER_KEY 以及对应的值，值可以通过 leancloud 获取
  • 然后就是 vercel 项目域名的配置，这一步和之前的类似，就略过了，注意域名前面加个前缀，比如 xx.hello.com，因为 hello.com 已经被博客服务占用了
  • 把子域名填入到博客项目的配置文件中，推送到 github 仓库中
  • 评论的管理页面是 评论域名/ui，第一个注册的会成为管理员

如果换用 Giscus 评论系统的话，配置起来会更加方便，而且DoIt这个主题也是支持的，下面也简单说下流程

  • 新建一个公开 github 仓库，专门用来存储评论，并在setting-General-Features-Discussions 中设置启用
  • 到这个网页，根据流程依次操作下来即可，其实也就是安装 Giscus、输入仓库名、分类选择公告（announcements）类型
  • 最后把末尾的配置写入博客的相关配置文件即可

我用的是 waline，它是可以在未登录情况下进行评论的，注册登录也比较方便。如果遭到攻击的话，会出现两个问题

  • 我得花很多时间去处理机器人发送的垃圾评论
  • 部署 waline 时用到了 leancloud 提供的数据库服务，而免费的服务是有限制的，指不定什么时候就给我整挂了

所以就需要一些机制来过滤掉简单的攻击请求，而 waline 系统本身是支持 cloudflare 提供的 TURNSTILE 和 Google 提供的 reCAPTCHA V3 的。不过测试后发现，貌似根据 waline 文档配置了相关的参数也没用，可能 DoIt 主题对于 waline 验证特性的支持度不够吧。

后来自己试着调下源码，总算是能让 reCAPTCHA V3 正常使用了，不过 TURNSTILE 还是没办法。体验下来后，发现 reCAPTCHA V3 还挺好用的，平时基本感知不到它的存在。

下面说下源码的大致修改操作吧，不保证绝对不出问题，毕竟前端也不太懂。

可以发现 themes/DoIt/layouts/partials/comment.html 中有关于 waline 参数的配置，于是在下面这段代码中自己添加了对于参数的支持，其实就是依样画葫芦加了个片段。

把下面的

{{- if eq $waline.texRenderer false -}}
    {{- $commentConfig = dict "texRenderer" false | dict "waline" | merge $commentConfig -}}
{{- end -}}

改为

{{- if eq $waline.texRenderer false -}}
    {{- $commentConfig = dict "texRenderer" false | dict "waline" | merge $commentConfig -}}
{{- end -}}
{{- with $waline.recaptchaV3Key -}}
    {{- $commentConfig = dict "recaptchaV3Key  " . | dict "waline" | merge $commentConfig -}}
{{- end -}}

这次选用的是 umami 开源统计系统，拉取下官方的 github，然后通过 vercel 构建运行服务，数据库用到 supabase，提供免费 postgres 数据库，虽说只有 500m，但存放统计数据足够用了。

整个过程如下

  • 克隆 umami 官方项目，地址

  • 注册 supabase 账号，创建一个数据库，注意数据库密码大小写字母 + 数字即可，之前用了特殊字符#，结果 vercel 一直连不上数据库，然后准备好连接，postgresql://用户名:密码@主机:端口/数据库名，根据数据库 setting 中的参数填充

  • vercel 导入自己的 github 对应仓库，其余默认，环境变量至少要填写两个，之后部署就行，表会由 vercel 自己去连数据库创建

    DATABASE_URL=之前配置好的连接
HASH_SALT=任意字符串，最好别放特殊字符
TRACKER_SCRIPT_NAME=任意字符串，避免被广告屏蔽软件标记，可选参数

  • 给 vercel 分配子域名，这个提过了，那就略过

  • 访问子域名，用户名admin，密码umami，进入后先改个密码

  • 然后添加网站，名字填 blog，域名填写博客域名，需要配置到博客里的就是里面那串跟踪代码。以 hugo 的 DoIt 主题为例，需要把 src 和 data-website-id 填入进去，另外两个参数留空

相关内容

改造自己的主题

更新于 2024-06-23
 博客
返回 | 主页