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

• 站点：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

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/ 覆盖对应模板。

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

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

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

4.1 站点语言

hugo.toml：

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

4.2 文件命名（重要）

默认语言是中文时：

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 媒体路径

视频推荐：

<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 仓库内文件

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 不能把数字渲染到页面上（无公开前台接口）。曾用过不蒜子/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 前台接入

关键文件：

配置示例：

[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. 参考资料

• LoveIt 主题文档
• Host on Cloudflare（Hugo）
• Giscus
• analytics_with_cloudflare
• Hugo 自托管访问量（Worker + D1）
• 本仓库：services/web-analytics/README.md
• Cloudflare Dashboard → Analytics & Logs → Web Analytics