Fqzlr的博客

友链挂了？自动检测+主页截图，GitHub Actions 全搞定

Sun, 26 Jul 2026 00:00:00 GMT

为什么要做这个#

友链多了之后总有个头疼的问题——对方悄悄撤了你的链接，或者站点直接挂了，你还蒙在鼓里。手动一个个点进去检查？四五十个友链，想想就累。

所以我搞了个自动化方案：每天定时检测友链状态，每 6 天自动截一张主页图，结果输出成一个 JSON，博客前端直接拉取展示。全程跑在 GitHub Actions 上，不用服务器，不用花钱。

参考链接#

项目	说明
willow-god/check-flink	友链状态检测核心（多线程延迟检测 + 反链检测）
thun888/Python-WebSite-Screenshot	Selenium 主页截图核心
fqzlr/check-flink	我的整合版（本文主角）
cfbed.sanyue.de	图床 API 规范（截图上传用）
image.thum.io	截图兜底服务（Selenium 挂了也不怕）

实现思路#

把两个开源项目深度整合，最终架构长这样：

1
博客 friends.json（唯一数据源）
2
        │
3
        ▼
4
┌─ check_links job（每天 2 次）─────────┐
5
│  多线程请求每个友链                     │
6
│  统计：延迟 / 失败次数 / 反链存在       │
7
│  输出 → result.json                    │
8
└────────────────────────────────────────┘
9
        │
10
        ▼
11
┌─ take_screenshots job（每 6 天）──────┐
12
│  读取 result.json 中可达的友链          │
13
│  Selenium 截图 → 上传图床              │
14
│  失败 → thum.io 兜底                   │
15
│  截图 URL 写回 result.json             │
16
└────────────────────────────────────────┘
17
        │
18
        ▼
19
  Vercel 托管 result.json（CDN 加速）
20
        │
21
        ▼
22
  博客前端 fetch → 渲染友链卡片

显示更多显示更少

关键文件#

文件	作用
`main.py`	状态检测 + 反链检测 + 增量合并
`screenshot.py`	Selenium 截图 + 图床上传 + thum.io 兜底
`screenshot_runner.py`	截图入口，从 result.json 读取目标
`inject.css`	截图时注入目标页面（隐藏滚动条/弹窗）
`.github/workflows/check_links.yml`	调度核心：定时 + 手动 + 条件触发

反链检测怎么做的#

访问对方的友链页面，用正则提取所有真实的 <a href> 链接，解析主机名后跟自己的域名比对。

注意：只有真实超链接才算反链。如果对方只是在文章里提了一嘴你的域名（纯文本），不算。之前旧版用字符串匹配，结果把 5 个只是文字提及的站点误判成了有反链，后来重写了这块逻辑。

怎么部署#

完整 8 步教程在 README，这里挑重点说。

第一步：Fork 仓库#

把 fqzlr/check-flink fork 到你自己的 GitHub。

第二步：配置 Secrets#

在仓库 Settings → Secrets and variables → Actions 里添加：

Secret	说明	示例
`AUTHOR_URL`	你的域名（反链检测用）	`fqzlr.com`
`SOURCE_URL`	友链 JSON 地址	`https://fqzlr.com/friends.json`
`IMG_API_URL`	图床上传 API	`https://tu.xxx.com/api/upload`
`IMG_API_TOKEN`	图床 API Token	`your-token`

第三步：开启 Actions 写权限#

仓库 Settings → Actions → General → Workflow permissions → 选 Read and write permissions。

不然 workflow 没法把 result.json 提交回仓库。

第四步：准备友链数据源#

你的博客需要暴露一个 JSON 接口，格式类似：

1
[
2
  {
3
    "name": "番茄的博客",
4
    "link": "https://blog.example.com",
5
    "avatar": "https://...",
6
    "linkpage": "https://blog.example.com/friends"
7
  }
8
]

其中 linkpage 是对方的友链页面地址（反链检测会访问这个页面）。

第五步：准备图床#

截图需要上传到图床。我用的是 Cloudflare-ImgBed（博客系列第 4 期讲过），API 兼容 cfbed.sanyue.de 规范。

第六步：首次触发#

Actions → Run workflow → task 选 both → target_link 留空 → 跑！

首次全量跑一遍，之后日常就自动了。

第七步：部署到 Vercel#

把仓库导入 Vercel，Output Directory 填 static，得到一个 CDN 地址。博客前端 fetch 这个地址的 result.json 就行。

怎么触发#

这是我最满意的部分——灵活到可以只跑一个友链。

自动触发（不用管）#

时间	执行内容
每天 01:00、13:00	仅状态检测（~1 分钟）
每 6 天（1/7/13/19/25 号 01:30）	状态检测 + 截图（~10 分钟）

手动触发（按需）#

进 Actions → Run workflow，有两个参数：

task（选执行内容）：

status_only：仅状态检测（默认）
screenshots_only：仅截图（用上次检测数据）
both：检测 + 截图

target_link（只处理指定友链）：

填友链名称或 URL 关键词，如 番茄 或 blog.example.com
留空 = 处理全部

常见场景#

我想…	task	target_link
日常看看谁挂了	`status_only`	留空
新加了个友链，检测一下	`status_only`	`新友链名字`
新加了个友链，检测+截图	`both`	`新友链名字`
截图太旧了，全部重截	`screenshots_only`	留空
全量跑一遍	`both`	留空

增量处理是什么#

当你填了 target_link，只有匹配的友链会被重新检测/截图，其余友链保留上次结果。不会出现”只跑了一个友链，其他 46 个数据全没了”的情况。total_count 始终不变。

一些细节#

截图兜底链#

1
Selenium 本地截图
2
  ├─ 成功 → 上传图床 → 图床 URL
3
  └─ 失败 → thum.io 在线截图（永远可用）

所以即使 GitHub Actions 环境抽风装不上 Chrome，也不会出现白屏。

截图频率为什么是 6 天#

Selenium + Chrome 安装要 2-3 分钟，截完全部友链要 5-10 分钟。每天跑太浪费 Actions 配额（每月 2000 分钟），6 天一次刚刚好。

状态检测就轻量多了，纯 requests 请求，1 分钟跑完，所以每天 2 次不心疼。

数据源只维护一份#

友链配置只在博客侧维护（我的 friends.json），检测仓库自动读取。不用两边同步，加友链只需要在博客加一次。

最后#

整套方案跑下来零成本：GitHub Actions 免费额度足够，图床用 Cloudflare Workers 免费套餐，Vercel 也是免费的。

如果你也有几十号友链，与其隔三差五手动检查，不如让机器帮你盯着。

fqzlr

check-flink

Waiting for api.github.com...

00K

Waiting...

有问题欢迎评论区交流～

评论区也能发图了：Waline 接入图床 + 按页面路径自动归类

Sun, 26 Jul 2026 00:00:00 GMT

为什么要做这个#

Waline 评论系统默认只支持填图片 URL，访客想发张图得自己找地方传完再贴链接——基本等于没人会发图。

但接上

不需要服务器，0成本，搭建属于自己的个人图床

博客系列第5期。用 Cloudflare Workers 部署专属图床 Cloudflare-ImgBed，免费、全球加速、数据自己掌控。

里搭的 Cloudflare-ImgBed 之后，评论区直接支持粘贴/选择图片自动上传，体验完全不一样。更进一步，我还让它根据当前页面路径自动归档到对应文件夹，图床后台不会乱成一锅粥。

实现思路#

graph TD A[访客在评论区粘贴图片] --> B[Waline imageUploader 拦截] B --> C[解析当前页面 URL 路径] C --> D[生成 uploadFolder 参数] D --> E[POST 图床 /upload?uploadFolder=xxx] E --> F[图床返回图片 URL] F --> G[URL 自动插入评论正文]

核心就一件事：Waline 提供了 imageUploader 配置项，传一个函数进去，函数负责把图片文件传到图床、返回 URL，剩下的插入评论正文 Waline 自己搞定。

官方文档：Waline 自定义图片上传

准备工作#

东西	说明
自建图床	Cloudflare-ImgBed，第 4 期讲过怎么搭
图床 API Token	图床管理面板 → Token 管理 → 创建，权限勾选 `upload`
Waline 已接入	评论系统跑起来了才有意义，迁移教程见 Twikoo 评论一键迁移 Waline（双向互转）

第一步：配置文件加入图床入口#

在 src/config/commentConfig.ts 的 waline 配置里加两项：

commentConfig.ts

1
waline: {
2
  serverURL: "https://waline.fqzlr.com",
3
  lang: "zh-CN",
4
  // ... 其他配置
5

6
  // ===== 评论图片上传（图床接入） =====
7
  // 图床上传地址（/upload 端点）
8
  imageUploadURL: "https://tu.fqzlr.com/upload",
9
  // 图床 API Token —— 不要硬编码！走环境变量
10
  imageUploadToken: import.meta.env?.PUBLIC_IMG_UPLOAD_TOKEN || "",
11
},

Token 安全

Token 绝对不要直接写在代码里提交到仓库。通过环境变量注入：

Vercel：Settings → Environment Variables → 添加 PUBLIC_IMG_UPLOAD_TOKEN
本地开发：项目根目录 .env 文件添加 PUBLIC_IMG_UPLOAD_TOKEN=imgbed_xxxxx

两项都填了才启用上传，任一留空自动禁用——这个判断逻辑后面会写到。

第二步：补全类型声明#

Astro + TypeScript 项目，新加的配置项和环境变量都要声明类型，不然编辑器会报错。

配置类型（src/types/config.ts）：

types/config.ts

1
waline?: {
2
  serverURL: string;
3
  lang?: string;
4
  login?: "enable" | "force" | "disable";
5
  visitorCount?: boolean;
6
  emoji?: string[];
7
  imageUploadURL?: string;   // ← 新增
8
  imageUploadToken?: string; // ← 新增
9
};

环境变量类型（src/env.d.ts）：

env.d.ts

1
interface ImportMetaEnv {
2
  readonly PUBLIC_IMG_UPLOAD_TOKEN: string; // ← 新增
3
}

第三步：实现 imageUploader#

这是核心部分，在 src/components/comment/Waline.astro 里完成。

注入配置到客户端#

Astro 组件的 frontmatter 是服务端代码，imageUploader 需要在浏览器里跑，所以用 define:vars 把配置注入到内联脚本：

Waline.astro

1
---
2
const imageUploadURL = commentConfig.waline?.imageUploadURL || "";
3
const imageUploadToken = commentConfig.waline?.imageUploadToken || "";
4
---
5
<script type="module" is:inline define:vars={{ config, imageUploadURL, imageUploadToken }}>
6
  import { init } from 'https://unpkg.com/@waline/client@v3/dist/waline.js';
7
  // ...
8
</script>

上传函数本体#

imageUploader 核心逻辑显示更多显示更少

1
if (imageUploadURL && imageUploadToken) {
2
  config.imageUploader = (file) => {
3
    var folder = getUploadFolder();
4
    var uploadURL = imageUploadURL + '?uploadFolder=' + encodeURIComponent(folder);
5

6
    var formData = new FormData();
7
    formData.append('file', file);
8
    return fetch(uploadURL, {
9
      method: 'POST',
10
      headers: {
11
        'Authorization': 'Bearer ' + imageUploadToken,
12
        'Accept': 'application/json',
13
      },
14
      body: formData,
15
    })
16
      .then((resp) => {
17
        if (!resp.ok) throw new Error('图片上传失败: ' + resp.status);
18
        return resp.json();
19
      })
20
      .then((data) => {
21
        // 解析响应，拿到图片 URL（下面细说）
22
        return url;
23
      });
24
  };
25
}

显示更多显示更少

几个要点：

条件启用：imageUploadURL && imageUploadToken 都成立才挂载 imageUploader，否则 Waline 走默认行为（不允许发图）
Bearer 认证：cfbed 规范用 Authorization: Bearer {token} 请求头
FormData：字段名必须是 file，这是 cfbed API 的约定

亮点：按页面路径自动归类#

这是我觉得最实用的部分——不同页面的评论图片，自动传到图床的不同文件夹。

归类规则#

getUploadFolder()

1
function getUploadFolder() {
2
  var segments = window.location.pathname
3
    .split('/')
4
    .filter(function (s) { return s.length > 0; });
5
  if (segments.length === 0) return 'fqzlrcom/comments';
6
  var parts = segments.slice(0, 2);
7
  return 'fqzlrcom/' + parts.join('/');
8
}

规则很简单：

前缀统一为 fqzlrcom/（域名标识，图床里一眼就知道是哪个站的图）
取当前页面路径的前 2 段作为子文件夹
超出的段直接截断，不无限建目录
根路径 / 或解析失败时，回退到 fqzlrcom/comments

实际效果#

评论所在页面	路径段	上传文件夹
`/friends/`	`friends`	`fqzlrcom/friends`
`/dynamic/`	`dynamic`	`fqzlrcom/dynamic`
`/posts/blog/check-flink/`	`posts` `blog` `check-flink`	`fqzlrcom/posts/blog`（截断第 3 段）
`/`	无	`fqzlrcom/comments`（回退）

为什么最多取 2 段？文章路径 /posts/博客相关/xxx/ 如果全取，文件夹会深到三四层，图床后台点进去找图很痛苦。2 段刚好能区分「哪个板块 + 哪个子分类」，够用了。

传给图床#

cfbed API 通过 query 参数 uploadFolder 接收文件夹路径：

1
POST https://tu.fqzlr.com/upload?uploadFolder=fqzlrcom%2Ffriends

记得 encodeURIComponent，路径里的 / 需要编码。

响应解析：兼容多种格式#

cfbed 不同版本/配置的响应格式不完全一样，所以解析逻辑做了多路兼容：

响应解析

1
var url = '';
2
if (Array.isArray(data) && data[0]) {
3
  // 格式一：[{ src, publicUrl }]
4
  url = data[0].publicUrl || data[0].src || '';
5
} else if (data?.data?.links?.url) {
6
  // 格式二：{ data: { links: { url } } }
7
  url = data.data.links.url;
8
} else if (data?.src) {
9
  // 格式三：{ src }
10
  url = data.src;
11
}
12
if (!url) throw new Error('图床响应格式异常');

还有一个容易踩的坑：publicUrl 未配置时，src 是相对路径（如 /file/xxx.jpg），直接插入评论会 404。需要拼接图床域名：

相对路径补全

1
if (url.startsWith('/')) {
2
  url = new URL(imageUploadURL).origin + url;
3
}

new URL(imageUploadURL).origin 从上传地址里提取协议 + 域名（https://tu.fqzlr.com），不用额外硬编码域名配置。

完整文件改动清单#

文件	改动
`src/config/commentConfig.ts`	新增 `imageUploadURL` / `imageUploadToken` 配置项
`src/types/config.ts`	waline 类型补充两个可选字段
`src/env.d.ts`	声明 `PUBLIC_IMG_UPLOAD_TOKEN` 环境变量类型
`src/components/comment/Waline.astro`	实现 `getUploadFolder` + `imageUploader`

四个文件，改动量不大，但评论区从此支持发图了。

常见问题#

图片上传失败怎么排查

打开浏览器 DevTools → Network，看 /upload 请求的状态码
401：Token 错了或权限没勾 upload
404：imageUploadURL 地址写错了，确认是 /upload 端点
响应格式异常：图床版本不同响应结构可能不一样，对照上面的三路解析逻辑检查

本地测试

.env 里配好 PUBLIC_IMG_UPLOAD_TOKEN 后跑 pnpm dev，在任意有评论区的页面粘贴图片即可测试。上传成功的话，图片 URL 会自动出现在评论输入框里。

最后#

整个方案零额外成本：图床跑在 Cloudflare Workers 免费套餐上，Token 走环境变量不泄露，文件夹自动归类让图床后台始终清爽。

如果你也在用 Waline + Cloudflare-ImgBed，这套配置抄过去改改域名就能用。

图床搭建教程：不需要服务器，0成本，搭建属于自己的个人图床
Waline 官方图片上传文档：waline.js.org/cookbook/customize/upload-image.html
cfbed API 规范：cfbed.sanyue.de
有问题欢迎评论区交流～（对，就是本文接好的那个评论区）

博客，是好看好，还是简单好？

Thu, 23 Jul 2026 00:00:00 GMT

很多搭建个人博客的人，都会纠结一个问题：页面究竟该精致好看，还是干净简单。

有人专注打磨页面颜值，有人偏爱极简文字氛围。两种风格没有高低优劣，只有适配场景的不同。

一、颜值型博客：主打审美与个人风格#

颜值型博客视觉表现力更强，配色精致、排版个性，搭配适量装饰元素，能快速抓住访客眼球。

非常适合摄影、美学、穿搭、文艺随笔等内容，氛围感充足，能大幅提升内容质感和读者停留意愿。

对应的取舍也很清晰：页面元素较多，加载会稍有影响，且需要花费大量时间调试、维护主题，容易分流创作精力。

二、极简型博客：主打阅读与实用性#

极简博客的核心是服务阅读。版面干净、留白充足、层级清晰，剔除所有多余干扰，让读者专注文字内容。

适配技术干货、读书笔记、日常记录、知识总结类内容，稳定省心、几乎零维护。

风格短板也十分明显：视觉辨识度低，整体偏平淡，缺少氛围感，难以支撑美学展示、创意类内容的调性。

三、两种风格核心对比#

颜值型博客：优势是审美出众、记忆点强、氛围感足；局限是维护成本高、深度阅读体验一般。

极简型博客：优势是阅读舒适、稳定省心、低维护成本；局限是视觉单调、缺少设计质感。

四、结语：适配自己的，就是最好的#

博客不必在好看与简单之间强行二选一，也无需跟风主流风格。

所有设计都该为内容服务。好看是独特的个人名片，简单是长久的阅读底气。

根据自己的内容定位选择风格，适配自己的创作节奏，能安心记录、让人静心阅读，就是最好的博客模样。

Twikoo 评论一键迁移 Waline（双向互转）

Sat, 18 Jul 2026 00:00:00 GMT

一、迁移前置说明#

本文档适配基于 Firefly 主题的 Astro 静态博客，完整覆盖 Twikoo ↔ Waline 评论数据双向转换全流程，解决四大高频痛点：

转换后的时间戳格式非法，导入时 Waline 后台报 500: invalid input syntax for type timestamp；
Waline 后台导入提示成功，但前台页面完全不显示评论（路径尾斜杠不匹配）；
转换后父子回复全部平铺，多层嵌套回复层级直接丢失；
Twikoo 与 Waline 互转时缺少双向支持，无法反向恢复。

前置准备清单#

已部署完成 Waline 服务（示例地址：https://waline.fqzlr.com）；
Firefly 博客页面已挂载 Waline 前端评论组件；
可正常登录 Twikoo 管理后台导出原始评论 JSON；
浏览器推荐 Chrome / Edge。

二、第一步：导出原始评论数据#

Twikoo 导出#

进入 Twikoo 管理后台；
找到「数据导出」，导出全部评论为 纯 JSON 数组，保存为 .json 文件。

Waline 导出#

进入 Waline 管理后台 https://waline.fqzlr.com/ui；
左侧菜单「导入导出」→ 导出全部数据，保存为 .json 文件。

重要：Twikoo 导出每条评论需包含 _id、pid、rid 字段；Waline 导出需包含 data.Comment、data.Users、data.Counter 三表。

三、第二步：双向转换工具（自动修复路径尾斜杠 + 保留嵌套回复）#

工具核心能力#

Important

本工具针对实际迁移踩坑场景做了以下修复和增强：

修复时间格式 500 错误：toISOString() 已自带 3 位毫秒（如 2026-04-25T11:23:19.928Z），不再拼接多余的 .000，避免产生非法格式 2026-04-25T11:23:19.928.000Z；
自动补路径尾斜杠：所有 url 末尾自动追加 /，与 Firefly 前台路径格式（/friends/）完全一致；
完整还原嵌套回复：Twikoo _id ↔ Waline objectId 建立完整映射表，pid/rid 精准关联父子评论；
1:1 对齐 Waline 数据表：补齐 Comment/Counter/Users 三表及所有必填字段；
支持双向互转：Twikoo → Waline 和 Waline → Twikoo 均可一键转换；
本地离线运算：所有数据在浏览器端处理，不上传任何服务器。

内嵌交互式转换工具#

Twikoo ↔ Waline 双向转换器

1. 粘贴 JSON 数据或上传文件
2. 自动给 url 末尾加 /（Twikoo→Waline 方向）
3. 完整保留多级嵌套回复关系，支持双向互转

Twikoo → WalineWaline → Twikoo

批量替换 url 前缀：一键替换全部 url

上传本地 JSON开始转换下载结果 JSON清空全部

转换结果预览

新建文本文件，复制下方全部代码，保存为 twikoo-to-waline.html，双击用浏览器打开即可离线使用：

▶📝 点击查看完整工具源代码（可复制保存为 HTML 文件离线使用，支持双向互转）

twikoo-to-waline.html

HTML复制

<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Twikoo ↔ Waline 评论数据双向转换工具</title>
<style>
* { margin: 0; padding: 0; box-sizing: border-box; }
body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; background: #f5f6fa; color: #2c3e50; min-height: 100vh; }
.header { background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); color: #fff; padding: 24px 32px; }
.header h1 { font-size: 22px; font-weight: 600; }
.header p { font-size: 13px; opacity: 0.85; margin-top: 4px; }
.container { max-width: 1100px; margin: 0 auto; padding: 24px; }
.card { background: #fff; border-radius: 10px; padding: 24px; margin-bottom: 16px; box-shadow: 0 1px 4px rgba(0,0,0,0.06); }
.step-label { display: inline-block; background: #667eea; color: #fff; font-size: 12px; font-weight: 600; padding: 2px 10px; border-radius: 10px; margin-right: 8px; }
.card h3 { font-size: 16px; margin-bottom: 16px; display: flex; align-items: center; }
.mode-switch { display: flex; gap: 0; margin-bottom: 20px; border-radius: 8px; overflow: hidden; border: 2px solid #667eea; }
.mode-btn { flex: 1; padding: 10px 16px; border: none; font-size: 14px; font-weight: 600; cursor: pointer; background: #fff; color: #667eea; transition: all 0.2s; }
.mode-btn.active { background: #667eea; color: #fff; }
.mode-btn:hover:not(.active) { background: #f0f2ff; }
.drop-zone { border: 2px dashed #d0d5dd; border-radius: 8px; padding: 40px; text-align: center; cursor: pointer; transition: all 0.2s; margin-bottom: 8px; }
.drop-zone:hover, .drop-zone.dragover { border-color: #667eea; background: #f0f2ff; }
.drop-zone p { color: #888; font-size: 14px; }
.drop-zone p strong { color: #667eea; }
.file-hint { font-size: 12px; color: #aaa; margin-top: 4px; }
.stats { display: grid; grid-template-columns: repeat(auto-fit, minmax(140px, 1fr)); gap: 10px; }
.stat-box { background: #f8f9fc; border-radius: 8px; padding: 12px; text-align: center; }
.stat-box .num { font-size: 26px; font-weight: 700; color: #667eea; }
.stat-box .label { font-size: 11px; color: #888; margin-top: 3px; }
.toolbar { display: flex; gap: 8px; flex-wrap: wrap; margin-bottom: 12px; }
.btn { padding: 8px 18px; border: none; border-radius: 6px; font-size: 13px; cursor: pointer; font-weight: 500; transition: all 0.2s; }
.btn-primary { background: #667eea; color: #fff; }
.btn-primary:hover { background: #5a6fd6; }
.btn-secondary { background: #e8eaed; color: #333; }
.btn-secondary:hover { background: #d8dbe0; }
.btn-success { background: #27ae60; color: #fff; }
.btn-success:hover { background: #219a52; }
.btn:disabled { opacity: 0.45; cursor: not-allowed; }
.comment-list { max-height: 500px; overflow-y: auto; border: 1px solid #eee; border-radius: 8px; }
.comment-item { padding: 10px 16px; border-bottom: 1px solid #f0f0f0; display: flex; gap: 10px; align-items: flex-start; }
.comment-item:last-child { border-bottom: none; }
.comment-item .oid { background: #667eea; color: #fff; font-size: 10px; min-width: 24px; height: 20px; border-radius: 10px; display: flex; align-items: center; justify-content: center; flex-shrink: 0; }
.comment-item .indent { color: #aaa; font-size: 12px; margin-right: 4px; }
.comment-item.level-1 { padding-left: 44px; }
.comment-item.level-2 { padding-left: 66px; }
.comment-item.level-3 { padding-left: 88px; }
.comment-info { flex: 1; min-width: 0; }
.comment-info .author { font-weight: 600; font-size: 13px; }
.comment-info .meta { font-size: 11px; color: #999; margin-top: 2px; }
.comment-info .text { font-size: 13px; margin-top: 3px; color: #444; word-break: break-all; }
.log { background: #1e1e1e; color: #d4d4d4; padding: 12px 16px; border-radius: 8px; font-family: "SF Mono", "Cascadia Code", Consolas, monospace; font-size: 12px; max-height: 200px; overflow-y: auto; white-space: pre-wrap; }
.log .ok { color: #6a9955; }
.log .warn { color: #dcdcaa; }
.log .err { color: #f44747; }
.note { font-size: 12px; color: #999; background: #fffbe6; border: 1px solid #ffe58f; border-radius: 6px; padding: 10px 14px; margin-top: 12px; line-height: 1.6; }
</style>
</head>
<body>

<div class="header">
  <h1>Twikoo ↔ Waline 评论数据双向转换工具</h1>
  <p>保留留言回复层级关系 · 支持双向互转 · 纯浏览器端运行，数据不上传</p>
</div>

<div class="container">

  <!-- 方向选择 -->
  <div class="card">
    <h3><span class="step-label">1</span> 选择转换方向</h3>
    <div class="mode-switch">
      <button class="mode-btn active" id="modeTW" onclick="setMode('tw2wl')">Twikoo → Waline</button>
      <button class="mode-btn" id="modeWT" onclick="setMode('wl2tw')">Waline → Twikoo</button>
    </div>
    <div id="modeDesc" style="font-size:13px;color:#666;">将 Twikoo 导出的 JSON 数组转换为 Waline 导入格式（含 Comment / Users / Counter 三表）</div>
  </div>

  <!-- 加载 -->
  <div class="card">
    <h3><span class="step-label">2</span> 加载源文件</h3>
    <div class="drop-zone" id="dropZone">
      <p id="dropText">拖拽 <strong>twikoo-comment.json</strong> 到此处<br>或 <strong>点击选择文件</strong></p>
      <input type="file" id="fileInput" accept=".json" style="display:none">
    </div>
    <div class="file-hint" id="fileHint">Twikoo 导出文件通常是一个 JSON 数组，Waline 导出文件是一个含 data.Comment 的对象</div>
    <div id="fileInfo" style="margin-top:8px;font-size:13px;color:#888;"></div>
  </div>

  <!-- 统计 -->
  <div class="card" id="statsCard" style="display:none">
    <h3>数据概览</h3>
    <div class="stats" id="statsGrid"></div>
  </div>

  <!-- 转换 -->
  <div class="card" id="convertCard" style="display:none">
    <h3><span class="step-label">3</span> 转换 & 预览</h3>
    <div class="toolbar">
      <button class="btn btn-primary" id="btnConvert">执行转换</button>
      <button class="btn btn-success" id="btnDownload" disabled>下载结果 JSON</button>
      <button class="btn btn-secondary" id="btnPreview" disabled>预览评论列表</button>
    </div>
    <div class="log" id="logArea" style="display:none;"></div>
    <div class="comment-list" id="previewList" style="display:none;margin-top:12px;"></div>
    <div class="note" id="noteArea" style="display:none;"></div>
  </div>

</div>

<script>
// ==================== 状态 ====================
let currentMode = 'tw2wl'; // 'tw2wl' | 'wl2tw'
let sourceData = null;
let outputData = null;
let convertLog = [];
let convertStats = null;

// ==================== UUID 生成 ====================
function generateUUID() {
  return 'xxxxxxxxxxxx4xxxyxxxxxxxxxxxxxxx'.replace(/[xy]/g, c => {
    const r = Math.random() * 16 | 0;
    return (c === 'x' ? r : (r & 0x3 | 0x8)).toString(16);
  });
}

// ==================== 工具函数 ====================
function stripHtml(html) {
  const div = document.createElement('div');
  div.innerHTML = html;
  return div.textContent || div.innerText || '';
}

function tsToISO(ms) {
  return new Date(ms).toISOString();
}

function isoToTs(iso) {
  return new Date(iso).getTime();
}

function normalizeUrl(url) {
  if (!url) return '/';
  return url.endsWith('/') ? url : url + '/';
}

function wrapHtml(text) {
  if (!text || text.trim() === '') return '';
  return '<p>' + text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/\n/g, '</p>\n<p>') + '</p>\n';
}

function parseIPRegion(ipRegion) {
  if (!ipRegion) return '';
  const parts = ipRegion.split('|');
  return [parts[0], parts[2], parts[3]].filter(Boolean).join(' ');
}

// ==================== 核心：Twikoo → Waline ====================
function convertTW2WL(data) {
  const comments = Array.isArray(data) ? data : (data.data || data.comments || data);
  if (!Array.isArray(comments) || comments.length === 0) {
    throw new Error('未识别到评论数组');
  }

  const log = [];
  log.push('[Twikoo → Waline] 开始转换...');
  log.push(`源评论数: ${comments.length}`);

  // 分配数字 objectId
  let nextId = 1;
  const idMap = {}; // twikoo _id → waline objectId
  for (const c of comments) {
    idMap[c._id] = nextId++;
  }

  // Users 按邮箱去重
  const userMap = {};
  const users = [];
  let uidCounter = 0;
  const usedEmails = new Set();

  for (const c of comments) {
    const email = (c.mail || '').trim().toLowerCase();
    if (email && !usedEmails.has(email)) {
      usedEmails.add(email);
      uidCounter++;
      userMap[email] = uidCounter;
      users.push({
        objectId: uidCounter,
        display_name: c.nick || '',
        email: email,
        password: '',
        type: c.master === 1 ? 'administrator' : 'guest',
        label: c.master === 1 ? '主理人' : null,
        url: c.link || null,
        avatar: c.avatar || null,
        github: null, twitter: null, facebook: null, google: null,
        weibo: null, qq: null, oidc: null, huawei: null, "2fa": null,
        createdAt: tsToISO(c.created),
        updatedAt: tsToISO(c.updated || c.created)
      });
    }
  }
  log.push(`去重用户: ${users.length}`);

  // Counter 按 url 去重
  const urlCountMap = {};
  for (const c of comments) {
    const url = normalizeUrl(c.url);
    urlCountMap[url] = (urlCountMap[url] || 0) + 1;
  }
  const counters = [];
  let cidCounter = 0;
  for (const [url, count] of Object.entries(urlCountMap)) {
    cidCounter++;
    counters.push({
      objectId: cidCounter, url, time: count,
      reaction0: null, reaction1: null, reaction2: null,
      reaction3: null, reaction4: null, reaction5: null,
      reaction6: null, reaction7: null, reaction8: null,
      createdAt: tsToISO(Date.now()),
      updatedAt: tsToISO(Date.now())
    });
  }

  // 转换 Comment
  const walineComments = [];
  let topCount = 0, replyCount = 0, orphanCount = 0;

  for (const c of comments) {
    const email = (c.mail || '').trim().toLowerCase();
    const userId = userMap[email] || 0;
    let pid = null, rid = null;

    if (c.pid && c.pid.trim() !== '') {
      pid = idMap[c.pid] || null;
      if (pid === null) { orphanCount++; log.push(`⚠ 孤儿回复: ${c._id} → 父 ${c.pid} 不存在`); }
    }
    if (c.rid && c.rid.trim() !== '') {
      rid = idMap[c.rid] || null;
    }
    if (pid !== null && rid === null) rid = pid;

    pid === null ? topCount++ : replyCount++;

    walineComments.push({
      objectId: idMap[c._id],
      user_id: userId,
      comment: stripHtml(c.comment || ''),
      ip: c.ip || '',
      link: c.link || null,
      mail: c.mail || '',
      nick: c.nick || '',
      pid, rid,
      sticky: c.top === 1 ? 1 : null,
      status: c.isSpam ? 'spam' : 'approved',
      like: null,
      ua: c.ua || '',
      url: normalizeUrl(c.url),
      insertedAt: tsToISO(c.created),
      createdAt: tsToISO(c.created),
      updatedAt: tsToISO(c.updated || c.created)
    });
  }

  log.push(`顶级: ${topCount} · 回复: ${replyCount} · 孤儿: ${orphanCount}`);

  return {
    result: {
      __version: '1.41.3', type: 'waline', version: 1, time: Date.now(),
      tables: ['Comment', 'Counter', 'Users'],
      data: { Comment: walineComments, Counter: counters, Users: users }
    },
    log, stats: { total: comments.length, top: topCount, reply: replyCount, users: users.length, urls: counters.length, orphan: orphanCount }
  };
}

// ==================== 核心：Waline → Twikoo ====================
function convertWL2TW(data) {
  const log = [];
  log.push('[Waline → Twikoo] 开始转换...');

  // 提取数据
  let walineObj = data;
  if (Array.isArray(data)) {
    // 可能是单纯的 Comment 数组
    walineObj = { data: { Comment: data, Users: [], Counter: [] } };
  }

  const wlComments = walineObj?.data?.Comment || walineObj?.Comment || walineObj?.comments || [];
  const wlUsers = walineObj?.data?.Users || walineObj?.Users || [];
  const wlCounters = walineObj?.data?.Counter || walineObj?.Counter || [];

  if (!Array.isArray(wlComments) || wlComments.length === 0) {
    throw new Error('未识别到 Waline Comment 数据');
  }

  log.push(`源评论数: ${wlComments.length}`);
  log.push(`源用户数: ${wlUsers.length}`);
  log.push(`源计数器: ${wlCounters.length}`);

  // 构建 user_id → 用户信息 的映射
  const userInfoMap = {};
  for (const u of wlUsers) {
    userInfoMap[u.objectId] = u;
  }

  // 分配 Twikoo 的 _id（UUID）
  const idMap = {}; // waline objectId → twikoo _id
  for (const c of wlComments) {
    idMap[c.objectId] = generateUUID();
  }
  log.push(`生成 UUID _id: ${Object.keys(idMap).length} 个`);

  // 构建 url → 页面信息映射（用于补充 href）
  const urlInfoMap = {};
  for (const ct of wlCounters) {
    if (ct.url) urlInfoMap[ct.url] = ct;
  }

  // 转换
  const twikooComments = [];
  let topCount = 0, replyCount = 0, orphanCount = 0;

  for (const c of wlComments) {
    const userInfo = userInfoMap[c.user_id] || {};
    const email = c.mail || userInfo.email || '';
    const nick = c.nick || userInfo.display_name || '';

    let pid = '';
    let rid = '';

    if (c.pid != null) {
      pid = idMap[c.pid] || '';
      if (pid === '') { orphanCount++; log.push(`⚠ 孤儿回复: objectId=${c.objectId} → 父 ${c.pid} 不存在`); }
    }
    if (c.rid != null) {
      rid = idMap[c.rid] || '';
    }

    pid ? replyCount++ : topCount++;

    const created = typeof c.createdAt === 'number' ? c.createdAt : isoToTs(c.createdAt || c.insertedAt || new Date().toISOString());
    const updated = typeof c.updatedAt === 'number' ? c.updatedAt : isoToTs(c.updatedAt || c.createdAt || new Date().toISOString());

    // 构建 ipRegion（近似还原）
    // Waline 没有 ipRegion 字段，只能留空或尝试从其他字段推断
    const ipRegion = '';

    twikooComments.push({
      _id: idMap[c.objectId],
      uid: '',
      nick: nick,
      mail: email,
      mailMd5: '',
      link: c.link || userInfo.url || '',
      ua: c.ua || '',
      ip: c.ip || '',
      ipRegion: ipRegion,
      master: (userInfo.type === 'administrator') ? 1 : 0,
      url: c.url || '/',
      href: c.url ? ('https://fqzlr.com' + c.url + '/') : '',
      comment: wrapHtml(c.comment || ''),
      pid: pid,
      rid: rid,
      isSpam: c.status === 'spam' ? 1 : 0,
      created: created,
      updated: updated,
      like: c.like ? JSON.stringify(c.like) : '[]',
      top: c.sticky ? 1 : 0,
      avatar: userInfo.avatar || ''
    });
  }

  log.push(`顶级: ${topCount} · 回复: ${replyCount} · 孤儿: ${orphanCount}`);

  return {
    result: twikooComments,
    log, stats: { total: twikooComments.length, top: topCount, reply: replyCount, users: wlUsers.length, orphan: orphanCount }
  };
}

// ==================== UI ====================
const dropZone = document.getElementById('dropZone');
const fileInput = document.getElementById('fileInput');
const fileInfo = document.getElementById('fileInfo');
const statsCard = document.getElementById('statsCard');
const statsGrid = document.getElementById('statsGrid');
const convertCard = document.getElementById('convertCard');
const btnConvert = document.getElementById('btnConvert');
const btnDownload = document.getElementById('btnDownload');
const btnPreview = document.getElementById('btnPreview');
const logArea = document.getElementById('logArea');
const previewList = document.getElementById('previewList');
const noteArea = document.getElementById('noteArea');
const dropText = document.getElementById('dropText');
const fileHint = document.getElementById('fileHint');
const modeDesc = document.getElementById('modeDesc');

function setMode(mode) {
  currentMode = mode;
  document.getElementById('modeTW').classList.toggle('active', mode === 'tw2wl');
  document.getElementById('modeWT').classList.toggle('active', mode === 'wl2tw');

  if (mode === 'tw2wl') {
    modeDesc.textContent = '将 Twikoo 导出的 JSON 数组转换为 Waline 导入格式（含 Comment / Users / Counter 三表）';
    dropText.innerHTML = '拖拽 <strong>twikoo-comment.json</strong> 到此处<br>或 <strong>点击选择文件</strong>';
    fileHint.textContent = 'Twikoo 导出文件通常是一个 JSON 数组，每个元素是一条评论';
  } else {
    modeDesc.textContent = '将 Waline 导出的 JSON 对象转换为 Twikoo 评论数组格式（含层级关系）';
    dropText.innerHTML = '拖拽 <strong>waline-export.json</strong> 到此处<br>或 <strong>点击选择文件</strong>';
    fileHint.textContent = 'Waline 导出文件是一个含 data.Comment / data.Users / data.Counter 的 JSON 对象';
  }

  // 重置
  sourceData = null;
  outputData = null;
  convertLog = [];
  convertStats = null;
  fileInfo.textContent = '';
  statsCard.style.display = 'none';
  convertCard.style.display = 'none';
  logArea.style.display = 'none';
  previewList.style.display = 'none';
  noteArea.style.display = 'none';
  btnDownload.disabled = true;
  btnPreview.disabled = true;
}

dropZone.addEventListener('click', () => fileInput.click());
dropZone.addEventListener('dragover', e => { e.preventDefault(); dropZone.classList.add('dragover'); });
dropZone.addEventListener('dragleave', () => dropZone.classList.remove('dragover'));
dropZone.addEventListener('drop', e => {
  e.preventDefault();
  dropZone.classList.remove('dragover');
  const file = e.dataTransfer.files[0];
  if (file) loadFile(file);
});
fileInput.addEventListener('change', e => {
  const file = e.target.files[0];
  if (file) loadFile(file);
});

function loadFile(file) {
  fileInfo.textContent = `已选择: ${file.name} (${(file.size / 1024).toFixed(1)} KB)`;
  const reader = new FileReader();
  reader.onload = function() {
    try {
      sourceData = JSON.parse(reader.result);

      let arr;
      if (currentMode === 'tw2wl') {
        arr = Array.isArray(sourceData) ? sourceData : (sourceData.data || sourceData.comments || []);
      } else {
        arr = sourceData?.data?.Comment || sourceData?.Comment || sourceData?.comments || [];
      }

      statsCard.style.display = 'block';
      convertCard.style.display = 'block';

      const topArr = currentMode === 'tw2wl'
        ? arr.filter(c => !c.pid || c.pid === '')
        : arr.filter(c => c.pid == null);
      const replyArr = currentMode === 'tw2wl'
        ? arr.filter(c => c.pid && c.pid !== '')
        : arr.filter(c => c.pid != null);
      const userCount = currentMode === 'tw2wl'
        ? new Set(arr.map(c => c.mail?.trim().toLowerCase()).filter(Boolean)).size
        : (sourceData?.data?.Users || sourceData?.Users || []).length || '未知';

      statsGrid.innerHTML = `
        <div class="stat-box"><div class="num">${arr.length}</div><div class="label">评论总数</div></div>
        <div class="stat-box"><div class="num">${topArr.length}</div><div class="label">顶级评论</div></div>
        <div class="stat-box"><div class="num">${replyArr.length}</div><div class="label">回复评论</div></div>
        <div class="stat-box"><div class="num">${userCount}</div><div class="label">关联用户</div></div>
      `;

      logArea.style.display = 'none';
      previewList.style.display = 'none';
      noteArea.style.display = 'none';
      btnDownload.disabled = true;
      btnPreview.disabled = true;
    } catch (err) {
      fileInfo.innerHTML = `<span style="color:#e74c3c">JSON 解析失败: ${err.message}</span>`;
    }
  };
  reader.readAsText(file);
}

btnConvert.addEventListener('click', () => {
  if (!sourceData) return alert('请先加载源 JSON 文件');
  try {
    let result;
    if (currentMode === 'tw2wl') {
      result = convertTW2WL(sourceData);
    } else {
      result = convertWL2TW(sourceData);
    }
    outputData = result.result;
    convertLog = result.log;
    convertStats = result.stats;

    logArea.style.display = 'block';
    logArea.innerHTML = convertLog.map(l => {
      if (l.startsWith('⚠')) return `<span class="warn">${l}</span>`;
      if (l.startsWith('❌')) return `<span class="err">${l}</span>`;
      return `<span class="ok">${l}</span>`;
    }).join('\n');

    btnDownload.disabled = false;
    btnPreview.disabled = false;
    previewList.style.display = 'none';

    // 显示注意事项
    if (currentMode === 'wl2tw') {
      noteArea.style.display = 'block';
      noteArea.innerHTML = `
        <strong>注意：</strong>Waline 原始数据不包含 <code>uid</code>、<code>mailMd5</code>、<code>ipRegion</code>、<code>href</code> 等字段，转换后这些字段将为空或使用默认值。<br>
        建议导入 Twikoo 后手动补充站点域名等配置。
      `;
    } else {
      noteArea.style.display = 'block';
      noteArea.innerHTML = `
        <strong>注意：</strong>转换后的 Waline JSON 可直接通过 Waline 管理后台"导入数据"功能导入。<br>
        评论中的 HTML 标签已去除，纯文本保留。回复层级关系通过 <code>pid</code>/<code>rid</code> 数字 ID 保留。
      `;
    }
  } catch (err) {
    alert('转换失败: ' + err.message);
  }
});

btnDownload.addEventListener('click', () => {
  if (!outputData) return;
  const filename = currentMode === 'tw2wl' ? 'waline-import.json' : 'twikoo-export.json';
  const blob = new Blob([JSON.stringify(outputData, null, '\t')], { type: 'application/json' });
  const url = URL.createObjectURL(blob);
  const a = document.createElement('a');
  a.href = url; a.download = filename; a.click();
  URL.revokeObjectURL(url);
});

btnPreview.addEventListener('click', () => {
  if (!outputData) return;

  let comments;
  if (currentMode === 'tw2wl') {
    comments = outputData.data.Comment;
  } else {
    comments = outputData;
  }

  previewList.style.display = 'block';

  // 构建映射 + 计算层级
  const commentMap = {};
  for (const c of comments) {
    const id = currentMode === 'tw2wl' ? c.objectId : c._id;
    commentMap[id] = c;
  }

  function getPid(c) {
    if (currentMode === 'tw2wl') return c.pid;
    return c.pid || null;
  }

  function getId(c) {
    if (currentMode === 'tw2wl') return c.objectId;
    return c._id;
  }

  function getLevel(comment) {
    let level = 0;
    let current = comment;
    const pid = getPid(current);
    if (pid && commentMap[pid]) {
      level++;
      current = commentMap[pid];
      let safety = 0;
      while (safety < 50) {
        const p = getPid(current);
        if (p && commentMap[p]) {
          level++;
          current = commentMap[p];
        } else break;
        safety++;
      }
    }
    return level;
  }

  function getNick(c) { return c.nick || '匿名'; }
  function getText(c) { const t = c.comment || ''; return t.length > 100 ? t.slice(0, 100) + '...' : (t || '(空)'); }
  function getUrl(c) { return c.url || '/'; }
  function getTime(c) {
    const t = c.createdAt || c.created || '';
    if (typeof t === 'number') return new Date(t).toISOString().slice(0, 10);
    return String(t).slice(0, 10);
  }
  function getStatus(c) { return currentMode === 'tw2wl' ? c.status : (c.isSpam ? 'spam' : 'approved'); }
  function getDisplayId(c) { return currentMode === 'tw2wl' ? c.objectId : c._id.slice(0, 8); }
  function getPidDisplay(c) {
    if (currentMode === 'tw2wl') return c.pid ? ' → 回复 #' + c.pid : '';
    return c.pid ? ' → 回复 ' + c.pid.slice(0, 8) : '';
  }

  // 保持原始顺序
  previewList.innerHTML = comments.map(c => {
    const level = getLevel(c);
    const indent = '└ '.repeat(Math.min(level, 10));
    return `
      <div class="comment-item level-${Math.min(level, 3)}">
        <div class="oid">${getDisplayId(c)}</div>
        <div class="comment-info">
          <div class="author">${indent}${getNick(c)}${getPidDisplay(c)}</div>
          <div class="meta">${getUrl(c)} · ${getTime(c)} · ${getStatus(c)}</div>
          <div class="text">${getText(c)}</div>
        </div>
      </div>
    `;
  }).join('');
});
</script>
</body>
</html>

转换工具操作步骤#

Twikoo → Waline 方向#

在上方内嵌工具中，顶部切换按钮选择「Twikoo → Waline」；
导入数据，二选一：
- 粘贴 Twikoo 完整 JSON 数组到输入框；
- 点击「上传本地 JSON」，选中导出的 Twikoo 备份文件；
（可选）路径前缀批量替换：填写旧/新路径前缀后点击「一键替换全部 url」，替换后自动补尾斜杠；
点击「开始转换」；
预览校验：
- 每条评论 "url": "/xxx/" 末尾已自动补 /；
- 子评论 pid 为数字 ID，代表父子关联正常；
点击「下载结果 JSON」保存 waline-import.json。

Waline → Twikoo 方向（反向恢复）#

顶部切换按钮选择「Waline → Twikoo」；
粘贴 Waline 导出的完整 JSON 对象；
点击「开始转换」→ 下载 twikoo-export.json；
注意：Waline 原始数据不含 uid、mailMd5、ipRegion、href 等 Twikoo 特有字段，转换后这些字段为空或默认值。

四、第三步：Waline 后台导入转换后的评论文件#

访问 Waline 管理后台：https://waline.fqzlr.com/ui；
左侧菜单栏打开「导入导出」页面；
Warning
导入操作会覆盖现有评论，务必先导出当前 Waline 评论备份，防止数据丢失；
上传刚下载的 waline-import.json，点击执行导入；
导入完成后，Ctrl + F5 强制刷新后台页面，即可在评论列表看到全部迁移历史评论，嵌套回复正常分层展示。

五、第四步：Firefly 博客前台验证评论展示#

路径匹配原理#

转换工具已自动为所有评论 url 末尾添加 /，Waline 使用精确字符串匹配页面路径，和 Firefly 前台手动提交评论的路径格式完全一致。

打开博客任意文章页面，示例：fqzlr.com/friends/；
Ctrl + F5 强制清除浏览器缓存刷新页面；
页面加载全部迁移历史评论，子评论正常缩进嵌套展示。

前台无评论 / 层级错乱排查方案#

F12 打开浏览器开发者工具，切换到 Network 面板；
筛选 Waline API 请求，查看请求参数 path 是否为带尾斜杠格式（/friends/）；
进入 Waline 后台查看单条评论详情：
- 若 url 缺少末尾 /：重新转换，确认路径已自动补斜杠；
- 若子评论 pid 为 null：原始 Twikoo 数据缺失 _id/pid/rid，清理脏数据后重新导出转换；
确认导入流程无报错、未清空原有评论数据。

六、高频踩坑问题汇总#

坑1：导入时报 500 错误 `invalid input syntax for type timestamp`#

具体报错：500: invalid input syntax for type timestamp: "2026-04-25T11:23:19.928.000Z"
根因：旧版转换工具的 tsToISO 使用了 toISOString().replace('Z', '.000Z')，当毫秒本身已有 3 位时（如 .928Z），替换后变成 .928.000Z，PostgreSQL 无法解析双重小数点格式；
解决方案：使用本文新版转换工具（v2），new Date(ms).toISOString() 直接输出标准 ISO 8601 格式，无需额外拼接。

坑2：导入成功，后台可见评论，Firefly 前台页面空白#

根因：路径末尾斜杠不匹配（/friends vs /friends/）；
解决方案：使用本文新版转换工具，转换时自动为所有 url 补尾斜杠，清空旧评论后重新导入。

坑3：导入提示成功，但 Waline 后台无任何评论#

原因1：转换 JSON 缺失 createdAt/user_id/like 数据库必填字段；
原因2：外层 JSON 结构缺少 Counter、Users 空数组；
解决方案：使用本文完整版转换工具，已补齐全部标准字段与外层结构。

坑4：所有回复全部平铺，没有嵌套层级#

根因：转换工具未做 Twikoo _id 与 Waline objectId ID 映射，父子评论 pid 关联断裂；
解决方案：使用本文修复层级回复的新版转换器，完整还原多级回复关系。

坑5：转换工具下载按钮点击无响应#

解决方案：更换 Chrome / Edge 浏览器，关闭浏览器弹窗拦截功能。

坑6：评论图片、换行、Emoji 丢失乱码#

解决方案：工具内置 UTF-8 编码处理，Twikoo→Waline 方向会去除 HTML 标签保留纯文本。

七、兜底备用方案（后台导入解析失败时）#

若 Waline 后台导入接口持续丢失数据、层级错乱，可直接写入数据库绕过解析器：

打开转换后的 waline-import.json，复制 data.Comment 数组内全部评论对象；
进入数据库管理面板（MySQL / SQLite / LeanCloud）；
找到 wl_Comment 数据表，批量插入复制的评论数组；
直接写入数据库不会丢失任何评论数据、完整保留回复层级。

小白怎么二改博客？使用国产 Codex 阿里的 Qoder、字节的 Trae 来一键修改

Sun, 28 Jun 2026 00:00:00 GMT

不会代码也能改博客#

很多人搭好博客之后想改点东西——换个颜色、加个功能、调一下布局——但一看代码就懵了。这期教你用 AI 工具来干这事，你只需要用中文描述想要什么效果，AI 帮你改代码。

这里用两款国产工具：阿里 Qoder 和 字节 Trae。都是免费的，对新手很友好。

工具介绍#

阿里 Qoder#

Qoder 是阿里推出的 AI 编程助手，擅长整体性的代码生成和重构。你可以把它理解为一个能读懂你项目代码的 AI 助手，告诉它要改什么，它直接帮你改好。

适合场景：整体重构、添加新功能模块、大范围样式调整。

字节 Trae#

Trae 是字节跳动做的 AI IDE（代码编辑器），内置了 AI 辅助编程能力。它更擅长细节优化和错误修复，可以一边写代码一边让 AI 帮忙。

适合场景：细节调整、修 bug、局部优化。

对比#

	Qoder	Trae
开发商	阿里巴巴	字节跳动
擅长	整体重构、功能添加	细节优化、错误修复
使用方式	描述需求 -> 生成方案	编辑器内实时辅助
上手难度	简单	简单

两个都可以试试，看哪个更合你习惯。

操作流程#

整个流程其实很简单：

1. 安装工具#

去官网下载安装就行，Qoder 和 Trae 都有 Windows 版本。

2. 导入博客项目#

把你在 GitHub 上的博客仓库克隆到本地，然后用工具打开项目文件夹。

3. 描述你的需求#

直接用中文告诉 AI 你想改什么。比如：

“把首页的文章卡片改成圆角阴影样式”
“在导航栏加一个关于我的页面链接”
“把代码块的主题换成深色风格”
“给文章页加一个目录导航”

描述得越具体，AI 改出来的效果越接近你的预期。

4. AI 生成方案并应用#

AI 会分析你的项目代码，生成修改方案。你确认后它直接改文件。

5. 预览效果#

本地跑 pnpm dev 看效果，不满意就继续让 AI 调。

6. 满意后推送#

Terminal window

1
git add .
2
git commit -m "修改xxx样式"
3
git push

常见修改场景#

这些是 AI 工具比较擅长的：

样式调整：颜色、字体、间距、圆角、阴影这些视觉相关的改动，AI 处理得很好。

添加功能：搜索框、评论区、分享按钮、暗色模式切换等常见功能，基本一句话就能加上。

响应式适配：让博客在手机上也好看，AI 能帮你写媒体查询。

SEO 优化：让 AI 帮你优化 meta 标签、文章结构。

注意事项#

改之前先备份。 虽然 Git 本身就有版本记录，但保险起见，大改之前先 commit 一次当前状态。

小步测试。 不要一次让 AI 改太多东西，改一点测一点，出问题容易定位。

了解基本概念。 虽然不用会写代码，但知道 HTML 是结构、CSS 是样式这种基本概念，和 AI 沟通会更顺畅。

参考博客#

视频里展示的几个改得很好看的博客：

mmzhiku 大佬：tblog.mmzhiku.xyz
团子和蛋糕大佬：blog.tsh520.cn
我的博客：fqzlr.com

可以去参考一下别人的改法，找到自己喜欢的风格再动手。

视频链接：BV131TM6FEPJ

用 Obsidian 丝滑的写博客，分享一个轻量化的笔记博客

Wed, 27 May 2026 00:00:00 GMT

这个方案适合谁#

前面几期讲了完整的 Firefly 博客搭建流程，有些人可能觉得还是有点复杂。这期分享一个更轻量的方案——直接用 Obsidian 当博客后端，生成一个简洁的笔记站点。

如果你只是想有个地方放笔记、分享知识，不需要花里胡哨的设计，这个方案很适合。

效果展示#

演示站点：bj.fqzlr.com

整体风格非常简洁，就是笔记列表 + 文章内容的形式。没有复杂的导航、没有炫酷的动效，就是安安静静展示内容。

和完整博客的区别#

	完整博客（Firefly）	轻量化笔记博客
功能	完整博客功能	纯笔记展示
自定义	高度可定制	开箱即用
配置复杂度	需要配不少东西	基本不用配
适合场景	个人品牌、内容运营	个人笔记、知识分享
维护成本	偶尔需要更新	几乎不用管

核心思路#

其实和上一期讲的 Obsidian 联动方案类似，区别在于：

不需要完整的 Firefly 主题，用更轻量的 Astro 模板
Obsidian 里写笔记，通过插件同步到 Astro 项目
部署方式和之前一样用 Cloudflare

最大的区别是简单。不用折腾主题配置、不用管各种插件，装上就能用。

快速上手#

如果你已经有 Obsidian 和 Astro 环境：

创建一个轻量的 Astro 项目
配置 Astro Composer 插件（参考上一期）
部署到 Cloudflare

如果你还没有这些，建议先看前面的教程把基础环境搭好，再回来做这个就很快了。

一些使用建议#

笔记组织：在 Obsidian 里建一个专门的文件夹放要发布的笔记，和日常笔记分开管理。

写作习惯：不用每篇都追求完美，笔记嘛，记录想法就好。积累多了自然有价值。

定期整理：隔一段时间回顾一下，把好的笔记优化一下，过时的删掉或归档。

演示站点：bj.fqzlr.com
视频链接：BV1eUG16nErs

Obsidian 笔记软件联动 Mizuki & Firefly Astro 等个人博客，优雅的利用图床写文章

Mon, 18 May 2026 00:00:00 GMT

这套工作流是什么#

简单说就是：用 Obsidian 写笔记 -> 自动转成博客文章格式 -> 推送到 GitHub -> 博客自动更新。

写文章的人不需要关心部署、构建这些事，只管在 Obsidian 里写就行。整个流程打通之后，写作体验非常丝滑。

这个方案适用于所有基于 Astro 的博客主题，包括 Mizuki、Firefly 等。

前置条件#

已经有一个 Astro 博客（参考前面几期教程）
安装了 Obsidian
有一个自建图床（参考第5期图床教程）
会基本的 Git 操作

核心：安装 Astro Composer 插件#

这个插件是 Obsidian 和 Astro 博客之间的桥梁，它能把 Obsidian 笔记自动转换成 Astro 能识别的 Markdown 格式。

安装步骤#

Astro Composer 还没上架社区插件库，需要通过 BRAT 安装：

先在 Obsidian 社区插件里搜索安装 BRAT
启用 BRAT 后，打开 BRAT 设置
点 Add a beta plugin
输入仓库地址：https://github.com/astro-modular/astro-composer
点 Add Plugin，等安装完启用

配置插件#

安装后进入 Astro Composer 设置，有几个关键配置项：

Posts Folder — Obsidian 里放博客文章的文件夹

比如设成 Blog/Posts，以后所有要发到博客的笔记都放在这个文件夹下。

Astro Content Path — 本地 Astro 项目的 src/content 目录路径

比如 D:/MyBlog/Firefly/src/content，插件会把转换后的内容同步到这个目录。

Link Base Path — 博客的文章访问路径前缀

比如填 /blog，插件会自动把 Obsidian 内部链接转成博客友好的格式。

Creation Mode — 文章存储结构

推荐选 Folder-based with index.md，每篇文章一个文件夹，里面放 index.md。

Draft Management — 草稿管理

建议启用 Underscore Prefix，草稿文件会自动加下划线前缀（如 _my-draft.md），Astro 会忽略这些文件不发布。

配合图床使用#

写文章的时候图片怎么办？这就是图床派上用场的时候了。

在 Obsidian 里插入图片
图片自动上传到你的 Cloudflare 图床
文章里的图片链接自动替换成图床 URL
推送到 GitHub 后，博客上的图片直接加载图床链接

这样图片不占项目仓库空间，加载速度也快。

日常写作流程#

配好之后日常使用就三步：

打开 Obsidian，在 Posts Folder 里新建笔记，正常写
写完后用 Git 推送代码到 GitHub
Cloudflare 自动构建，博客更新

整个过程不需要手动去管 Astro 的文件格式、Frontmatter 这些，Astro Composer 都帮你处理好了。

进阶：配合 Git 插件自动同步#

Obsidian 有个 Obsidian Git 插件，可以设置定时自动 commit + push。配好之后你连 Git 命令都不用打，写完笔记保存，Obsidian 自动帮你推到 GitHub。

这样就实现了真正的「写完即发布」。

视频链接：BV1jWLH6cERQ

fuwari 博客主题 Mizuki 和 Firefly 对比，以及好玩的主页和笔记博客分享

Sun, 10 May 2026 00:00:00 GMT

fuwari 框架简介#

fuwari 是一个基于 Astro 的静态博客框架体系，下面有多个主题可选。它的特点是部署方式统一（都是 Astro 生态），但不同主题的视觉风格差异很大，适合不同需求的人。

这期视频主要对比其中两个主题：Mizuki 和 Firefly。

Mizuki vs Firefly#

Mizuki#

Mizuki 更偏「笔记/知识库」风格，界面简洁清爽，适合喜欢极简风的人。它的特点是：

布局紧凑，信息密度高
适合做个人笔记、知识分享
首页展示文章列表，一目了然
整体风格偏学术/技术博客

如果你主要想拿来写技术笔记、做知识库，Mizuki 很合适。

Firefly#

Firefly 更偏「个人博客/主页」风格，视觉设计更丰富，可玩性更高。它的特点是：

界面更现代，动效和排版更讲究
支持更多自定义配置
社区活跃，文档齐全
适合做个人品牌展示

如果你想打造一个有设计感的个人博客，Firefly 是更好的选择。

怎么选#

	Mizuki	Firefly
风格	极简笔记	设计感博客
适合场景	知识库、技术笔记	个人品牌、内容展示
上手难度	简单	稍复杂但文档全
自定义程度	中等	较高

我的建议：如果你纠结，选 Firefly。它的文档更完善，社区更大，遇到问题更容易找到解决方案。而且后面几期教程都是基于 Firefly 讲的。

好玩的主页玩法#

除了传统博客，fuwari 生态还可以做很多有趣的东西：

个人主页：不做博客，就做一个简洁的个人介绍页，放你的联系方式、项目链接、技能展示。

笔记站：把 Obsidian 的笔记同步到博客，变成一个在线知识库。

项目展示：用来展示你的开源项目或者作品集。

友链#

视频里提到了友链功能。友链就是和其他博主互换链接，互相导流。Firefly 主题自带友链页面，你可以在 src/content/ 下创建友链数据文件，格式大概是：

1
name: 博主名
2
link: https://他们的博客地址
3
avatar: 头像链接
4
description: 一句话介绍

也可以加一个友链自助申请按钮，让访客自己提交。这个在后面的文章里有专门讲（Firefly 友链自助申请）。

欢迎来加友链：fqzlr.com/friends

不需要服务器，0成本，搭建属于自己的个人图床

Thu, 07 May 2026 00:00:00 GMT

什么是图床#

简单说就是一个专门存图片、能生成图片链接的服务。写博客、发公众号、做文档的时候经常会用到，有了图床就不用把图片塞在项目里占空间，也不用担心某个平台的图片链接失效。

市面上免费图床不少，但第三方图床总有跑路风险。自己搭一个最安心，而且用 Cloudflare 的方案完全免费。

为什么选 Cloudflare-ImgBed#

这个项目（github.com/MarSeventh/CloudFlare-ImgBed）支持多种存储方式（R2、KV、D1、Telegram），部署在 Cloudflare Workers 上，全球 CDN 加速，而且支持通过 GitHub Actions 自动更新。

核心优势：零成本、无服务器、全球加速、数据可控。

准备工作#

需要这些东西，后面一步步拿：

GitHub 账号
Cloudflare 账号（免费注册）
Cloudflare Account ID
Cloudflare API Token
KV 或 D1 数据库（二选一）

不需要装任何软件，全程浏览器操作。

部署步骤#

第一步：Fork 项目#

打开 CloudFlare-ImgBed 仓库，点右上角 Fork。

第二步：获取 Cloudflare 信息#

拿 Account ID 和 API Token：

登录 Cloudflare Dashboard
右上角头像 -> 我的个人资料 -> API 令牌
创建令牌，选模板「编辑 Cloudflare Workers」，一路下一步
生成的 Token 立刻复制保存，它只显示一次
回到 Dashboard 首页，右侧复制 Account ID

创建数据库（KV 和 D1 二选一）：

方案 A - KV（读写更快）：

存储和数据库 -> Workers KV -> 创建
名称填 img_url
复制命名空间 ID

方案 B - D1（免费额度更高）：

存储和数据库 -> D1 SQL 数据库 -> 创建
名称填 img_d1
复制数据库 ID
进入控制台，执行项目提供的 init.sql 初始化

可选：创建 R2 存储桶（用来存图片）

存储和数据库 -> R2 对象存储 -> 创建，名称随意。

第三步：配置 GitHub Secrets#

进入你 Fork 的仓库 -> Settings -> Secrets and variables -> Actions -> New repository secret，依次添加：

Secret 名称	值	必填
`CLOUDFLARE_API_TOKEN`	你的 API Token	是
`CLOUDFLARE_ACCOUNT_ID`	你的 Account ID	是
`KV_NAMESPACE_ID`	KV 命名空间 ID	KV/D1 二选一
`D1_DATABASE_ID`	D1 数据库 ID	KV/D1 二选一
`R2_BUCKET_NAME`	R2 存储桶名	可选

注意一定要用 Secrets 而不是 Variables，Variables 是公开的。

第四步：部署#

进入仓库 Actions 页面
选择 Deploy to Cloudflare Workers
点 Run workflow，分支选 main
等 1-3 分钟

看到绿色勾就部署成功了。

如果想以后自动同步上游更新，可以启用 Upstream Sync workflow，以后上游有新版本会自动同步并重新部署。

部署后#

访问 Worker 地址就能使用图床了。不过第一次使用需要先在后台管理面板配置存储渠道（R2 或 Telegram），配好之后才能正常上传图片。

常见问题#

部署失败：检查 Secrets 有没有填错，Token 权限对不对
无法上传图片：还没配置存储渠道，去后台绑定 R2 或 Telegram
链接打不开：确认 Worker 已启用，名称和子域名拼写正确

文字版教程：fqzlr.com/posts/blog/img-bed
视频链接：BV1MFRtBbE9B
项目地址：github.com/MarSeventh/CloudFlare-ImgBed

博客部署教程补充之 Cloudflare IP优选及文章编写发布

Sun, 03 May 2026 00:00:00 GMT

为什么要做 IP 优选#

Cloudflare 的默认节点对国内访问不太友好，有时候打开很慢。IP 优选的原理是找到一个国内延迟最低的 Cloudflare 节点，把你的域名解析到这个节点上，访问速度会有明显提升。

做完之后体感差别很大，建议部署好博客之后就做这一步。

IP 优选三步走#

第一步：添加路由规则#

登录 Cloudflare，进入你博客域名的控制台
左侧菜单找到 规则（Rules）
点 添加路由，地址填 你的域名/*（比如 blog.example.com/*）
保存

这条规则的作用是让博客的所有页面和静态资源都走优选节点。

第二步：配置 DNS 优选解析#

左侧菜单进入 DNS -> 记录
点 添加记录：
- 类型：A 记录或 CNAME 都行
- 名称：随便起个前缀，比如 speed
- 目标：填优选节点地址（格式 任意内容.cf.090227.xyz）
- 重点：关闭代理（把云朵图标点灰），不然优选不生效
保存

第三步：把主域名指向优选节点#

再添加一条 DNS 记录：
- 名称：填你博客域名的前缀（比如 blog，根域名就填 @）
- 目标：填上一步创建的记录名（比如 speed.你的域名.com）
- 代理状态：同样关闭
保存，等 1-3 分钟生效

刷新博客试试，应该能感觉到速度提升。

原理简述：博客域名 -> 优选地址 -> Cloudflare 自动选最快的国内节点。Astro 生成的都是纯静态文件（HTML/CSS/图片），配合 CDN 加速效果很好。

文章编写规范#

博客部署好了，接下来就是写文章。Firefly 用 Markdown（.md）或 MDX（.mdx）格式，功能很丰富。

文章放哪#

所有文章放在 src/content/posts/ 目录下，可以建子目录来组织。图片等资源放在同目录或 src/assets/ 下。文件名建议用英文连字符格式（如 cloudflare-ip-optimize.md），避免中文路径问题。

Frontmatter 必须写#

每篇文章顶部用 --- 包裹 YAML 元数据：

1
---
2
title: "文章标题"           # 必填
3
published: 2026-05-03       # 必填，发布日期
4
updated: 2026-05-04         # 可选，更新日期
5
description: "文章简介"      # 可选，首页卡片显示
6
image:                      # 可选，封面图（相对路径/网络链接/随机图API都行）
7
tags:
8
  - 标签1
9
  - 标签2
10
category: 分类名             # 可选
11
draft: false                # true 则隐藏不显示
12
pinned: false               # true 则置顶
13
slug: my-custom-url         # 可选，自定义URL路径
14
author: 作者名               # 可选
15
comment: true               # 可选，是否开启评论
16
---

显示更多显示更少

各字段说明：

字段	必填	说明
`title`	是	文章标题
`published`	是	发布日期，格式 `YYYY-MM-DD`
`updated`	否	更新日期
`description`	否	首页卡片显示的简介
`image`	否	封面图，支持相对路径、绝对路径、网络链接、随机图 API
`tags`	否	标签列表
`category`	否	分类
`draft`	否	`true` 为草稿不显示，`false` 正式发布
`pinned`	否	`true` 置顶显示
`slug`	否	自定义 URL 路径，建议英文连字符
`author`	否	作者名
`comment`	否	是否开启评论，默认 true
`licenseName`	否	许可证名称（如 CC BY-NC-SA 4.0）
`password`	否	文章密码，设置后需输入密码才能查看

数学公式（KaTeX）#

主题内置 KaTeX，直接用就行。

行内公式用单 $： $E = mc^2$

块级公式用双 $$：

1
$$
2
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
3
$$

Mermaid 图表#

用 mermaid 代码块即可渲染各种图表：

1
```mermaid
2
graph TD
3
    A[开始] --> B{条件}
4
    B -->|是| C[执行]
5
    B -->|否| D[结束]
6
```

还支持时序图、甘特图、饼图、类图、状态图等。

提醒框#

用 GitHub 风格的语法，很直观：

1
> [!NOTE]
2
> 普通提示
3

4
> [!TIP]
5
> 小技巧
6

7
> [!WARNING]
8
> 注意
9

10
> [!CAUTION]
11
> 危险操作

嵌入视频#

直接粘贴 iframe：

1
<iframe src="//player.bilibili.com/player.html?bvid=BV1xxxxx"
2
  scrolling="no" border="0" frameborder="no"
3
  framespacing="0" allowfullscreen="true">
4
</iframe>

GitHub 仓库卡片#

1
::github{repo="CuteLeaf/Firefly"}

编辑器选择#

两个推荐：

VS Code：适合想折腾项目配置的人，对 Astro 项目支持好
Obsidian：适合只想安静写文章的人，可视化编辑，不用记语法（后面有专门的教程讲怎么联动）

写完之后#

文章写好后：

Terminal window

1
git add .
2
git commit -m "新增文章：xxx"
3
git push

推到 GitHub 后 Cloudflare 自动构建上线，刷新博客就能看到了。

官方文档：docs-firefly.cuteleaf.cn/zh/guide/writing
文字版：fqzlr.com/posts/blog/ip
视频链接：BV1Hk9fBTE6H

不用服务器，零成本搭建一个自己的个人博客

Sat, 02 May 2026 00:00:00 GMT

根据Firefly 官方文档，涵盖全流程操作，代码可直接复制，小白可按步完成，附关键避坑提示。说明：基于 Windows 系统；命令可直接执行。

第一篇：前置准备｜安装必备环境#

一、前言#

Firefly 是 Astro 静态博客主题，本文是作者的搭建笔记，为以后回溯搭建过程，为后续操作筑牢基础。

二、必备软件清单#

Node.js：核心环境，版本 ≥22
pnpm
Git：用于拉取源码、提交代码
VS Code：推荐编辑器，用于修改配置、写文章

三、分步安装教程#

1. 安装 Node.js#

访问 https://nodejs.org/，下载 LTS 版。
image.png|528

image.png|534

终端执行 node -v、npm -v，输出版本号即成功。

image.png

注意：安装后重启终端，无效则重启电脑。

2. 安装 pnpm#

终端执行：npm install -g pnpm
执行 pnpm -v 输出版本号即成功，权限不足用管理员终端。

image.png

注意：网络超时切换手机热点。

3. 安装 Git#

1.访问 https://git-scm.com/download/win，下载最新版并默认安装。

image.png

2. 一直下一步就行了，全程默认安装。

4. 安装 VS Code（可选）#

1.访问 https://code.visualstudio.com/，下载并安装，勾选“创建桌面快捷方式”和“将 Code 加入 PATH”。

image.png

推荐安装中文插件。

image.png

四、常见环境问题排查#

node 命令无效 → 重新安装并勾选“Add to PATH”，重启终端/电脑。
pnpm 权限不足 → 用管理员终端执行命令。
git 无反应 → 重启电脑，无效则重装。

第二篇：源码托管｜Fork Firefly 官方仓库#

一、前言#

通过Fork官方仓库，获得自己的独立仓库，可自由修改内容、同步官方更新，后续推送代码到该仓库，Cloudflare会自动触发构建部署。

二、前置准备#

已完成第一篇环境安装（Node ≥22、pnpm、Git、VS Code）
已注册并登录 GitHub 账号

三、Fork 操作步骤（1分钟完成）#

打开Firefly官方仓库：https://github.com/CuteLeaf/Firefly
点击页面右上角的「Fork」按钮（绿色/灰色，位置显眼）。
等待3-5秒，页面自动跳转，此时你已拥有「自己的Firefly仓库」（仓库地址：https://github.com/你的GitHub用户名/Firefly）。

关键说明：Fork后的仓库归你所有，修改内容不会影响官方仓库，后续可一键同步官方更新，适合长期维护。

第三篇：本地搭建｜克隆仓库 + 本地预览调试#

一、前言#

将你Fork后的仓库克隆到本地，安装依赖后启动本地服务，用于预览修改效果（仅本地查看，无需打包，推送代码后Cloudflare自动部署）。

二、前置准备#

已完成前两篇操作（环境安装、Fork仓库）
新建空文件夹：路径无中文、无空格、无特殊字符（示例：D:\blog）

三、分步操作教程#

四、克隆你自己的仓库到本地#

进入 你的 Fork 仓库 页面
点击 Code → 复制 HTTPS 地址
执行克隆（把地址换成你自己的）：运行

1
git clone https://github.com/你的用户名/Firefly.git

1
cd Firefly

2. 安装本地依赖（仅用于本地预览）#

安装依赖（用 pnpm）运行

1
pnpm install

3. 启动本地预览服务#

1
pnpm dev

等待10-30秒，终端显示访问地址： http://localhost:4321
打开浏览器输入该地址，看到Firefly默认首页，即本地搭建成功。

4. 本地简单调试#

修改配置 / 文章 → 保存自动刷新

在项目根目录创建wrangler.toml： Cloudflare Workers部署需要

1
name = "firefly"
2
compatibility_date = "YYYY-MM-DD" # 更为今日
3

4
[assets]
5
directory = "./dist"
6

7
[vars]
8
NODE_VERSION = "22"

2.简单修改站点信息。

停止服务：Ctrl + C
重新启动：pnpm dev
本地仅用于预览，无需执行任何打包命令（Cloudflare会自动打包）。

5. 本地开发完成后#

1.先配置本地 Git 身份

打开电脑的终端（Mac/Linux） 或 Git Bash/CMD（Windows），执行 2 条命令：

1
# 1. 设置你的GitHub用户名（就是你GitHub主页的用户名）
2
git config --global user.name "你的GitHub用户名"
3

4
# 2. 设置你的GitHub绑定邮箱（就是你注册GitHub用的邮箱）
5
git config --global user.email "你的GitHub邮箱"

检测是否成功

1
git config --global user.name
2
git config --global user.email

1
能显示出你填的信息，就说明绑定好了。

2. 推送到 GitHub：

1
git add .
2
git commit -m "更新内容"
3
git push

第四篇：部署配置｜Cloudflare 关联GitHub自动构建#

一、前言#

这是核心部署步骤，关联你的GitHub仓库后，后续只要推送代码到GitHub，Cloudflare会自动执行「安装依赖→打包→上线」，全程无需手动操作。

二、前置准备#

已完成前几篇操作（环境安装、Fork仓库、本地搭建，简单修改，上传到github）
已注册并登录Cloudflare账号（无账号可注册：https://dash.cloudflare.com/）
你的GitHub仓库已包含完整Firefly源码

三、分步配置教程#

1. 新建 Cloudflare Worker 应用#

登录 Cloudflare 控制台 打开浏览器访问官方控制台：https://dash.cloudflare.com/，输入账号密码完成登录。
进入 Workers & Pages 页面 登录后，在左侧菜单栏找到并点击 Workers 和 Pages（英文对应：Workers & Pages），进入应用管理页面。
创建应用程序 在页面右上角，点击 创建应用程序（英文对应：Create application），进入应用创建流程。
关联 GitHub 代码仓库 在创建页面中，选择 连接到 Git（Connect Git），然后选中 GitHub，按照页面提示完成授权，允许 Cloudflare 访问你的 GitHub 账号。
选择目标仓库 授权完成后，系统会列出你的 GitHub 所有仓库，从中选中需要部署到 Cloudflare Worker 的代码仓库（如 Firefly 仓库）。
配置构建设置 ：

Build command: pnpm build
Deploy command: npx wrangler deploy

发起首次部署 配置完成后，点击页面底部的 部署（Deploy），启动首次自动部署流程。
等待自动构建完成 Cloudflare 会自动执行三个操作：拉取 GitHub 仓库代码 → 执行构建命令 → 将项目部署至 Workers 服务器，耐心等待即可。。

2. 验证自动部署是否成功#

当构建状态显示“成功”后，点击 Worker 项目顶部的 临时域名（格式为：xxx.workers.dev）。
打开浏览器访问该临时域名，若页面展示效果与本地预览的博客首页完全一致，说明 Cloudflare Worker 与 GitHub 自动部署配置成功。

第五篇：绑定域名（Spaceship 平台域名适配）#

完成 Cloudflare Worker 自动部署后，默认使用 xxx.workers.dev 临时域名访问，为了提升专业性和记忆性，我们将你在 Spaceship 平台注册的域名，绑定到 Worker 应用，全程适配博客框架，步骤清晰无冗余。

一、绑定前准备（必做）#

确认域名状态：登录 Spaceship 控制台，确认你的域名状态为“正常”，未被锁定、未过期，且已完成实名认证（若有要求），避免因域名异常导致绑定失败。

二、Step 1：在 Cloudflare 中添加自定义域名#

登录 Cloudflare 控制台，进入之前创建的 Worker 项目主页（可通过左侧「Workers 和 Pages」找到对应项目）。
在项目主页左侧导航栏，点击 触发器（英文：Triggers）选项卡，找到「自定义域」模块，点击 添加自定义域。
在弹出的输入框中，填写你在 Spaceship 平台的域名（如 yourdomain.com 或 www.yourdomain.com），点击添加。
添加后，Cloudflare 会自动生成对应的 DNS 解析记录（CNAME 记录），记录下该 CNAME 记录的「目标值」（通常为你的 Worker 临时域名），后续需在 Spaceship 平台配置该解析。

三、Step 2：在 Spaceship 平台配置 DNS 解析（核心步骤）#

这一步是关键，需在你的域名所在平台（Spaceship）修改 DNS 解析，将域名指向 Cloudflare Worker，具体操作如下：

登录 Spaceship 控制台：打开浏览器，访问 https://www.spaceship.com/zh/auth/?returnUrl=%2Flaunchpad%2F，输入你的账号密码完成登录（若已登录可直接进入）。
进入域名管理页面：登录后，点击顶部「Launchpad」（控制台），找到「Domain Manager」（域名管理）模块，在域名列表中找到你要绑定的域名，点击该域名进入详情页。
进入 DNS 解析设置：在域名详情页中，找到「DNS」选项（或「DNS 解析」「解析设置」），点击进入 DNS 解析配置页面，删除当前无关的解析记录（避免冲突）。
添加 CNAME 解析记录：点击「添加记录」（或「新增解析」），按以下参数填写（适配 Cloudflare Worker 绑定）：
1. 记录类型：选择 CNAME（核心类型，用于将域名指向 Worker 临时域名，适配 IP 动态变化场景）；
2. 主机记录：填写 @（代表主域名，如 yourdomain.com）或 www（代表带 www 前缀的域名，如 www.yourdomain.com，建议两者都添加）；
3. 记录值：粘贴 Step 1 中 Cloudflare 生成的 CNAME 目标值（即 Worker 临时域名，如xxx.workers.dev），确保填写无误；
4. TTL（缓存时间）：设置为 10~60 分钟（数值越小，解析生效越快，新手可直接默认）；
点击「保存」，完成 DNS 解析配置，此时 Spaceship 平台的域名解析已指向 Cloudflare Worker。

四、Step 4：验证域名绑定是否成功#

DNS 解析生效时间通常为 10 分钟~24 小时（新域名生效较快，老域名可能需等待更久），可通过以下两种方式验证绑定结果：

浏览器直接访问：打开浏览器，输入你绑定的域名（如 yourdomain.com），若能正常显示博客首页，且地址栏有 HTTPS 小锁标志，说明绑定成功；若提示“无法访问”，请耐心等待解析生效，或检查解析记录填写是否正确。
在线工具查询：使用 DNS 解析查询工具（如 DNSChecker.org），输入你的域名，查询 CNAME 记录，若查询结果与你配置的 Worker 临时域名一致，说明解析已生效，绑定成功。

###五、域名绑定常见问题排查

解析配置后无法访问：检查 Spaceship 平台的 CNAME 记录值是否与 Cloudflare 生成的目标值一致，TTL 设置是否过小，若无误，耐心等待解析生效（最长 24 小时）；同时确认 Cloudflare 中自定义域已添加成功。
浏览器提示“不安全”：检查 Cloudflare 的 SSL/TLS 加密模式是否设置正确，证书是否已生效，若未生效，等待几分钟后刷新页面重试。
提示“域名已被占用”：确认该域名未被其他 Cloudflare 项目绑定，若已绑定，先删除原有绑定，再重新添加。
DNS 解析修改无效：检查 Spaceship 平台的域名 DNS 服务器是否为默认服务器，若已修改为第三方 DNS，需先改回默认或同步解析记录至对应 DNS 服务器。

写在最后#

整个过程不需要写代码，核心操作就是 Fork 仓库、改配置、Cloudflare 关联 GitHub。部署完成后，写文章就是在 src/content/posts/ 目录下新建 Markdown 文件，push 到 GitHub 就自动上线。

文字版教程：fqzlr.com/posts/firefly-set/windows-firefly
官方文档：docs-firefly.cuteleaf.cn
视频链接：BV1hX9XBKEhm
Firefly 源码：github.com/CuteLeaf/Firefly

Git 使用教程

Tue, 28 Apr 2026 00:00:00 GMT

Git 详细使用教程（命令行版，附命令作用解释）#

Git 是目前最流行的分布式版本控制系统，核心作用是跟踪文件变化、管理代码版本，支持多人协作开发，可随时回滚到历史版本，避免代码丢失或冲突。本教程全程使用命令行操作（Windows 用 Git Bash、Mac/Linux 用终端），从基础配置到高级用法，逐一讲解命令作用和实操场景，新手可直接跟着步骤练习。

一、Git 前期准备（必做）#

1. 安装 Git#

先在本地安装 Git，安装完成后，打开命令行，输入以下命令验证是否安装成功：

Terminal window

1
git --version

命令作用：查看当前 Git 版本，若输出类似git version 2\.43\.0，说明安装成功；若提示“命令不存在”，需重新安装 Git。

2. 初始配置（绑定身份，关键步骤）#

Git 每次提交代码时，会记录提交者的身份（用户名和邮箱），用于区分不同开发者，必须配置后才能正常提交代码。

Terminal window

1
# 配置用户名（建议和 GitHub/GitLab 用户名一致）
2

3
git config --global user.name "你的用户名"
4

5

6

7
# 配置邮箱（建议和 GitHub/GitLab 绑定邮箱一致）
8

9
git config --global user.email "你的邮箱地址"

命令作用详解：

git config：Git 的配置命令，用于设置 Git 相关参数；
\-\-global：全局参数，意味着该配置在当前电脑所有 Git 项目中生效（若只想针对单个项目配置，去掉该参数，进入项目后再执行）；
user\.name/user\.email：配置提交者的用户名和邮箱，后续所有提交记录都会显示该信息。

验证配置是否成功：

Terminal window

1
git config --list

命令作用：查看当前 Git 的所有配置，若能看到刚才设置的用户名和邮箱，即为配置成功。

二、Git 核心概念（先理解，再操作）#

在使用命令前，先明确 3 个核心工作区域，避免操作混乱：

工作区（Working Directory）：就是你本地电脑上的项目文件夹，你直接修改的文件都在这个区域；
暂存区（Stage/Index）：临时存放你修改的文件，相当于“缓存区”，用于确认哪些修改需要提交到版本库；
版本库（Repository）：Git 真正保存版本的地方，存放所有提交记录，可随时回滚到任意历史版本（分为本地版本库和远程版本库，如 GitHub）。

核心流程：工作区修改 → 提交到暂存区 → 提交到本地版本库 → 推送到远程版本库（如 GitHub）。

三、本地仓库操作（最基础，必练）#

本地仓库是 Git 操作的基础，无需联网，可独立完成版本管理，适合个人开发或离线工作。

1. 初始化本地仓库（创建新项目）#

适用于：新建一个项目，想要用 Git 管理版本（比如本地新建的文件夹，需要变成 Git 仓库）。

Terminal window

1
# 1. 进入你要管理的项目文件夹（先切换到目标路径）
2

3
cd 你的项目文件夹路径（如：cd /Users/xxx/Documents/MyProject）
4

5

6

7
# 2. 初始化 Git 仓库
8

9
git init

命令作用详解：

cd：切换目录命令，用于进入你要操作的项目文件夹（若路径错误，会提示“没有该文件或目录”）；
git init：初始化 Git 仓库，执行后会在项目文件夹中生成一个隐藏的 \.git 文件夹（该文件夹是 Git 版本库的核心，不要删除），此时项目就被 Git 管理起来了。

注意：每个项目只需初始化一次，初始化后，该文件夹就是 Git 仓库了。

2. 查看工作区状态（高频命令）#

无论做什么操作，建议先查看工作区状态，确认当前文件的修改情况，避免误操作。

Terminal window

1
git status

命令作用：查看工作区、暂存区的文件状态，常见输出场景：

未修改：提示 nothing to commit, working tree clean（工作区干净，没有任何修改）；
已修改但未提交到暂存区：文件名称显示为 modified（红色）；
已提交到暂存区但未提交到版本库：文件名称显示为 staged（绿色）。

3. 将修改的文件提交到暂存区#

适用于：你在工作区修改了文件（如新增、修改、删除文件），需要先提交到暂存区，再准备提交到版本库。

Terminal window显示更多显示更少

1
# 方式1：提交所有修改的文件（最常用）
2

3
git add .
4

5

6

7
# 方式2：提交指定文件（适用于只提交部分修改）
8

9
git add 文件名（如：git add index.html）
10

11

12

13
# 方式3：提交指定文件夹下的所有文件
14

15
git add 文件夹名（如：git add src/）

显示更多显示更少

命令作用详解：

git add：将工作区的修改“暂存”起来，告诉 Git“这些修改我要提交到版本库，请先记录下来”；
\.：表示当前目录下所有修改的文件（包括新增、修改、删除），简化操作，无需逐个指定文件；
提交后，再执行git status，会看到文件变成绿色，提示“changes to be committed”（暂存区有等待提交的内容）。

4. 将暂存区的文件提交到本地版本库#

这是 Git 版本管理的核心步骤，提交后，修改会被永久保存到本地版本库，生成一条新的版本记录。

Terminal window

1
git commit -m "提交说明"

命令作用详解：

git commit：将暂存区的内容提交到本地版本库，完成一次版本更新；
\-m \&\#34;提交说明\&\#34;：必填参数，用于描述本次提交的内容（如“新增登录页面”“修复首页轮播bug”），建议说明清晰，方便后续查看历史记录时，快速知道该版本做了什么修改；
提交成功后，会提示类似 1 file changed, 2 insertions$\+$ 的信息，表示“1个文件被修改，新增了2行内容”。

注意：必须先执行 git add，再执行 git commit，否则会提示“没有可提交的内容”。

5. 查看提交历史记录#

适用于：查看之前的提交记录，包括提交者、提交时间、提交说明、版本号（用于回滚版本）。

Terminal window显示更多显示更少

1
# 方式1：查看完整历史记录（详细）
2

3
git log
4

5

6

7
# 方式2：查看简洁历史记录（只显示版本号和提交说明，推荐）
8

9
git log --oneline
10

11

12

13
# 方式3：查看所有提交记录（包括回滚的记录）
14

15
git reflog

显示更多显示更少

命令作用详解：

git log：显示所有提交记录，每条记录包含版本号（40位哈希值）、提交者、提交时间、提交说明；
\-\-oneline：简化输出，每条记录只显示前7位版本号和提交说明，更易查看；
git reflog：比 git log 更全面，会记录所有操作（包括回滚、撤销提交），常用于找回误删的版本。

6. 版本回滚（恢复到历史版本）#

适用于：修改出错、代码丢失，需要恢复到之前的某个稳定版本（核心操作，务必掌握）。

Terminal window显示更多显示更少

1
# 第一步：查看历史版本，获取要回滚的版本号（前7位即可）
2

3
git log --oneline
4

5

6

7
# 第二步：回滚到指定版本（两种常用方式）
8

9
# 方式1：彻底回滚，删除回滚版本之后的所有提交记录（谨慎使用，适合个人开发）
10

11
git reset --hard 版本号（如：git reset --hard a1b2c3d）
12

13

14

15
# 方式2：安全回滚，保留回滚版本之后的修改（推荐，适合多人协作）
16

17
git revert 版本号（如：git revert a1b2c3d）

显示更多显示更少

命令作用详解：

git reset \-\-hard 版本号：强制回滚到指定版本，工作区、暂存区的内容都会同步到该版本，之后的提交记录会被删除（无法恢复，谨慎使用）；
git revert 版本号：不会删除任何提交记录，而是生成一条新的提交记录，将代码恢复到指定版本，后续的修改仍然保留（安全，多人协作时优先使用）；
版本号：通过 git log \-\-oneline 获取，如 a1b2c3d（前7位即可，Git 会自动识别）。

7. 撤销工作区的修改（未提交到暂存区）#

适用于：在工作区修改了文件，但还没执行 git add，想放弃修改，恢复到上一次提交后的状态。

Terminal window

1
# 撤销单个文件的修改
2

3
git checkout -- 文件名（如：git checkout -- index.html）
4

5

6

7
# 撤销所有工作区的修改（未 add 的）
8

9
git checkout .

命令作用：放弃工作区的所有未暂存修改，将文件恢复到最近一次 git commit 或 git add 后的状态（注意：撤销后，修改会彻底丢失，无法恢复）。

8. 撤销暂存区的修改（已 add 但未 commit）#

适用于：执行了 git add，将修改提交到了暂存区，但还没执行 git commit，想撤销暂存，重新修改。

Terminal window

1
git reset HEAD 文件名（如：git reset HEAD index.html）
2

3

4

5
# 撤销所有暂存区的修改
6

7
git reset HEAD .

命令作用：将暂存区的修改撤销回工作区，此时文件状态会从“绿色（staged）”变回“红色（modified）”，之后可以重新修改、重新 add。

四、远程仓库操作（多人协作必备）#

远程仓库（如 GitHub、GitLab、Gitee）是用于多人共享代码的服务器，本地仓库的代码可以推送到远程，也可以从远程拉取别人的代码，实现协作开发。

前提：你已经有一个远程仓库（如在 GitHub 上创建了仓库），且本地 Git 已配置好远程仓库地址。

1. 关联远程仓库（第一次绑定）#

适用于：本地已有 Git 仓库，想要和远程仓库绑定，实现代码同步。

Terminal window

1
git remote add origin 远程仓库地址

命令作用详解：

git remote：用于管理远程仓库的命令（如添加、删除、查看远程仓库）；
add：添加远程仓库；
origin：远程仓库的别名（默认用 origin，可自定义，如 git remote add github 远程地址），后续操作远程仓库时，用别名即可，无需输入完整地址；
远程仓库地址：从 GitHub/GitLab 复制，一般分为 HTTPS 和 SSH 两种（HTTPS 无需配置密钥，直接输入账号密码即可；SSH 需要配置密钥，无需每次输入账号密码，推荐长期使用）。

查看已关联的远程仓库：

Terminal window

1
git remote -v

命令作用：查看当前本地仓库关联的所有远程仓库，输出会显示远程仓库的别名、地址，以及可进行的操作（fetch：拉取，push：推送）。

2. 从远程仓库拉取代码（同步别人的修改）#

适用于：多人协作时，别人将代码推送到了远程仓库，你需要将远程的最新代码拉取到本地，保持本地和远程同步。

Terminal window

1
# 方式1：拉取远程默认分支（如 main/master）的最新代码（最常用）
2

3
git pull origin main（或 master，取决于远程仓库的默认分支名）
4

5

6

7
# 方式2：拉取远程指定分支的代码
8

9
git pull origin 分支名（如：git pull origin develop）

命令作用详解：

git pull：等价于 git fetch \+ git merge，即先从远程拉取最新代码到本地临时区域，再自动合并到当前本地分支；
origin：远程仓库别名；
main/master：远程仓库的默认分支（GitHub 现在默认分支是 main，旧版本是 master）；
注意：拉取代码前，建议先执行 git commit，将本地的修改提交到本地版本库，避免拉取时出现代码冲突。

3. 将本地代码推送到远程仓库（分享自己的修改）#

适用于：你在本地完成了代码修改（已 commit 到本地版本库），想要将修改推送到远程仓库，让别人看到你的代码。

Terminal window显示更多显示更少

1
# 方式1：推送本地默认分支到远程默认分支（第一次推送需加 -u）
2

3
# 第一次推送（绑定本地分支和远程分支，后续可直接用 git push）
4

5
git push -u origin main（或 master）
6

7

8

9
# 后续推送（已绑定分支，无需加 -u）
10

11
git push origin main（或 master）
12

13

14

15
# 方式2：推送本地指定分支到远程指定分支
16

17
git push origin 本地分支名:远程分支名（如：git push origin develop:develop）

显示更多显示更少

命令作用详解：

git push：将本地版本库的提交记录推送到远程仓库；
\-u：第一次推送时使用，用于绑定本地分支和远程分支（如本地 main 分支绑定远程 main 分支），后续推送时，直接输入 git push 即可，无需指定别名和分支；
推送失败常见原因：① 本地代码不是最新的（需先 git pull 拉取远程最新代码，解决冲突后再推送）；② 没有远程仓库的权限（检查账号密码或 SSH 密钥配置）。

4. 克隆远程仓库到本地（第一次下载）#

适用于：本地没有该项目，直接从远程仓库下载完整的项目代码（包括所有版本记录）。

Terminal window

1
git clone 远程仓库地址

命令作用详解：

git clone：将远程仓库的所有内容（包括代码、版本记录、分支）完整下载到本地，自动创建项目文件夹，并初始化 Git 仓库；
执行后，本地会自动关联该远程仓库（别名默认是 origin），无需再执行 git remote add；
示例：git clone https://github\.com/用户名/项目名\.git（HTTPS 地址），或 git clone git@github\.com:用户名/项目名\.git（SSH 地址）。

5. 查看远程分支#

Terminal window显示更多显示更少

1
# 查看本地所有分支
2

3
git branch
4

5

6

7
# 查看远程所有分支
8

9
git branch -r
10

11

12

13
# 查看本地和远程所有分支
14

15
git branch -a

显示更多显示更少

命令作用：

git branch：查看本地已有的分支，当前所在分支会用 \* 标记；
\-r：查看远程仓库的所有分支；
\-a：查看本地和远程的所有分支（远程分支会显示为 remotes/origin/分支名）。

6. 切换/创建分支（多人协作核心）#

多人协作时，建议每人在自己的分支上开发，避免直接修改默认分支（main/master），开发完成后再合并到默认分支。

Terminal window显示更多显示更少

1
# 1. 创建新分支（并切换到该分支，最常用）
2

3
git checkout -b 分支名（如：git checkout -b develop）
4

5

6

7
# 等价于以下两条命令：
8

9
# git branch 分支名（创建分支）
10

11
# git checkout 分支名（切换到该分支）
12

13

14

15
# 2. 切换到已有的本地分支
16

17
git checkout 分支名（如：git checkout main）
18

19

20

21
# 3. 切换到远程分支（并创建本地对应分支）
22

23
git checkout -b 本地分支名 origin/远程分支名（如：git checkout -b develop origin/develop）

显示更多显示更少

命令作用详解：

git checkout \-b 分支名：一次性完成“创建分支+切换分支”，高效便捷；
分支命名建议：按功能命名（如 feature/login，表示登录功能分支）、按bug修复命名（如 fix/banner\-bug），便于区分。

7. 合并分支（将开发分支的代码合并到默认分支）#

适用于：在开发分支（如 develop）完成开发后，将代码合并到默认分支（如 main），让修改生效。

Terminal window

1
# 1. 先切换到要合并到的目标分支（如 main 分支）
2

3
git checkout main
4

5

6

7
# 2. 合并开发分支（如 develop 分支）到当前分支（main）
8

9
git merge develop

命令作用：将指定分支（如 develop）的所有修改，合并到当前所在的分支（如 main），合并后，main 分支就包含了 develop 分支的所有代码。

注意：合并时可能会出现代码冲突（如两个人同时修改了同一个文件的同一行），此时需要手动解决冲突：

执行 git merge 后，Git 会提示“冲突文件”；
打开冲突文件，找到标记冲突的地方（用 \<\<\<\<\<\<\<、=======、\>\>\>\>\>\>\> 标记）；
修改冲突内容（保留需要的代码，删除冲突标记）；
执行 git add \. 和 git commit \-m \&\#34;解决合并冲突\&\#34;，完成合并。

8. 删除分支（分支开发完成后）#

Terminal window显示更多显示更少

1
# 删除本地分支（分支已合并到主分支，可安全删除）
2

3
git branch -d 分支名（如：git branch -d develop）
4

5

6

7
# 强制删除本地分支（分支未合并，强行删除，谨慎使用）
8

9
git branch -D 分支名
10

11

12

13
# 删除远程分支
14

15
git push origin --delete 分支名（如：git push origin --delete develop）

显示更多显示更少

命令作用：删除无用的分支，保持分支结构清晰，避免混乱。

五、常用补充命令（高频实用）#

Terminal window显示更多显示更少

1
# 1. 查看当前分支的提交差异（对比工作区和暂存区）
2

3
git diff
4

5

6

7
# 2. 查看暂存区和本地版本库的差异
8

9
git diff --cached
10

11

12

13
# 3. 查看两个分支之间的差异
14

15
git diff 分支1 分支2（如：git diff main develop）
16

17

18

19
# 4. 暂存当前修改，切换到其他分支（临时切换分支，不提交当前修改）
20

21
git stash  # 暂存当前修改
22

23
git stash pop  # 恢复暂存的修改（恢复后，暂存记录删除）
24

25
git stash list  # 查看所有暂存记录
26

27

28

29
# 5. 重命名本地分支
30

31
git branch -m 旧分支名 新分支名
32

33

34

35
# 6. 更新远程分支列表（远程删除了分支，本地同步）
36

37
git fetch --prune

显示更多显示更少

每个命令的作用简要说明：

git diff：快速查看修改的具体内容（哪一行被修改、新增/删除了什么）；
git stash：临时保存未提交的修改，常用于“正在开发一个功能，突然需要切换到其他分支修复bug”的场景；
git fetch \-\-prune：同步远程分支的删除操作，避免本地显示已删除的远程分支。

六、常见问题解决（新手必看）#

1. 拉取/推送代码时，提示“权限不足”#

原因：未配置正确的账号密码或 SSH 密钥。

解决方法：

若用 HTTPS 地址：重新输入正确的 GitHub/GitLab 账号密码；
若用 SSH 地址：配置 SSH 密钥（网上搜索“GitHub SSH 密钥配置”，按步骤操作即可，配置一次终身可用）。

2. 合并分支时出现代码冲突#

解决方法：按前面“合并分支”部分的步骤，手动修改冲突文件，删除冲突标记，保留需要的代码，再提交即可。

注意：冲突解决后，一定要仔细检查代码，确保没有误删有用的内容。

3. 误删本地代码/误回滚版本，如何恢复？#

解决方法：执行 git reflog，查看所有操作记录，找到误删/误回滚前的版本号，再执行git reset \-\-hard 版本号，即可恢复到该版本。

4. 推送代码时，提示“本地版本落后于远程版本”#

原因：远程仓库有别人推送的最新代码，你的本地代码不是最新的，无法直接推送。

解决方法：先执行 git pull 拉取远程最新代码，解决冲突后，再执行 git push。

七、总结（核心流程梳理）#

Git 的核心操作围绕“本地仓库”和“远程仓库”展开，新手记住以下流程即可快速上手：

前期准备：安装 Git → 配置用户名和邮箱；
本地开发：初始化仓库（git init）→ 修改文件 → 提交到暂存区（git add .）→ 提交到本地版本库（git commit -m "说明"）；
多人协作：克隆远程仓库（git clone）→ 拉取远程更新（git pull）→ 创建分支开发 → 推送分支到远程（git push）→ 合并分支；
问题处理：版本回滚（git reset/git revert）、解决冲突、恢复误删代码（git reflog）。

Git 命令看似多，但常用的只有十几个，多练习几次（比如新建一个测试项目，反复执行 add、commit、push、pull 等操作），就能熟练掌握。记住：所有命令的核心都是“跟踪版本、同步代码”，理解每个命令的作用，比死记硬背更重要。

域名注册教程，最低一年只需要6元，com域名优惠价一年20元

Tue, 21 Apr 2026 00:00:00 GMT

为什么选 Spaceship#

Spaceship 是 Namecheap 旗下的域名注册平台，经常有新用户优惠，价格比国内大多数平台便宜不少。.com 域名首年大概 20 元左右，部分冷门后缀最低能到 6 元/年。

对比一下常见平台的价格：阿里云/腾讯云 .com 首年大概 55-69 元，续费也差不多。Spaceship 的价格优势很明显。

注册流程#

1. 注册账号#

打开 spaceship.com，右上角注册账号，用邮箱注册就行。

2. 搜索域名#

首页搜索框输入你想要的域名，比如 myblog，系统会列出所有可用后缀和对应价格。

几个建议：

优先选 .com，认知度最高
预算有限可以选 .xyz、.site、.online 这类，首年很便宜
域名尽量短，好记，避免拼音太长
注意看续费价格，有些首年便宜续费贵

3. 加入购物车并结算#

选好域名后加入购物车，结算时注意：

WHOIS 隐私保护：Spaceship 默认免费赠送，不用额外花钱
取消不必要的附加服务：默认可能会勾选一些付费服务，按需取消
支付方式支持信用卡、PayPal、支付宝等

4. 完成购买#

付款成功后，域名会出现在你的控制台。进入 Domain Manager 就能看到管理页面。

几个要注意的坑#

续费价格不等于首年价格。 买之前看一眼续费价，有些 .xyz 首年 6 块，续费可能要 60+。

域名转出有限制。 注册后 60 天内不能转出，不过正常使用不受影响。

实名认证。 Spaceship 是国外平台，不需要国内的实名认证流程，但如果后续要绑定国内服务器，则需要完成备案。我们后面搭建博客用的是 Cloudflare，流程相对简单。

后续步骤#

域名注册好了之后，后面搭建博客时会用到。主要是在 Cloudflare 里把域名解析到博客地址，这个在后面的部署教程里会详细讲。

视频链接：BV1BEdCBsEEw

怎么使用obsidian 来编写 astro 博客

Sat, 18 Apr 2026 00:00:00 GMT

Obsidian + Astro Composer + Git 插件同步 Astro 博客到 GitHub 完整教程

前置前提（必做）：

已安装 Obsidian 客户端，且启用「第三方插件」（设置 → 第三方插件 → 关闭“安全模式”）。
已创建 Astro 博客项目（本地需有 Astro 项目文件夹，可通过 pnpm create astro@latest 快速创建，选择 blog 模板即可），并熟悉 Astro 项目的 src/content 目录（用于存放博客文章）。
已注册 GitHub 账号，且创建了用于托管 Astro 博客的仓库（建议仓库名与 Astro 博客项目名一致，若要部署 GitHub Pages，仓库名可设为 用户名.github.io）。
已安装所需插件：Astro Composer（Obsidian 插件）、Git（Obsidian 插件，常用 Obsidian Git 或 Git Vault/Folder Sync，本教程以 Obsidian Git 为例，适配多数用户需求）。

第一步：安装并配置 Astro Composer 插件（核心：Obsidian 笔记转 Astro 内容）#

Astro Composer 是 Obsidian 与 Astro 博客无缝衔接的关键插件，可自动将 Obsidian 笔记转换为 Astro 支持的 Markdown 格式（含自动处理链接、标准化属性、管理草稿等），目前该插件暂未上架 Obsidian 社区插件库，需通过 BRAT 插件安装或手动安装，推荐 BRAT 安装（更便捷，支持自动更新）。

1.1 安装 Astro Composer 插件#

先安装 BRAT 插件：Obsidian 内 → 设置 → 第三方插件 → 浏览社区插件 → 搜索「BRAT」→ 安装并启用。
启用 BRAT 后，打开 BRAT 设置 → 点击「Add a beta plugin」→ 输入 Astro Composer 插件仓库地址（https://github.com/astro-modular/astro-composer）→ 点击「Add Plugin」，等待安装完成后启用插件。

1.2 配置 Astro Composer 插件#

配置核心目的：让插件知道「Obsidian 笔记存放位置」和「Astro 项目的内容目录位置」，实现笔记自动转换后同步到 Astro 项目中。

打开 Obsidian 设置 → 找到「Astro Composer」插件，进入配置页面。
image.png

image.png

image.png
核心配置项（必设）：
1. Posts Folder：设置 Obsidian 中用于存放博客文章的文件夹（例如 Blog/Posts），后续所有要发布的笔记都放在这个文件夹下。
2. Astro Content Path：设置本地 Astro 项目的src/content 目录路径（例如 D:/MyBlog/astro-blog/src/content），插件会自动将转换后的笔记同步到这个目录。
3. Link Base Path：设置链接基准路径，填写 Astro 博客的文章访问路径（例如 /blog），插件会自动将 Obsidian 内部链接（ wikilinks 或 Markdown 内部链接）转换为 Astro 友好的链接格式，避免发布后链接失效。
4. Creation Mode：选择文章存储结构，推荐「Folder-based with index.md」（每个文章对应一个文件夹，内部包含 index.md 文件），适配多数 Astro 博客模板。
5. Draft Management：启用「Underscore Prefix」，插件会为草稿笔记添加下划线前缀（例如 _my-draft.md），Astro 会自动隐藏这些草稿，避免误发布。
可选配置（优化体验）：
1. Property Standardization：设置笔记属性模板（例如标题、日期、标签等），启用「Standardize Properties」命令，可自动为笔记添加缺失的属性，保持 Astro 文章格式统一。
2. Rename Post Command：启用后，修改笔记的「title」属性，插件会自动将笔记文件名/文件夹名更新为 kebab-case 格式（例如“我的第一篇博客”→「my-first-blog」），适配 Astro 的路由规则。
配置完成后，点击「Save Settings」，重启插件（Obsidian 重启或禁用再启用），确保配置生效。

Include Video in the Posts

Mon, 01 Aug 2022 00:00:00 GMT

Just copy the embed code from YouTube or other platforms, and paste it in the markdown file.

1
---
2
title: Include Video in the Post
3
published: 2023-10-19
4
// ...
5
---
6

7
<iframe width="100%" height="468" src="https://www.youtube.com/embed/5gIf0_xpFPI?si=N1WTorLKL0uwLsU_" title="YouTube video player" frameborder="0" allowfullscreen></iframe>

YouTube#

Bilibili#

MDX 格式文章示例

Fri, 02 Jan 1970 00:00:00 GMT

Tip

Firefly 支持 MDX 和 Markdown 两种类型的文章，你可以在文章中混合使用两种格式，如果没有特别复杂内容和需求，推荐使用 Markdown 格式就够了。

Markdown 和 MDX 的区别#

Markdown (MD) 是一种轻量级标记语言，允许用户使用纯文本格式编写文档，然后将其转换为格式化的HTML。它因其简洁易用的语法而广受欢迎，特别适合编写文档和博客文章。
MDX 是一种扩展了 Markdown 语法的格式，允许在 Markdown 文档中无缝地插入 JSX 代码。通过 MDX，用户可以在文档中嵌入 React 组件，从而实现更丰富的交互性和动态性。

特性	Markdown	MDX
基础语法	支持 (CommonMark)	支持 (CommonMark)
HTML 标签	支持	支持 (作为 JSX)
组件导入	不支持	支持 (import)
动态数据	不支持	支持 (JS 表达式)
样式定制	有限 (class/style)	灵活 (className/CSS-in-JS)

使用组件#

这是一个图标组件：

import { Icon } from 'astro-icon/components'

<div class="flex items-center gap-2 my-4">
  <Icon name="fa7-solid:rocket" class="text-4xl text-red-500" />
  <span>火箭发射！</span>
</div>

火箭发射！

使用 JSX#

你也可以直接写 HTML/JSX：

<div className="p-4 bg-blue-100 dark:bg-blue-900 rounded-lg my-4">
  这是一个自定义样式的 div 块，使用了 Tailwind CSS 类。
</div>

这是一个自定义样式的 div 块，使用了 Tailwind CSS 类。

简单的变量导出#

export const year = new Date().getFullYear()

今年是 {year} 年。

今年是 2026 年。

更多信息，请查看 MDX 文档

Markdown 扩展功能

Thu, 01 Jan 1970 00:00:00 GMT

GitHub 仓库卡片#

您可以添加链接到 GitHub 仓库的动态卡片，在页面加载时，仓库信息会从 GitHub API 获取。

CuteLeaf

Firefly

Waiting for api.github.com...

00K

Waiting...

使用代码 ::github{repo="CuteLeaf/Firefly"} 创建 GitHub 仓库卡片。

1
::github{repo="CuteLeaf/Firefly"}

提醒框(Admonitions)配置#

Firefly 采用了 rehype-callouts 插件，支持了四种风格的提醒框主题：GitHub、Obsidian、VitePress 和 Docusaurus。您可以在 src/config/siteConfig.ts 中进行配置：

src/config/siteConfig.ts

1
export const siteConfig: SiteConfig = {
2
  // ...
3
  rehypeCallouts: {
4
    // 选项: "github" | "obsidian" | "vitepress" | "docusaurus"
5
    theme: "github",
6
  },
7
  // ...
8
};

注意：更改配置后需要重启开发服务器才能生效。

以下是各个主题支持的类型列表，每个主题风格和语法不同，可根据喜好选择。

1. GitHub 主题风格#

这是 GitHub 官方支持的 5 种基本类型。

GitHub

基本语法

1
> [!NOTE] NOTE
2
> 突出显示用户应该考虑的信息。
3

4
> [!TIP] TIP
5
> 可选信息，帮助用户更成功。
6

7
> [!IMPORTANT] IMPORTANT
8
> 用户成功所必需的关键信息。
9

10
> [!WARNING] WARNING
11
> 关键内容，需要立即注意。
12

13
> [!CAUTION] CAUTION
14
> 行动的负面潜在后果。
15

16
> [!NOTE] 自定义标题
17
> 这是一个带有自定义标题的示例。

显示更多显示更少

2. Obsidian 主题风格#

Obsidian 风格支持非常丰富的类型和别名。

点击展开 Obsidian 语法列表

1
> [!NOTE] NOTE
2
> 通用的笔记块。
3

4
> [!ABSTRACT] ABSTRACT
5
> 文章的摘要。
6

7
> [!SUMMARY] SUMMARY
8
> 文章的总结（同 Abstract）。
9

10
> [!TLDR] TLDR
11
> 太长不看（同 Abstract）。
12

13
> [!INFO] INFO
14
> 提供额外信息。
15

16
> [!TODO] TODO
17
> 需要完成的事项。
18

19
> [!TIP] TIP
20
> 实用技巧或提示。
21

22
> [!HINT] HINT
23
> 暗示（同 Tip）。
24

25
> [!IMPORTANT] IMPORTANT
26
> 重要信息（Obsidian 风格通常使用类似的图标）。
27

28
> [!SUCCESS] SUCCESS
29
> 操作成功。
30

31
> [!CHECK] CHECK
32
> 检查通过（同 Success）。
33

34
> [!DONE] DONE
35
> 已完成（同 Success）。
36

37
> [!QUESTION] QUESTION
38
> 提出问题。
39

40
> [!HELP] HELP
41
> 寻求帮助（同 Question）。
42

43
> [!FAQ] FAQ
44
> 常见问题（同 Question）。
45

46
> [!WARNING] WARNING
47
> 警告信息。
48

49
> [!CAUTION] CAUTION
50
> 注意事项（同 Warning）。
51

52
> [!ATTENTION] ATTENTION
53
> 引起注意（同 Warning）。
54

55
> [!FAILURE] FAILURE
56
> 操作失败。
57

58
> [!FAIL] FAIL
59
> 失败（同 Failure）。
60

61
> [!MISSING] MISSING
62
> 缺失内容（同 Failure）。
63

64
> [!DANGER] DANGER
65
> 危险操作警告。
66

67
> [!ERROR] ERROR
68
> 错误信息（同 Danger）。
69

70
> [!BUG] BUG
71
> 报告软件缺陷。
72

73
> [!EXAMPLE] EXAMPLE
74
> 展示一个例子。
75

76
> [!QUOTE] QUOTE
77
> 引用一段话。
78

79
> [!CITE] CITE
80
> 引证（同 Quote）。
81

82
> [!NOTE] 自定义标题
83
> 这是一个带有自定义标题的示例。

显示更多显示更少

Obsidian

3. VitePress 主题风格#

VitePress 风格提供了一套现代化的、扁平的默认样式。目前仅包含与 GitHub 一致的 5 种 基础类型。

点击展开 VitePress 语法列表

1
> [!NOTE] NOTE
2
> 对应 GitHub 的 Note。
3

4
> [!TIP] TIP
5
> 对应 GitHub 的 Tip。
6

7
> [!IMPORTANT] IMPORTANT
8
> 对应 GitHub 的 Important。
9

10
> [!WARNING] WARNING
11
> 对应 GitHub 的 Warning。
12

13
> [!CAUTION] CAUTION
14
> 对应 GitHub 的 Caution。
15

16
> [!TIP] 自定义标题
17
> VitePress 风格同样支持自定义标题。

显示更多显示更少

VitePress

4. Docusaurus 主题风格#

Docusaurus 风格提供了一套现代化的提醒框样式，支持 5 种类型。

点击展开 Docusaurus 语法列表

支持以下类型的提醒框：note tip info warning danger

1
:::note
2
突出显示用户应该考虑的信息，即使在快速浏览时也是如此。
3
:::
4

5
:::tip
6
可选信息，帮助用户更成功。
7
:::
8

9
:::info
10
一般信息。
11
:::
12

13
:::warning
14
由于潜在风险需要用户立即注意的关键内容。
15
:::
16

17
:::danger
18
行动的负面潜在后果。
19
:::
20

21
:::tip[自定义标题]
22
可选信息，帮助用户更成功。
23
:::

显示更多显示更少

Docusaurus

剧透#

您可以为文本添加剧透。文本也支持 Markdown 语法。

内容被隐藏了哈哈！

1
内容 :spoiler[被隐藏了 **哈哈**]！

图片画廊网格 (Image Grid)#

您可以使用 [grid] 和 [/grid] 标签将多张图片纵向并排展示。这对于展示照片画廊或对比图非常有用。系统会自动根据包裹在其中的图片数量（最多支持并排展示4张）以响应式网格进行布局。

自动补齐图片高度： 同一排中如果有高度、大小或者比例不一的图片，会像「九宫格画廊相册」一样自动撑满。较短或不协调的图片会自动使用 object-cover 进行完美中心裁剪补充视野。图片边框水平彻底对齐无缝隙，但被裁剪后，只有点击图片通过灯箱才能查看完整图片，所以建议尽量避免使用长宽比例不一致的图片在同一排中。

图注恒定底端对齐： 不论上面的图片长宽如何变化，在同一行的所有图像解释文字（图注）都会对标到一条完美的水平基线上了。

[grid]

示例图片一

示例图片二

[/grid]

基本语法

1
[grid]
2
![示例图片一](../images/firefly1.avif)
3
![示例图片二](../images/firefly2.avif)
4
![示例图片二](../images/firefly3.avif)
5
[/grid]

Markdown Mermaid 图表

Thu, 01 Jan 1970 00:00:00 GMT

Markdown 中 Mermaid 图表完整指南#

本文演示如何在 Markdown 文档中使用 Mermaid 创建各种复杂图表，包括流程图、时序图、甘特图、类图和状态图。

流程图示例#

流程图非常适合表示流程或算法步骤。

graph TD A[开始] --> B{条件检查} B -->|是| C[处理步骤 1] B -->|否| D[处理步骤 2] C --> E[子过程] D --> E subgraph E [子过程详情] E1[子步骤 1] --> E2[子步骤 2] E2 --> E3[子步骤 3] end E --> F{另一个决策} F -->|选项 1| G[结果 1] F -->|选项 2| H[结果 2] F -->|选项 3| I[结果 3] G --> J[结束] H --> J I --> J

时序图示例#

时序图显示对象之间随时间的交互。

sequenceDiagram participant User as 用户 participant WebApp as 网页应用 participant Server as 服务器 participant Database as 数据库 User->>WebApp: 提交登录请求 WebApp->>Server: 发送认证请求 Server->>Database: 查询用户凭据 Database-->>Server: 返回用户数据 Server-->>WebApp: 返回认证结果 alt 认证成功 WebApp->>User: 显示欢迎页面 WebApp->>Server: 请求用户数据 Server->>Database: 获取用户偏好 Database-->>Server: 返回偏好设置 Server-->>WebApp: 返回用户数据 WebApp->>User: 加载个性化界面 else 认证失败 WebApp->>User: 显示错误消息 WebApp->>User: 提示重新输入 end

甘特图示例#

甘特图非常适合显示项目进度和时间线。

gantt title 网站开发项目时间线 dateFormat YYYY-MM-DD axisFormat %m/%d section 设计阶段需求分析 :a1, 2023-10-01, 7d UI设计 :a2, after a1, 10d 原型创建 :a3, after a2, 5d section 开发阶段前端开发 :b1, 2023-10-20, 15d 后端开发 :b2, after a2, 18d 数据库设计 :b3, after a1, 12d section 测试阶段单元测试 :c1, after b1, 8d 集成测试 :c2, after b2, 10d 用户验收测试 :c3, after c2, 7d section 部署生产环境部署 :d1, after c3, 3d 发布 :milestone, after d1, 0d

类图示例#

类图显示系统的静态结构，包括类、属性、方法及其关系。

classDiagram class User { +String username +String password +String email +Boolean active +login() +logout() +updateProfile() } class Article { +String title +String content +Date publishDate +Boolean published +publish() +edit() +delete() } class Comment { +String content +Date commentDate +addComment() +deleteComment() } class Category { +String name +String description +addArticle() +removeArticle() } User "1" -- "*" Article : 写作 User "1" -- "*" Comment : 发表 Article "1" -- "*" Comment : 拥有 Article "1" -- "*" Category : 属于

状态图示例#

状态图显示对象在其生命周期中经历的状态序列。

stateDiagram-v2 [*] --> 草稿草稿 --> 审核中 : 提交审核中 --> 草稿 : 拒绝审核中 --> 已批准 : 批准已批准 --> 已发布 : 发布已发布 --> 已归档 : 归档已发布 --> 草稿 : 撤回 state 已发布 { [*] --> 活跃活跃 --> 隐藏 : 临时隐藏隐藏 --> 活跃 : 恢复活跃 --> [*] 隐藏 --> [*] } 已归档 --> [*]

饼图示例#

饼图非常适合显示比例和百分比数据。

pie title 网站流量来源分析 "搜索引擎" : 45.6 "直接访问" : 30.1 "社交媒体" : 15.3 "推荐链接" : 6.4 "其他来源" : 2.6

总结#

Mermaid 是在 Markdown 文档中创建各种类型图表的强大工具。本文演示了如何使用流程图、时序图、甘特图、类图、状态图和饼图。这些图表可以帮助您更清晰地表达复杂的概念、流程和数据结构。

要使用 Mermaid，只需在代码块中指定 mermaid 语言，并使用简洁的文本语法描述图表。Mermaid 会自动将这些描述转换为美观的可视化图表。

尝试在您的下一篇技术博客文章或项目文档中使用 Mermaid 图表 - 它们将使您的内容更加专业且更易理解！

Markdown PlantUML 图表

Thu, 01 Jan 1970 00:00:00 GMT

Markdown 中 PlantUML 图表指南#

PlantUML 是一种使用纯文本描述图表的工具。你只需要写一段结构化语法，就可以生成时序图、类图、用例图、活动图等常见工程图。

它特别适合写在技术博客和项目文档里：

图表和正文一起版本管理，便于协作与审阅
修改图只需要改文本，适合频繁迭代
能和 Markdown 无缝结合，保持文档统一

在 Firefly 中，plantuml 代码块会在构建阶段编码并生成服务器 SVG 地址，页面端再根据亮暗主题自动切换图源，并支持缩放、拖拽和全屏交互。

如果你想快速上手，可以记住这个最小模板：

1
@startuml
2
Alice -> Bob: Hello
3
Bob --> Alice: Hi
4
@enduml

活动图示例#

1
@startuml
2
start
3
:用户提交订单;
4
if (库存充足?) then (是)
5
  :冻结库存;
6
  :创建支付单;
7
  if (支付成功?) then (是)
8
    :生成发货单;
9
    :通知仓库拣货;
10
  else (否)
11
    :取消订单;
12
    :释放库存;
13
  endif
14
else (否)
15
  :提示缺货;
16
endif
17
stop
18
@enduml

显示更多显示更少

状态图示例#

1
@startuml
2
[*] --> 草稿
3

4
草稿 --> 待审核 : 提交
5
待审核 --> 草稿 : 驳回
6
待审核 --> 已发布 : 审核通过
7
已发布 --> 已归档 : 到期归档
8
已发布 --> 草稿 : 撤回修改
9

10
state 已发布 {
11
  [*] --> 可见
12
  可见 --> 隐藏 : 手动隐藏
13
  隐藏 --> 可见 : 恢复展示
14
}
15

16
已归档 --> [*]
17
@enduml

显示更多显示更少

用例图示例#

1
@startuml
2
left to right direction
3
actor 游客
4
actor 用户
5
actor 管理员
6

7
rectangle 博客系统 {
8
  usecase "浏览文章" as UC1
9
  usecase "搜索内容" as UC2
10
  usecase "发表评论" as UC3
11
  usecase "点赞收藏" as UC4
12
  usecase "审核评论" as UC5
13
  usecase "发布文章" as UC6
14
}
15

16
游客 --> UC1
17
游客 --> UC2
18
用户 --> UC1
19
用户 --> UC2
20
用户 --> UC3
21
用户 --> UC4
22
管理员 --> UC5
23
管理员 --> UC6
24
@enduml

显示更多显示更少

组件图示例#

1
@startuml
2
package "Firefly Site" {
3
  [Astro App] as App
4
  [Markdown Parser] as Parser
5
  [PlantUML Encoder] as Encoder
6
  [Theme Switcher] as Theme
7
  [Search Indexer] as Search
8
}
9

10
cloud "PlantUML Server" as PU
11
database "Content Store" as Content
12

13
App --> Parser : parse markdown
14
Parser --> Encoder : encode plantuml blocks
15
Encoder --> PU : request svg
16
App --> Theme : switch dark/light src
17
App --> Search : build page index
18
Parser --> Content : read posts
19
@enduml

显示更多显示更少

部署图示例#

1
@startuml
2
node "User Device" {
3
  artifact "Browser"
4
}
5

6
node "CDN / Edge" {
7
  artifact "Static Assets"
8
}
9

10
node "Cloudflare Worker" {
11
  artifact "SSR Handler"
12
}
13

14
node "PlantUML Service" {
15
  artifact "SVG Renderer"
16
}
17

18
database "Object Storage" {
19
  artifact "Markdown Content"
20
}
21

22
"Browser" --> "Static Assets" : GET js/css/img
23
"Browser" --> "SSR Handler" : request page
24
"SSR Handler" --> "Markdown Content" : read post
25
"Browser" --> "SVG Renderer" : fetch diagram svg
26
@enduml

显示更多显示更少

ER 图示例#

1
@startuml
2
entity User {
3
  *id : uuid <<PK>>
4
  --
5
  username : varchar
6
  email : varchar
7
  created_at : datetime
8
}
9

10
entity Post {
11
  *id : uuid <<PK>>
12
  --
13
  author_id : uuid <<FK>>
14
  title : varchar
15
  content : text
16
  published_at : datetime
17
}
18

19
entity Comment {
20
  *id : uuid <<PK>>
21
  --
22
  post_id : uuid <<FK>>
23
  user_id : uuid <<FK>>
24
  body : text
25
  created_at : datetime
26
}
27

28
User ||--o{ Post : writes
29
User ||--o{ Comment : creates
30
Post ||--o{ Comment : has
31
@enduml

显示更多显示更少

时序图示例（登录与刷新令牌）#

1
@startuml
2
autonumber
3
actor User as 用户
4
participant Web as 前端页面
5
participant API as 网关接口
6
participant Auth as 认证服务
7
database Redis as 会话缓存
8

9
用户 -> 前端页面 : 输入账号密码并提交
10
前端页面 -> 网关接口 : POST /login
11
网关接口 -> 认证服务 : 校验凭据
12
认证服务 -> 会话缓存 : 写入 refresh_token
13
认证服务 --> 网关接口 : access_token + refresh_token
14
网关接口 --> 前端页面 : 200 登录成功
15

16
... access_token 过期 ...
17

18
前端页面 -> 网关接口 : POST /refresh
19
网关接口 -> 认证服务 : 校验 refresh_token
20
认证服务 -> 会话缓存 : 轮换 refresh_token
21
认证服务 --> 网关接口 : 新 access_token
22
网关接口 --> 前端页面 : 200 新令牌
23
@enduml

显示更多显示更少

C4 风格容器图示例#

1
@startuml
2
!includeurl https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
3

4
Person(user, "博客访客", "阅读文章与搜索内容")
5

6
System_Boundary(system, "Firefly Blog") {
7
  Container(web, "Web App", "Astro + Svelte", "渲染页面与交互")
8
  Container(worker, "SSR Worker", "Cloudflare Workers", "处理服务端渲染请求")
9
  ContainerDb(content, "Content Store", "Markdown / Object Storage", "存储文章与资源元数据")
10
  Container(search, "Search Index", "Pagefind", "提供全文检索")
11
}
12

13
System_Ext(plantuml, "PlantUML Server", "生成 SVG 图表")
14

15
Rel(user, web, "访问", "HTTPS")
16
Rel(web, worker, "请求 SSR 页面", "HTTPS")
17
Rel(worker, content, "读取文章")
18
Rel(web, search, "查询关键词")
19
Rel(web, plantuml, "请求图表 SVG")
20

21
LAYOUT_LEFT_RIGHT()
22
@enduml

显示更多显示更少

Markdown 教程

Thu, 01 Jan 1970 00:00:00 GMT

这是一个展示如何编写 Markdown 文件的示例。本文档汇总了核心语法与常见扩展（GFM）。

块级元素
- 段落与换行
- 标题
- 引用
- 列表
- 代码块
- 分割线
- 表格
内联元素
- 链接
- 强调
- 行内代码
- 图片
- 删除线
杂项
- 自动链接
- 反斜杠转义
内联 HTML

块级元素#

段落与换行#

段落#

HTML 标签：<p>

使用一个或多个空行分隔段落。（仅包含空格或制表符的行也视为空行。）

代码：

1
This will be
2
inline.
3

4
This is second paragraph.

预览：

This will be inline.

This is second paragraph.

换行#

HTML 标签：<br />

在行末添加两个或更多空格来产生换行。

代码：

1
This will be not
2
inline.

预览：

This will be not
inline.

标题#

Markdown 支持两种标题样式：Setext 与 atx。

Setext#

HTML 标签：<h1>，<h2>

使用等号 (=) 表示 <h1>、使用短横线 (-) 表示 <h2>，数量不限，作为“下划线”。

代码：

1
This is an H1
2
=============
3
This is an H2
4
-------------

预览：

This is an H1#

This is an H2#

atx#

HTML 标签：<h1>，<h2>，<h3>，<h4>，<h5>，<h6>

在行首使用 1-6 个井号 (#)，对应 <h1> 至 <h6>。

代码：

1
# This is an H1
2
## This is an H2
3
###### This is an H6

预览：

This is an H1#

This is an H2#

This is an H6#

可选：你可以在行尾“闭合” atx 标题。末尾的井号数量不必与开头一致。

代码：

1
# This is an H1 #
2
## This is an H2 ##
3
### This is an H3 ######

预览：

This is an H1#

This is an H2#

This is an H3#

引用#

HTML 标签：<blockquote>

Markdown 使用邮件风格的 > 作为引用符号。若手动换行并在每行前加 >，显示效果最佳。

代码：

1
> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
2
> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
3
> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
4
>
5
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
6
> id sem consectetuer libero luctus adipiscing.

预览：

This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

Markdown 允许“偷懒”：在一个硬换行段落中，只在第一行前加 > 即可。

代码：

1
> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
2
consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
3
Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
4

5
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
6
id sem consectetuer libero luctus adipiscing.

预览：

This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

引用可以嵌套（引用中的引用），通过增加 > 层级实现。

代码：

1
> This is the first level of quoting.
2
>
3
> > This is nested blockquote.
4
>
5
> Back to the first level.

预览：

This is the first level of quoting.
This is nested blockquote.
Back to the first level.

引用内可包含其他 Markdown 元素，包括标题、列表与代码块。

代码：

1
> ## This is a header.
2
>
3
> 1.   This is the first list item.
4
> 2.   This is the second list item.
5
>
6
> Here's some example code:
7
>
8
>     return shell_exec("echo $input | $markdown_script");

预览：

This is a header.#

This is the first list item.

This is the second list item.

Here’s some example code:
1
return shell_exec("echo $input | $markdown_script");

列表#

Markdown 支持有序（数字）与无序（圆点）列表。

无序列表#

HTML 标签：<ul>

无序列表可使用 星号 (*)、加号 (+) 或 短横线 (-)。

代码：

1
*   Red
2
*   Green
3
*   Blue

预览：

Red
Green
Blue

等价于：

代码：

1
+   Red
2
+   Green
3
+   Blue

或者：

代码：

1
-   Red
2
-   Green
3
-   Blue

有序列表#

HTML 标签：<ol>

有序列表使用数字加英文句点：

代码：

1
1.  Bird
2
2.  McHale
3
3.  Parish

预览：

Bird
McHale
Parish

注意：像下面这样可能会“意外触发”有序列表：

代码：

1
1986. What a great season.

预览：

What a great season.

你可以用反斜杠转义 (\) 句点：

代码：

1
1986\. What a great season.

预览：

1986. What a great season.

列表中的缩进内容#

列表项里的引用#

在列表项内放置引用，需要将 > 符号整体缩进：

代码：

1
*   A list item with a blockquote:
2

3
    > This is a blockquote
4
    > inside a list item.

预览：

A list item with a blockquote:

This is a blockquote inside a list item.

列表项里的代码块#

在列表项内放置代码块，需要缩进两层——8 个空格或两个 Tab：

代码：

1
*   A list item with a code block:
2

3
        <code goes here>

预览：

A list item with a code block:
```
1
<code goes here>
```

嵌套列表#

代码：

1
* A
2
  * A1
3
  * A2
4
* B
5
* C

预览：

A
- A1
- A2
B
C

代码块#

HTML 标签：<pre>

将代码块中的每行缩进至少4 个空格或1 个制表符。

代码：

1
This is a normal paragraph:
2

3
    This is a code block.

预览：

This is a normal paragraph:

1
This is a code block.

代码块会一直持续，直到遇到未缩进的行（或文末）。

在代码块内，与号 (&) 和尖括号 (< >) 会自动转为 HTML 实体。

代码：

1
    <div class="footer">
2
        &copy; 2004 Foo Corporation
3
    </div>

预览：

1
<div class="footer">
2
    &copy; 2004 Foo Corporation
3
</div>

下文的“围栏代码块”和“语法高亮”属于扩展语法，你也可以用它们来书写代码块。

围栏代码块#

使用成对的反引号围起来（如下所示），就不需要四空格缩进了。

代码：

1
Here's an example:
2

3
```
4
function test() {
5
  console.log("notice the blank line before this function?");
6
}
7
```

预览：

Here’s an example:

1
function test() {
2
  console.log("notice the blank line before this function?");
3
}

语法高亮#

在围栏代码块后添加可选的语言标识，即可启用语法高亮（参见支持语言列表）。

代码：

1
```ruby
2
require 'redcarpet'
3
markdown = Redcarpet.new("Hello World!")
4
puts markdown.to_html
5
```

预览：

1
require 'redcarpet'
2
markdown = Redcarpet.new("Hello World!")
3
puts markdown.to_html

分割线（水平线）#

HTML 标签：<hr /> 一行中放置三个或以上的短横线 (-)、星号 (*) 或下划线 (_)。符号之间允许有空格。

代码：

1
* * *
2
***
3
*****
4
- - -
5
---------------------------------------
6
___

预览：

表格#

HTML 标签：<table>

这是扩展语法。

用竖线 (|) 分隔列，用短横线 (-) 分隔表头，使用冒号 (:) 指定对齐方式。

两侧的竖线 (|) 与对齐可选。用于表头分隔时，每列至少需要 3 个短横线。

代码：

1
| Left | Center | Right |
2
|:-----|:------:|------:|
3
|aaa   |bbb     |ccc    |
4
|ddd   |eee     |fff    |
5

6
 A | B
7
---|---
8
123|456
9

10

11
A |B
12
--|--
13
12|45

预览：

Left	Center	Right
aaa	bbb	ccc
ddd	eee	fff

A	B
123	456

A	B
12	45

内联元素#

链接#

HTML 标签：<a>

Markdown 支持两种链接样式：行内链接与引用式链接。

行内链接#

行内链接格式：[文本](URL "标题")

标题可选。

代码：

1
This is [an example](http://example.com/ "Title") inline link.
2

3
[This link](http://example.net/) has no title attribute.

预览：

This is an example inline link.

This link has no title attribute.

如果引用同一站点的本地资源，可以使用相对路径：

代码：

1
See my [About](/about/) page for details.

预览：

See my About page for details.

引用式链接#

可以预定义链接引用。定义格式：[id]: URL "标题"

标题同样可选。引用时使用：[文本][id]

代码：

1
[id]: http://example.com/  "Optional Title Here"
2
This is [an example][id] reference-style link.

预览：

This is an example reference-style link.

说明：

方括号中包含链接标识（不区分大小写，可在左侧缩进最多三格空格）；
随后是冒号；
再跟一个或多个空格（或 tab）；
然后是链接 URL；
URL 可选地用尖括号包裹；
可选地跟随标题属性，用引号或圆括号包裹。

以下三种定义等价：

代码：

1
[foo]: http://example.com/  "Optional Title Here"
2
[foo]: http://example.com/  'Optional Title Here'
3
[foo]: http://example.com/  (Optional Title Here)
4
[foo]: <http://example.com/>  "Optional Title Here"

如果使用空的方括号，则链接文本本身会作为名称。

代码：

1
[Google]: http://google.com/
2
[Google][]

预览：

Google

强调#

HTML 标签：<em>，<strong>

Markdown 使用 星号 (*) 或 下划线 (_) 表示强调。一个分隔符对应 <em>；两个分隔符对应 <strong>。

代码：

1
*single asterisks*
2

3
_single underscores_
4

5
**double asterisks**
6

7
__double underscores__

预览：

single asterisks

single underscores

double asterisks

double underscores

但如果两侧有空格，则会被视作普通字符而非强调语法。

你可以使用反斜杠进行转义：

代码：

1
\*this text is surrounded by literal asterisks\*

预览：

*this text is surrounded by literal asterisks*

行内代码#

HTML 标签：<code>

用反引号 (`) 包裹。

代码：

1
Use the `printf()` function.

预览：

Use the printf() function.

若行内代码中需要包含反引号字符，可使用多重反引号作为定界符：

代码：

1
``There is a literal backtick (`) here.``

预览：

There is a literal backtick (`) here.

行内代码两侧的定界符允许包含空格（开头一个、结尾一个），方便在代码起始或结尾放置反引号字符：

代码：

1
A single backtick in a code span: `` ` ``
2

3
A backtick-delimited string in a code span: `` `foo` ``

预览：

A single backtick in a code span: `

A backtick-delimited string in a code span: `foo`

图片#

HTML 标签：<img />

Markdown 的图片语法与链接类似，支持行内与引用两种方式。

行内图片#

行内图片语法：![替代文本](URL "标题")

标题可选。

代码：

1
![Alt text](/path/to/img.jpg)
2

3
![Alt text](/path/to/img.jpg "Optional title")

预览：

Alt text

说明：

一个感叹号 !；
后接方括号，放置图片的替代文本；
再接圆括号，内含图片 URL/路径，及可选的标题（引号包裹）。

引用式图片#

引用式图片语法：![替代文本][id]

代码：

1
[img id]: https://s2.loli.net/2024/08/20/5fszgXeOxmL3Wdv.webp  "Optional title attribute"
2
![Alt text][img id]

预览：

Alt text

删除线#

HTML 标签：<del>

这是扩展语法。

GFM 增加了删除线语法。

代码：

1
~~Mistaken text.~~

预览：

Mistaken text.

杂项#

自动链接#

Markdown 支持一种便捷写法来创建“自动链接”（URL 与邮箱地址）：只需用尖括号将其包住即可。

代码：

1
<http://example.com/>
2

3
<address@example.com>

预览：

http://example.com/

address@example.com

GFM 会自动识别标准 URL 并转换为链接。

代码：

1
https://github.com/emn178/markdown

预览：

https://github.com/emn178/markdown

反斜杠转义#

Markdown 允许使用反斜杠来转义那些本用于 Markdown 语法的特殊字符，使其按字面显示。

代码：

1
\*literal asterisks\*

预览：

*literal asterisks*

以下字符可通过反斜杠转义以按字面量输出：

Code:

1
\   backslash
2
`   backtick
3
*   asterisk
4
_   underscore
5
{}  curly braces
6
[]  square brackets
7
()  parentheses
8
#   hash mark
9
+   plus sign
10
-   minus sign (hyphen)
11
.   dot
12
!   exclamation mark

内联 HTML#

对于 Markdown 语法未覆盖的标记，直接使用原生 HTML 即可。无需特别声明从 Markdown 切换到 HTML，直接写标签就行。

代码：

1
This is a regular paragraph.
2

3
<table>
4
    <tr>
5
        <td>Foo</td>
6
    </tr>
7
</table>
8

9
This is another regular paragraph.

预览：

This is a regular paragraph.

Foo

This is another regular paragraph.

请注意：在块级 HTML 标签内不会处理 Markdown 语法。

与块级标签不同，在行内级标签内会处理 Markdown 语法。

代码：

1
<span>**Work**</span>
2

3
<div>
4
    **No Work**
5
</div>

预览：

Work

**No Work**

***

Fqzlr的博客

友链挂了？自动检测+主页截图，GitHub Actions 全搞定

为什么要做这个#

参考链接#

实现思路#

关键文件#

反链检测怎么做的#

怎么部署#

第一步：Fork 仓库#

第二步：配置 Secrets#

第三步：开启 Actions 写权限#

第四步：准备友链数据源#

第五步：准备图床#

第六步：首次触发#

第七步：部署到 Vercel#

怎么触发#

自动触发（不用管）#

手动触发（按需）#

常见场景#

增量处理是什么#

一些细节#

截图兜底链#

截图频率为什么是 6 天#

数据源只维护一份#

最后#

评论区也能发图了：Waline 接入图床 + 按页面路径自动归类

为什么要做这个#

实现思路#

准备工作#

第一步：配置文件加入图床入口#

第二步：补全类型声明#

第三步：实现 imageUploader#

注入配置到客户端#

上传函数本体#

亮点：按页面路径自动归类#

归类规则#

实际效果#

传给图床#

响应解析：兼容多种格式#

完整文件改动清单#

常见问题#

最后#

博客，是好看好，还是简单好？

一、颜值型博客：主打审美与个人风格#

二、极简型博客：主打阅读与实用性#

三、两种风格核心对比#

四、结语：适配自己的，就是最好的#

Twikoo 评论一键迁移 Waline（双向互转）

一、迁移前置说明#

前置准备清单#

二、第一步：导出原始评论数据#

Twikoo 导出#

Waline 导出#

三、第二步：双向转换工具（自动修复路径尾斜杠 + 保留嵌套回复）#

工具核心能力#

内嵌交互式转换工具#

Twikoo ↔ Waline 双向转换器

转换结果预览

转换工具操作步骤#

Twikoo → Waline 方向#

Waline → Twikoo 方向（反向恢复）#

四、第三步：Waline 后台导入转换后的评论文件#

五、第四步：Firefly 博客前台验证评论展示#

路径匹配原理#

前台无评论 / 层级错乱排查方案#

六、高频踩坑问题汇总#

坑1：导入时报 500 错误 invalid input syntax for type timestamp#

坑2：导入成功，后台可见评论，Firefly 前台页面空白#

坑3：导入提示成功，但 Waline 后台无任何评论#

坑4：所有回复全部平铺，没有嵌套层级#

坑5：转换工具下载按钮点击无响应#

坑6：评论图片、换行、Emoji 丢失乱码#

七、兜底备用方案（后台导入解析失败时）#

小白怎么二改博客？使用国产 Codex 阿里的 Qoder、字节的 Trae 来一键修改

不会代码也能改博客#

工具介绍#

阿里 Qoder#

字节 Trae#

对比#

操作流程#

坑1：导入时报 500 错误 `invalid input syntax for type timestamp`#