应用页与集成功能完整指南

本文档详细记录了从 Examplefuwari 项目集成到 FireflyBlog 的四大功能，包含完整的文件清单、配置方法和使用说明。

一、功能总览

本次集成共涉及以下功能，所有改动均不改变原有代码结构：

二、新增文件清单

1
FireflyBlog/
2
├── src/
3
│   ├── plugins/
4
│   │   ├── rehype-image-fallback.mjs    ← 双 CDN 图床回退插件
5
│   │   └── rehype-image-attrs.mjs       ← 图片懒加载插件
6
│   ├── pages/
7
│   │   ├── apps.astro                   ← 应用中心页面
8
│   │   └── api/
9
│   │       └── indexnow.ts              ← IndexNow API 端点
10
├── .github/
11
│   └── workflows/
12
│       └── indexnow.yml                 ← IndexNow GitHub Action
13
├── scripts/
14
│   └── submit-indexnow.mjs              ← IndexNow CLI 提交脚本

三、修改文件清单

四、功能详解与使用方法

4.1 双 CDN 图床回退

原理：通过 rehype 插件在 Markdown 渲染时为所有来自主力图床的 <img> 标签添加 onerror 属性，当图片加载失败时自动切换到备用图床。

文件：src/plugins/rehype-image-fallback.mjs

配置方法：

打开 astro.config.mjs，找到 rehypePlugins 数组末尾的 rehypeImageFallback 配置：

1
import rehypeImageFallback from "./src/plugins/rehype-image-fallback.mjs";
2

3
// 在 rehypePlugins 数组中：
4
[
5
  rehypeImageFallback,
6
  {
7
    enable: true,  // ← 改为 true 启用
8
    originalDomain: "你的主力图床域名",  // 例如 "images.example.com"
9
    fallbackDomain: "你的备用图床域名",  // 例如 "backup.example.com"
10
  },
11
],

配置示例：

1
// 假设主力图床是 images.mysite.com，备用是 backup.r2.dev
2
[
3
  rehypeImageFallback,
4
  {
5
    enable: true,
6
    originalDomain: "images.mysite.com",
7
    fallbackDomain: "backup.r2.dev",
8
  },
9
],

工作流程：

1
文章图片: https://images.mysite.com/photo.webp
2
    ↓ 加载失败触发 onerror
3
自动切换: https://backup.r2.dev/photo.webp

注意事项：

• 仅对 Markdown 内容中的图片生效，不影响 Astro <Image> 组件
• 主力和备用图床的文件路径结构必须一致
• 默认关闭（enable: false），需手动开启

4.2 图片懒加载

原理：通过 rehype 插件为 Markdown 渲染输出中所有 <img> 标签自动添加 loading="lazy" 和 decoding="async" 属性，实现原生懒加载。

文件：src/plugins/rehype-image-attrs.mjs

配置方法：

打开 astro.config.mjs，在 rehypePlugins 数组中添加：

1
import rehypeImageAttrs from "./src/plugins/rehype-image-attrs.mjs";
2

3
// 在 rehypePlugins 数组中（建议放在 rehypeImageFallback 之前）：
4
rehypeImageAttrs,

效果：

1
<!-- 渲染前 -->
2
<img src="photo.webp" alt="风景">
3

4
<!-- 渲染后（自动添加） -->
5
<img src="photo.webp" alt="风景" loading="lazy" decoding="async">

注意事项：

• 仅在属性未设置时才添加，不会覆盖已有属性
• 不设置 fetchpriority，避免影响 LCP（最大内容绘制）图片
• 与 ImageWrapper 组件的 loading="lazy" 互不冲突

4.3 IndexNow 集成

原理：IndexNow 是一个即时索引协议，允许网站主动通知搜索引擎（Bing、Yandex、Naver 等）内容已更新，加速搜索引擎收录。

涉及文件：

• src/pages/api/indexnow.ts — API 端点
• .github/workflows/indexnow.yml — GitHub Action
• scripts/submit-indexnow.mjs — CLI 提交脚本
• package.json — 添加 submit-indexnow 命令

步骤 1：申请 IndexNow Key

1. 访问 indexnow.org
2. 生成一个 Key（一串随机字符串）
3. 在你的网站根目录放置一个 {key}.txt 文件，内容为 Key 本身
   • 例如 Key 为 abc123，则创建 public/abc123.txt，内容为 abc123

步骤 2：配置 GitHub Secrets

在你的 GitHub 仓库中：

1. 进入 Settings → Secrets and variables → Actions
2. 点击 New repository secret
3. Name: INDEXNOW_KEY
4. Value: 你申请到的 Key

步骤 3：配置站点 URL

打开 src/pages/api/indexnow.ts，确认以下配置：

1
const baseUrl = "https://f3f3.top";  // ← 改为你的站点 URL

打开 scripts/submit-indexnow.mjs，确认：

1
const host = "f3f3.top";  // ← 改为你的站点域名

步骤 4：验证配置

1
# 本地测试（需要先构建）
2
pnpm build
3
pnpm submit-indexnow
4

5
# 强制提交所有 URL
6
curl -X POST https://你的域名/api/indexnow \
7
  -H "Content-Type: application/json" \
8
  -d '{"force": true}'

GitHub Action 工作流程

1
push 到 master 分支
2
    ↓
3
自动触发 indexnow.yml
4
    ↓
5
安装依赖 → 构建站点 → 恢复缓存 → 增量提交新 URL → 保存缓存

API 端点说明

请求体：

1
{
2
  "force": false  // true=强制提交所有URL，false=仅提交新增URL
3
}

响应示例：

1
{
2
  "success": true,
3
  "message": "URLs submitted to IndexNow successfully (incremental mode)",
4
  "totalUrls": 5,
5
  "newUrls": 2,
6
  "isIncremental": true
7
}

4.4 文章置顶

状态：FireflyBlog 已完整实现，无需额外操作。

使用方法：

在文章的 frontmatter 中添加 pinned: true：

1
---
2
title: 我的置顶文章
3
published: 2026-06-05
4
pinned: true    ← 添加这行
5
tags:
6
  - 博客
7
category: 博客导航
8
---

效果：

• 置顶文章始终显示在文章列表最前面
• 文章卡片和文章详情页显示 📌 置顶标记
• 多篇置顶文章之间按发布日期排序

配置（已预设，无需修改）：

• 内容 Schema：src/content.config.ts 中 pinned: z.boolean().optional().default(false)
• 排序逻辑：src/utils/content-utils.ts 中置顶文章优先
• UI 组件：PostCard.astro 和 PostMeta.astro 显示置顶标记

4.5 应用中心页面

原理：新增 /apps/ 页面，以网格卡片形式展示个人应用、工具和服务链接。

文件：

• src/pages/apps.astro — 页面组件
• src/config/siteConfig.ts — 应用数据配置
• src/types/config.ts — 类型定义
• src/config/navBarConfig.ts — 导航栏配置

步骤 1：添加应用数据

打开 src/config/siteConfig.ts，在 apps 数组中添加你的应用：

1
apps: [
2
  {
3
    name: "ChatGPT",
4
    description: "AI 对话助手，支持多模态交互",
5
    url: "https://chat.openai.com",
6
    image: "https://cdn.oaistatic.com/images/favicon-o.svg",
7
    external: true,
8
  },
9
  {
10
    name: "Claude",
11
    description: "Anthropic 出品的 AI 助手",
12
    url: "https://claude.ai",
13
    image: "https://claude.ai/images/branding/claude-logo.svg",
14
    external: true,
15
  },
16
  {
17
    name: "我的工具站",
18
    description: "自研在线工具集合",
19
    url: "/tools/",
20
    image: "/assets/images/tools-icon.webp",
21
    external: false,
22
  },
23
],

字段说明

步骤 2：页面开关

在 siteConfig.ts 中控制页面是否启用：

1
pages: {
2
  // ...其他配置
3
  apps: true,  // true=显示，false=隐藏
4
},

关闭后：

• 访问 /apps/ 返回 404
• 导航栏不再显示”应用”入口
• 不出现在 sitemap 中

步骤 3：导航栏位置

默认在”关于”子菜单中。如需修改位置，编辑 src/config/navBarConfig.ts：

1
// 默认位置：关于 → 应用
2
links.push({
3
  name: "关于",
4
  url: "/about/",
5
  children: [
6
    LinkPreset.About,
7
    ...(siteConfig.pages.friends ? [LinkPreset.Friends] : []),
8
    ...(siteConfig.pages.sponsor ? [LinkPreset.Sponsor] : []),
9
    ...(siteConfig.pages.apps ? [{
10
      name: "应用",
11
      url: "/apps/",
12
      icon: "material-symbols:apps",
13
    }] : []),
14
  ],
15
});
16

17
// 如果想放在"动态"子菜单下，将上面的代码移到"动态"的 children 中即可

五、配置速查表

astro.config.mjs 完整改动

1
// ===== 新增导入 =====
2
import rehypeImageAttrs from "./src/plugins/rehype-image-attrs.mjs";
3
import rehypeImageFallback from "./src/plugins/rehype-image-fallback.mjs";
4

5
// ===== rehypePlugins 数组末尾添加 =====
6
rehypeImageAttrs,
7
[
8
  rehypeImageFallback,
9
  {
10
    enable: false,           // 改为 true 启用双 CDN 回退
11
    originalDomain: "",       // 填写主力图床域名
12
    fallbackDomain: "",       // 填写备用图床域名
13
  },
14
],
15

16
// ===== sitemap filter 中添加 =====
17
if (pathname === "/apps/" && !siteConfig.pages.apps) {
18
  return false;
19
}

siteConfig.ts 完整改动

1
// ===== pages 对象中添加 =====
2
pages: {
3
  // ...已有配置
4
  apps: true,  // 应用中心页面开关
5
},
6

7
// ===== 对象末尾添加（在 lang 之后） =====
8
apps: [
9
  {
10
    name: "应用名称",
11
    description: "应用描述",
12
    url: "https://example.com",
13
    image: "https://example.com/icon.png",
14
    external: true,
15
  },
16
],

六、常见问题

Q: 双 CDN 回退不生效？

1. 确认 enable 已设为 true
2. 确认 originalDomain 和 faviconDomain 填写正确
3. 回退仅对 Markdown 内容中的 <img> 标签生效，不适用于 Astro <Image> 组件

Q: IndexNow 提交失败？

1. 确认 GitHub Secrets 中已配置 INDEXNOW_KEY
2. 确认网站根目录有 {key}.txt 文件且内容正确
3. 检查 src/pages/api/indexnow.ts 中的站点 URL 是否正确
4. IndexNow 支持的搜索引擎：Bing、Yandex、Naver、Seznam 等（不包括 Google）

Q: 应用页面图片显示异常？

1. 网络图片需确保 URL 可访问
2. 本地图片放在 public/ 目录下，以 / 开头引用
3. 图片建议使用正方形（1:1 比例）以获得最佳显示效果

Q: 文章置顶不生效？

1. 确认 frontmatter 中 pinned: true（注意是布尔值，不是字符串 "true"）
2. 确认文章未设置 draft: true（草稿不会显示在列表中）

七、版本信息

• 集成日期：2026-06-05
• 参考项目：Examplefuwari (Astro 5.x)
• 适配版本：FireflyBlog 6.10.5 (Astro 6.3.5)
• 构建验证：通过 ✅