Simon's Blog
所有文章 标签 分类 关于 赛道雷达
Simon's Blog

目录

Hugo + LoveIt 博客优化复盘：从搭建到可复现配置

Simon 收录于 博客
     约 3683 字   预计阅读 8 分钟  阅读 -
/images/posts/hugo-loveit-blog-optimization-notes/featured.jpg

汇总本站自搭建以来的优化与落地步骤，便于对照仓库复现。

  • 站点：https://blog.leeissonba.com/
  • 主题：LoveIt · 部署：Cloudflare Workers 静态资源
  • 仓库：https://github.com/simonlee-hello/MyBlog

1. 背景与目标

个人博客基于 Hugo Extended + LoveIt，需要同时满足：

  • 中文为默认语言，英文可切换阅读
  • 从 Obsidian / Typora 写稿，尽量自动补 front matter、配图、英文版并发布
  • 部署到 Cloudflare，绑定自定义域名
  • 评论、前台阅读量、后台访客分析各自就位
  • 代码块 / 视频等排版不翻车

各节给出对应路径与配置要点，可直接对照仓库当前状态。

2. 项目骨架与本地命令

本章约定仓库布局、本地命令与忽略规则，是后续覆盖模板、样式与部署的前提。

2.1 关键目录

.
├── archetypes/          # 新建文章模板
├── assets/css/          # _custom.scss 覆盖主题样式
├── content/posts/       # 文章（中文 .md / 英文 .en.md）
├── drafts/              # 本地草稿（已 gitignore，不进仓库）
├── layouts/             # 覆盖主题模板（勿改 themes/LoveIt）
├── static/              # 图片、视频、favicon
├── themes/LoveIt/       # Git submodule
├── .cursor/skills/      # hugo-blog-publish / loveit-theme
├── build.sh / wrangler.jsonc / package.json  # Cloudflare 构建
├── hugo.toml
└── Makefile

2.2 常用命令

make dev      # hugo server -D
make build    # HUGO_ENV=production hugo --minify
make clean
注意
LoveIt 的评论、CDN、部分分析脚本只在 hugo.Environment == production 时启用。本地验证评论请运行：HUGO_ENV=production hugo server

2.3 .gitignore

public/、resources/、.hugo_build.lock、.cache/、drafts/ 已忽略。

  • 不影响发布：Cloudflare 构建时在 CI 里重新 hugo build 生成 public/，不依赖仓库里的产物。
  • drafts/ 只留在本机，审稿通过后再发布到 content/posts/。

3. Hugo 弃用 API 修复

新版 Hugo 对 .Site.LanguageCode、.Language.LanguageName、.Sites、配置项 languageCode 等发出弃用警告。

原则：不改 submodule 内主题源码，在项目 layouts/ 覆盖对应模板。

覆盖文件调整要点
layouts/baseof.htmllang 用 .Site.Language.Locale
layouts/_partials/header.html语言切换用 hugo.Sites、.Language.Label
layouts/_partials/head/seo.htmlLocale 同上
layouts/_partials/init.html去掉开发环境多余 warn；生产环境再挂 comment / analytics
layouts/home.rss.xml 等 RSSLocale 同上

配置侧：语言块使用 locale（本站中文为 zh-CN，英文为 en），不再依赖已弃用的 languageCode 写法。

4. 中文默认与双语内容约定

默认语言与文件命名必须一致，否则语言切换后文章列表会空。

4.1 站点语言

hugo.toml：

  • defaultContentLanguage = "zh-cn"
  • [languages.zh-cn] weight 更小（优先）
  • [languages.en] 为英文站

4.2 文件命名（重要）

默认语言是中文时：

语言路径
中文content/posts/{slug}.md（不要用 .zh-cn.md）
英文content/posts/{slug}.en.md

About 页同理：content/about/index.md + index.en.md。

若把英文写在无后缀的 .md、中文写成 .zh-cn.md，切换到 /en/ 时会看不到英文文章——这是早期踩过的坑。

4.3 社交媒体

[params.home.profile] social = true，并配置 [params.social]（如 GitHub、Email、RSS）。首页 Profile 才会显示社交图标。

5. 内容写作与发布工作流

从草稿到上线的约定：front matter、配图、媒体路径，以及 Cursor skill 如何协助发布。

5.1 发布流程（最小集）

  1. 在 Obsidian / Typora / drafts/ 写中文 Markdown
  2. 用 Cursor skill hugo-blog-publish 发布（默认：补 front matter、配图、译英文、hugo build、commit + push）
  3. 若指定仅本地验证则跳过 push；若指定仅中文则不生成 .en.md

5.2 front matter 约定

---
title: ""
date: 2026-07-13T12:00:00+08:00
draft: false
description: ""
categories: []
tags: []
featuredImage: "/images/posts/{slug}/featured.jpg"
featuredImagePreview: "/images/posts/{slug}/featured.jpg"
---
  • 第一段后插入 <!--more--> 作为摘要分隔
  • 中英文共用同一套配图 / 媒体路径

5.3 媒体路径

类型目录正文引用
配图 / 插图static/images/posts/{slug}//images/posts/{slug}/...
视频static/videos/posts/{slug}//videos/posts/{slug}/...

视频推荐：

<video controls playsinline preload="metadata" src="/videos/posts/{slug}/demo.mp4"></video>

外链图、Bilibili / YouTube 不强制下载进仓库；B 站可用 LoveIt bilibili shortcode。

5.4 LoveIt 写作技巧 skill

另有 loveit-theme skill（与 publish 联动）：admonition、image、mermaid、math、Giscus、访问量等速查。发布时会按需把提示改成 admonition、B 站链接改成 shortcode 等。

官方文档见 LoveIt。

6. 排版修复：代码与视频

线上曾出现：超长代码行撑破代码框；<video> 宽度与正文不一致。在 assets/css/_custom.scss 中处理：

  • 代码块：max-width: 100%、overflow-x: auto、必要时 pre-wrap
  • video：width/max-width: 100%、display: block、height: auto

正文侧仍建议对极长命令行适度断行，观感更好。

7. 部署到 Cloudflare Workers

静态站点按 Hugo 官方 Cloudflare 文档 接入；本站使用 Workers 静态资源模式。

7.1 仓库内文件

文件作用
wrangler.jsoncWorker 名（如 simons-blog）、assets.directory = ./public
build.sh安装 Hugo Extended、更新 submodule、HUGO_ENV=production hugo build
package.json便于构建缓存

Cloudflare 控制台中的项目名应与 wrangler.jsonc 的 name 保持一致。

7.2 Dashboard 注意点

  • 纯静态 Worker：不要在「变量和密钥」（运行时）里配 HUGO_BASEURL
  • 构建相关变量应放在 Build variables，或直接写死 hugo.toml 的 baseURL（本站已用 https://blog.leeissonba.com）
  • 自定义域名在 Workers → Domains 绑定即可

7.3 submodule

主题是 submodule，Cloudflare 构建脚本里需 git submodule update --init --recursive，本地 clone 也要带 submodule。

8. 评论：Giscus

曾评估 Valine（LeanCloud），最终改用 Giscus（基于 GitHub Discussions）。

8.1 前置

  1. 仓库 Public
  2. 开启 Discussions
  3. 安装 giscus GitHub App 并授权本仓库

8.2 本站配置（hugo.toml）

[params.page.comment]
  enable = true
  [params.page.comment.giscus]
    enable = true
    repo = "simonlee-hello/MyBlog"
    repoId = "R_kgDOTVNnWg"
    category = "Announcements"
    categoryId = "DIC_kwDOTVNnWs4DBC6N"
    mapping = "pathname"

repoId / categoryId 是 GitHub GraphQL 公开节点 ID，会出现在页面源码中，不属于密钥，可随站点配置公开。

单篇关闭：comment: false。
仅 production 构建加载；本地需 HUGO_ENV=production。

评论数据在仓库 Discussions 中管理。

9. 访问统计：两套分工

用途方案说明
站长后台分析Cloudflare Web Analytics本站域名挂在主域 leeissonba.com 下，子域 blog.* 流量已出现在同一报表，过滤 Host 即可
前台展示数字自托管 Worker + D1（services/web-analytics）页脚全站 PV/UV + 文章 meta 阅读量；数据归自己

Cloudflare Web Analytics 不能把数字渲染到页面上（无公开前台接口）。曾用过不蒜子/Vercount，第三方计数会丢数重置，已弃用。

本站前台方案基于 analytics_with_cloudflare，并按 Hugo 自托管访问量实践 补上全站 spv / suv。对照仓库即可复现。

9.1 架构

  • 独立 Worker web-analytics（与博客静态站 myblog / simons-blog 分开）
  • D1 库 web_analytics 存访问记录
  • 浏览器 POST /api/visit：写入一条访客，并按需返回单页 pv、全站 spv / suv
  • Hugo 仅在 production 加载脚本（与 Giscus 一致）

9.2 部署计数 API（Cloudflare）

在仓库子目录操作（勿与根目录 Hugo 的 wrangler.jsonc 搞混）：

cd services/web-analytics
npm install
npx wrangler login
npx wrangler d1 create web_analytics
# 将返回的 database_id 写入本目录 wrangler.jsonc
npm run initSql
npm run deploy

注意：

  • npm run deploy 已带 --config wrangler.jsonc。若误用仓库根配置，会去跑 Hugo 的 build.sh 并报错
  • Dashboard → Workers → web-analytics → 添加自定义域，例如 analytics.leeissonba.com（workers.dev 在部分地区不可用）
  • 冒烟：POST https://analytics.你的域名/api/visit，body 含 hostname、url、spv: true 等，应返回 {"ret":"OK","data":{...}}

9.3 Hugo 前台接入

关键文件：

路径作用
services/web-analytics/Worker + D1 源码与 wrangler.jsonc
assets/js/analytics.js请求 API，回填 #page_pv / #site_pv / #site_uv
layouts/_partials/plugin/web-analytics.html仅 production 注入 fingerprint 脚本
layouts/_partials/footer.html全站 PV/UV 占位 + 加载脚本（全站一次）
layouts/posts/single.html文章 meta「阅读量」#page_pv
hugo.toml → [params.webAnalytics]开关与 baseURL

配置示例：

[params.webAnalytics]
  enable = true
  baseURL = "https://analytics.leeissonba.com"  # 与自定义域一致

页脚占位示例：

本站总访问量 <span id="site_pv">-</span> 次 | 访客 <span id="site_uv">-</span> 人

文章 meta 占位示例：

阅读 <span id="page_pv">-</span>

实现注意：

  • 脚本只在 footer 加载一次，避免重复计数
  • 去掉上游 demo 里对 document.head.innerHTML 的注入（会重建 head，易弄坏主题脚本）
  • 本地验证：HUGO_ENV=production hugo server；普通 hugo server 不加载、不计数
  • 推送博客仓库后，等静态站重建，线上才会出现数字

9.4 验收

  1. 打开任意文章：meta 阅读量有数字；刷新应递增
  2. 页脚全站人次 / 访客有数字
  3. Cloudflare 里看 web-analytics Worker 的请求量（不是博客静态站 myblog 的 0 请求）

10. 配置开关速查

# 评论
[params.page.comment]
  enable = true

# 前台访问量（自托管 Worker + D1）
[params.webAnalytics]
  enable = true
  baseURL = "https://analytics.leeissonba.com"

# 首页社交图标
[params.home.profile]
  social = true

主题相关覆盖一律放在项目 layouts/、assets/，升级 LoveIt submodule 时冲突面更小。

11. 复现检查清单

从零对齐本站时，建议按序确认：

  1. Hugo Extended + git submodule update --init
  2. hugo.toml：baseURL、默认语言、社交、Giscus、webAnalytics
  3. Cloudflare 博客项目名与根目录 wrangler.jsonc 的 name 一致
  4. layouts/ 弃用 API 覆盖 + footer / posts/single / web-analytics partial
  5. assets/css/_custom.scss 代码与视频样式；assets/js/analytics.js 已就位
  6. Cloudflare 博客：连接仓库、构建脚本、自定义域名、HUGO_ENV=production
  7. Giscus App 已安装；Discussions 已开
  8. （可选）Web Analytics 过滤 blog. 子域
  9. 部署 services/web-analytics：D1 + Worker + 自定义域，与 baseURL 一致
  10. 发布用 Cursor skills：hugo-blog-publish + loveit-theme
  11. 试发一篇：中英文、featuredImage、本地媒体路径、<!--more-->；生产环境核对阅读量

12. 参考资料

更新于 2026-07-29
 Hugo, Loveit, Cloudflare, Giscus, Analytics, D1
返回 | 主页