像风

快速开始

Fri, 05 Jun 2026 00:00:00 GMT

快速开始#

Firefly 是一款基于 Astro 框架和 Fuwari 模板开发的清新美观且现代化个人博客主题，专为技术爱好者和内容创作者设计。该主题融合了现代 Web 技术栈，提供了丰富的功能模块和高度可定制的界面，让您能够轻松打造出专业且美观的个人博客网站。

环境要求#

Node.js 22.0 或更高版本
pnpm 包管理器（推荐）
Git

安装#

克隆仓库

Terminal window

1
git clone https://github.com/CuteLeaf/Firefly.git
2
cd Firefly

安装依赖

Terminal window

1
pnpm install

启动开发服务器

Terminal window

1
pnpm dev

构建生产版本

Terminal window

1
pnpm build

项目结构#

1
Firefly/
2
├── src/
3
│   ├── config/          # 配置文件目录
4
│   ├── components/      # 组件目录
5
│   ├── content/         # 内容目录（文章、页面）
6
│   ├── layouts/         # 布局模板
7
│   ├── pages/           # 页面路由
8
│   └── types/           # 类型定义
9
├── public/              # 静态资源
10
└── astro.config.mjs     # Astro 配置

配置文件概览#

所有配置文件位于 src/config/ 目录下：

配置文件	说明	文档
`siteConfig.ts`	站点基础配置	站点配置
`navBarConfig.ts`	导航栏配置	导航栏
`sidebarConfig.ts`	侧边栏布局配置	侧边栏
`profileConfig.ts`	个人资料配置	个人资料
`backgroundWallpaper.ts`	背景壁纸配置	背景壁纸
`commentConfig.ts`	评论系统配置	评论系统
`musicConfig.ts`	音乐播放器配置	音乐播放器
`fontConfig.ts`	字体配置	字体
`coverImageConfig.ts`	封面图片配置	封面图片
`expressiveCodeConfig.ts`	代码块配置	代码块
`sakuraConfig.ts`	樱花特效配置	樱花特效
`announcementConfig.ts`	公告配置	公告
`footerConfig.ts`	页脚配置	页脚
`licenseConfig.ts`	许可证配置	许可证
`friendsConfig.ts`	友链配置	友链
`sponsorConfig.ts`	赞助配置	赞助
`adConfig.ts`	广告配置	广告
`pioConfig.ts`	Live2D/Spine 模型配置	看板娘

AI 封面图生成

Fri, 12 Jun 2026 00:00:00 GMT

方案说明#

手动为每篇文章找封面图很费时间，本方案通过 AI 图片生成 API 自动生成封面图：

读取文章的 title、description、tags，生成中文提示词
调用图片生成 API（如 DALL-E、Stable Diffusion 等）
将生成的图片保存到 public/images/covers/generated/
自动更新文章 frontmatter 的 image 字段
支持批量生成或指定单篇文章生成

配置 .env#

文件路径：.env

Terminal window

1
# AI 封面图生成配置（仅本地生成时使用，不需要提交，也不需要配到部署平台）
2
AI_COVER_API_KEY=sk-xxxxxxxxxxxxxxxx
3
AI_COVER_API_URL=https://api.openai.com/v1
4
AI_COVER_MODEL=dall-e-3

.env 已在 .gitignore 中，不会被提交。支持 OpenAI 原生 API 和兼容的第三方代理。

编写生成脚本#

文件路径：scripts/generate-cover-images.ts

导入依赖#

1
import { readdir, readFile, writeFile, mkdir } from "node:fs/promises";
2
import { join } from "node:path";
3
import { config } from "dotenv";
4

5
config();
6

7
const BLOG_DIR = "src/content/blog";
8
const OUTPUT_DIR = "public/images/covers/generated";
9
const API_KEY = process.env.AI_COVER_API_KEY;
10
const API_URL = process.env.AI_COVER_API_URL;
11
const MODEL = process.env.AI_COVER_MODEL || "dall-e-3";

解析 Frontmatter#

1
function parseFrontmatter(content: string) {
2
  const match = content.match(/^---\n([\s\S]*?)\n---/);
3
  if (!match) return null;
4

5
  const frontmatter: Record<string, any> = {};
6
  const lines = match[1].split("\n");
7

8
  for (const line of lines) {
9
    const [key, ...valueParts] = line.split(":");
10
    if (key && valueParts.length) {
11
      const value = valueParts.join(":").trim();
12
      frontmatter[key.trim()] = value.replace(/^["']|["']$/g, "");
13
    }
14
  }
15

16
  return frontmatter;
17
}

展开收起

生成提示词#

根据文章元数据生成图片生成提示词：

1
function generatePrompt(frontmatter: any): string {
2
  const title = frontmatter.title || "";
3
  const description = frontmatter.description || "";
4
  const tags = frontmatter.tags || "";
5

6
  return `为技术博客文章创建一个简洁、现代的封面图片。文章标题：${title}。描述：${description}。标签：${tags}。风格要求：扁平化设计、渐变色背景、图标或抽象元素、适合作为博客封面。`;
7
}

调用 API 生成图片#

使用 fetch 直接调用图片生成 API，接收 base64 格式图片：

1
async function generateImage(prompt: string, filename: string): Promise<string> {
2
  console.log(`🎨 正在生成图片：${filename}`);
3

4
  const response = await fetch(`${API_URL}/images/generations`, {
5
    method: "POST",
6
    headers: {
7
      Authorization: `Bearer ${API_KEY}`,
8
      "Content-Type": "application/json",
9
    },
10
    body: JSON.stringify({
11
      model: MODEL,
12
      prompt,
13
      n: 1,
14
      size: "1792x1024",
15
      response_format: "b64_json",
16
    }),
17
  });
18

19
  if (!response.ok) {
20
    const errorText = await response.text();
21
    throw new Error(`API 请求失败 (${response.status}): ${errorText}`);
22
  }
23

24
  const data = await response.json();
25
  const b64Data = data.data?.[0]?.b64_json;
26
  if (!b64Data) throw new Error("生成图片失败");
27

28
  const imageBuffer = Buffer.from(b64Data, "base64");
29
  const outputPath = join(OUTPUT_DIR, filename);
30

31
  await mkdir(OUTPUT_DIR, { recursive: true });
32
  await writeFile(outputPath, imageBuffer);
33
  console.log(`✅ 已保存：${outputPath}`);
34

35
  return `/images/covers/generated/${filename}`;
36
}

展开收起

处理单个文章#

1
async function processFile(file: string) {
2
  const filePath = join(BLOG_DIR, file);
3
  const content = await readFile(filePath, "utf-8");
4
  const frontmatter = parseFrontmatter(content);
5

6
  if (!frontmatter) {
7
    console.log(`⚠️  跳过（无 frontmatter）：${file}`);
8
    return;
9
  }
10

11
  // 跳过已有封面的文章（非 api 且非 unsplash）
12
  if (frontmatter.image && frontmatter.image !== "api" && !frontmatter.image.includes("source.unsplash.com")) {
13
    console.log(`⏭️  跳过（已有封面）：${file}`);
14
    return;
15
  }
16

17
  const prompt = generatePrompt(frontmatter);
18
  const filename = `${file.replace(/\.(md|mdx)$/, "")}.png`.replace(/\//g, "-");
19
  const imagePath = await generateImage(prompt, filename);
20

21
  // 更新 frontmatter 的 image 字段
22
  const newContent = content.replace(
23
    /^(---\n[\s\S]*?)image:.*$/m,
24
    `$1image: ${imagePath}`,
25
  );
26

27
  if (newContent === content) {
28
    // 如果没有 image 字段，追加一个
29
    const updatedContent = content.replace(
30
      /^(---\n[\s\S]*?)\n---/,
31
      `$1\nimage: ${imagePath}\n---`,
32
    );
33
    await writeFile(filePath, updatedContent);
34
  } else {
35
    await writeFile(filePath, newContent);
36
  }
37

38
  console.log(`✨ 已更新文章：${file}\n`);
39
}

展开收起

主函数#

支持两种模式：批量生成所有文章，或指定单篇文章：

1
async function main() {
2
  const targetFile = process.argv[2];
3

4
  if (targetFile) {
5
    // 单文章模式
6
    const relativePath = targetFile
7
      .replace(/\\/g, "/")
8
      .replace(/^src\/content\/blog\//, "");
9
    console.log(`📝 处理单个文章：${relativePath}\n`);
10
    try {
11
      await processFile(relativePath);
12
    } catch (error) {
13
      console.error(`❌ 处理失败：${relativePath}`, error);
14
      process.exit(1);
15
    }
16
  } else {
17
    // 批量模式
18
    const files = await readdir(BLOG_DIR, { recursive: true });
19
    const mdFiles = files.filter((f) => f.endsWith(".md") || f.endsWith(".mdx"));
20

21
    console.log(`📝 找到 ${mdFiles.length} 篇文章\n`);
22

23
    for (const file of mdFiles) {
24
      try {
25
        await processFile(file);
26
      } catch (error) {
27
        console.error(`❌ 处理失败：${file}`, error);
28
      }
29
    }
30
  }
31

32
  console.log("\n🎉 全部完成！");
33
}
34

35
main();

展开收起

注册命令#

文件路径：package.json

1
"scripts": {
2
  "cover-images": "npx tsx scripts/generate-cover-images.ts"
3
}

使用方法#

批量生成所有文章封面#

Terminal window

1
pnpm cover-images

会扫描 src/content/blog/ 下所有文章，跳过已有封面的文章，为其他文章生成封面图。

为单篇文章生成封面#

Terminal window

1
pnpm cover-images src/content/blog/xxx.md

只为指定文章生成封面图，即使它已有封面也会重新生成（除非是本地路径的封面）。

完整工作流#

Terminal window

1
# 1. 写好文章，frontmatter 的 image 设为 "api"
2
# 2. 生成封面图
3
pnpm cover-images src/content/blog/新文章.md
4

5
# 3. 提交文章和生成的图片
6
git add src/content/blog/ public/images/covers/generated/
7

8
# 4. 推送
9
git push

跳过逻辑#

脚本会自动跳过以下情况：

无 frontmatter - 不是标准的 Markdown 文章
已有本地封面 - image 字段已设置且不是 api 或 unsplash 随机图
处理失败 - API 调用失败时保留原文件，继续处理下一篇

如果想强制重新生成，可以先把 frontmatter 的 image 改为 api，再运行命令。

成本优化建议#

图片生成 API 通常按次数计费，建议：

精准生成 - 用单文章模式，只为需要的文章生成
提示词优化 - 修改 generatePrompt() 函数，生成更符合需求的提示词
使用代理 - 使用第三方 API 代理服务，成本更低
批量提交 - 一次性生成多篇文章的封面后再提交，避免频繁调用

注意事项#

API 限流 - 批量生成时注意 API 限流，必要时添加延迟
图片质量 - DALL-E 3 生成质量较高但成本也高，可根据需求选择其他模型
提示词语言 - 当前使用中文提示词，部分 API 可能需要改为英文
文件命名 - 生成的文件名会替换路径分隔符为 -，避免子目录问题

扩展思路#

自定义提示词模板 - 根据分类或标签使用不同风格的提示词
图片尺寸配置 - 支持配置不同的图片尺寸
本地模型 - 接入 Stable Diffusion 本地模型，完全免费
审核机制 - 生成后人工审核，不满意的可以重新生成

AI 文章摘要

Thu, 11 Jun 2026 00:00:00 GMT

方案说明#

常见的 AI 摘要做法是在文章页前端实时调用 API 生成，但这样会暴露密钥，也依赖部署平台的环境变量。本方案改为 本地预生成 + 缓存提交：

本地运行脚本读取所有文章，调用 AI API 生成摘要，写入 src/constants/ai-summaries.json
把缓存 JSON 随仓库一起提交
构建时文章页直接读缓存，不调 API、不暴露密钥
摘要文本通过打字机逐字播放

密钥只存在本地 .env，构建环境完全不需要任何 AI 相关的环境变量。

配置 .env#

文件路径：.env

Terminal window

1
# AI 摘要生成配置（仅本地生成时使用，不需要提交，也不需要配到部署平台）
2
AI_SUMMARY_API_KEY=sk-xxxxxxxxxxxxxxxx
3
AI_SUMMARY_API_ENDPOINT=https://api.deepseek.com
4
AI_SUMMARY_MODEL=deepseek-chat

.env 已在 .gitignore 中，不会被提交。AI_SUMMARY_API_ENDPOINT 和 AI_SUMMARY_MODEL 有默认值（DeepSeek），只配 AI_SUMMARY_API_KEY 也能用。

编写生成脚本#

文件路径：scripts/generate-ai-summaries.ts

脚本逻辑：读取 .env → 遍历文章 → 以正文 hash 为指纹做增量（未变化的跳过）→ 调 API → 写入缓存。

1
import crypto from "node:crypto";
2
import fs from "node:fs";
3
import fsp from "node:fs/promises";
4
import path from "node:path";
5
import { glob } from "glob";
6

7
const BLOG_DIR = "src/content/blog";
8
const OUTPUT_FILE = "src/constants/ai-summaries.json";
9
// 正文截断长度，避免超长文章浪费 token
10
const MAX_CONTENT_LENGTH = 6000;
11

12
// 轻量解析 .env，避免依赖 node --env-file（npx tsx 下不一定生效），也不引入 dotenv
13
function loadEnv(file = ".env") {
14
  if (!fs.existsSync(file)) return;
15
  const raw = fs.readFileSync(file, "utf-8");
16
  for (const line of raw.split(/\r?\n/)) {
17
    const trimmed = line.trim();
18
    if (!trimmed || trimmed.startsWith("#")) continue;
19
    const eq = trimmed.indexOf("=");
20
    if (eq === -1) continue;
21
    const key = trimmed.slice(0, eq).trim();
22
    let value = trimmed.slice(eq + 1).trim();
23
    if (
24
      (value.startsWith('"') && value.endsWith('"')) ||
25
      (value.startsWith("'") && value.endsWith("'"))
26
    ) {
27
      value = value.slice(1, -1);
28
    }
29
    if (process.env[key] === undefined) {
30
      process.env[key] = value;
31
    }
32
  }
33
}
34

35
loadEnv();
36

37
const API_KEY = process.env.AI_SUMMARY_API_KEY;
38
const API_ENDPOINT = process.env.AI_SUMMARY_API_ENDPOINT || "https://api.deepseek.com";
39
const API_MODEL = process.env.AI_SUMMARY_MODEL || "deepseek-chat";
40
const API_PATH = process.env.AI_SUMMARY_API_PATH || "/v1/chat/completions";

展开收起

system prompt 强约束输出，禁止以「内容不足」为由拒绝生成：

1
const SYSTEM_PROMPT =
2
  "你是一个文章摘要助手。请根据给出的标题、描述和正文，用 120-180 个中文字符总结文章核心内容，语言与原文保持一致。写成 2-3 句自然短句，覆盖文章主题、关键做法和读者能获得的价值。即使正文较短或以代码/步骤为主，也必须结合标题与描述给出合理摘要，绝不能输出“无法生成/内容不足/未包含正文”之类的拒绝性语句。只输出摘要正文，不要标题、前缀、列表或解释。";

缓存键与 entry.id 对齐#

这是最关键的一步。缓存键必须和 Astro glob loader 的 entry.id 完全一致，否则文章页查不到摘要：

frontmatter 有自定义 slug 时，entry.id 就是该 slug
否则是相对 blog 目录的路径去掉扩展名

1
// 生成缓存键，与 Astro glob loader 的 entry.id 对齐
2
function postToKey(file: string, slug: string): string {
3
  if (slug) {
4
    // 去掉首尾斜杠：frontmatter 写 "/AISummary"，统一成 "AISummary"
5
    return slug.replace(/^\/+/, "").replace(/\/+$/, "");
6
  }
7
  const rel = path.relative(BLOG_DIR, file).replace(/\\/g, "/");
8
  return rel.replace(/\.[^/.]+$/, "");
9
}

请求摘要#

1
async function requestSummary(content: string): Promise<string> {
2
  const res = await fetch(API_ENDPOINT + API_PATH, {
3
    method: "POST",
4
    headers: {
5
      "Content-Type": "application/json",
6
      Authorization: `Bearer ${API_KEY}`,
7
    },
8
    body: JSON.stringify({
9
      model: API_MODEL,
10
      messages: [
11
        { role: "system", content: SYSTEM_PROMPT },
12
        { role: "user", content },
13
      ],
14
      stream: false,
15
    }),
16
  });
17

18
  if (!res.ok) {
19
    const detail = await res.text().catch(() => "");
20
    throw new Error(`API 请求失败 (${res.status}) ${detail.slice(0, 200)}`);
21
  }
22

23
  const json = (await res.json()) as {
24
    choices?: { message?: { content?: string } }[];
25
  };
26
  const summary = json.choices?.[0]?.message?.content?.trim();
27
  if (!summary) {
28
    throw new Error("API 返回内容为空");
29
  }
30
  return summary;
31
}

展开收起

主流程以 hash 做增量：hash 未变直接复用旧摘要，只为新增或改动过的文章调 API，并清理已删除文章的缓存。完整脚本可参考仓库源码。

注册命令#

文件路径：package.json

1
"scripts": {
2
  "ai-summaries": "npx tsx scripts/generate-ai-summaries.ts"
3
}

运行 pnpm ai-summaries 即可生成或更新摘要缓存。

添加类型定义#

文件路径：src/types/config.ts

1
// AI 文章摘要配置
2
// 摘要由本地脚本预生成并缓存在 src/constants/ai-summaries.json，
3
// API 密钥等配置在 .env 中，此处仅控制是否展示摘要卡片。
4
aiSummary?: {
5
  enable: boolean; // 是否启用 AI 摘要功能
6
};

添加配置项#

文件路径：src/config/siteConfig.ts

1
// 摘要由本地脚本预生成并缓存在 src/constants/ai-summaries.json，
2
// 运行 `pnpm ai-summaries` 生成（API 密钥等配置在 .env 中：AI_SUMMARY_API_KEY / AI_SUMMARY_API_ENDPOINT / AI_SUMMARY_MODEL）。
3
// 此处仅控制是否在文章页展示摘要卡片。
4
aiSummary: {
5
  enable: true,
6
},

摘要展示组件#

文件路径：src/components/features/AISummary.astro

组件只负责接收摘要文本并渲染卡片，不调 API、不暴露密钥。打字机脚本不放在这里（原因见末尾的踩坑记录）。

1
---
2
// AI 文章摘要组件
3
// 摘要由本地脚本预生成并缓存在 src/constants/ai-summaries.json，
4
// 文章页按 entry.id 取出摘要文本通过 summary prop 传入。
5
import { siteConfig } from "@/config/siteConfig";
6

7
interface Props {
8
  summary?: string;
9
}
10

11
const { summary } = Astro.props;
12

13
// 未启用或无摘要时不渲染卡片
14
if (!siteConfig.aiSummary?.enable || !summary?.trim()) {
15
  return;
16
}
17
---
18

19
<div id="ai-summary" class="onload-animation" data-summary={summary.trim()}>
20
  <div class="ai-summary-header">
21
    <div class="ai-summary-icon">
22
      <!-- 魔法笔图标 -->
23
      <svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24">
24
        <path fill="currentColor" d="M7.5 5.6L5.6 7.5L8 9.9L9.9 8L7.5 5.6M14.4 3L13.2 5.6L10.6 6.8L13.2 8L14.4 10.6L15.6 8L18.2 6.8L15.6 5.6L14.4 3M19 9.8L17.9 12.1L15.6 13.2L17.9 14.3L19 16.6L20.1 14.3L22.4 13.2L20.1 12.1L19 9.8M4.2 18.4L13.8 8.8L15.2 10.2L5.6 19.8C5.2 20.2 4.6 20.2 4.2 19.8C3.8 19.4 3.8 18.8 4.2 18.4Z"/>
25
      </svg>
26
    </div>
27
    <div class="ai-summary-title">文章摘要</div>
28
  </div>
29
  <div id="ai-summary-content" class="ai-summary-content">
30
    <span class="ai-summary-cursor"></span>
31
  </div>
32
</div>

展开收起

样式部分（玻璃质感卡片、光标闪烁、暗色适配）可参考仓库源码，这里省略。

在文章页接入#

文件路径：src/pages/blog/[...slug].astro

导入缓存和组件：

1
import AISummary from "@/components/features/AISummary.astro";
2
import aiSummaries from "@/constants/ai-summaries.json";

按 entry.id 取出摘要。注意：查找时要对 entry.id 做和缓存键一致的归一化（去首尾斜杠），否则带 slug 的文章会因为前导斜杠匹配不上：

1
// 从本地预生成的缓存中取出 AI 摘要（无则为 undefined，组件不渲染）
2
// entry.id 在有 slug 时会带前导斜杠（如 "/AISummary"），需归一化后再查
3
const aiSummaryKey = entry.id.replace(/^\/+/, "").replace(/\/+$/, "");
4
const aiSummaryText = (aiSummaries as Record<string, { summary: string }>)[
5
  aiSummaryKey
6
]?.summary;

在正文上方渲染组件：

1
<AISummary summary={aiSummaryText} />
2
<Markdown class="mb-6 markdown-content onload-animation">
3
  <Content />
4
</Markdown>

全局打字机脚本#

文件路径：src/layouts/Layout.astro

打字机脚本放在全局 Layout，而不是组件内部（原因见末尾踩坑记录）。在文件末尾添加：

1
<!-- AI 摘要打字机：脚本放在全局 Layout，保证 Swup 翻页（非整页刷新）也能初始化 -->
2
<script>
3
  // 模块级 timer，使翻页时能真正取消上一次未完成的打字动画
4
  let aiSummaryTimer: ReturnType<typeof setTimeout> | undefined;
5

6
  function initAiSummary() {
7
    const container = document.getElementById("ai-summary");
8
    if (!container) return;
9

10
    const text = container.dataset.summary;
11
    if (!text) return;
12

13
    const target = document.getElementById("ai-summary-content");
14
    if (!target) return;
15

16
    function escapeHtml(str: string): string {
17
      return str
18
        .replace(/&/g, "&amp;")
19
        .replace(/</g, "&lt;")
20
        .replace(/>/g, "&gt;")
21
        .replace(/"/g, "&quot;");
22
    }
23

24
    // 取消上一次可能还在进行的打字，避免翻页后两次动画叠加
25
    if (aiSummaryTimer) clearTimeout(aiSummaryTimer);
26

27
    const full = text;
28
    let i = 0;
29

30
    function typeNext() {
31
      i++;
32
      if (i <= full.length) {
33
        target.innerHTML =
34
          escapeHtml(full.slice(0, i)) +
35
          '<span class="ai-summary-cursor"></span>';
36
        // 标点处稍作停顿，更接近自然书写节奏
37
        const ch = full[i - 1];
38
        const delay = /[，。！？、；,.!?]/.test(ch) ? 90 : 28;
39
        aiSummaryTimer = setTimeout(typeNext, delay);
40
      } else {
41
        target.innerHTML = escapeHtml(full);
42
        container?.classList.add("fade-in");
43
      }
44
    }
45

46
    typeNext();
47
  }
48

49
  window.addEventListener("load", initAiSummary);
50
  document.addEventListener("astro:page-load", initAiSummary);
51
  document.addEventListener("swup:contentReplaced", () => {
52
    requestAnimationFrame(initAiSummary);
53
  });
54
</script>

展开收起

使用流程#

以后每写一篇新文章：

Terminal window

1
# 1. 生成 / 更新摘要缓存（增量，未变化的文章会跳过）
2
pnpm ai-summaries
3

4
# 2. 提交文章和缓存
5
git add src/content/blog/ src/constants/ai-summaries.json
6

7
# 3. 推送，构建时直接读缓存，不调 API
8
git push

踩坑记录#

实现过程中有两个不明显的坑，单独记一下。

entry.id 会保留 frontmatter slug 的前导斜杠#

frontmatter 写 slug: /AI文章摘要，Astro glob loader 的 entry.id 实际是 /AISummary（带斜杠），而输出目录是干净的 AISummary。如果缓存键用了不带斜杠的形式，aiSummaries[entry.id] 就永远查不到，摘要不显示且没有任何报错。

解决：生成键和查找时都做 replace(/^\/+/, "").replace(/\/+$/, "") 归一化，两边对齐。

组件内 script 在 Swup 翻页时不执行#

Astro 组件级 <script> 只会打包进「渲染了该组件的页面」。AI 摘要组件只在文章页出现，首页没有它，所以首页不加载这段脚本。而 Swup 翻页只替换容器内容、不执行新页面里的 script 标签，于是从首页点进文章时打字机从未初始化，表现为光标一直闪、刷新后才正常。

解决：把打字机脚本移到始终渲染的 Layout.astro 全局脚本，并监听 astro:page-load 和 swup:contentReplaced，覆盖首次加载和翻页两种场景。

隐藏封面图

Thu, 11 Jun 2026 00:00:00 GMT

添加类型定义#

文件路径：src/types/config.ts

1
// 文章列表布局配置
2
  postListLayout: {
3
    allowCoverSwitch?: boolean; // 是否允许用户切换文章封面图显示
4
    showCover?: boolean; // 默认是否显示文章封面图
5
  };

添加配置项#

文件路径：src/config/siteConfig.ts

1
postListLayout: {
2
  allowCoverSwitch: true,  // 新增：允许切换封面图显示
3
  showCover: true,         // 新增：默认显示封面图
4
},

设置工具函数#

文件路径：src/utils/setting-utils.ts

1
// 获取默认封面图显示状态
2
export function getDefaultPostCoverImageEnabled(): boolean {
3
  return siteConfig.postListLayout.showCover ?? true;
4
}
5

6
// 从localStorage读取封面图显示状态
7
export function getStoredPostCoverImageEnabled(): boolean {
8
  if (
9
    typeof localStorage === "undefined" ||
10
    typeof localStorage.getItem !== "function"
11
  ) {
12
    return getDefaultPostCoverImageEnabled();
13
  }
14
  const stored = localStorage.getItem("postCoverImageEnabled");
15
  if (stored === null) {
16
    return getDefaultPostCoverImageEnabled();
17
  }
18
  return stored === "true";
19
}
20

21
// 设置封面图显示状态
22
export function setPostCoverImageEnabled(enabled: boolean): void {
23
  if (
24
    typeof localStorage === "undefined" ||
25
    typeof localStorage.setItem !== "function"
26
  ) {
27
    return;
28
  }
29
  localStorage.setItem("postCoverImageEnabled", String(enabled));
30
  applyPostCoverImageEnabledToDocument(enabled);
31
  if (typeof window !== "undefined") {
32
    window.dispatchEvent(
33
      new CustomEvent("postCoverImageChange", {
34
        detail: { enabled },
35
      }),
36
    );
37
  }
38
}
39

40
// 将封面图状态应用到文档
41
export function applyPostCoverImageEnabledToDocument(enabled: boolean): void {
42
  if (typeof document === "undefined") {
43
    return;
44
  }
45
  document.documentElement.setAttribute(
46
    "data-post-cover-enabled",
47
    String(enabled),
48
  );
49
}

展开收起

添加设置面板开关#

文件路径：src/components/controls/DisplaySettingsIntegrated.svelte

导入相关函数#

在文件顶部导入新添加的工具函数：

1
import {
2
  // ... 其他导入
3
  getDefaultPostCoverImageEnabled,
4
  getStoredPostCoverImageEnabled,
5
  setPostCoverImageEnabled,
6
  applyPostCoverImageEnabledToDocument,
7
} from "@utils/setting-utils";

添加状态变量#

在脚本部分添加以下状态变量：

1
const defaultPostCoverImageEnabled = getDefaultPostCoverImageEnabled();
2
const isPostCoverImageSwitchable = siteConfig.postListLayout.allowCoverSwitch ?? true;
3
let postCoverImageEnabled = $state(true);

添加切换函数#

添加切换封面图状态的函数：数：

1
function togglePostCoverImageEnabled() {
2
  postCoverImageEnabled = !postCoverImageEnabled;
3
  setPostCoverImageEnabled(postCoverImageEnabled);
4
}

在 onMount 中初始化状态#

1
// 从localStorage读取文章封面图状态
2
postCoverImageEnabled = getStoredPostCoverImageEnabled();
3
// 将状态应用到文档
4
applyPostCoverImageEnabledToDocument(postCoverImageEnabled);

添加开关 UI#

在 HTML 模板部分（布局切换区域后）添加：

1
<!-- Post Cover Image Switch Section -->
2
{#if isPostCoverImageSwitchable}
3
  <div class="mt-2 mb-2">
4
    <div class="flex gap-2 font-bold text-lg text-neutral-900 dark:text-neutral-100 transition relative ml-3 mb-2
5
        before:w-1 before:h-4 before:rounded-md before:bg-(--primary)
6
        before:absolute before:-left-3 before:top-1/2 before:-translate-y-1/2"
7
    >
8
      {i18n(I18nKey.postCoverImage)}
9
      <button aria-label="Reset to Default" class="btn-regular w-7 h-7 rounded-md active:scale-90"
10
              class:opacity-0={postCoverImageEnabled === defaultPostCoverImageEnabled}
11
              class:pointer-events-none={postCoverImageEnabled === defaultPostCoverImageEnabled}
12
              onclick={() => {
13
                postCoverImageEnabled = defaultPostCoverImageEnabled;
14
                setPostCoverImageEnabled(defaultPostCoverImageEnabled);
15
              }}>
16
        <div class="text-(--btn-content)">
17
          <Icon icon="fa7-solid:arrow-rotate-left" class="text-[0.875rem]"></Icon>
18
        </div>
19
      </button>
20
    </div>
21
    <div class="space-y-1">
22
      <button
23
        class="w-full btn-regular rounded-md py-2 px-3 flex items-center gap-3 text-left active:scale-95 transition-all relative overflow-hidden"
24
        class:bg-(--btn-regular-bg-hover)={postCoverImageEnabled}
25
        onclick={togglePostCoverImageEnabled}
26
      >
27
        <Icon icon="material-symbols:image" class="text-[1.25rem] shrink-0"></Icon>
28
        <span class="text-sm flex-1">{i18n(I18nKey.postCoverImage)}</span>
29
        <div class="w-10 h-5 rounded-full transition-all duration-200 relative"
30
             class:bg-(--primary)={postCoverImageEnabled}
31
             class:bg-(--btn-regular-bg-active)={!postCoverImageEnabled}>
32
          <div class="absolute top-0.5 w-4 h-4 bg-white rounded-full shadow transition-all duration-200"
33
               class:left-0.5={!postCoverImageEnabled}
34
               class:left-5={postCoverImageEnabled}></div>
35
        </div>
36
      </button>
37
    </div>
38
  </div>
39
{/if}

展开收起

添加样式控制#

文件路径：src/components/layout/PostCard.astro

1
/* === Hide Post Cover Image === */
2
/* 当 data-post-cover-enabled="false" 时隐藏封面图 */
3
:global([data-post-cover-enabled="false"]) .post-card-image {
4
  display: none !important;
5
}
6

7
:global([data-post-cover-enabled="false"]) .has-cover {
8
  &.post-card-wrapper {
9
    .post-card-content {
10
      width: calc(100% - 52px - 12px) !important;
11
    }
12
  }
13
}
14

15
:global([data-post-cover-enabled="false"]) .has-cover .post-card-enter-btn {
16
  display: flex !important;
17
}

展开收起

语言配置#

文件路径：src/i18n/i18nKey.ts

1
postCoverImage = "postCoverImage",

文件路径：src/i18n/languages/en.ts

1
[Key.postCoverImage]: "Post Cover Image",

文件路径：src/i18n/languages/ja.ts

1
[Key.postCoverImage]: "記事のカバー画像",

文件路径：src/i18n/languages/ru.ts

1
[Key.postCoverImage]: "Обложка поста",

文件路径：src/i18n/languages/zh_CN.ts

1
[Key.postCoverImage]: "文章封面图",

文件路径：src/i18n/languages/zh_TW.ts

1
[Key.postCoverImage]: "文章封面圖",

恋爱计时组件

Wed, 10 Jun 2026 00:00:00 GMT

创建组件#

文件路径：src/components/widget/RelationshipTimer.astro

1
<!-- 恋爱倒计时组件 -->
2
---
3
import WidgetLayout from "@/components/common/WidgetLayout.astro";
4
import { relationshipConfig } from "@/config/relationshipConfig";
5

6
const config = relationshipConfig;
7

8
interface Props {
9
  class?: string;
10
  style?: string;
11
}
12
const className = Astro.props.class;
13
const style = Astro.props.style;
14
---
15

16
<WidgetLayout
17
  name={config.title || "恋爱时光"}
18
  id="relationship"
19
  class={className}
20
  style={style}
21
>
22
  <div class="flex flex-col items-center p-2">
23
    <!-- 顶部名称栏 -->
24
    <div class="flex items-center justify-center gap-2 mb-4 text-sm font-medium text-neutral-600 dark:text-neutral-400">
25
      <span>{config.name1}</span>
26
      <span class="text-red-500 animate-pulse">❤️</span>
27
      <span>{config.name2}</span>
28
    </div>
29

30
    <!-- 头像和爱心 -->
31
    <div class="flex items-center justify-center gap-4 mb-6">
32
      <div class="w-16 h-16 rounded-full overflow-hidden border-2 border-white dark:border-neutral-800 shadow-md transition-transform hover:scale-110">
33
        <img src={config.avatar1} alt={config.name1} class="w-full h-full object-cover" />
34
      </div>
35
      <div class="text-2xl text-red-500 transform transition-all hover:scale-125 hover:rotate-12 cursor-pointer">
36
        ❤️
37
      </div>
38
      <div class="w-16 h-16 rounded-full overflow-hidden border-2 border-white dark:border-neutral-800 shadow-md transition-transform hover:scale-110">
39
        <img src={config.avatar2} alt={config.name2} class="w-full h-full object-cover" />
40
      </div>
41
    </div>
42

43
    <!-- 计时器 -->
44
    <div class="relationship-timer flex items-center justify-center gap-x-1 text-sm whitespace-nowrap overflow-x-auto">
45
      <span class="timer-num" data-timer-years>0</span><span class="timer-unit bg-red-400">年</span>
46
      <span class="timer-num" data-timer-months>0</span><span class="timer-unit bg-red-300">月</span>
47
      <span class="timer-num" data-timer-days>0</span><span class="timer-unit bg-blue-400">天</span>
48
      <span class="timer-num" data-timer-hours>0</span><span class="timer-unit bg-orange-400">时</span>
49
      <span class="timer-num" data-timer-minutes>0</span><span class="timer-unit bg-blue-500">分</span>
50
      <span class="timer-num" data-timer-seconds>00</span><span class="timer-unit bg-purple-400">秒</span>
51
    </div>
52
  </div>
53
</WidgetLayout>
54

55
<style>
56
  @reference "tailwindcss";
57

58
  .timer-num {
59
    @apply font-bold text-neutral-700 dark:text-neutral-200 min-w-[0rem] text-center;
60
    color: var(--primary);
61
  }
62
  .timer-unit {
63
    @apply px-1 py-0.5 rounded text-[10px] text-white font-medium shrink-0;
64
  }
65
</style>
66

67
<script is:inline define:vars={{ startDateStr: config.startDate }}>
68
  function updateRelationshipTimer() {
69
    const startDate = new Date(startDateStr);
70
    const now = new Date();
71

72
    let diff = now.getTime() - startDate.getTime();
73

74
    if (diff < 0) return;
75

76
    // 计算年月日时分秒的差值
77
    let years = now.getFullYear() - startDate.getFullYear();
78
    let months = now.getMonth() - startDate.getMonth();
79
    let days = now.getDate() - startDate.getDate();
80
    let hours = now.getHours() - startDate.getHours();
81
    let minutes = now.getMinutes() - startDate.getMinutes();
82
    let seconds = now.getSeconds() - startDate.getSeconds();
83

84
    // 处理借位逻辑
85
    if (seconds < 0) {
86
      seconds += 60;
87
      minutes--;
88
    }
89
    if (minutes < 0) {
90
      minutes += 60;
91
      hours--;
92
    }
93
    if (hours < 0) {
94
      hours += 24;
95
      days--;
96
    }
97
    if (days < 0) {
98
      const lastMonth = new Date(now.getFullYear(), now.getMonth(), 0);
99
      days += lastMonth.getDate();
100
      months--;
101
    }
102
    if (months < 0) {
103
      months += 12;
104
      years--;
105
    }
106

107
    // 更新所有实例，避免移动端和电脑端 ID 冲突
108
    const update = (attr, value) => {
109
      const elements = document.querySelectorAll(`[data-timer-${attr}]`);
110
      elements.forEach(el => {
111
        el.innerText = value;
112
      });
113
    };
114

115
    update('years', years);
116
    update('months', months);
117
    update('days', days);
118
    update('hours', hours);
119
    update('minutes', minutes);
120
    update('seconds', seconds.toString().padStart(2, '0'));
121
  }
122

123
  // 立即运行并每秒更新
124
  updateRelationshipTimer();
125
  if (!window.relationshipTimerInterval) {
126
    window.relationshipTimerInterval = setInterval(updateRelationshipTimer, 1000);
127
  }
128

129
  // 监听 Swup 页面切换
130
  document.addEventListener('swup:content:replace', updateRelationshipTimer);
131
</script>

展开收起

注册组件#

文件路径：src/components/layout/SideBar.astro

1
---
2
import RelationshipTimer from "@/components/widget/RelationshipTimer.astro";  // 引入恋爱计时组件
3
---
4

5
// 组件映射表
6
const componentMap = {
7
    <!-- 恋爱计时组件 -->
8
  relationship: RelationshipTimer,
9
} satisfies Record<WidgetComponentType, typeof Profile>;

启用组件#

文件路径：src/config/sidebarConfig.ts

右侧边栏配置

1
{
2
  type: "relationship",    // 组件类型，与 componentMap 中的 key 对应
3
  enable: true,            // 是否启用
4
  position: "top",         // 组件位置：top（固定顶部）或 sticky（粘性定位）
5
  showOnPostPage: true,    // 是否在文章详情页显示
6
},

移动端配置

1
{
2
// 组件类型：恋爱计时小组件
3
type: "relationship",
4
// 是否启用该组件
5
enable: true,
6
// 是否在文章详情页显示
7
showOnPostPage: true,
8
},

配置类型定义#

文件路径：src/types/config.ts

1
// 组件配置类型定义
2
export type WidgetComponentType =
3
  | "relationship";

双方信息配置#

文件路径：src/config/relationshipConfig.ts

1
import type { RelationshipConfig } from "../types/config";
2

3
export const relationshipConfig: RelationshipConfig = {
4
  // 恋爱开始日期
5
  startDate: "2026-01-06",
6
  // 双方名称
7
  name1: "---------TSH",
8
  name2: "CXY---------",
9
  // 双方头像
10
  avatar1: "https://re.tsh520.cn/zl/tsh.jpg",
11
  avatar2: "https://re.tsh520.cn/zl/cxy.jpg",
12
  // 小组件标题
13
  title: "我和宝宝在一起已经",
14
};

Umami 访问统计卡片

Wed, 10 Jun 2026 00:00:00 GMT

提示

本文是在博主 THW 文章：为 Fuwari 添加 Umami 访问统计卡片基础上增加了自己实践过程的一些细节，转载无需和我联系，但请注明文章来源。如果侵权之处，请联系博主进行删除，谢谢~

开始#

对于静态博客而言，了解访客来源与流量趋势是很有必要的。在不自建服务器的前提下，配置简单，功能强大的 Umami 往往是我们的首选。

然而，直接挂载 Umami 的分享外链不够直观且破坏页面一致性。本文将教你如何将 Umami 的统计数据以原生组件的形式集成到 Firefly 主题的侧边栏中，让你的博客实时展示访问数据。

Umami 访问统计卡片

准备工作#

一个已部署好的Firefly博客
无服务器部署Umami统计教程：Vercel 部署
启用Umami统计的站点

获取数据#

为了获取到图中的这些数据，我们需要启用 Umami 统计的分享 URL。

你应该会得到一个类似 https://umami.cchaoka.cn/share/xxxxxxxxxxxx 格式的链接。记下这个链接，现在我们只需要它就能完成所有配置。

alt text

创建组件#

文件路径：src/components/widget/UmamiStats.astro

1
---
2
import WidgetLayout from "@/components/common/WidgetLayout.astro";
3

4
interface Props {
5
  class?: string;
6
  style?: string;
7
}
8
const { class: className, style } = Astro.props;
9
---
10

11
<WidgetLayout id="umami-stats" name="统计" class:list={["umami-stats-container", className, "cursor-pointer transition-opacity active:scale-95"]} {style}>
12
    <a target="_blank" rel="noopener noreferrer" class="block umami-link">
13
        <div class="text-center py-2">
14
            <div class="text-3xl font-bold text-neutral-900 dark:text-neutral-100 umami-total-pageviews">-</div>
15
            <div class="text-sm text-neutral-500 dark:text-neutral-400">总浏览量</div>
16
        </div>
17
        <div class="grid grid-cols-2 divide-x divide-neutral-200 dark:divide-neutral-700 text-center pt-2">
18
            <div class="px-2">
19
                <div class="text-xl font-bold text-neutral-900 dark:text-neutral-100 umami-total-visits">-</div>
20
                <div class="text-sm text-neutral-500 dark:text-neutral-400">访问数</div>
21
            </div>
22
            <div class="px-2">
23
                <div class="text-xl font-bold text-neutral-900 dark:text-neutral-100 umami-total-visitors">-</div>
24
                <div class="text-sm text-neutral-500 dark:text-neutral-400">游客数</div>
25
            </div>
26
        </div>
27
    </a>
28
</WidgetLayout>
29

30
<script>
31
const UMAMI_CONFIG = {
32
    shareUrl: 'https://umami.cchaoka.cn/share/xxxxxxxxxxxx',
33
};
34

35
let __UMAMI_INTERNAL = {
36
    baseUrl: '',
37
    websiteId: '',
38
    shareToken: '',
39
    shareId: '',
40
    isReady: false
41
};
42

43
const FALLBACK_STATS = {
44
    pageviews: 1000,
45
    visits: 1000,
46
    visitors: 1000,
47
};
48

49
async function initUmamiConfig() {
50
    try {
51
        const sharePath = UMAMI_CONFIG.shareUrl.split('/share/')[1];
52
        if (!sharePath) throw new Error('Invalid Umami Share URL');
53

54
        let apiBase = '';
55
        if (UMAMI_CONFIG.shareUrl.includes('cloud.umami.is') || UMAMI_CONFIG.shareUrl.includes('analytics.umami.is')) {
56
            const region = UMAMI_CONFIG.shareUrl.includes('/analytics/eu/') ? 'eu' : 'us';
57
            apiBase = `https://cloud.umami.is/analytics/${region}/api`;
58
        } else {
59
            const urlObj = new URL(UMAMI_CONFIG.shareUrl);
60
            apiBase = `${urlObj.origin}/api`;
61
        }
62

63
        const res = await fetch(`${apiBase}/share/${sharePath}`);
64
        if (!res.ok) throw new Error(`Failed to fetch share config: ${res.status}`);
65
        const data = await res.json();
66

67
        __UMAMI_INTERNAL = {
68
            baseUrl: apiBase,
69
            websiteId: data.websiteId,
70
            shareToken: data.token,
71
            shareId: data.shareId,
72
            isReady: true
73
        };
74

75
        const links = document.querySelectorAll('.umami-link');
76
        links.forEach(link => link.setAttribute('href', UMAMI_CONFIG.shareUrl));
77

78
    } catch (e) {
79
        console.error('Umami Config Init Failed:', e);
80
    }
81
}
82

83
function formatNumber(num: number): string {
84
    if (num >= 1000000) {
85
        return (num / 1000000).toFixed(1) + 'M';
86
    } else if (num >= 1000) {
87
        return (num / 1000).toFixed(1) + 'K';
88
    }
89
    return Math.round(num).toString();
90
}
91

92
function setStats(values: { pageviews: number; visits: number; visitors: number }) {
93
    const pageviewsElements = document.querySelectorAll('.umami-total-pageviews');
94
    const visitsElements = document.querySelectorAll('.umami-total-visits');
95
    const visitorsElements = document.querySelectorAll('.umami-total-visitors');
96

97
    const easeOutCubic = (t: number) => 1 - Math.pow(1 - t, 3);
98
    const animHandles = new Map<HTMLElement, number>();
99

100
    const animateStat = (el: HTMLElement | null, to: number, duration = 2000) => {
101
        if (!el) return;
102

103
        const prev = animHandles.get(el);
104
        if (prev) cancelAnimationFrame(prev);
105

106
        const from = 0;
107
        const startTime = performance.now();
108

109
        const tick = (now: number) => {
110
            const elapsed = now - startTime;
111
            const progress = Math.min(1, elapsed / duration);
112
            const easedProgress = easeOutCubic(progress);
113

114
            const current = from + (to - from) * easedProgress;
115
            el.textContent = formatNumber(current);
116

117
            if (progress < 1) {
118
                animHandles.set(el, requestAnimationFrame(tick));
119
            }
120
        };
121
        animHandles.set(el, requestAnimationFrame(tick));
122
    };
123

124
    pageviewsElements.forEach(el => animateStat(el as HTMLElement, values.pageviews));
125
    visitsElements.forEach(el => animateStat(el as HTMLElement, values.visits));
126
    visitorsElements.forEach(el => animateStat(el as HTMLElement, values.visitors));
127
}
128

129
async function fetchUmamiStats() {
130
    if (!__UMAMI_INTERNAL.isReady) {
131
        await initUmamiConfig();
132
    }
133

134
    if (!__UMAMI_INTERNAL.isReady) {
135
        setStats(FALLBACK_STATS);
136
        return;
137
    }
138

139
    try {
140
        const endAt = Date.now();
141
        const startAt = 0;
142
        const url = `${__UMAMI_INTERNAL.baseUrl}/websites/${__UMAMI_INTERNAL.websiteId}/stats?startAt=${startAt}&endAt=${endAt}&unit=hour&timezone=Asia%2FShanghai`;
143

144
        const response = await fetch(url, {
145
            headers: {
146
                'x-umami-share-context': '1',
147
                'x-umami-share-token': __UMAMI_INTERNAL.shareToken
148
            }
149
        });
150

151
        if (!response.ok) throw new Error(`HTTP ${response.status}`);
152
        const data = await response.json();
153
        const getValue = (field: any) => (typeof field === 'object' ? field?.value : field) || 0;
154

155
        setStats({
156
            pageviews: getValue(data.pageviews),
157
            visits: getValue(data.visits),
158
            visitors: getValue(data.visitors),
159
        });
160

161
    } catch (error) {
162
        console.error('Umami Fetch Failed:', error);
163
        setStats(FALLBACK_STATS);
164
    }
165
}
166

167
let __umamiStatsStarted = false;
168
function startUmamiStats() {
169
    if (__umamiStatsStarted) return;
170
    __umamiStatsStarted = true;
171
    fetchUmamiStats();
172
}
173

174
function initUmamiStatsVisibility() {
175
    const containers = document.querySelectorAll('.umami-stats-container');
176
    const io = new IntersectionObserver((entries) => {
177
        let isAnyVisible = false;
178
        entries.forEach(entry => {
179
            if (entry.isIntersecting) isAnyVisible = true;
180
        });
181

182
        if (isAnyVisible) {
183
            startUmamiStats();
184
            io.disconnect();
185
        }
186
    }, { threshold: 0.1 });
187

188
    containers.forEach(container => io.observe(container));
189
}
190

191
initUmamiStatsVisibility();
192

193
if (window.swup) {
194
    window.swup.hooks.on('page:view', () => {
195
        __umamiStatsStarted = false;
196
        initUmamiStatsVisibility();
197
    });
198
}
199
</script>

展开收起

配置参数#

在代码文件的 script 部分，填入你的分享链接：

1
const UMAMI_CONFIG = {
2
    shareUrl: 'https://umami.cchaoka.cn/share/xxxxxxxxxxxx',  // ← 这里改成你自己的
3
};

系统会自动解析 API 路径、Website ID 和验证 Token。

注册组件#

文件路径：src/components/layout/SideBar.astro

1
---
2
import UmamiStats from "@/components/widget/UmamiStats.astro";  // 引入 Umami 组件
3
---
4

5
// 组件映射表
6
const componentMap = {
7
  umamiStats: UmamiStats,
8
} satisfies Record<WidgetComponentType, typeof Profile>;

配置侧边栏#

文件路径：src/config/sidebarConfig.ts

1
{
2
    // 组件类型：Umami 统计组件
3
    type: "umamiStats",
4
    // 是否启用该组件
5
    enable: true,
6
    // 组件位置
7
    position: "top",
8
    // 是否在文章详情页显示
9
    showOnPostPage: true,
10
},

修改统计周期#

默认为所有时间，如果你想要调整浏览量统计的时间范围，可以修改 fetchUmamiStats 函数内的 startAt 参数。

常用时间周期公式（单位：毫秒）：

24小时：24 * 60 * 60 * 1000 = 86400000

最近30天：30 * 24 * 60 * 60 * 1000 = 2592000000

最近90天：90 * 24 * 60 * 60 * 1000 = 7776000000

修改示例（例如改为最近 30 天）：

1
try {
2
    const endAt = Date.now();
3
    const startAt = 0; // [!code --]
4
    const startAt = Date.now() - 2592000000; //[!code ++]
5
}

这将从 30 天前开始统计浏览量。

##配置备用数据

如果遇到 API 请求失败，全新的组件会显示你配置的备用数据以保持 UI 美观。你可以在 FALLBACK_STATS 对象中修改这些数值（默认为1000）：

1
const FALLBACK_STATS = {
2
    pageviews: 1000, // 备用总浏览量
3
    visits: 1000,    // 备用访问数
4
    visitors: 1000,  // 备用游客数
5
};

结尾#

通过以上步骤，你就成功为 Fuwari 添加了具有丰富交互感、自动解析配置且支持点击查看详情的 Umami 统计卡片。

欢迎提示组件

Wed, 10 Jun 2026 00:00:00 GMT

提示

本文是在博主年华文章：Firefly 主题 WelcomeToast 组件分析基础上增加了自己实践过程的一些细节，转载无需和我联系，但请注明文章来源。如果侵权之处，请联系博主进行删除，谢谢~

欢迎提示组件

创建组件#

文件路径：src/components/widget/WelcomeToast.astro

src/components/WelcomeToast.astro展开收起

1
<script>
2
    // const VISIT_SESSION_KEY = 'blog_visit_flag';
3
    let hasShownToast = false;
4

5
    function createWelcomeToast() {
6
        const toast = document.createElement('div');
7
        toast.id = 'welcome-toast';
8
        // Tailwind 样式控制：自动适配深色模式
9
        toast.className = 'fixed bottom-4 right-4 z-50 transform translate-y-full opacity-0 transition-all duration-500 ease-out';
10

11
        //使用 bg-white dark:bg-zinc-800 强制适配颜色
12
        toast.innerHTML = `
13
            <div class="bg-white dark:bg-zinc-800 border border-gray-200 dark:border-zinc-700 rounded-lg shadow-lg p-4 max-w-xs">
14
                <div class="flex items-start gap-3">
15
                    <div class="flex-shrink-0 text-2xl">👋</div>
16
                    <div class="flex-1 min-w-0">
17
                        <p id="welcome-message" class="text-sm font-semibold text-gray-900 dark:text-gray-100">
18
                            正在加载...
19
                        </p>
20
                        <p class="text-xs text-gray-600 dark:text-gray-400 mt-2 italic">
21
                            欢迎来到我的博客
22
                        </p>
23
                    </div>
24
                    <button
25
                        onclick="closeWelcomeToast()"
26
                        class="flex-shrink-0 text-gray-400 hover:text-gray-800 dark:hover:text-gray-200 transition-colors"
27
                        aria-label="关闭"
28
                    >
29
                        <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
30
                            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12"></path>
31
                        </svg>
32
                    </button>
33
                </div>
34
            </div>
35
        `;
36
        document.body.appendChild(toast);
37
        return toast;
38
    }
39

40
    function closeWelcomeToast() {
41
        const toast = document.getElementById('welcome-toast');
42
        if (toast) {
43
            toast.classList.add('translate-y-full', 'opacity-0');
44
            toast.classList.remove('translate-y-0', 'opacity-100');
45
            setTimeout(() => { toast.remove(); }, 500);
46
        }
47
    }
48

49
    async function fetchLocation() {
50
        try {
51
            const response = await fetch('https://v2.xxapi.cn/api/ip');
52
            const data = await response.json();
53
            if (data.code === 200 && data.data) {
54
                const locationText = `你好，来自${data.data.address}的朋友`;
55
                const messageEl = document.getElementById('welcome-message');
56
                if (messageEl) messageEl.textContent = locationText;
57
            }
58
        } catch (error) {
59
            const messageEl = document.getElementById('welcome-message');
60
            if (messageEl) messageEl.textContent = '你好，欢迎来到我的博客';
61
        }
62
    }
63

64
    async function showWelcomeToast() {
65
        if (hasShownToast) return;
66
        const toast = createWelcomeToast();
67
        setTimeout(() => {
68
            toast.classList.remove('translate-y-full', 'opacity-0');
69
            toast.classList.add('translate-y-0', 'opacity-100');
70
        }, 100);
71
        hasShownToast = true;
72
        await fetchLocation();
73
        setTimeout(() => { closeWelcomeToast(); }, 5000);
74
    }
75

76
    function initWelcome() {
77
        // 检查是否已显示过欢迎弹窗
78
        // if (!sessionStorage.getItem(VISIT_SESSION_KEY)) {
79
        //     sessionStorage.setItem(VISIT_SESSION_KEY, 'true');
80
        //     showWelcomeToast();
81
        // }
82
        // 显示欢迎弹窗
83
        showWelcomeToast();
84
    }
85

86
    if (document.readyState === 'loading') {
87
        document.addEventListener('DOMContentLoaded', initWelcome);
88
        document.addEventListener('astro:page-load', initWelcome);
89
    } else {
90
        initWelcome();
91
    }
92

93
    (window as any).closeWelcomeToast = closeWelcomeToast;
94
</script>
95

96
<style>
97
    /* 样式保持不变 */
98
    #welcome-toast { max-width: calc(100vw - 2rem); }
99
    @media (max-width: 640px) {
100
        #welcome-toast {
101
            top: auto; bottom: 1rem; left: 50%; right: auto;
102
            transform: translateX(-50%) translateY(100%);
103
            width: 90%; max-width: none;
104
            transition: transform 0.5s ease-out, opacity 0.5s ease-out;
105
        }
106
        #welcome-toast.translate-y-0 { transform: translateX(-50%) translateY(0); }
107
        #welcome-toast.translate-y-full { transform: translateX(-50%) translateY(100%); }
108
    }
109
</style>

展开收起

使用组件#

文件路径：src/layouts/MainGridLayout.astro

1
---
2
import WelcomeToast from "@components/widget/WelcomeToast.astro"; //欢迎提示组件
3
---
4

5
<!-- 欢迎提示组件 -->
6
<WelcomeToast></WelcomeToast>

显示逻辑配置#

访客只在首次访问时显示欢迎弹窗（原作者）

1
    function initWelcome() {
2
        // 检查是否已显示过欢迎弹窗
3
        if (!sessionStorage.getItem(VISIT_SESSION_KEY)) {
4
            sessionStorage.setItem(VISIT_SESSION_KEY, 'true');
5
            showWelcomeToast(); // 显示欢迎弹窗
6
        }
7
    }

访客只会在首页刷新时显示，非首页刷新不会显示（正在使用）

1
    function initWelcome() {
2
        // 检查是否为首页（路径为 "/" 或 "/index.html"）
3
        const isHomePage = window.location.pathname === '/' || window.location.pathname === '/index.html';
4

5
        // 只在首页显示欢迎弹窗
6
        if (isHomePage) {
7
            showWelcomeToast();
8
        }
9
    }

访客每次刷新页面时，欢迎提示组件会重新显示，不限于文章页。

1
    function initWelcome() {
2
        // 显示欢迎弹窗
3
        showWelcomeToast();
4
    }

归档统计

Tue, 09 Jun 2026 00:00:00 GMT

获取归档列表#

文件路径：src/pages/archive.astro

1
---
2
import { getSortedPostsList } from "@/utils/content-utils";  // [!code --]
3
const sortedPostsList = await getSortedPostsList();     // [!code --]
4
<ArchivePanel sortedPosts={sortedPostsList} client:only="svelte" /> // [!code --]
5

6
import { getArchiveList } from "@/utils/content-utils";
7

8
// 获取归档列表（posts + moments + bangumi + life）
9
const archiveList = await getArchiveList();
10

11
// 计算各类型数量
12
const postsCount = archiveList.filter(item => item.type === "post").length;
13
const momentsCount = archiveList.filter(item => item.type === "moment").length;
14
const bangumiCount = archiveList.filter(item => item.type === "bangumi").length;
15
const lifeCount = archiveList.filter(item => item.type === "life").length;
16
const totalCount = postsCount + momentsCount + bangumiCount + lifeCount;
17
---
18

19
<MainGridLayout title={i18n(I18nKey.archive)}>
20
      <!-- 统计信息 -->
21
    <div class="card-base px-8 py-6 mb-6">
22
        <div class="flex flex-wrap gap-6 justify-center text-center">
23
            <div class="flex flex-col">
24
                <span class="text-3xl font-bold text-amber-500">{postsCount}</span>
25
                <span class="text-sm text-30 mt-1">{i18n(I18nKey.postList)}</span>
26
            </div>
27
            <div class="w-px bg-neutral-200 dark:bg-neutral-700"></div>
28
            <div class="flex flex-col">
29
                <span class="text-3xl font-bold text-(--primary)">{momentsCount}</span>
30
                <span class="text-sm text-30 mt-1">{i18n(I18nKey.moments)}</span>
31
            </div>
32
            <div class="w-px bg-neutral-200 dark:bg-neutral-700"></div>
33
            <div class="flex flex-col">
34
                <span class="text-3xl font-bold text-red-500 dark:text-red-400">{bangumiCount}</span>
35
                <span class="text-sm text-30 mt-1">{i18n(I18nKey.bangumi)}</span>
36
            </div>
37
            <div class="w-px bg-neutral-200 dark:bg-neutral-700"></div>
38
            <div class="flex flex-col">
39
                <span class="text-3xl font-bold text-emerald-600 dark:text-emerald-400">{lifeCount}</span>
40
                <span class="text-sm text-30 mt-1">生活</span>
41
            </div>
42
            <div class="w-px bg-neutral-200 dark:bg-neutral-700"></div>
43
            <div class="flex flex-col">
44
                <span class="text-3xl font-bold text-(--primary)">{totalCount}</span>
45
                <span class="text-sm text-30 mt-1">总计</span>
46
            </div>
47
        </div>
48
    </div>
49
  <ArchivePanel sortedPosts={archiveList} client:only="svelte" />
50
</MainGridLayout>

展开收起

更新内容工具函数文件#

文件路径：src/utils/content-utils.ts

1
---
2
import { getCategoryUrl, getPostUrlBySlug } from "@utils/url-utils";
3
import { getDiaryList } from "@/data/diary"
4
---
5

6
export interface ArchiveItem {
7
  id: string;
8
  type: "post" | "moment" | "bangumi" | "life";
9
  link?: string;
10
  data: {
11
    title: string;
12
    published: Date;
13
    tags: string[];
14
    category?: string | null;
15
  };
16
}
17

18
export async function getArchiveList(): Promise<ArchiveItem[]> {
19
  const posts = await getCollection("posts", ({ data }) => {
20
    return import.meta.env.PROD ? data.draft !== true : true;
21
  });
22
  const diaryList = getDiaryList();
23

24
  const postItems: ArchiveItem[] = posts.map((post) => ({
25
    id: post.id,
26
    type: "post",
27
    link: getPostUrlBySlug(post.id),
28
    data: {
29
      title: post.data.title,
30
      published: post.data.published,
31
      tags: post.data.tags,
32
      category: post.data.category || null,
33
    },
34
  }));
35

36
  // 将日记数据转换为归档项
37
  const momentItems: ArchiveItem[] = diaryList.map((diary) => {
38
    let title = diary.content || "";
39
    title = title.replace(/[#*`]/g, "").trim();
40
    if (title.length > 50) title = `${title.substring(0, 50)}...`;
41
    if (!title) title = i18n(I18nKey.moments) || "日常动态";
42

43
    return {
44
      id: String(diary.id),
45
      type: "moment",
46
      link: "/diary/",
47
      data: {
48
        title: title,
49
        published: new Date(diary.date),
50
        tags: diary.tags || [],
51
        category: null,
52
      },
53
    };
54
  });
55

56
  // 空数组，用于保持接口兼容性
57
  const bangumiItems: ArchiveItem[] = [];
58
  const lifeItems: ArchiveItem[] = [];
59

60
  return [...postItems, ...momentItems, ...bangumiItems, ...lifeItems].sort((a, b) => {
61
    const timeA = a.data.published.getTime();
62
    const timeB = b.data.published.getTime();
63
    return timeB - timeA;
64
  });
65
}

展开收起

定义类型#

文件路径：src/components/controls/ArchivePanel.svelte

1
interface Post {
2
  id: string;
3
  type?: "post" | "moment" | "bangumi" | "life";
4
  link?: string;
5
  data: {
6
    title: string;
7
    tags: string[];
8
    category?: string | null;
9
    published: Date;
10
  };
11
}
12

13
{@const postLink = post.link || getPostUrlBySlug(post.id)}
14
<a
15
  href={getPostUrlBySlug(post.id)}  // [!code --]
16
    href={postLink}  // [!code ++]
17
  aria-label={post.data.title}
18
  class="group btn-plain block! h-10 w-full rounded-lg hover:text-[initial]"
19
>
20

21
<div
22
                class="w-[70%] md:max-w-[65%] md:w-[65%] text-left font-bold
23
                     group-hover:translate-x-1 transition-all group-hover:text-(--primary)
24
                     text-75 pr-8 whitespace-nowrap text-ellipsis overflow-hidden flex items-center gap-2"
25
            >
26
              {#if post.type === 'post'}
27
                <span class="px-1.5 py-0.5 text-[10px] bg-amber-500 text-white rounded-md shrink-0 uppercase tracking-wider opacity-80 font-normal">
28
                  文章
29
                </span>
30
              {:else if post.type === 'moment'}
31
                <span class="px-1.5 py-0.5 text-[10px] bg-(--primary) text-white rounded-md shrink-0 uppercase tracking-wider opacity-80 font-normal">
32
                  {i18n(I18nKey.moments) || 'Moment'}
33
                </span>
34
              {:else if post.type === 'bangumi'}
35
                <span class="px-1.5 py-0.5 text-[10px] bg-red-500 text-white rounded-md shrink-0 uppercase tracking-wider opacity-80 font-normal">
36
                  {i18n(I18nKey.bangumi) || 'Record'}
37
                </span>
38
              {:else if post.type === 'life'}
39
                <span class="px-1.5 py-0.5 text-[10px] bg-emerald-600 text-white rounded-md shrink-0 uppercase tracking-wider opacity-80 font-normal">
40
                  生活
41
                </span>
42
              {/if}
43
              <span class="truncate">{post.data.title}</span>
44
            </div>

展开收起

语言配置#

文件路径：src/i18n/i18nKey.ts

1
moments = "moments",

文件路径：src/i18n/languages/en.ts

1
[Key.moments]: "Dynamic",

文件路径：src/i18n/languages/ja.ts

1
[Key.moments]: "ダイナミック",

文件路径：src/i18n/languages/ru.ts

1
[Key.moments]: "Динамика",

文件路径：src/i18n/languages/zh_CN.ts

1
[Key.moments]: "动态",

文件路径：src/i18n/languages/zh_TW.ts

1
[Key.moments]: "動態",

给博客增加单个和全部分类页面

Tue, 09 Jun 2026 00:00:00 GMT

文件目录#

1
src/
2
├── components/
3
│   └── layout/
4
│       ├── CategoryBar.astro          [分类栏组件：显示主页、归档、分类按钮，支持横向滚动]
5
├── config/
6
│   └── navBarConfig.ts                [导航栏配置：动态生成导航链接，添加分类菜单项]
7
├── i18n/
8
│   ├── i18nKey.ts                     [国际化键定义：新增 allCategories 和 searchAlbums 键]
9
│   └── languages/
10
│       ├── en.ts                      [英文翻译文件]
11
│       ├── ja.ts                      [日文翻译文件]
12
│       ├── ru.ts                      [俄文翻译文件]
13
│       ├── zh_CN.ts                   [简体中文翻译文件]
14
│       └── zh_TW.ts                   [繁体中文翻译文件]
15
├── pages/
16
│   ├── categories.astro               [全部分类页面：显示所有分类卡片列表（新增）]
17
│   └── categories/
18
│       └── [category].astro           [单个分类详情页：显示该分类文章和标签筛选（新增）]
19
└── utils/
20
    └── url-utils.ts                   [URL工具函数：新增分类相关URL生成函数]

展开收起

创建全部分类页面#

文件路径：src/pages/categories.astro

1
---
2
import { Icon } from "astro-icon/components";
3
import MainGridLayout from "@layouts/MainGridLayout.astro";
4
import { getCategoryList } from "@/utils/content-utils";
5
import I18nKey from "@i18n/i18nKey";
6
import { i18n } from "@i18n/translation";
7

8
const categories = await getCategoryList();
9
const totalPosts = categories.reduce((sum, cat) => sum + cat.count, 0);
10
---
11

12
<MainGridLayout title={i18n(I18nKey.categories)}>
13
    <!-- 页面标题 -->
14
    <div class="card-base px-8 py-6 mb-6">
15
        <h1 class="text-2xl font-bold text-(--primary) mb-2">
16
            {i18n(I18nKey.categories)}
17
        </h1>
18
        <p class="text-30 text-sm">
19
            {i18n(I18nKey.allCategories)} · {totalPosts} {i18n(I18nKey.postsCount)}
20
        </p>
21
    </div>
22

23
    <!-- 分类卡片列表 -->
24
    <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4 mb-6">
25
        {
26
            categories.map((category, index) => (
27
                <a
28
                    href={category.url}
29
                    class="card-base p-6 flex items-center gap-4 transition-all duration-300
30
                           hover:scale-[1.02] hover:shadow-lg active:scale-[0.98]
31
                           onload-animation"
32
                    style={`animation-delay: calc(var(--content-delay) + ${index * 50}ms);`}
33
                >
34
                    <div class="flex-shrink-0 w-12 h-12 rounded-full bg-(--primary)/10 flex items-center justify-center">
35
                        <Icon
36
                            name="material-symbols:folder-open"
37
                            class="text-2xl text-(--primary)"
38
                        />
39
                    </div>
40
                    <div class="flex-1 min-w-0">
41
                        <h2 class="text-lg font-bold text-90 truncate">
42
                            {category.name}
43
                        </h2>
44
                        <p class="text-sm text-30 mt-1">
45
                            {category.count} {i18n(I18nKey.postsCount)}
46
                        </p>
47
                    </div>
48
                    <div class="flex-shrink-0">
49
                        <Icon
50
                            name="material-symbols:chevron-right-rounded"
51
                            class="text-2xl text-30 transition-transform duration-200 group-hover:translate-x-1"
52
                        />
53
                    </div>
54
                </a>
55
            ))
56
        }
57
    </div>
58

59
    <!-- 空状态 -->
60
    {
61
        categories.length === 0 && (
62
            <div class="card-base px-8 py-12 text-center">
63
                <Icon
64
                    name="material-symbols:folder-off"
65
                    class="text-5xl text-30 mx-auto mb-4"
66
                />
67
                <p class="text-30">{i18n(I18nKey.bangumiNoData)}</p>
68
            </div>
69
        )
70
    }
71
</MainGridLayout>
72

73
<style>
74
    .card-base {
75
        background: var(--card-bg);
76
        border: 1px solid var(--card-border);
77
        border-radius: var(--radius-large);
78
    }
79

80
    a.card-base:hover {
81
        border-color: var(--primary);
82
    }
83

84
    a.card-base:active {
85
        background: var(--card-bg-active);
86
    }
87
</style>

展开收起

创建单个分类详情页#

文件路径：src/pages/categories/[category].astro

1
---
2
import type { GetStaticPaths } from "astro";
3
import type { CollectionEntry } from "astro:content";
4
import { getCollection } from "astro:content";
5
import { Icon } from "astro-icon/components";
6
import PostCard from "@/components/layout/PostCard.astro";
7
import MainGridLayout from "@layouts/MainGridLayout.astro";
8
import { getCategoryList } from "@/utils/content-utils";
9
import { getTagUrl, getCategoryPageUrl, getPostUrlBySlug } from "@/utils/url-utils";
10
import I18nKey from "@i18n/i18nKey";
11
import { i18n } from "@i18n/translation";
12
import { siteConfig } from "@/config";
13

14
type PostEntry = CollectionEntry<"posts">;
15

16
interface Props {
17
  categoryName: string;
18
  posts: PostEntry[];
19
  totalPosts: number;
20
  tags: { name: string; count: number }[];
21
}
22

23
export const getStaticPaths = (async () => {
24
  const categories = await getCategoryList();
25
  const allPosts = await getCollection("posts", ({ data }) => {
26
    return import.meta.env.PROD ? data.draft !== true : true;
27
  }) as PostEntry[];
28

29
  const paths: any[] = [];
30

31
  for (const category of categories) {
32
    // 过滤该分类下的文章
33
    const categoryPosts = allPosts.filter((post) => {
34
      const postCategory = post.data.category?.trim() || "";
35
      const uncategorized = i18n(I18nKey.uncategorized).toLowerCase();
36

37
      if (!category.name || category.name.toLowerCase() === uncategorized) {
38
        // 未分类：没有分类或分类为空/未分类
39
        return !postCategory || postCategory.toLowerCase() === uncategorized;
40
      }
41
      return postCategory === category.name;
42
    });
43

44
    // 按日期排序
45
    categoryPosts.sort((a, b) => {
46
      if (a.data.pinned && !b.data.pinned) return -1;
47
      if (!a.data.pinned && b.data.pinned) return 1;
48
      return new Date(b.data.published).getTime() - new Date(a.data.published).getTime();
49
    });
50

51
    // 收集该分类下所有标签
52
    const tagCountMap: Record<string, number> = {};
53
    categoryPosts.forEach((post) => {
54
      (post.data.tags || []).forEach((tag: string) => {
55
        tagCountMap[tag] = (tagCountMap[tag] || 0) + 1;
56
      });
57
    });
58
    const tags = Object.entries(tagCountMap)
59
      .sort((a, b) => b[1] - a[1])
60
      .map(([name, count]) => ({ name, count }));
61

62
    paths.push({
63
      params: { category: category.name },
64
      props: {
65
        categoryName: category.name,
66
        posts: categoryPosts,
67
        totalPosts: categoryPosts.length,
68
        tags,
69
      },
70
    });
71
  }
72

73
  return paths;
74
}) satisfies GetStaticPaths;
75

76
const { categoryName, posts, totalPosts, tags } = Astro.props;
77

78
// 解码分类名称
79
const decodedCategory = decodeURIComponent(categoryName);
80

81
let delay = 0;
82
const interval = 50;
83

84
const masonryEnabled = siteConfig.postListLayout.grid.masonry;
85
const columnWidth = siteConfig.postListLayout.grid.columnWidth || 280;
86

87
const defaultLayout = siteConfig.postListLayout.defaultMode || "list";
88
const mobileDefaultLayout =
89
  siteConfig.postListLayout.mobileDefaultMode || defaultLayout;
90
const initialLayoutClass =
91
  defaultLayout === "grid"
92
    ? "post-grid-auto grid-mode"
93
    : "flex flex-col gap-4 md:gap-4 list-mode";
94
---
95

96
<MainGridLayout title={`${decodedCategory} - ${i18n(I18nKey.categories)}`}>
97
    <!-- 面包屑导航 -->
98
    <div class="card-base px-6 py-4 mb-6">
99
        <nav class="flex items-center gap-2 text-sm text-30">
100
            <a href="/" class="hover:text-(--primary) transition-colors">
101
                <Icon name="material-symbols:home" class="inline-block align-middle" />
102
            </a>
103
            <span class="opacity-50">/</span>
104
            <a href={getCategoryPageUrl()} class="hover:text-(--primary) transition-colors">
105
                {i18n(I18nKey.categories)}
106
            </a>
107
            <span class="opacity-50">/</span>
108
            <span class="text-90 font-medium">{decodedCategory}</span>
109
        </nav>
110
    </div>
111

112
    <!-- 分类标题 -->
113
    <div class="card-base px-8 py-6 mb-6">
114
        <div class="flex items-center gap-4">
115
            <div class="w-14 h-14 rounded-full bg-(--primary)/10 flex items-center justify-center flex-shrink-0">
116
                <Icon name="material-symbols:folder-open" class="text-3xl text-(--primary)" />
117
            </div>
118
            <div>
119
                <h1 class="text-2xl font-bold text-90">{decodedCategory}</h1>
120
                <p class="text-sm text-30 mt-1">
121
                    {totalPosts} {i18n(I18nKey.postsCount)}
122
                </p>
123
            </div>
124
        </div>
125
    </div>
126

127
    <!-- 标签筛选区域 -->
128
    {
129
        tags.length > 0 && (
130
            <div class="card-base px-6 py-5 mb-6">
131
                <div class="flex items-center gap-3 mb-3">
132
                    <Icon name="material-symbols:label" class="text-lg text-(--primary)" />
133
                    <span class="text-sm font-medium text-90">{i18n(I18nKey.tags)}</span>
134
                    <span class="text-xs text-30">({tags.length})</span>
135
                </div>
136
                <div class="flex flex-wrap gap-2">
137
                    {tags.map((tag: { name: string; count: number }) => (
138
                        <a
139
                            href={getTagUrl(tag.name)}
140
                            class="btn-regular px-3 py-1.5 text-sm rounded-md
141
                                     transition-all duration-200
142
                                     hover:scale-105 hover:bg-(--primary)/20
143
                                     active:scale-95"
144
                        >
145
                            #{tag.name}
146
                            <span class="ml-1 text-xs opacity-60">({tag.count})</span>
147
                        </a>
148
                    ))}
149
                </div>
150
            </div>
151
        )
152
    }
153

154
    <!-- 文章列表 -->
155
    <div
156
        id="post-list-container"
157
        class={`transition-all duration-500 ease-in-out mb-4 ${initialLayoutClass}`}
158
        data-default-layout={defaultLayout}
159
        data-mobile-default-layout={mobileDefaultLayout}
160
        data-masonry-enabled={masonryEnabled}
161
        data-column-width={columnWidth}
162
        style={`--post-card-min-width: ${columnWidth}px;`}
163
    >
164
        {
165
            posts.length > 0 ? (
166
                posts.map((entry: PostEntry, index: number) => (
167
                    <PostCard
168
                        entry={entry}
169
                        title={entry.data.title}
170
                        tags={entry.data.tags}
171
                        category={entry.data.category}
172
                        published={entry.data.published}
173
                        updated={entry.data.updated}
174
                        url={getPostUrlBySlug(entry.id)}
175
                        image={entry.data.image}
176
                        description={entry.data.description}
177
                        draft={entry.data.draft}
178
                        pinned={entry.data.pinned}
179
                        password={!!entry.data.password}
180
                        loading={index < 2 ? "eager" : "lazy"}
181
                        class:list="onload-animation post-card-item"
182
                        style={`animation-delay: calc(var(--content-delay) + ${delay++ * interval}ms);`}
183
                    />
184
                ))
185
            ) : (
186
                <div class="card-base px-8 py-12 text-center w-full">
187
                    <Icon name="material-symbols:article" class="text-5xl text-30 mx-auto mb-4" />
188
                    <p class="text-30">{i18n(I18nKey.bangumiNoData)}</p>
189
                </div>
190
            )
191
        }
192
    </div>
193
</MainGridLayout>
194

195
<script is:inline define:vars={{ defaultLayout, mobileDefaultLayout, columnWidth }}>
196
    (function() {
197
        const savedLayout = localStorage.getItem('postListLayout');
198
        const effectiveDefault = window.innerWidth < 780 ? mobileDefaultLayout : defaultLayout;
199
        const effectiveLayout = window.innerWidth < 380 ? 'grid' : (savedLayout || effectiveDefault);
200

201
        if (effectiveLayout !== defaultLayout) {
202
            const container = document.getElementById('post-list-container');
203

204
            if (container) {
205
                container.style.transition = 'none';
206
                container.classList.remove('list-mode', 'grid-mode', 'post-grid-auto', 'flex', 'flex-col', 'gap-4', 'md:gap-4');
207

208
                if (effectiveLayout === 'grid') {
209
                    container.classList.add('grid-mode', 'post-grid-auto');
210
                } else {
211
                    container.classList.add('list-mode', 'flex', 'flex-col', 'gap-4', 'md:gap-4');
212
                }
213

214
                container.offsetHeight;
215
                container.style.transition = '';
216
            }
217
        }
218
    })();
219
</script>
220

221
<script>
222
    function initLayout() {
223
        const postListContainer = document.getElementById("post-list-container");
224
        if (!postListContainer) return;
225

226
        const savedLayout = localStorage.getItem("postListLayout");
227
        const defaultLayout =
228
            postListContainer.getAttribute("data-default-layout") || "list";
229
        const mobileDefaultLayout =
230
            postListContainer.getAttribute("data-mobile-default-layout") || defaultLayout;
231

232
        const effectiveDefault = window.innerWidth < 780 ? mobileDefaultLayout : defaultLayout;
233
        let currentLayout = savedLayout || effectiveDefault;
234

235
        if (window.innerWidth < 380) {
236
            currentLayout = "grid";
237
        }
238

239
        updatePostListLayout(currentLayout);
240
    }
241

242
    function updatePostListLayout(layout: string) {
243
        const postListContainer = document.getElementById("post-list-container");
244
        if (!postListContainer) return;
245

246
        const isCurrentGrid = postListContainer.classList.contains("grid-mode");
247
        const isCurrentList = postListContainer.classList.contains("list-mode");
248
        const currentLayout = isCurrentGrid ? "grid" : (isCurrentList ? "list" : null);
249

250
        const masonryEnabled = postListContainer.getAttribute("data-masonry-enabled") === "true";
251

252
        const applyClasses = () => {
253
            postListContainer.classList.remove("list-mode", "grid-mode", "post-grid-auto");
254
            if (layout === "grid") {
255
                postListContainer.classList.add("grid-mode");
256
                postListContainer.classList.remove("flex", "flex-col");
257
                if (masonryEnabled) {
258
                    postListContainer.classList.remove("post-grid-auto");
259
                    applyMasonryLayout();
260
                } else {
261
                    postListContainer.classList.add("post-grid-auto");
262
                    resetMasonryLayout();
263
                }
264
            } else {
265
                postListContainer.classList.add("list-mode");
266
                postListContainer.classList.add("flex", "flex-col", "gap-4", "md:gap-4");
267
                postListContainer.classList.remove("post-grid-auto");
268
                resetMasonryLayout();
269
            }
270
        };
271

272
        if (!currentLayout) {
273
            applyClasses();
274
            return;
275
        }
276

277
        if (currentLayout === layout) {
278
            if (layout === "grid" && masonryEnabled) {
279
                applyMasonryLayout();
280
            }
281
            return;
282
        }
283

284
        postListContainer.classList.add("layout-switching");
285

286
        setTimeout(() => {
287
            applyClasses();
288

289
            requestAnimationFrame(() => {
290
                postListContainer.classList.remove("layout-switching");
291
            });
292
        }, 200);
293
    }
294

295
    function resetMasonryLayout() {
296
        const container = document.getElementById("post-list-container");
297
        if (!container) return;
298

299
        container.style.height = "";
300
        container.style.position = "";
301
        container.style.display = "";
302

303
        const items = container.querySelectorAll(".post-card-item");
304
        items.forEach((item) => {
305
            // @ts-ignore
306
            item.style.position = "";
307
            // @ts-ignore
308
            item.style.top = "";
309
            // @ts-ignore
310
            item.style.left = "";
311
            // @ts-ignore
312
            item.style.width = "";
313
        });
314
    }
315

316
    function applyMasonryLayout() {
317
        const container = document.getElementById("post-list-container");
318
        if (!container) return;
319

320
        const masonryEnabled = container.getAttribute("data-masonry-enabled") === "true";
321
        if (!masonryEnabled) return;
322

323
        if (!container.classList.contains("grid-mode")) return;
324

325
        const items = Array.from(container.querySelectorAll(".post-card-item"));
326
        if (items.length === 0) return;
327

328
        const gap = 16;
329
        const columnWidth = parseInt(container.getAttribute("data-column-width") || "280");
330

331
        container.style.position = "relative";
332
        container.style.display = "block";
333

334
        const containerWidth = container.offsetWidth;
335
        const colCount = Math.max(1, Math.floor((containerWidth + gap) / (columnWidth + gap)));
336
        const itemWidth = (containerWidth - (colCount - 1) * gap) / colCount;
337

338
        const colHeights = new Array(colCount).fill(0);
339

340
        items.forEach((item) => {
341
            const colIndex = colHeights.indexOf(Math.min(...colHeights));
342
            // @ts-ignore
343
            item.style.position = "absolute";
344
            // @ts-ignore
345
            item.style.width = `${itemWidth}px`;
346
            // @ts-ignore
347
            item.style.setProperty('height', 'auto', 'important');
348

349
            // @ts-ignore
350
            const height = item.offsetHeight;
351
            const top = colHeights[colIndex];
352
            const left = colIndex * (itemWidth + gap);
353

354
            // @ts-ignore
355
            item.style.top = `${top}px`;
356
            // @ts-ignore
357
            item.style.left = `${left}px`;
358

359
            colHeights[colIndex] += height + gap;
360
        });
361

362
        container.style.height = `${Math.max(...colHeights)}px`;
363
    }
364

365
    document.addEventListener("DOMContentLoaded", function () {
366
        setTimeout(initLayout, 50);
367

368
        const imgs = document.querySelectorAll('#post-list-container img');
369
        imgs.forEach(img => {
370
            // @ts-ignore
371
            if(img.complete) return;
372
            img.addEventListener('load', () => {
373
                applyMasonryLayout();
374
            });
375
        });
376
    });
377

378
    document.addEventListener("visibilitychange", function () {
379
        if (!document.hidden) {
380
            setTimeout(initLayout, 100);
381
        }
382
    });
383

384
    window.addEventListener("layoutChange", function (event) {
385
        // @ts-ignore
386
        const newLayout = event.detail.layout;
387
        const postListContainer = document.getElementById("post-list-container");
388
        if (!postListContainer) return;
389

390
        updatePostListLayout(newLayout);
391
    });
392

393
    let resizeTimeout: any;
394
    window.addEventListener("resize", function () {
395
        clearTimeout(resizeTimeout);
396
        resizeTimeout = setTimeout(function () {
397
            initLayout();
398
        }, 250);
399
    });
400

401
    document.addEventListener("astro:page-load", function () {
402
        setTimeout(initLayout, 50);
403

404
        const imgs = document.querySelectorAll('#post-list-container img');
405
        imgs.forEach(img => {
406
            // @ts-ignore
407
            if(img.complete) return;
408
            img.addEventListener('load', () => {
409
                applyMasonryLayout();
410
            });
411
        });
412
    });
413

414
    document.addEventListener("astro:after-swap", function () {
415
        setTimeout(initLayout, 50);
416
    });
417

418
    setTimeout(initLayout, 0);
419
</script>
420

421
<style is:global>
422
    .post-grid-auto {
423
        display: grid;
424
        grid-template-columns: repeat(auto-fill, minmax(var(--post-card-min-width, 320px), 1fr));
425
        gap: 1rem;
426
    }
427

428
    @media (max-width: 767px) {
429
        .list-mode .post-meta-root {
430
            transform: scale(0.72) !important;
431
            transform-origin: top left !important;
432
            margin-bottom: 0.25rem !important;
433
            width: 139% !important;
434
        }
435
        .list-mode :global(.post-meta) {
436
            margin-bottom: 0.25rem !important;
437
            gap: 0.25rem !important;
438
        }
439
    }
440
</style>
441

442
<style>
443
    #post-list-container {
444
        transition: opacity 0.5s cubic-bezier(0.4, 0, 0.2, 1),
445
                    transform 0.5s cubic-bezier(0.4, 0, 0.2, 1);
446
    }
447

448
    #post-list-container > :global(*) {
449
        transition: opacity 0.4s cubic-bezier(0.4, 0, 0.2, 1),
450
                    transform 0.4s cubic-bezier(0.4, 0, 0.2, 1);
451
    }
452

453
    #post-list-container {
454
        transition: opacity 0.2s ease-out, transform 0.2s ease-out;
455
    }
456

457
    #post-list-container.layout-switching {
458
        opacity: 0;
459
        transform: translateY(10px);
460
    }
461

462
    #post-list-container.grid-mode :global(.post-card-wrapper) {
463
        flex-direction: column-reverse !important;
464
    }
465

466
    #post-list-container.grid-mode :global(.post-card-image) {
467
        width: 100% !important;
468
        position: relative !important;
469
        top: auto !important;
470
        right: auto !important;
471
        bottom: auto !important;
472
        border-radius: var(--radius-large) var(--radius-large) 0 0 !important;
473
    }
474

475
    #post-list-container.grid-mode :global(.post-card-content) {
476
        width: 100% !important;
477
        padding: 1rem !important;
478
    }
479

480
    #post-list-container.grid-mode :global(.no-cover .post-card-content) {
481
        padding-right: 4.5rem !important;
482
    }
483

484
    #post-list-container.grid-mode :global(.post-card-title) {
485
        font-size: 1.35rem !important;
486
        line-height: 1.75rem !important;
487
        margin-bottom: 0.5rem !important;
488
    }
489

490
    #post-list-container.grid-mode :global(.post-card-title::before) {
491
        display: none !important;
492
    }
493

494
    #post-list-container.grid-mode :global(.post-meta) {
495
        margin-bottom: 0.5rem !important;
496
        gap: 0.5rem !important;
497
    }
498

499
    #post-list-container.grid-mode :global(.post-meta .text-xl) {
500
        font-size: 1rem !important;
501
        line-height: 1.25rem !important;
502
    }
503

504
    #post-list-container.grid-mode :global(.meta-icon) {
505
        width: 1.5rem !important;
506
        height: 1.5rem !important;
507
        margin-right: 0.25rem !important;
508
    }
509

510
    #post-list-container.grid-mode :global(.post-meta .text-sm) {
511
        font-size: 0.75rem !important;
512
        line-height: 1rem !important;
513
    }
514

515
    #post-list-container.grid-mode :global(.post-meta .pinned-btn) {
516
        padding: 0.25rem 0.375rem !important;
517
    }
518
</style>

展开收起

创建URL工具函数#

文件路径：src/utils/url-utils.ts

1
export function getCategoryUrl(category: string | null): string {
2
  if (
3
    !category ||
4
    category.trim() === "" ||
5
    category.trim().toLowerCase() === i18n(I18nKey.uncategorized).toLowerCase()
6
  )
7
    return url("/categories/uncategorized/");
8
  return url(`/categories/${encodeURIComponent(category.trim())}/`);
9
}
10

11
export function getCategoryPageUrl(): string {
12
  return url("/categories/");
13
}

更新分类栏组件#

文件路径：src/components/layout/CategoryBar.astro

1
---
2
import { url, getCategoryPageUrl } from "@/utils/url-utils";
3
const categoriesUrl = getCategoryPageUrl();
4
---
5

6
<a
7
      href={categoriesUrl}
8
      class="category-pill text-sm px-3 py-1 rounded-lg whitespace-nowrap flex-shrink-0
9
             transition-colors duration-200 flex items-center justify-center"
10
      data-category-name="__categories__"
11
    >
12
      {i18n(I18nKey.categories)}
13
      <span class="text-xs opacity-60 ml-1">{categories.length}</span>
14
</a>

导航栏配置#

文件路径：src/config/navBarConfig.ts

1
// 根据页面开关动态生成导航栏配置
2
const getDynamicNavBarConfig = (): NavBarConfig => {
3
  // 基础导航栏链接
4
  const links: (NavBarLink | LinkPreset)[] = [
5
    // 主页
6
    LinkPreset.Home,
7

8
    // 文章分类
9
    {
10
      name: "分类",
11
      url: "/categories/",
12
      icon: "material-symbols:folder-open",
13
    },
14

15
    // 归档
16
    LinkPreset.Archive,
17
  ];
18
}

展开收起

语言配置#

文件路径：src/i18n/i18nKey.ts

1
allCategories = "allCategories",

文件路径：src/i18n/languages/en.ts

1
[Key.allCategories]: "All Categories",

文件路径：src/i18n/languages/ja.ts

1
[Key.allCategories]: "すべてのカテゴリ",

文件路径：src/i18n/languages/ru.ts

1
[Key.allCategories]: "Все категории",

文件路径：src/i18n/languages/zh_CN.ts

1
  [Key.allCategories]: "全部分类",

文件路径：src/i18n/languages/zh_TW.ts

1
  [Key.allCategories]: "全部分類",

实现今日一言功能

Mon, 08 Jun 2026 00:00:00 GMT

创建数据文件#

文件路径：src/content/ziyuan/ 目录并添加文件：quote.md

1
---
2
title: "每日一言"
3
quotes:
4
  - text: "生活不是等待暴风雨过去，而是学会在雨中跳舞。"
5
    author: "塞维涅夫人"
6
  - text: "世界上只有一种英雄主义，就是在认清生活真相之后依然热爱生活。"
7
    author: "罗曼·罗兰"
8
---

创建组件文件#

文件路径：src/components/widget/QuoteOfTheDay.astro

1
---
2
import WidgetLayout from "@/components/common/WidgetLayout.astro";
3
import { getCollection } from "astro:content";
4

5
// 从 content/ziyuan/quote.md 读取名言数据
6
const ziyuanEntries = await getCollection("ziyuan");
7
const quoteEntry = ziyuanEntries.find((e) => e.id === "quote");
8
const quoteData = quoteEntry?.data as any;
9
const quotes = quoteData?.quotes || [];
10

11
interface Props {
12
  class?: string;
13
  style?: string;
14
}
15

16
const { class: className, style } = Astro.props;
17

18
// 使用日期作为随机种子，确保同一天显示相同的名言
19
const today = new Date();
20
const dateStr = today.toISOString().split("T")[0];
21
const seed = dateStr.split("").reduce((acc, char) => acc + char.charCodeAt(0), 0);
22
const randomIndex = seed % quotes.length;
23
const quote = quotes[randomIndex] || { text: "暂无名言", author: "" };
24
---
25

26
<WidgetLayout name="✨ 今日一言" id="quote-of-the-day" class={className} style={style}>
27
  <div class="quote-content">
28
    <blockquote class="quote-text">
29
      <span class="quote-mark">"</span>
30
      {quote.text}
31
      <span class="quote-mark">"</span>
32
    </blockquote>
33
    <cite class="quote-author">—— {quote.author}</cite>
34
  </div>
35
</WidgetLayout>
36

37
<style>
38
  .quote-content {
39
    display: flex;
40
    flex-direction: column;
41
    gap: 0.75rem;
42
    padding: 0.5rem 0;
43
  }
44

45
  .quote-text {
46
    position: relative;
47
    font-style: italic;
48
    font-size: 0.9rem;
49
    line-height: 1.6;
50
    color: var(--text-color);
51
    padding: 0 0.5rem;
52
    margin: 0;
53
  }
54

55
  .quote-mark {
56
    font-size: 1.5rem;
57
    line-height: 0;
58
    vertical-align: middle;
59
    color: var(--primary);
60
    opacity: 0.6;
61
    font-family: Georgia, serif;
62
  }
63

64
  .quote-author {
65
    display: block;
66
    text-align: right;
67
    font-size: 0.75rem;
68
    color: var(--content-meta);
69
    font-style: normal;
70
    margin-top: 0.25rem;
71
  }
72

73
  /* 深色模式优化 */
74
  :global(html.dark) .quote-text {
75
    color: var(--text-color);
76
  }
77

78
  /* 悬停效果 */
79
  :global(.quote-content:hover .quote-text) {
80
    color: var(--primary);
81
    transition: color 0.2s ease;
82
  }
83
</style>

展开收起

配置数据加载方式#

在 src/content.config.ts 配置数据加载方式：

1
const ziyuanCollection = defineCollection({
2
  loader: glob({ pattern: "**/*.md", base: "./src/content/ziyuan" }),
3
  schema: z.union([
4
    z.object({
5
      title: z.string(),
6
      content: z.string(),
7
      closable: z.boolean().optional().default(true),
8
      link: z
9
        .object({
10
          enable: z.boolean().optional().default(true),
11
          text: z.string(),
12
          url: z.string(),
13
          external: z.boolean().optional().default(false),
14
        })
15
        .optional(),
16
      quotes: z.undefined().optional(),
17
    }),
18
    z.object({
19
      title: z.string(),
20
      quotes: z.array(
21
        z.object({
22
          text: z.string(),
23
          author: z.string(),
24
        })
25
      ),
26
      content: z.undefined().optional(),
27
      closable: z.undefined().optional(),
28
      link: z.undefined().optional(),
29
    }),
30
  ]),
31
});
32

33
export const collections = {
34
  ziyuan: ziyuanCollection,
35
};

展开收起

注册组件#

文件路径：src/components/layout/SideBar.astro

1
import QuoteOfTheDay from "@/components/widget/QuoteOfTheDay.astro";

添加到组件映射表：

1
const componentMap = {
2
  quoteOfTheDay: QuoteOfTheDay,  // 添加这一行
3
};

侧边栏配置#

文件路径：src/config/sidebarConfig.ts

添加到右侧边栏

1
rightComponents: [
2
  {
3
    type: "quoteOfTheDay",  // 必须与 componentMap 的 key 一致
4
    enable: true,           // true = 启用，false = 禁用
5
    position: "sticky",        // "top" = 固定顶部，"sticky" = 粘性定位
6
    showOnPostPage: true,   // 是否在文章详情页显示
7
  },
8
  // ... 其他组件
9
],

添加到移动端底部

1
mobileBottomComponents: [
2
  {
3
      // 组件类型：今日一言
4
      type: "quoteOfTheDay",
5
      // 是否启用该组件
6
      enable: true,
7
      // 是否在文章详情页显示
8
      showOnPostPage: true,
9
  },
10
  // ... 其他组件
11
],

类型定义#

文件路径：src/types/config.ts

1
export type WidgetComponentType =
2
  | "profile"
3
  | "announcement"
4
  // ... 其他类型
5
  | "quoteOfTheDay";  // 确保这一行存在

待办

Sun, 07 Jun 2026 00:00:00 GMT

功能#

BUG#

修复生产环境下顶部滚动条刷新页面不显示
浏览量一直加载中…
自定义Footer页面生产环境不显示主题版本号，本地环境显示

优化#

右侧滚动条优化，和teek保持一致

年轻的时候是旅游重要还是攒钱重要？

Sat, 06 Jun 2026 00:00:00 GMT

独特价值#

18岁时，我们揣着打工兼职存下的钱，就能在绿皮火车的硬座上熬一整夜

住青旅像回到大学宿舍般自在，和萍水相逢的陌生人聊起梦想，眼睛里都闪着光

那时的快乐很简单：有耗不尽的体力，特种兵旅行一整天，到第二天还有精力继续开启旅行

少年心气是不可再生之物，一场说走就走的旅行，一次毫不犹豫的出发，都是青春最滚烫的印记

人生有无数个夏天，却只有一次少年的烟火人间

我们只来一次，不如真诚一点，过得肆意，活成自己并永远热烈且自由

旅行心境#

或许到了30多岁，我们终于有能力选择喝着咖啡在沙滩边看日出日落、睡一觉就能抵达异国他乡的飞机，去往年轻时日思夜想的雪山

可站在山脚下的那一刻，却少了当年的激动，多了几分家里的柴米油盐和下班的疲惫

不再忙着打卡拍照发朋友圈，只想独自坐在山顶晒晒太阳发着呆

原来，最好的旅行从来不是在准备和计划中，而是在出发的那一刻

感悟人生#

大家常说：“欲买桂花同载酒，终不似少年游”

可也别忘了，“莫道桑榆晚，为霞尚满天”

人生还很长，一程有一程的风景

20岁没有完成的事情，30岁去完成也没关系；

就算是朝花夕拾，你觉得没有意义了，那也无所谓

人生于天地间，若白驹过隙，忽然而已

所以岁月不待人，及时当勉励，重在的是”诗酒趁年华”

遗憾错过#

你一生追求的东西，其实一开始就有

18岁的你想去旅行，可你囊中羞涩，止于心动

20岁的你，朋友都叫你出去玩，可你说学业要紧，止于行动

我们总说来日方长，却忘了人只活这一次

很多事情错过一次，可能就再也没有机会了；很多远方，错过一次就再也去不成了

所有的错过，最终都成为这辈子难以忘怀的遗憾；

或许等我老了，躺在床上回想起这一生，要是因为一些事而一次次错过自己的梦想与决定，那我该多懊悔啊！

出发勇气#

很多幸福和快乐都是后知后觉，当我们身在其中的时候，或许觉得并没有什么，但过了很久以后，就会开始怀念

在所有不确定的时间里，好好珍惜当下才是最珍贵的

愿你我永远有出发的勇气和说走就走的行动力，并一直朝着梦想远航