早安喵栈

在 Astro Firefly 主题中集成专属 AI 智能助手：从 API 配置到 UI 落地全记录

Sat, 31 Oct 2026 00:00:00 GMT

在搭建独立博客的过程中，为访客提供一个轻量、实时且懂你网站的 AI 助手一直是许多独立开发者的心愿。今天这篇文章，就带大家把一个非intrusive（不唐突）、支持上下文问答与文章摘要的 AI 聊天小组件，完美集成到基于 Astro 的 Firefly 主题中。

技术栈选型#

前端框架：Astro (SSR 动态渲染模式)
部署托管：Vercel Serverless Functions
AI 引擎：Groq API (选用高性价比且高效的 openai/gpt-oss-20b 模型)
UI 交互：原生 Tailwind CSS + 浮动卡片交互，完美兼容 Swup 无刷新跳转

后端 API 接口实现 (`src/pages/api/ai.ts`)#

为了保证安全性，我们不能把 API Key 暴露在前端。因此，我们需要在 Astro 中创建一个后端的 Serverless 接口。

这里我们不仅实现了基础的聊天问答，还加入了针对长文章的 AI 摘要功能，以及一套全能文本清洗逻辑——用来彻底过滤掉大模型偶尔“抽风”吐出的 Markdown 表格管道符（|）和多余符号，确保在纯文本聊天框中排版清爽。

在项目的 src/pages/api/ 目录下创建 ai.ts 文件：

1
import type { APIRoute } from 'astro';
2

3
export const prerender = false;
4

5
// 🧹 全能文本清洗函数：确保在纯文本气泡中格式清爽、多余 Markdown 符号彻底被清除
6
function cleanAiResponse(text: string): string {
7
  if (!text) return "";
8

9
  let cleaned = text;
10

11
  // 1. 转换表格管道符为竖向列表
12
  if (cleaned.includes('|')) {
13
    const lines = cleaned.split('\n');
14
    const formattedLines: string[] = [];
15
    for (const line of lines) {
16
      if (line.replace(/[\s|:\-]+/g, '') === '') continue;
17
      if (line.includes('|')) {
18
        const parts = line.split('|').map(p => p.trim()).filter(Boolean);
19
        if (parts.length > 0) {
20
          formattedLines.push(`• ${parts.join('：')}`);
21
        }
22
      } else {
23
        formattedLines.push(line);
24
      }
25
    }
26
    cleaned = formattedLines.join('\n');
27
  }
28

29
  // 2. 清除裸露的反引号和粗体符号
30
  cleaned = cleaned.replace(/`/g, '');
31
  cleaned = cleaned.replace(/\*\*/g, '');
32

33
  // 3. 确保列表项前自带换行，防止粘连
34
  cleaned = cleaned.replace(/([^\n])\s*[-•]\s*/g, '$1\n• ');
35
  cleaned = cleaned.replace(/([^\n])\s*(\d+\.)\s*/g, '$1\n$2 ');
36

37
  return cleaned.trim();
38
}
39

40
export const POST: APIRoute = async ({ request }) => {
41
  try {
42
    const apiKey = import.meta.env.GROQ_API_KEY || process.env.GROQ_API_KEY;
43

44
    if (!apiKey) {
45
      return new Response(
46
        JSON.stringify({ result: "服务器未配置 API Key，请检查 Vercel 环境变量设置。" }),
47
        { status: 200, headers: { 'Content-Type': 'application/json' } }
48
      );
49
    }
50

51
    const body = await request.json();
52
    const { action, prompt, text } = body;
53

54
    let systemPrompt = "";
55
    let userContent = "";
56

57
    if (action === 'summary') {
58
      systemPrompt = "你是一个专业的博客文章摘要助手。请为以下文章生成一段结构清晰、内容充实的摘要，字数控制在 150~200 字左右，包含文章的核心观点和主要干货，语言亲切自然，不要使用表格。";
59
      userContent = (text || "").slice(0, 3000);
60
    } else {
61
      systemPrompt = `你是「喵栈 AI」小助手，专为独立博客「早安喵栈 (929255.xyz)」服务。
62
【核心规则】：
63
1. 语言亲切可爱，控制在 100 字以内。
64
2. 遇到列表或多项说明时，每条内容必须换行输出（使用 - 或 • 开头）。
65
3. 严禁使用表格，严禁输出反引号或粗体符号。
66

67
【本站背景与精准指引】：
68
- 站点核心技术：Astro 静态博客框架、Tailwind CSS 自定义样式、Vercel 自动化部署、GitHub 托管、Cloudflare CDN 加速、Markdown/MDX 写作。
69
- 若询问“有哪些文章推荐”：请推荐本站关于 Astro 博客配置、Vercel 部署实践、Docker/Gatus 自建服务和独立博客搭建的探索记录。
70
- 若询问“怎么搭建类似博客”：简要列出使用 Astro、Tailwind CSS、Vercel 与 GitHub 部署的步骤。`;
71

72
      userContent = prompt || "你好";
73
    }
74

75
    // 封装带自动重试的 Groq 请求函数（应对 429 或 500 抖动）
76
    async function fetchWithRetry(retries = 2, delay = 1000): Promise<any> {
77
      try {
78
        const response = await fetch('https://api.groq.com/openai/v1/chat/completions', {
79
          method: 'POST',
80
          headers: {
81
            'Authorization': `Bearer ${apiKey}`,
82
            'Content-Type': 'application/json'
83
          },
84
          body: JSON.stringify({
85
            model: 'openai/gpt-oss-20b',
86
            messages: [
87
              { role: 'system', content: systemPrompt },
88
              { role: 'user', content: userContent }
89
            ],
90
            temperature: 0.2,
91
            max_tokens: 800
92
          })
93
        });
94

95
        if (!response.ok) {
96
          const errText = await response.text();
97
          if ((response.status === 429 || response.status >= 500) && retries > 0) {
98
            await new Promise(resolve => setTimeout(resolve, delay));
99
            return fetchWithRetry(retries - 1, delay * 2);
100
          }
101
          throw new Error(`Groq 状态码 ${response.status}: ${errText}`);
102
        }
103

104
        return await response.json();
105
      } catch (error) {
106
        if (retries > 0) {
107
          await new Promise(resolve => setTimeout(resolve, delay));
108
          return fetchWithRetry(retries - 1, delay * 2);
109
        }
110
        throw error;
111
      }
112
    }
113

114
    const data = await fetchWithRetry();
115
    const rawResult = data.choices?.[0]?.message?.content || "";
116

117
    const aiResult = cleanAiResponse(rawResult);
118

119
    if (!aiResult.trim()) {
120
      return new Response(
121
        JSON.stringify({ result: "喵~ AI 刚才走神了，请再点一次发送试试！" }),
122
        { status: 200, headers: { 'Content-Type': 'application/json' } }
123
      );
124
    }
125

126
    return new Response(
127
      JSON.stringify({ result: aiResult }),
128
      { status: 200, headers: { 'Content-Type': 'application/json' } }
129
    );
130

131
  } catch (error: any) {
132
    console.error("❌ AI API 内部错误:", error);
133
    return new Response(
134
      JSON.stringify({ result: "网络开小差啦，请稍后再提问~" }),
135
      { status: 200, headers: { 'Content-Type': 'application/json' } }
136
    );
137
  }
138
};

展开收起

前端悬浮挂件与 UI 落地 (`Layout.astro` 或根布局)#

为了让所有页面都能在左下角展示这个可爱的 AI 悬浮球，我们在全局布局文件（例如 Firefly 主题的根 Layout 中）加入了挂件的 HTML 结构与交互脚本。

1. HTML 与样式组件#

在布局文件的底部（</body> 之前）加入悬浮窗 DOM：

1
<!-- 🤖 全站固定悬浮“喵栈 AI”小助手（固定左下角） -->
2
<div id="ai-widget" class="fixed bottom-6 left-6 z-50">
3
  <!-- 聊天对话框（默认隐藏） -->
4
  <div id="ai-box" class="hidden w-[360px] h-[460px] mb-4 rounded-2xl border border-black/10 dark:border-white/10 card-base shadow-2xl flex flex-col overflow-hidden text-neutral-800 dark:text-neutral-200">
5
    <!-- 头部 -->
6
    <div class="px-4 py-3 border-b border-black/10 dark:border-white/10 flex justify-between items-center bg-black/5 dark:bg-white/5">
7
      <div class="flex items-center gap-2.5">
8
        <div class="w-7 h-7 rounded-lg bg-teal-500/20 border border-teal-500/30 flex items-center justify-center text-teal-600 dark:text-teal-400 text-sm">🐱</div>
9
        <span class="font-semibold text-sm text-neutral-900 dark:text-white">喵栈 AI</span>
10
        <span class="text-[10px] px-2 py-0.5 rounded-full bg-emerald-500/10 text-emerald-600 dark:text-emerald-400 border border-emerald-500/20 font-medium">在线</span>
11
      </div>
12
      <div class="flex items-center gap-3 text-neutral-500 dark:text-neutral-400 text-xs">
13
        <button id="ai-clear" class="hover:text-black dark:hover:text-white transition-colors" title="清空对话">🗑️</button>
14
        <button id="ai-close" class="hover:text-black dark:hover:text-white text-base leading-none transition-colors">✕</button>
15
      </div>
16
    </div>
17

18
    <!-- 消息展示区（关键点：加入 whitespace-pre-wrap 确保换行生效） -->
19
    <div id="ai-messages" class="flex-1 p-4 overflow-y-auto space-y-3.5 text-xs leading-relaxed">
20
      <div class="flex gap-2">
21
        <div class="w-6 h-6 rounded-md bg-teal-500/20 text-teal-600 dark:text-teal-400 flex items-center justify-center text-xs shrink-0">🐱</div>
22
        <div class="space-y-3">
23
          <div class="bg-black/5 dark:bg-white/5 border border-black/5 dark:border-white/5 p-3 rounded-2xl rounded-tl-none max-w-[90%] text-neutral-800 dark:text-neutral-200 whitespace-pre-wrap">
24
            喵~ 我是「喵栈 AI」小助手，专门为早安喵栈 (929255.xyz) 服务。有什么想问的吗？
25
          </div>
26
          <!-- 快捷提问按钮 -->
27
          <div class="flex flex-wrap gap-2 pt-1" id="ai-quick-prompts">
28
            <button class="quick-btn px-3 py-1.5 rounded-full bg-black/5 hover:bg-black/10 dark:bg-white/5 dark:hover:bg-white/10 border border-black/10 dark:border-white/10 text-neutral-700 dark:text-neutral-300 text-[11px] transition-all hover:scale-[1.02] active:scale-95">
29
              这个博客用了什么技术？
30
            </button>
31
            <button class="quick-btn px-3 py-1.5 rounded-full bg-black/5 hover:bg-black/10 dark:bg-white/5 dark:hover:bg-white/10 border border-black/10 dark:border-white/10 text-neutral-700 dark:text-neutral-300 text-[11px] transition-all hover:scale-[1.02] active:scale-95">
32
              有哪些文章推荐？
33
            </button>
34
            <button class="quick-btn px-3 py-1.5 rounded-full bg-black/5 hover:bg-black/10 dark:bg-white/5 dark:hover:bg-white/10 border border-black/10 dark:border-white/10 text-neutral-700 dark:text-neutral-300 text-[11px] transition-all hover:scale-[1.02] active:scale-95">
35
              怎么搭建类似的博客？
36
            </button>
37
          </div>
38
        </div>
39
      </div>
40
    </div>
41

42
    <!-- 底部输入框 -->
43
    <div class="p-3 border-t border-black/10 dark:border-white/10 bg-black/5 dark:bg-white/5 flex gap-2 items-center">
44
      <input id="ai-input" type="text" placeholder="向喵栈 AI 提问..." class="flex-1 bg-black/5 dark:bg-white/5 border border-black/10 dark:border-white/10 rounded-xl px-3.5 py-2 text-neutral-900 dark:text-white placeholder-neutral-400 dark:placeholder-neutral-500 outline-none focus:border-black/30 dark:focus:border-white/30 text-xs transition-colors" />
45
      <button id="ai-send" class="bg-black/10 hover:bg-black/20 dark:bg-white/15 dark:hover:bg-white/25 text-neutral-900 dark:text-white px-3.5 py-2 rounded-xl text-xs font-medium transition-all active:scale-95">发送</button>
46
    </div>
47
  </div>
48

49
  <!-- 悬浮触发圆球 -->
50
  <button id="ai-toggle" class="w-12 h-12 rounded-full card-base border border-black/10 dark:border-white/10 shadow-2xl flex items-center justify-center text-xl hover:scale-110 active:scale-95 transition-transform">
51
    🐱
52
  </button>
53
</div>

展开收起

2. 交互与无刷新挂载脚本 (`<script>`)#

由于 Astro 主题通常支持 Swup 无刷新路由切换，我们需要确保每次页面跳转后脚本都能正确初始化：

1
<script is:inline>
2
  function initGlobalAIFeatures() {
3
    const toggleBtn = document.getElementById('ai-toggle');
4
    const closeBtn = document.getElementById('ai-close');
5
    const clearBtn = document.getElementById('ai-clear');
6
    const box = document.getElementById('ai-box');
7
    const sendBtn = document.getElementById('ai-send');
8
    const input = document.getElementById('ai-input');
9
    const msgContainer = document.getElementById('ai-messages');
10

11
    if (toggleBtn && !toggleBtn.dataset.inited) {
12
      toggleBtn.dataset.inited = 'true';
13

14
      toggleBtn.addEventListener('click', () => {
15
        box.classList.toggle('hidden');
16
      });
17

18
      closeBtn?.addEventListener('click', () => box.classList.add('hidden'));
19

20
      clearBtn?.addEventListener('click', () => {
21
        msgContainer.innerHTML = `
22
          <div class="flex gap-2">
23
            <div class="w-6 h-6 rounded-md bg-teal-500/20 text-teal-600 dark:text-teal-400 flex items-center justify-center text-xs shrink-0">🐱</div>
24
            <div class="space-y-3">
25
              <div class="bg-black/5 dark:bg-white/5 border border-black/5 dark:border-white/5 p-3 rounded-2xl rounded-tl-none max-w-[90%] text-neutral-800 dark:text-neutral-200 whitespace-pre-wrap">
26
                对话已清空，我是「喵栈 AI」，随时准备为你解答！
27
              </div>
28
            </div>
29
          </div>`;
30
      });
31

32
      async function handleSend(textToSend) {
33
        const text = textToSend || input.value.trim();
34
        if (!text) return;
35

36
        msgContainer.innerHTML += `
37
          <div class="flex justify-end">
38
            <div class="bg-teal-600/20 border border-teal-500/30 text-teal-900 dark:text-teal-100 p-2.5 px-3.5 rounded-2xl rounded-tr-none max-w-[85%] text-xs">
39
              ${text}
40
            </div>
41
          </div>`;
42

43
        if (!textToSend) input.value = '';
44
        msgContainer.scrollTop = msgContainer.scrollHeight;
45

46
        const loadingId = 'loading-' + Date.now();
47
        msgContainer.innerHTML += `
48
          <div id="${loadingId}" class="flex gap-2">
49
            <div class="w-6 h-6 rounded-md bg-teal-500/20 text-teal-600 dark:text-teal-400 flex items-center justify-center text-xs shrink-0">🐱</div>
50
            <div class="bg-black/5 dark:bg-white/5 border border-black/5 dark:border-white/5 p-2.5 px-3.5 rounded-2xl rounded-tl-none max-w-[85%] text-neutral-500 dark:text-neutral-400 animate-pulse text-xs">
51
              正在思考...
52
            </div>
53
          </div>`;
54
        msgContainer.scrollTop = msgContainer.scrollHeight;
55

56
        try {
57
          const res = await fetch('/api/ai/', {
58
            method: 'POST',
59
            headers: { 'Content-Type': 'application/json' },
60
            body: JSON.stringify({ action: 'chat', prompt: text })
61
          });
62
          const data = await res.json();
63
          const targetEl = document.getElementById(loadingId);
64
          if (targetEl) {
65
            // 💡 注意：必须加上 whitespace-pre-wrap 类名，否则换行符会被浏览器忽略
66
            targetEl.outerHTML = `
67
              <div class="flex gap-2">
68
                <div class="w-6 h-6 rounded-md bg-teal-500/20 text-teal-600 dark:text-teal-400 flex items-center justify-center text-xs shrink-0">🐱</div>
69
                <div class="bg-black/5 dark:bg-white/5 border border-black/5 dark:border-white/5 p-3 rounded-2xl rounded-tl-none max-w-[85%] text-neutral-800 dark:text-neutral-200 text-xs whitespace-pre-wrap">
70
                  ${data.result || data.error || '出错了，请稍后重试。'}
71
                </div>
72
              </div>`;
73
          }
74
        } catch (err) {
75
          const targetEl = document.getElementById(loadingId);
76
          if (targetEl) {
77
            targetEl.outerHTML = `
78
              <div class="flex gap-2">
79
                <div class="w-6 h-6 rounded-md bg-teal-500/20 text-teal-600 dark:text-teal-400 flex items-center justify-center text-xs shrink-0">🐱</div>
80
                <div class="bg-red-500/10 border border-red-500/20 text-red-600 dark:text-red-300 p-2.5 px-3.5 rounded-2xl rounded-tl-none text-xs">
81
                  网络连接失败，请稍后重试。
82
                </div>
83
              </div>`;
84
          }
85
        }
86
        msgContainer.scrollTop = msgContainer.scrollHeight;
87
      }
88

89
      sendBtn?.addEventListener('click', () => handleSend());
90
      input?.addEventListener('keydown', (e) => e.key === 'Enter' && handleSend());
91

92
      msgContainer.addEventListener('click', (e) => {
93
        const target = e.target;
94
        if (target && target.classList.contains('quick-btn')) {
95
          handleSend(target.innerText.trim());
96
        }
97
      });
98
    }
99
  }
100

101
  document.addEventListener('DOMContentLoaded', initGlobalAIFeatures);
102
  document.addEventListener('swup:pageView', initGlobalAIFeatures);
103
  document.addEventListener('astro:page-load', initGlobalAIFeatures);
104
</script>

展开收起

避坑指南与核心优化总结#

在开发和调试这个小组件时，我们踩过并解决了以下几个非常关键的痛点：

解决纯文本聊天框“排版乱七八糟”的问题：大模型经常喜欢输出 Markdown 表格（带有 | 管道符）或长段落。我们在后端编写了 cleanAiResponse 清洗函数，强行将表格转换为漂亮的带点列表（•），并移除了所有反引号和粗体符号。同时在前端容器上设置了 CSS whitespace-pre-wrap，完美解决了换行符失效、文本挤成一团的痛点。
防止回答“答非所问”或泛泛而谈：通过在后端 System Prompt 中加入强力的站点背景锚点（明确告知其专属早安喵栈 929255.xyz 的技术栈），AI 现在能够精准、可爱地回答关于本博客的架构、搭建指南和文章推荐。
环境变量与 Vercel 部署：确保在 Vercel 项目后台正确配置了 GROQ_API_KEY 环境变量，并将 Astro 接口设置为 export const prerender = false;（SSR 动态路由模式），接口即可稳定运行。

希望这篇分享能给同样使用 Astro 搭建独立博客的小伙伴们带来一些灵感！快去给你的小站也装上一个专属 AI 助手吧~ 🐱✨

给 Astro 博客的 CategoryBar 组件添加“特定页面显示”及 Swup 无刷新跳转适配指南

Wed, 21 Oct 2026 00:00:00 GMT

在基于 Astro（配合 Swup 客户端无刷新跳转）的博客主题中，我们经常会遇到需要对某些特定组件（如分类栏 CategoryBar）进行路由控制的需求。

在实际开发中，我们往往不希望分类栏在全站所有页面无条件显示（例如在关于页、友链页等独立页面中显得多余），而是希望它只在特定页面显示。例如：

首页（/）
归档页（/archive/）
分类汇总页（/categories/）
标签页与系列页（/tags/、/series/）
所有文章详情页（例如以 /posts/ 开头的所有路径：/posts/hello-world/、/posts/astro-tutorial/ 等）

本文将记录如何实现这一需求，并解决在无刷新跳转（Swup）环境下的状态同步与显隐控制问题。

核心痛点分析#

在实现“特定页面显示”时，会遇到两个典型问题：

直接服务端 return null 导致 Swup 状态失效：如果用传统的服务端判断，当处于非白名单页面时直接让组件不渲染，那么当用户通过 Swup 局部无刷新跳转到白名单页面时，由于 DOM 树中根本不存在该组件，导致分类栏无法显示，必须手动刷新网页。
动态路由匹配（如文章详情页 /posts/*）：静态白名单无法枚举所有的文章路径，因此需要引入前缀匹配逻辑（startsWith）。

最终解决方案：CSS 显隐控制 + Swup 动态响应#

为了兼顾 SSR（服务端首屏渲染性能） 与 Swup 客户端无刷新跳转，最佳策略是：

让组件正常渲染到 DOM 中，但在最外层套一个包装容器。
初始根据白名单（支持固定路径与动态前缀匹配）决定是否直接设置 display: none。
配合客户端脚本，在 Swup 页面切换（swup:contentReplaced / astro:page-load）时，实时检查当前新 URL 并动态控制容器显隐。

完整组件代码 (`CategoryBar.astro`)#

以下是完整实现，已内置具体的白名单路径（如 /tags、/series）以及动态文章详情页（/posts/*）的匹配逻辑：

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

8
interface Props {
9
  currentPostCategory?: string;
10
}
11

12
const { currentPostCategory } = Astro.props as Props;
13

14
const categories = await getCategoryList();
15
const totalPosts = (await getSortedPostsList()).length;
16
const homeUrl = url("/");
17
const archiveUrl = url("/archive/");
18

19
const pathname = Astro.url.pathname.replace(/\/$/, "");
20
const homePath = homeUrl.replace(/\/$/, "");
21
const archivePath = archiveUrl.replace(/\/$/, "");
22
const isHome = pathname === homePath || pathname === "" || pathname === "/";
23
const isCategories = pathname === "/categories";
24
const isArchive = pathname === archivePath;
25
const postCategory = (currentPostCategory || "").trim();
26

27
function initialActive(categoryName: string): {
28
  active?: boolean;
29
  soft?: boolean;
30
} {
31
  if (isHome) return categoryName === "" ? { active: true } : {};
32
  if (isCategories)
33
    return categoryName === "__categories__" ? { active: true } : {};
34
  if (isArchive) return categoryName === "__archive__" ? { active: true } : {};
35
  if (postCategory && categoryName === postCategory) return { soft: true };
36
  return {};
37
}
38

39
// ==================== 具体白名单与路由匹配配置 ====================
40
// 在这里列出你需要显示分类栏的具体路径
41
const allowedPaths = [
42
  homePath,      // 首页
43
  archivePath,   // 归档页
44
  "/categories", // 分类汇总页
45
  "/tags",       // 标签页
46
  "/series",     // 系列页
47
  "",
48
  "/"
49
];
50

51
// 判断当前路径是否在白名单中，或者是否以 /posts/ 开头（匹配所有文章详情页）
52
const isAllowed = allowedPaths.includes(pathname) || pathname.startsWith("/posts/");
53
---
54

55
<!-- 外层包裹容器：用动态 style 初始控制显隐，避免 SSR 闪烁 -->
56
<div
57
  id="category-bar-wrapper"
58
  style={isAllowed ? "" : "display: none;"}
59
  data-home-path={homeUrl}
60
  data-archive-path={archiveUrl}
61
>
62
  <div
63
    class="card-base category-bar p-3 onload-animation"
64
    id="category-bar"
65
    data-home-path={homeUrl}
66
    data-archive-path={archiveUrl}
67
    data-current-post-category={currentPostCategory || ""}
68
  >
69
    <div class="category-bar-inner flex gap-2">
70
      <a
71
        href={homeUrl}
72
        class="category-pill focus-ring-inset text-sm px-3 py-1.5 shrink-0
73
               transition-colors duration-150 ease-out flex items-center justify-center"
74
        data-category-name=""
75
        data-active={initialActive("").active ? "" : undefined}
76
        aria-label={i18n(I18nKey.home)}
77
      >
78
        <Icon class="text-lg" name="material-symbols:home"/>
79
      </a>
80
      <a
81
        href={archiveUrl}
82
        class="category-pill focus-ring-inset text-sm px-4 py-1.5 whitespace-nowrap shrink-0
83
               transition-colors duration-150 ease-out flex items-center justify-center"
84
        data-category-name="__archive__"
85
        data-active={initialActive("__archive__").active ? "" : undefined}
86
      >
87
        {i18n(I18nKey.archive)}
88
        <span class="pill-count">{totalPosts}</span>
89
      </a>
90
      <div class="category-divider shrink-0"></div>
91
      <div class="scroll-area relative">
92
        <div class="scroll-fade scroll-fade-left" aria-hidden="true"></div>
93
        <div class="category-scroll flex gap-2 overflow-x-auto">
94
          {
95
            categories.map((cat) => {
96
              const active = initialActive(cat.name);
97
              return (
98
              <a
99
                href={cat.url}
100
                class="category-pill focus-ring-inset text-sm px-4 py-1.5 whitespace-nowrap
101
                       transition-colors duration-150 ease-out flex items-center justify-center"
102
                data-category-name={cat.name}
103
                data-active={active.active ? "" : undefined}
104
                data-soft-active={active.soft ? "" : undefined}
105
              >
106
                {cat.name}
107
                <span class="pill-count">{cat.count}</span>
108
              </a>
109
              );
110
            })
111
          }
112
        </div>
113
        <div class="scroll-fade scroll-fade-right" aria-hidden="true"></div>
114
      </div>
115
      <div class="category-divider shrink-0 more-divider" aria-hidden="true"></div>
116
      <a
117
        href={url("/categories/")}
118
        class="category-pill focus-ring-inset text-sm px-3 py-1.5 shrink-0
119
               transition-colors duration-150 ease-out flex items-center justify-center gap-1"
120
        data-category-name="__categories__"
121
        data-active={initialActive("__categories__").active ? "" : undefined}
122
        aria-label={i18n(I18nKey.more)}
123
      >
124
        <span>{i18n(I18nKey.more)}</span>
125
        <Icon class="text-sm" name="fa7-solid:chevron-right"/>
126
      </a>
127
    </div>
128
  </div>
129
</div>
130

131
<style>
132
  .category-bar .category-pill {
133
    border: none;
134
  }
135
  .category-bar {
136
    margin-bottom: 1rem;
137
  }
138
  .category-divider {
139
    width: 1px;
140
    align-self: stretch;
141
    background: var(--line-divider);
142
    opacity: 0.5;
143
  }
144
  .more-divider {
145
    opacity: 0;
146
    transition: opacity 300ms ease-in-out;
147
  }
148
  .more-divider[data-visible] {
149
    opacity: 0.5;
150
  }
151
  .scroll-area {
152
    flex: 1;
153
    min-width: 0;
154
    position: relative;
155
  }
156
  .scroll-fade {
157
    position: absolute;
158
    top: 0;
159
    bottom: 0;
160
    width: 2.5rem;
161
    pointer-events: none;
162
    opacity: 0;
163
    transition: opacity 300ms ease-in-out;
164
    z-index: 1;
165
  }
166
  .scroll-fade[data-visible] {
167
    opacity: 1;
168
  }
169
  .scroll-fade-left {
170
    left: 0;
171
    background: linear-gradient(to left, transparent, var(--card-bg));
172
  }
173
  .scroll-fade-right {
174
    right: 0;
175
    background: linear-gradient(to right, transparent, var(--card-bg));
176
  }
177
  :global(body.wallpaper-transparent) .scroll-fade {
178
    display: none;
179
  }
180
  .category-scroll {
181
    scrollbar-width: none;
182
    -ms-overflow-style: none;
183
  }
184
  .category-scroll::-webkit-scrollbar {
185
    display: none;
186
  }
187
</style>
188

189
<script>
190
  let delayedCategoryBarScrollTimer: number | undefined;
191

192
  // 检查当前 URL 是否在白名单中，并动态控制显隐
193
  function checkRouteVisibility() {
194
    const wrapper = document.getElementById("category-bar-wrapper");
195
    if (!wrapper) return;
196

197
    const pathname = window.location.pathname.replace(/\/$/, "");
198
    const homePath = (wrapper.getAttribute("data-home-path") || "/").replace(/\/$/, "");
199
    const archivePath = (wrapper.getAttribute("data-archive-path") || "/archive").replace(/\/$/, "");
200

201
    // 客户端同步白名单路径
202
    const allowedPaths = [homePath, archivePath, "/categories", "/tags", "/series", "", "/"];
203
    const isAllowed = allowedPaths.includes(pathname) || pathname.startsWith("/posts/");
204

205
    if (isAllowed) {
206
      wrapper.style.display = "";
207
    } else {
208
      wrapper.style.display = "none";
209
    }
210
  }
211

212
  function getCategoryBarState(bar: HTMLElement, currentUrl: URL) {
213
    const pathname = currentUrl.pathname.replace(/\/$/, "");
214
    const homePath = (bar.getAttribute("data-home-path") || "/").replace(/\/$/, "");
215
    const archivePath = (bar.getAttribute("data-archive-path") || "/archive").replace(/\/$/, "");
216
    const isHome = pathname === homePath || pathname === "" || pathname === "/";
217
    const isArchive = pathname === archivePath;
218
    const isCategories = pathname === "/categories";
219

220
    return {
221
      isHome,
222
      isArchive,
223
      isCategories,
224
      activeCategory: currentUrl.searchParams.get("category") || "",
225
      hasTag: currentUrl.searchParams.has("tag"),
226
      hasUncategorized: currentUrl.searchParams.has("uncategorized"),
227
    };
228
  }
229

230
  function setActiveCategory(bar: HTMLElement, currentUrl: URL) {
231
    const { isHome, isArchive, isCategories, activeCategory, hasTag, hasUncategorized } =
232
      getCategoryBarState(bar, currentUrl);
233
    const postCategory = (bar.getAttribute("data-current-post-category") || "").trim();
234

235
    const pills = bar.querySelectorAll<HTMLAnchorElement>(".category-pill");
236
    pills.forEach((pill) => {
237
      pill.removeAttribute("data-active");
238
      pill.removeAttribute("data-soft-active");
239
    });
240

241
    if (isHome) {
242
      bar.querySelector<HTMLAnchorElement>('.category-pill[data-category-name=""]')
243
        ?.setAttribute("data-active", "");
244
      return;
245
    }
246

247
    if (isCategories) {
248
      bar.querySelector<HTMLAnchorElement>('.category-pill[data-category-name="__categories__"]')
249
        ?.setAttribute("data-active", "");
250
      return;
251
    }
252

253
    if (activeCategory) {
254
      pills.forEach((pill) => {
255
        if (pill.getAttribute("data-category-name") === activeCategory) {
256
          pill.setAttribute("data-active", "");
257
        }
258
      });
259
      return;
260
    }
261

262
    if (isArchive && !hasTag && !hasUncategorized) {
263
      bar.querySelector<HTMLAnchorElement>('.category-pill[data-category-name="__archive__"]')
264
        ?.setAttribute("data-active", "");
265
      return;
266
    }
267

268
    if (postCategory) {
269
      pills.forEach((pill) => {
270
        if (pill.getAttribute("data-category-name") === postCategory) {
271
          pill.setAttribute("data-soft-active", "");
272
        }
273
      });
274
    }
275
  }
276

277
  function scrollActiveCategoryIntoView(bar: HTMLElement, behavior: ScrollBehavior = "smooth") {
278
    const activePill =
279
      bar.querySelector<HTMLAnchorElement>('.category-pill[data-active]') ||
280
      bar.querySelector<HTMLAnchorElement>('.category-pill[data-soft-active]');
281
    const scroll = bar.querySelector<HTMLElement>(".category-scroll");
282
    if (!activePill || !scroll) return;
283

284
    const scrollLeft = activePill.offsetLeft - scroll.offsetLeft - (scroll.clientWidth - activePill.offsetWidth) / 2;
285
    scroll.scrollTo({ left: Math.max(0, scrollLeft), behavior });
286
  }
287

288
  function shouldDeferCategoryScroll(bar: HTMLElement, currentUrl: URL) {
289
    const { isHome } = getCategoryBarState(bar, currentUrl);
290
    const isMobile = window.innerWidth < 1024;
291
    const isBannerMode =
292
      document.documentElement.getAttribute("data-wallpaper-mode") === "banner";
293
    return isMobile && isBannerMode && !isHome;
294
  }
295

296
  function updateCategoryBar(
297
    currentUrl = new URL(window.location.href),
298
    options: { scrollBehavior?: ScrollBehavior; deferScroll?: boolean } = {},
299
  ) {
300
    checkRouteVisibility(); // 每次更新时同步显隐状态
301

302
    const bar = document.getElementById("category-bar");
303
    if (!bar) return;
304

305
    const swupContainer = document.getElementById("swup-container");
306
    if (swupContainer) {
307
      const currentPostCategory = swupContainer.getAttribute("data-current-post-category") || "";
308
      bar.setAttribute("data-current-post-category", currentPostCategory);
309
    }
310

311
    setActiveCategory(bar, currentUrl);
312

313
    const deferScroll = options.deferScroll ?? shouldDeferCategoryScroll(bar, currentUrl);
314
    const scrollBehavior = options.scrollBehavior ?? (deferScroll ? "auto" : "smooth");
315

316
    if (delayedCategoryBarScrollTimer) {
317
      window.clearTimeout(delayedCategoryBarScrollTimer);
318
      delayedCategoryBarScrollTimer = undefined;
319
    }
320

321
    if (deferScroll) {
322
      delayedCategoryBarScrollTimer = window.setTimeout(() => {
323
        requestAnimationFrame(() => {
324
          requestAnimationFrame(() => {
325
            scrollActiveCategoryIntoView(bar, scrollBehavior);
326
            updateScrollHint();
327
          });
328
        });
329
      }, 220);
330
      return;
331
    }
332

333
    scrollActiveCategoryIntoView(bar, scrollBehavior);
334
    updateScrollHint();
335
  }
336

337
  function initCategoryBarInteractions() {
338
    const bar = document.getElementById("category-bar");
339
    if (!bar || bar.dataset.clickBound === "true") return;
340

341
    bar.dataset.clickBound = "true";
342
    bar.addEventListener("click", (event) => {
343
      if (!(event.target instanceof Element)) return;
344

345
      const pill = event.target.closest<HTMLAnchorElement>(".category-pill");
346
      if (!pill) return;
347

348
      if (
349
        event.defaultPrevented ||
350
        event.button !== 0 ||
351
        event.metaKey ||
352
        event.ctrlKey ||
353
        event.shiftKey ||
354
        event.altKey
355
      ) {
356
        return;
357
      }
358

359
      if (pill.target && pill.target !== "_self") return;
360

361
      const targetUrl = new URL(pill.href, window.location.href);
362
      if (targetUrl.origin !== window.location.origin) return;
363

364
      setActiveCategory(bar, targetUrl);
365
      scrollActiveCategoryIntoView(bar, "auto");
366
    });
367
  }
368

369
  function initScrollFeatures() {
370
    const bar = document.getElementById("category-bar");
371
    if (!bar) return;
372

373
    const scroll = bar.querySelector<HTMLElement>(".category-scroll");
374
    if (!scroll) return;
375

376
    if (scroll.dataset.featuresBound === "true") {
377
      updateScrollHint();
378
      return;
379
    }
380
    scroll.dataset.featuresBound = "true";
381

382
    scroll.addEventListener("wheel", (e) => {
383
      if (
384
        scroll.scrollWidth <= scroll.clientWidth ||
385
        e.ctrlKey ||
386
        Math.abs(e.deltaX) >= Math.abs(e.deltaY)
387
      ) return;
388

389
      const delta = e.deltaMode === WheelEvent.DOM_DELTA_LINE
390
        ? e.deltaY * 16
391
        : e.deltaMode === WheelEvent.DOM_DELTA_PAGE
392
          ? e.deltaY * scroll.clientWidth
393
          : e.deltaY;
394
      const maxScrollLeft = scroll.scrollWidth - scroll.clientWidth;
395
      const atStart = scroll.scrollLeft <= 1;
396
      const atEnd = scroll.scrollLeft >= maxScrollLeft - 1;
397

398
      if ((delta < 0 && atStart) || (delta > 0 && atEnd)) return;
399

400
      const nextScrollLeft = Math.min(
401
        maxScrollLeft,
402
        Math.max(0, scroll.scrollLeft + delta),
403
      );
404

405
      if (nextScrollLeft === scroll.scrollLeft) return;
406
      e.preventDefault();
407
      scroll.scrollLeft = nextScrollLeft;
408
    }, { passive: false });
409

410
    scroll.addEventListener("scroll", updateScrollHint);
411
    window.addEventListener("resize", updateScrollHint);
412
    updateScrollHint();
413
  }
414

415
  function updateScrollHint() {
416
    const bar = document.getElementById("category-bar");
417
    if (!bar) return;
418
    const scroll = bar.querySelector<HTMLElement>(".category-scroll");
419
    const fadeLeft = bar.querySelector<HTMLElement>(".scroll-fade-left");
420
    const fadeRight = bar.querySelector<HTMLElement>(".scroll-fade-right");
421
    if (!scroll || !fadeLeft || !fadeRight) return;
422

423
    const hasOverflow = scroll.scrollWidth > scroll.clientWidth + 1;
424
    const atStart = scroll.scrollLeft <= 1;
425
    const atEnd = scroll.scrollLeft + scroll.clientWidth >= scroll.scrollWidth - 1;
426

427
    if (hasOverflow && !atStart) {
428
      fadeLeft.setAttribute("data-visible", "");
429
    } else {
430
      fadeLeft.removeAttribute("data-visible");
431
    }
432

433
    if (hasOverflow && !atEnd) {
434
      fadeRight.setAttribute("data-visible", "");
435
    } else {
436
      fadeRight.removeAttribute("data-visible");
437
    }
438

439
    const moreDivider = bar.querySelector<HTMLElement>(".more-divider");
440
    if (moreDivider) {
441
      if (hasOverflow) {
442
        moreDivider.setAttribute("data-visible", "");
443
      } else {
444
        moreDivider.removeAttribute("data-visible");
445
      }
446
    }
447
  }
448

449
  updateCategoryBar();
450
  initCategoryBarInteractions();
451
  initScrollFeatures();
452

453
  if (!window.__categoryBarInit) {
454
    window.__categoryBarInit = true;
455
    document.addEventListener("astro:page-load", () => {
456
      updateCategoryBar();
457
      initScrollFeatures();
458
    });
459
    document.addEventListener("swup:contentReplaced", () => {
460
      updateCategoryBar();
461
      requestAnimationFrame(() => {
462
        updateCategoryBar();
463
      });
464
    });
465

466
    if (window.swup?.hooks) {
467
      setupSwupEarlyUpdate();
468
    } else {
469
      document.addEventListener("swup:enable", setupSwupEarlyUpdate);
470
    }
471
  }
472

473
  function setupSwupEarlyUpdate() {
474
    if (!window.swup?.hooks) return;
475
    window.swup.hooks.on("visit:start", (visit: any) => {
476
      const bar = document.getElementById("category-bar");
477
      if (!bar) return;
478
      const targetUrl = new URL(visit.to.url, window.location.href);
479
      setActiveCategory(bar, targetUrl);
480
    });
481
  }
482
</script>

展开收起

总结#

精准控制：通过 allowedPaths 数组自由增减固定路由（如 /tags、/series），配合 pathname.startsWith("/posts/") 优雅覆盖所有文章详情页。
丝滑体验：结合 Swup 的生命周期钩子，实现无刷新跳转时的即时显隐切换与状态对齐，省去用户手动刷新的烦恼。

Astro Iconify 格式图标踩坑指南

Wed, 21 Oct 2026 00:00:00 GMT

如果你也在用 Astro 搭博客或者企业官网，那大概率会用 astro-icon 配合 Iconify 去搞定各种小图标。不得不说，只要配置好了，在构建阶段直接把 SVG 内联进去，页面加载快到飞起，确实爽得不行。

但是——凡事就怕个但是。

你是不是也遇到过这种诡异现象：本地开发（npm run dev）跑得好好的，甚至预览也完全正常，结果一推送代码，CI/CD 打包部署直接报错，或者上线的页面图标莫名其妙全白了？

别慌，我也掉进这个坑里了。最后发现问题根本不在 Astro，而是 Iconify 和 Font Awesome 的图标命名与分类机制。今天就简单聊聊这两个让我抓耳挠腮的“小细节”，大家也赶紧自查一下！

坑一：Material Symbols 的命名，真不是直接复制粘贴的！#

我们在找图标的时候，很多人习惯直接去 Google Fonts 的 Material Symbols 页面找。看中一个 add_reaction，点一下复制名字，转头就在 Astro 里面写：

1
---
2
import { Icon } from 'astro-icon/components';
3
---
4
<!-- 错误示范：直接复制了 Google 官网的下划线名字 -->
5
<Icon name="material-symbols:add_reaction" />

写完觉得没啥毛病，结果一构建打包，终端直接给你报一堆找不到图标的 error。

怎么破？#

原来 Iconify 内部强制统一了规范：所有图标名必须是连字符（kebab-case）。

也就是说，不管是 Material Symbols 还是其他什么库，凡是在 Google 官方叫 add_reaction 的，到了 Iconify 这里，所有下划线 _ 都必须手动改成中划线 -。

正确姿势：

1
---
2
import { Icon } from 'astro-icon/components';
3
---
4
<!-- 正确示范：改成连字符 -->
5
<Icon name="material-symbols:add-reaction" />

一个小细节，不注意就能卡你半小时。

坑二：Telegram 到底算什么分类？别啥都往 `fa-solid` 塞！#

搞个人网站或者页脚的时候，少不了要放 Telegram、GitHub 这种社交媒体图标。因为平时用 Font Awesome 用习惯了，脑子一热可能顺手就写成了：

1
---
2
import { Icon } from 'astro-icon/components';
3
---
4
<!-- 错误示范：以为所有 FA 图标都能用 fa-solid -->
5
<Icon name="fa-solid:telegram" />

结果部署之后上线一看：咦？我那么大一个 Telegram 图标去哪了？

怎么破？#

这也是个常见误区。在 Font Awesome 的分类逻辑里，Telegram、Twitter/X、Discord 这种商业品牌 Logo，统统属于 Brands 分类，根本不属于 Solid（实心图标）！

如果你用的图标集是 FA6，前缀必须用 fa6-brands：

1
---
2
import { Icon } from 'astro-icon/components';
3
---
4
<!-- 正确示范：认准 Brands 分类 -->
5
<Icon name="fa6-brands:telegram" />

踩坑小贴士：遇到不确定的图标，强烈建议先去 Icônes 这个网站搜索一下，看看它究竟属于哪个包，别靠直觉盲猜。

顺便附赠：如何写出让部署更稳的 `astro.config.mjs`#

如果你不想在打包的时候发生预料之外的错误，最好在配置文件里给用到的图标做个“显式声明”，同时把依赖装全。

1. 显式声明：

astro.config.mjs

1
import { defineConfig } from 'astro/config';
2
import icon from 'astro-icon';
3

4
export default defineConfig({
5
  integrations: [
6
    icon({
7
      include: {
8
        // 显式引入，防止部署环境因为没按需解析到而报错
9
        'material-symbols': ['add-reaction', 'search', 'menu'],
10
        'fa6-brands': ['telegram', 'github', 'twitter'],
11
      },
12
    }),
13
  ],
14
});

2. 依赖别漏掉：

1
npm i -D @iconify-json/material-symbols @iconify-json/fa6-brands

写在最后#

总结起来，前端玩图标虽然简单，但也容易遇到这种“看似微不足道，实际上极度影响部署”的小绊脚石。

看下划线不爽就改中划线：Material Symbols 等图标名，统统换成 kebab-case。
分清品牌与通用：Telegram、GitHub 认准 brands 分类，别硬塞给 solid。

你最近在用 Astro 或者 Iconify 的时候还遇到过什么奇葩报错？欢迎在评论区吐槽交流！

极简页脚改版：为博客全量引入 Shields.io 徽章图标

Wed, 21 Oct 2026 00:00:00 GMT

在追求极简与美感的中途，我一直觉得原本纯文字渲染的页脚显得有些过于沉闷。原本的样式是由普通的文本链接拼接而成：

Powered by Astro & Firefly | Deployed on Vercel

🎨 改版效果与思路#

本次改版主要分为两个核心区域：

版权声明行：将原本的 © 2026 ZaoCat All Rights Reserved. 转化为统一样式的 Shields.io 徽章，并保留年份与站长配置的动态渲染能力。
技术栈与部署行：将 Astro、Firefly 主题以及 Vercel 部署标识转化为带有官方 Logo 和专属品牌色调的徽章组合。

🛠️ 具体实现步骤#

直接编辑 src/components/Footer.astro 组件，将原本的文字结构替换为带有 Shields.io 生成接口的 <img> 标签组合。

1. 动态版权徽章#

为了保持代码的灵活性，版权信息借由 Astro 的模板语法直接拼接 currentYear 与 profileConfig.name，免去每年手动更新代码的烦恼：

1
<!-- 动态年份与站名的版权徽章 -->
2
<div class="mx-0.5 my-2 flex items-center justify-center gap-2 flex-wrap">
3
  <a href="/" class="inline-flex items-center">
4
    <img
5
      src={`[https://img.shields.io/badge/%C2%A9%20$](https://img.shields.io/badge/%C2%A9%20$){currentYear}-${profileConfig.name}%20All%20Rights%20Reserved.-4B5563?style=flat`}
6
      alt={`Copyright ${currentYear} ${profileConfig.name}`}
7
    />
8
  </a>
9
</div>

2. 技术栈与部署徽章#

在驱动框架与部署服务的图标中，引入了对应品牌的颜色与矢量 Logo，提升辨识度：

代码段

1
<!-- 技术栈与部署徽章行 -->
2
<div class="mx-0.5 my-2 flex items-center justify-center gap-2 flex-wrap">
3
  <!-- Astro 徽章 -->
4
  <a target="_blank" href="[https://astro.build](https://astro.build)" class="inline-flex items-center">
5
    <img src="[https://img.shields.io/badge/Powered%20by-Astro-BC52EE?style=flat&logo=astro&logoColor=white](https://img.shields.io/badge/Powered%20by-Astro-BC52EE?style=flat&logo=astro&logoColor=white)" alt="Astro" />
6
  </a>
7

8
  <!-- Firefly 主题徽章 -->
9
  <a target="_blank" href="[https://github.com/CuteLeaf/Firefly](https://github.com/CuteLeaf/Firefly)" class="inline-flex items-center">
10
    <img src="[https://img.shields.io/badge/Theme-Firefly-ff69b4?style=flat](https://img.shields.io/badge/Theme-Firefly-00BA91?style=flat)" alt="Firefly" />
11
  </a>
12

13
  <span class="text-black/30 dark:text-white/30">|</span>
14

15
  <!-- Vercel 部署徽章 -->
16
  <a target="_blank" href="[https://vercel.com](https://vercel.com)" class="inline-flex items-center">
17
    <img src="[https://img.shields.io/badge/Deployed%20on-Vercel-000000?style=flat&logo=vercel&logoColor=white](https://img.shields.io/badge/Deployed%20on-Vercel-000000?style=flat&logo=vercel&logoColor=white)" alt="Vercel" />
18
  </a>
19
</div>

展开收起

💡 Shields.io 参数微调小结#

在定制 Shields.io 徽章时，有几个参数特别实用：

URL 编码：%C2%A9 对应 © 符号，%20 对应空格。
logo & logoColor：指定内置的标准图标（如 astro, vercel）及图标颜色。
style：默认使用 flat 样式，在现代轻量化界面中观感最为和谐；如果喜欢厚重的科技感，也可以尝试 for-the-badge。
配色选择：版权徽章选用了中灰 (#4B5563)，既能保证可读性，又不会在页面底部抢走主内容的焦点。

📝 完整 `Footer.astro` 结构参考#

最终重构后的代码块非常干练：

代码段

1
---
2
import fs from "node:fs";
3
import path from "node:path";
4
import { profileConfig } from "@/config";
5

6
const currentYear = new Date().getFullYear();
7

8
let customFooterHtml = "";
9
try {
10
  const footerHtmlPath = path.join(
11
    process.cwd(),
12
    "src",
13
    "config",
14
    "FooterConfig.html",
15
  );
16
  customFooterHtml = fs.readFileSync(footerHtmlPath, "utf-8");
17
  customFooterHtml = customFooterHtml.replace(/<!--[\s\S]*?-->/g, "").trim();
18
} catch (error) {
19
  console.warn(
20
    "FooterConfig.html 读取失败:",
21
    error instanceof Error ? error.message : String(error),
22
  );
23
}
24
---
25

26
<footer class="site-footer pointer-events-auto pb-4 md:pb-6">
27
  <div class="transition border-t border-black/10 dark:border-white/15 mt-10 mb-5 border-dashed mx-32"></div>
28

29
  <div class="transition flex flex-col items-center justify-center px-6">
30
    <div class="transition text-sm text-center">
31
      {customFooterHtml && <div set:html={customFooterHtml} class="mb-2" />}
32

33
      <!-- 版权行 -->
34
      <div class="mx-0.5 my-2 flex items-center justify-center gap-2 flex-wrap">
35
        <a href="/" class="inline-flex items-center">
36
          <img
37
            src={`[https://img.shields.io/badge/%C2%A9%20$](https://img.shields.io/badge/%C2%A9%20$){currentYear}-${profileConfig.name}%20All%20Rights%20Reserved.-4B5563?style=flat`}
38
            alt={`Copyright ${currentYear} ${profileConfig.name}`}
39
          />
40
        </a>
41
      </div>
42

43
      <!-- 技术栈与部署徽章行 -->
44
      <div class="mx-0.5 my-2 flex items-center justify-center gap-2 flex-wrap">
45
        <a target="_blank" href="[https://astro.build](https://astro.build)" class="inline-flex items-center">
46
          <img src="[https://img.shields.io/badge/Powered%20by-Astro-BC52EE?style=flat&logo=astro&logoColor=white](https://img.shields.io/badge/Powered%20by-Astro-BC52EE?style=flat&logo=astro&logoColor=white)" alt="Astro" />
47
        </a>
48

49
        <a target="_blank" href="[https://github.com/CuteLeaf/Firefly](https://github.com/CuteLeaf/Firefly)" class="inline-flex items-center">
50
          <img src="[https://img.shields.io/badge/Theme-Firefly-ff69b4?style=flat](https://img.shields.io/badge/Theme-Firefly-ff69b4?style=flat)" alt="Firefly" />
51
        </a>
52

53
        <span class="text-black/30 dark:text-white/30">|</span>
54

55
        <a target="_blank" href="[https://vercel.com](https://vercel.com)" class="inline-flex items-center">
56
          <img src="[https://img.shields.io/badge/Deployed%20on-Vercel-000000?style=flat&logo=vercel&logoColor=white](https://img.shields.io/badge/Deployed%20on-Vercel-000000?style=flat&logo=vercel&logoColor=white)" alt="Vercel" />
57
        </a>
58
      </div>
59
    </div>
60
  </div>
61
</footer>

展开收起

修改完成后提交代码，Vercel 会自动完成构建与部署。看着页脚整齐规范的徽章，博客的整体精致感又提升了不少！

在 GitHub Codespaces 中解决 Vercel + Astro 部署的 pnpm 锁文件报错

Wed, 21 Oct 2026 00:00:00 GMT

在使用 Vercel 部署基于 Astro 构建的博客（如 Firefly 主题）时，我们常常需要接入诸如 @vercel/analytics 这样强大的访问统计工具。

如果你手头没有本地开发环境，想直接在 GitHub 网页端搞定这一切，可能会遇到一些小坑。本文将带你从零开始，完整走通“注入统计代码 -> 触发云端报错 -> 使用 GitHub Codespaces 优雅解决”的全过程。

第一步：在 GitHub 网页端修改布局文件#

通常像 Astro 主题都会有一个全局的布局组件。我们可以直接在 GitHub 网页端找到它并植入统计代码。

打开你的 GitHub 项目仓库。
导航找到布局文件，路径通常是 src/layouts/Layout.astro（或者 BaseLayout.astro）。
点击文件右上角的 铅笔图标（Edit file） 开始在线编辑。

1. 顶部导入 Analytics 组件#

在文件最顶部的 Frontmatter 区域（前后都有 --- 的地方），加入导入语句：

1
---
2
// 其他已有的 import 语句...
3
import Analytics from '@vercel/analytics/astro';
4

5
// 接收的 Props 或其他代码...
6
---

2. 在 body 标签内部插入组件#

在 HTML 的 <body> 标签内部（建议放在页面的最底部、闭合标签 </body> 的上方），加入组件代码：

代码段

1
    <body>
2
      <!-- 页面主体内容 -->
3
      <slot />
4

5
      <!-- 插入 Vercel Analytics -->
6
      <Analytics/>
7
    </body>
8
  </html>

修改完成后，点击右上角的 Commit changes… 提交保存。

第二步：Vercel 部署报错：pnpm 锁文件冲突#

当你把代码提交到 GitHub 之后，Vercel 会自动触发重新部署。但如果你之前项目里没有安装过这个依赖，构建日志里大概率会抛出这样一个让人头疼的错误：

Plaintext

1
[ERR_PNPM_OUTDATED_LOCKFILE] Cannot install with "frozen-lockfile" because pnpm-lock.yaml is not up to date with <ROOT>/package.json
2
Error: [BUILD_UTILS_SPAWN_1] Command "pnpm install" exited with 1

这是因为项目使用的是 pnpm，而 Vercel 在云端构建时默认开启了严格的锁文件检查（Frozen Lockfile）。因为你在代码里用了新依赖，但没有本地电脑去运行 pnpm install 更新 pnpm-lock.yaml，导致两边对不上，构建直接中断。

没有本地电脑，怎么更新锁文件呢？别慌，我们有终极武器——GitHub Codespaces。

第三步：使用 GitHub Codespaces 妙解锁文件冲突#

GitHub 官方自带的云端开发环境（Codespaces）可以让我们直接在浏览器里拥有一个完整的 Linux 终端。

1. 召唤云端编辑器#

在你的 GitHub 项目仓库主页面，直接在键盘上按下英文句号键 .（点号）。
稍等几秒钟，页面就会神奇地变成一个网页版的 VS Code。

2. 在云端运行安装命令#

在页面下方自带的终端（Terminal）面板中，直接输入并回车：

Bash

1
pnpm install

这一步会让 pnpm 在云端自动帮你把依赖补全，并完美更新根目录下的 pnpm-lock.yaml 文件。

3. 提交并推送更改#

点击左侧边栏的源代码管理图标（分支图标）。
你会看到被自动更新的 pnpm-lock.yaml 和 package.json 文件。
在上方输入框写下提交信息，例如：fix: update pnpm-lock.yaml for vercel analytics。
点击 Commit，然后点击 Push 将代码推送到远程 GitHub 仓库。

🎉 大功告成#

完成推送后，你可以直接关掉 Codespaces 标签页。

回到你的 Vercel 控制台，你会发现项目已经自动触发了新的一次部署。这一次，由于 pnpm-lock.yaml 已经和代码完全同步，Vercel 顺利通过了严格锁文件检查，项目完美构建成功！

小结：善用 GitHub 网页端与 Codespaces 的组合，即使身边的电脑没有配开发环境，也能随时随地轻松搞定静态站点的各类维护与部署难题。

Astro 博客排坑指南：使用 Qexo 管理时的日期类型校验错误排查

Mon, 19 Oct 2026 00:00:00 GMT

在使用 Astro 搭建博客时，为了方便随时随地撰写和管理文章，许多小伙伴会引入轻量级的 Web CMS 系统，例如 Qexo。

然而，在配置好 Qexo 与 GitHub 仓库的连通性后，你可能会遇到一个诡异的现象：在 Qexo 后台修改网站配置（如修改站点名称）可以正常生效，但只要一添加或修改文章，系统就会报错，甚至直接在 GitHub 网页端手动修改文章也无法完成构建部署。

本文将还原整个排坑过程，并提供一劳永逸的解决方案。

🔍 问题现象与排查#

在 Qexo 端发布新文章后，触发 GitHub Actions 或 Vercel 构建，部署任务会瞬间标红中断，报错日志如下：

1
[InvalidContentEntryDataError] posts → draft data does not match collection schema.
2
  published**: **published: Expected type "date", received "string"
3
  updated**: **updated: Expected type "date", received "string"
4
  Hint:
5
    See https://docs.astro.build/en/guides/content-collections/ for more information on content schemas.
6
  Error reference:
7
    https://docs.astro.build/en/reference/errors/invalid-content-entry-data-error/
8
  Location:
9
    /vercel/path0/src/content/posts/draft.md:0:0

甚至有时报错信息会变成：

1
published**: **published: Expected type "date", received "object"

日志核心提示：#

posts → [文章文件名]：指出是某个 Content Collection 集合下的 Markdown 文件校验不通过。
Expected type "date", received "string" 或 received "object"：指出 published（发布时间）字段收到的类型与期望的类型不符。

🛠️ 根源分析#

这个问题的根源在于 Astro Content Collections（内容集合）严格的 Schema 校验机制 与 通用 CMS / YAML 解析机制 之间的摩擦。

Astro 主题的严格校验：在 Astro 主题中，src/content.config.ts（或 src/content/config.ts）通常会定义文章元数据（Frontmatter）的校验规则。大部分主题开发者会使用 Zod 库这样定义日期：
```
1
published: z.date(),
```
这里的 z.date()只接受标准的 JavaScript Date 对象。
Qexo 与 Frontmatter 的数据类型： Qexo 生成或修改 Markdown 时，写入文件顶部的 Frontmatter（YAML 格式）本质上是纯文本。当 Astro 构建时解析 YAML，传入 published 字段的值往往是一个 字符串（如 "2026-10-18"）或者由 YAML 解析器预处理出的某种对象。
冲突爆发：当 z.date() 遇上字符串类型的日期数据，Astro 认为数据非法，触发 InvalidContentEntryDataError 保护机制并立即终止构建。

💡 解决方案：使用 `z.coerce.date()`#

解决这个问题的关键，在于告诉 Zod 校验器：“不管传过来的是字符串还是 Date 对象，请尝试在构建时把它们自动转换为标准的 Date 对象。”

Zod 提供了强大的类型强制转换（Coercion）工具：z.coerce.date()。

操作步骤#

打开项目的配置文件 src/content.config.ts（或 src/content/config.ts）。
找到定义文章集合（如 postsCollection）的 schema 部分。
将所有的 z.date() 修改为 z.coerce.date()。

修改前代码：#

1
const postsCollection = defineCollection({
2
  loader: glob({ pattern: "**/*.{md,mdx}", base: "./src/content/posts" }),
3
  schema: z.object({
4
    title: z.string(),
5
    published: z.date(), // ❌ 卡得很死，只认 Date 对象
6
    updated: z.date().optional(), // ❌
7
  }),
8
});

修改后代码：#

1
const postsCollection = defineCollection({
2
  loader: glob({ pattern: "**/*.{md,mdx}", base: "./src/content/posts" }),
3
  schema: z.object({
4
    title: z.string(),
5
    published: z.coerce.date(), // ✅ 自动将字符串/对象转换为 Date 对象
6
    updated: z.coerce.date().optional(), // ✅
7
  }),
8
});

提示：如果你的配置文件中还有 dynamic（动态）、projects（项目）等其他带有 published 或时间字段的集合，建议一并修改为 z.coerce.date()。

保存并提交更改到 Git 仓库：

1
git add src/content.config.ts
2
git commit -m "fix: use z.coerce.date() to allow string dates from Qexo"
3
git push

⚠️ 避坑补充指南#

在排查过程中，如果你修改了代码依然报错，请检查以下细节：

双重后缀问题：Qexo 在极端情况下创建文件时可能会拼错文件名（例如生成了 article.md.md）。这类异常文件名会导致 Astro 加载器解析异常，请在 GitHub 仓库中清理掉多余的 .md.md 文件。
必填字段缺失：Astro 校验非常严格，除了日期之外，如果文章头部缺少了 title 等必须字段（如新建了空白测试文件 test.md），也会触发 title: Required 报错。确保所有文章都包含完整的基础元数据：
```
1
---
2
title: "文章标题"
3
published: 2026-10-18
4
draft: false
5
---
```

🎉 总结#

通过将 Zod 的 z.date() 升级为 z.coerce.date()，我们既保留了 TypeScript 的强类型检查，又赋予了 Content Collections 应对第三方 CMS 传入文本日期的容错能力。

现在，你可以继续享受 Astro 的极致性能，同时搭配 Qexo 随时随地愉快地创作博客了！

让自建 memos 服务完美融合在 Astro 博客里面

Sun, 18 Oct 2026 00:00:00 GMT

在独立博客中，我们常常希望有一个类似“微博/朋友圈”的角落，用来记录一些随想、短动态或生活碎片，而不需要像写正式文章那样绞尽脑汁去构思标题和排版。

如果你正在使用以轻量美观、支持丰富配置著称的 Astro 博客主题（如 Firefly），同时又部署了轻量级开源笔记/动态服务 Memos，那么将两者结合可以说是绝配——通过将 Memos 作为动态的数据源，你既能享受 Memos 专属后台带来的便捷发布体验（甚至可以用手机随时随地发动态），又能完美保留博客主题的高颜值与极简风格。

本文将带你从零开始，在服务器上使用 Docker 自建 Memos 服务，并通过 Cloudflare Tunnel 实现安全的公网访问，最终将其无缝整合到 Astro 博客的动态页面中。

使用 Docker 自建 Memos 服务#

Memos 是一个极佳的开源、自托管知识库与轻量动态记录工具。我们可以通过 Docker 快速将它部署到 VPS 上。

1. 编写 Docker Compose 配置文件#

在服务器的某个目录下（例如 /opt/memos），创建一个 docker-compose.yml 文件：

1
services:
2
  memos:
3
    image: neosmemo/memos:latest
4
    container_name: memos
5
    restart: unless-stopped
6
    ports:
7
      - "5230:5230"
8
    volumes:
9
      - ./data:/var/opt/memos
10
    environment:
11
      - MEMOS_INSTANCE_URL=https://memos.example.com  # 替换为你实际绑定的域名

💡 注意事项（关于版本与环境变量）：从 Memos 0.30.0 版本开始引入了较为严格的公开与私有模式破坏性变更。如果你的 Memos 版本号 ≥ 0.30.0，请务必在环境变量中配置 MEMOS_INSTANCE_URL，并且该地址需要与你后续在博客里配置的 apiUrl严格保持一致，否则前端跨域或 API 请求可能会遇到阻碍。

2. 启动容器#

在 docker-compose.yml 所在目录下执行：

1
docker compose up -d

使用 Cloudflare Tunnel 配置内网穿透与 HTTPS#

为了让博客能够安全地通过 HTTPS 访问 Memos 的 API（且无需繁琐配置 Nginx 和 SSL 证书），我们可以使用 Cloudflare Tunnels (cloudflared) 将本地的 5230 端口安全映射到公网域名。

1. 在 Cloudflare Zero Trust 中创建 Tunnel#

登录 Cloudflare Dashboard，进入 Zero Trust 面板。
导航至 Networks -> Tunnels，点击 Create a tunnel。
给隧道起个名字（例如 memos-tunnel），保存后选择你的操作系统或 Docker 部署方式获取运行命令。

2. 配置 Public Hostname（公网域名）#

在 Tunnel 创建完成后，为其绑定一个专属的子域名：

Subdomain & Domain: 填入你想要的域名，例如 memos.example.com。
Service:
- Type: HTTP
- URL: localhost:5230（如果 cloudflared 与 memos 容器在同一台机器上）或容器名 memos:5230（如果在同一个 Docker 网络下）。

保存后，Cloudflare 会自动为你处理 DNS 解析和免费的 SSL/TLS 证书。此时直接访问 [https://memos.example.com](https://memos.example.com) 即可打开 Memos 初始化页面，完成管理员账号注册。

在 Astro 博客（Firefly 主题为例）中接入 Memos 数据源#

当 Memos 搭建完毕并通过 Tunnel 成功上线后，我们就可以让 Astro 博客直接读取 Memos 的内容，并在前端动态页面中实时展示。

1. 开启动态页总开关#

首先，在站点配置文件（如 src/config/siteConfig.ts）中，确保开启了动态页面模块：

1
export const siteConfig = {
2
  // ... 其他配置
3
  pages: {
4
    dynamic: true, // 开启动态页
5
  },
6
};

2. 修改动态配置文件启用 Memos#

打开动态专属的配置文件 src/config/dynamicConfig.ts，将 memos 的 enable 改为 true，并正确填写你的 Memos 实例地址以及用户标识 (parent)：

1
export const dynamicConfig = {
2
  title: "",
3
  description: "",
4
  profileUrl: "/about/",
5
  showComment: true,
6
  itemsPerPage: 20,
7
  apiUrl: "/api/dynamic.json", // 当 memos.enable 为 true 时此项会被忽略
8
  memos: {
9
    enable: true,                            // 启用 Memos 数据源
10
    apiUrl: "https://memos.example.com",     // 你的 Memos 实例地址（需与 Docker 环境变量及 Tunnel 域名一致）
11
    parent: "users/your-username",           // 你的 Memos 用户标识（可在 Memos 后台或 API 路径中确认）
12
  },
13
};

配置项说明：#

enable: 设置为 true 后，博客客户端将绕过本地静态 JSON，直接从配置的 Memos API 实时拉取数据。
apiUrl: 你的 Memos 站点根地址。
parent: 目标用户的 Resource Name 格式（例如 users/xiaye 或你的实际用户名）。

效果与特性#

完成上述配置并部署上线后（如果你习惯直接通过 GitHub 在线修改代码同步更新，也可以直接在 GitHub 仓库中调整对应配置文件触发 Vercel 等平台自动部署）：

实时同步：你在 Memos 后台（或手机客户端）发布的任何碎碎念、动态，都会实时同步展现到 Astro 博客的动态页中。
特性支持：主题会自动处理 Memos 中的图片附件展示、置顶同步，甚至能将位置信息（location）完美映射并显示在动态发布时间旁。
小组件联动：博客侧边栏的「最新动态」等小组件也会无缝从该 Memos 接口获取最新内容，保持全站数据流的一致性。

通过这种方式，既省去了复杂的服务器运维与证书申请，又拥有了一个极其现代、方便管理的动态发布后台，可以说是独立开发者和博主们的理想搭配！

在 Vercel 部署 Astro 的 Firefly 主题模板

Wed, 31 Dec 2025 00:00:00 GMT

折腾静态博客好像有一种让人停不下来的魔力。之前对各种花哨的动态博客架构折腾了一圈后，最近反倒更向往那种轻量、干净、打开即用的静态站点。

**偶然刷到基于 Astro 框架开发的 **Firefly 主题（衍生自 Fuwari 模板），一眼就被它那清新现代的界面、细腻的动效以及丰富的内置组件给吸引住了。既然相中了，那就索性动手，把它直接部署到 Vercel 上，作为日常记录和分享的小天地。^^

整个过程出奇的顺畅，这里把折腾的步骤和一些个人感受简单记录下来。

为什么选择 Astro + Firefly？#

极致的性能：Astro 默认输出零客户端 JavaScript 的静态 HTML，对于我这种追求加载速度和极简体验的人来说，简直直击痛点。
现代且高颜值：Firefly 自身带有很多精致的细节，比如动态背景、暗色/亮色模式无缝切换、自定义主题色相，甚至还有项目展示、时间线、技能树等极具极客风格的页面，省去了自己从零写前端样式的大量精力。^^
省心的托管：不需要操心复杂的服务器运维，配合 GitHub 和 Vercel 的联动，真正实现了“修改代码、推送到仓库、自动构建上线”的丝滑体验。

部署步骤：比想象中更简单#

得益于现代 Jamstack 架构的成熟，整个部署流程基本可以概括为：Fork 仓库 -> 配置参数 -> 绑定 Vercel 自动构建。

1. 准备工作与仓库 Fork#

首先来到 GitHub 上的 Firefly 项目仓库（CuteLeaf/Firefly）。点击右上角的 Fork，把项目复制到你自己的 GitHub 账号下。

2. 基础配置与个性化#

Fork 下来之后，其实不用急着在本地搭建复杂的 Node.js 开发环境。因为平时更习惯直接在 GitHub 的在线编辑器里微调，或者通过 Vercel 触发同步更新，所以直接在线修改核心配置文件即可：

找到 src/config.ts（或者项目根目录下的相关配置文件），在这里可以修改你的博客标题、作者签名、社交链接、导航栏以及各种功能开关。
替换掉默认的头像、Banner 壁纸，换成自己喜欢的风格。^^

3. 在 Vercel 上一键托管#

从 GitHub 列表中选择你刚刚 Fork 的 Firefly 仓库。
Vercel 会非常智能地自动识别出这是一个 Astro 项目，构建命令（Build Command）通常会默认填充为 npm run build，输出目录（Output Directory）为 dist。
点击 Deploy，剩下的就交给 Vercel 的云端构建流水线。

看着终端里滚动几行日志，伴随着几秒钟的等待，站点就绿灯上线了。绑定好自己的自定义域名，顺便把 SSL 证书配置好，一个属于自己的全新 Firefly 博客就正式对外访问了。

写在最后#

折腾完之后，看着干净清爽的页面在浏览器里秒开，心情也会跟着平静下来。

静态博客的好处就在于此：它不要求你时刻去维护后端数据库的稳定，也不用担心哪天服务器过期。你只需要专注在 Markdown 文本里写下当下想说的话，然后点一下保存、推送到远端，剩下的交给云端去同步。

愿这盏小小的“Firefly”，能记录下更多技术与生活里的点滴微光。

博客迁移 Astro 并接入 Qexo 3.7.0 后台折腾手记

Mon, 06 Oct 2025 00:00:00 GMT

一直以来，对于静态博客的折腾似乎总有一种停不下来的魔力。从早期的 Hexo 搭配各种主题，到后来对现代化组件化架构的向往，总觉得博客不仅是文字的容器，也是技术审美的自留地。

最近关注到 Qexo 发布了 3.7.0 新版本，其中最让人眼前一亮的就是终于原生支持了 Astro！这对于一直想尝试 Astro 现代轻量化体验，又舍不得 Qexo 网页端便捷管理后台的我来说，简直是久旱逢甘霖。

趁着周末的闲暇，索性一不做二不休，把博客整个迁移到了 Astro（选用了一款心仪的 Astronauts 主题），并顺势部署了最新版的 Qexo 后台进行现代化管理。在此记录下整个折腾的过程，也给同样想折腾的朋友做个参考。

为什么选择 Astro 与 Qexo 3.7.0？#

在动手之前，先简单聊聊这次技术栈变动的初衷：

Astro 的现代化体验：相比传统 SSG，Astro 带来了极佳的组件化架构和零客户端 JavaScript 默认哲学，构建速度极快，页面轻量清爽，非常适合追求极致性能的个人独立博客。^^
Qexo 3.7.0 的完美适配：以往 Qexo 对 Hexo、Halo 等支持较多，而 3.7.0 版本的更新对 Astro 的内容结构、Frontmatter 以及发布流程有了更好的兼容，使得“网页端随时随地写文章/改文章”的梦想照进现实。
云端无缝协作：采用 Vercel 托管前端、GitHub 进行源码同步、结合 Qexo 后台与 PostgreSQL 数据库，整个链路完全跑通，免去了本地环境的束缚。

迁移与部署实录#

整个过程大致可以分为三个核心步骤：部署 Astro 主题、配置 Qexo 后台，以及打通两者的关联。

1. 部署 Astro 博客前台#

首先在 GitHub 上准备好基于 Astro 的博客仓库（以 Astronauts 主题为例）：

仓库关联：将项目推送到 GitHub，直接在 Vercel 中导入该仓库进行一键托管部署。
内容适配：检查 src/content/posts 下的 Markdown/MDX 文件结构，确保 Frontmatter 包含必要的字段（如 title, published, description, tags 等）。
日期与 Schema 校验：在对接后台时，建议在 Astro 的内容集合（Content Collections）中对日期字段做好处理（例如使用 z.coerce.date()），以防后台提交的时间格式引起构建报错。

2. 部署 Qexo 3.7.0 后台#

Qexo 的部署依然保持了一贯的轻量与灵活。这次我们将其部署在 Vercel 上，并连接到 PostgreSQL 数据库：

新建数据库：在 Vercel 或其他托管平台准备好 PostgreSQL 数据库实例。
Fork / 部署 Qexo：将 Qexo 源码部署到 Vercel，配置好环境变量：
- DATABASE_URL：连接你的 PostgreSQL 数据库。
- 其他安全与鉴权密钥。
初始化后台：访问部署好的域名，完成管理员账号的注册与初始化。

3. 对接与调优：让 Qexo 顺畅管理 Astro#

进入 Qexo 3.7.0 的后台设置，核心是配置好 GitHub 图床/仓库同步 以及 Astro 的API/Webhook 触发：

仓库连接：填入你的 GitHub 仓库信息、Personal Access Token（PAT），让 Qexo 能够直接读写仓库中的文章 Markdown 文件。
分支与路径映射：指定文章存放的对应目录（例如 src/content/posts/）。
自动触发构建：开启 Vercel 的 Deploy Hooks（部署钩子），这样每次在 Qexo 后台点击发布或修改文章时，都能自动触发 Vercel 重新编译部署，实现“网页端保存 $\rightarrow$ 自动同步 GitHub $\rightarrow$ 瞬间完成上线”的丝滑闭环。

遇到的一个小插曲#

在实际联调过程中，也遇到了一点小波折：由于 Astro 对文章 Frontmatter 的日期类型检查比较严格，如果后台提交的日期格式与本地定义的 Zod Schema 稍有出入，Vercel 构建时就会抛出类型错误。

解决办法：在 Astro 的 config.ts 中调整内容集合的 Schema 定义，针对日期字段加入类型强转（例如 z.coerce.date()），这样无论通过 Qexo 后台以何种时间格式写入，都能被正确解析，再也不用担心莫名其妙的构建失败了。

写在最后#

折腾完毕，看着新版博客在轻盈的加载动画中缓缓展开，后台也能随时随地用手机或网页顺畅地敲字、修改、发布，这种掌控感和新鲜感确实让人心情愉悦。

技术总是不断向前，工具也在变得越来越聪明。愿这片赛博空间能承载更多安静的文字、绵长的思绪，以及对代码和生活纯粹的热爱。

晚安，世界。 🌙

如果你在部署 Qexo 3.7.0 或迁移 Astro 的过程中遇到了什么问题，欢迎在评论区一起交流探讨！

Vercel 与 Cloudflare 优选 IP 加速完整指南

Sat, 31 May 2025 00:00:00 GMT

对于独立开发者和前端工程师来说，Vercel 绝对是部署静态网站、Next.js 应用和 Serverless 函数的神仙级平台。然而，由于众所周知的原因，Vercel 官方分配给国内访问的边缘节点有时表现不尽如人意，甚至偶发阻断。

**今天我们就来聊聊如何通过 **Cloudflare 优选 IP / Cloudflare SaaS（自定义主机名） 的组合拳，让托管在 Vercel 上的网站实现国内极速访问。^^

核心原理解析#

Vercel 的底层在全球使用了强大的 CDN 分发，但其默认的 Anycast IP 在国内的直连路由并不总是最优的。

**而 **Cloudflare SaaS 功能（Custom Hostnames，自定义主机名） 允许我们在自己的 Cloudflare 账号里接管一个域名，通过 CNAME 的方式把国内用户的流量引导到“优选 IP”上，再由 Cloudflare 安全回源到 Vercel。这样既能享受 Vercel 的免运维托管，又能享受到 Cloudflare 优选节点带来的低延迟和高稳定性。^^

准备工作#

在开始配置之前，你需要准备好以下几项：

**一个托管在 Vercel 上的项目，并已经绑定了你的自定义域名（例如 **example.com）。^^
一个可以正常使用的 Cloudflare 账号。
**辅助域名/主域名（建议准备两个域名，或者用主域名 + 子域名配合，例如主域名 **example.com 走优选，备用/回源域名 origin.example.com 指向源站）。^^

实操配置步骤#

1：在 Vercel 中绑定域名^^www.aichuangshi.com#

登录 Vercel 控制台，进入你的项目，点击 Settings -> Domains。
输入你的自定义域名（如 example.com），点击 Add。^^
**Vercel 会提示让你添加一条 CNAME 记录指向 **cname.vercel-dns.com。先记下这个要求。^^

2：在 Cloudflare 配置 SaaS（自定义主机名）^^星の住処#

为了绕过 Cloudflare 默认分配的慢速节点，我们需要利用 SaaS 功能绑定回源：^^

**准备一个托管在 Cloudflare 上的域名（假设叫 **fales.net 或使用你的主域名开启 SaaS）。^^
在 Cloudflare 面板中，找到 SSL/TLS -> 自定义主机名 (Custom Hostnames)。^^
点击 添加自定义主机名：^^
- 自定义主机名：**填入你要对外访问的域名（如 **example.com）。^^
- 回退源 (Fallback Origin)****：^^填入 Vercel 的别名或者你的回源代理域名（例如 cname.vercel-dns.com）。^^
按照页面提示完成 TXT 证书验证（Cloudflare 会要求你在 DNS 解析里加一条 TXT 记录以证明你拥有该域名所有权）。^^

3：获取并配置“优选 IP / 优选 CNAME”^^NodeSeek#

国内直连 Cloudflare 官方节点的带宽经常拥堵，我们需要通过测速工具（如 CloudflareSpeedTest）选出对三网（电信、联通、移动）延迟最低、丢包最少的 优选 IP 或 优选 CNAME。^^

DNS 分流解析设置**（**^^以 Cloudflare DNS 或第三方 DNS 为例）：^^
- 如果使用第三方多线路 DNS（如 DNSPod、阿里云解析），可以针对不同运营商设置线路：^^
  - 电信线路：A 记录解析到电信优选 IP^^
  - 联通线路**：**^^A 记录解析到联通优选 IP^^
  - 移动线路**：**^^A 记录解析到移动优选 IP^^
- 或者直接使用社区维护的稳定优选 CNAME 域名，将你的主域名 CNAME 指向该优选域名。^^

效果测试与优化#

配置完成并等待 DNS 生效（通常几分钟内）后：

**使用多地 Ping 工具（如 **ITDOG）测试你的自定义域名。^^
你会发现原本解析到海外高延迟节点的 IP 已经变成了优化后的国内或港台直连/优质中转节点，访问速度显著提升，网页秒开。

总结与注意事项#

**通过 **Vercel + Cloudflare SaaS + 优选 IP 的方案，我们完美结合了云平台的便捷与自选节点的网速优势。^^

优点：大幅降低访问延迟、防DDoS攻击、国内访问更稳定。
注意点：优选 IP 具有一定的时效性，部分免费优选 IP 可能会不定期失效，建议配合自动化脚本或关注相关社群定期更新优选 IP。

从 Purrfit 到 Flaris：借 Gemini 之手，搭一座属于自己的数字小岛

Tue, 20 May 2025 00:00:00 GMT

摘要：上一个月给猫咪写了个体重记录小工具 Purrfit，这个月又想整理一下设备里杂乱的书签。于是，在 Gemini 的配合下，我搞出了一个纯基于 Cloudflare Workers 的极简导航页 —— Flaris。

独立开发的“轻量”执念#

前阵子为了跟踪猫咪的日常体重变化，我写了开源项目 Purrfit，发布并跑在了 Cloudflare Workers 上。那种不依赖传统服务器、不需要繁琐配置 Nginx、完全依靠 Serverless 边缘网关“即即用”的体验，着实让人上瘾。

最近在整理浏览器书签和多设备同步时，我再次感觉到了不便：市面上的导航页要么功能过于堆砌，背景广告和新闻资讯乱飞；要么就是样式老旧，缺少一点通透现代的气息。

既然现有的都不太趁手，不如顺着之前的思路，再搭一座纯粹、轻量的“数字小岛”。

Flaris 的诞生#

这次我依然选择使用 Cloudflare Workers + KV 的单文件/轻量单体架构（Monolithic Script），前端则使用了轻量响应式的 Vue 3 + Tailwind CSS，并给项目起名 Flaris Navigation。

在和 Gemini 的多次互动交流与代码重构中，这个项目渐渐有了我理想中的模样：

通透的玻璃拟态 UI：告别厚重的背景块，采用高透明度的 Glassmorphism 卡片，让日光或暗夜背景自然透出来，视觉上更加轻盈。
高精度的 Open-Meteo 天气：放弃了容易超时或气温偏离较大的公共 API，重构引入 Open-Meteo 结合 IP 自动定位，实时显示当前城市的气温与天气图标。
农历与动态时间段问候：支持公历/农历一键切换，并按晨光、上午、午休、深夜等不同时间段，打字随机播放不同的小问候。
完善又克制的后台管理：支持密码登录、多级分类、私有链接隐藏，以及数据 JSON 一键备份与还原。
黑白猫的视觉灵魂：和 Purrfit 一样，在开屏动画与细节里，依然保留了我钟爱的黑白猫伸懒腰与小细节，给冰冷的代码凑上一丝温度。

AI 时代的工作流重塑#

回顾这次从想法到落地、再到在 V2EX 上发帖开源的过程，Gemini 在其中扮演的角色令人惊喜。

以前做 Web 开发，可能要花上大半天配置构建工具、解决复杂的依赖链，甚至为一段 WMO 天气代码解析或者农历转换算法头疼半天。而现在，我只需要把对界面交互的直觉、视觉透明度的微调诉求、以及逻辑上的边界异常告诉 Gemini，就能在几秒钟内拿到优雅整合且经过校验的代码片段。

从 Purrfit 的猫咪体重数据追踪，到 Flaris 的个人站点导航，这种“只专注于想法与体验，把繁琐实现交给 AI”的协同模式，让独立开发变得前所未有的顺畅与快乐。

写在最后#

Flaris 的源代码已经全面开源在 GitHub 上，直接复制单文件部署到 Cloudflare Worker 绑定 KV 即可免费使用。

zaocat

Flaris

🧭 Flaris - Your bookmark galaxy on the edge. A minimalist dashboard powered by Cloudflare KV. (🧭 Flaris - 边缘端的书签星系。由 Cloudflare KV 驱动的极简仪表盘。)

—

MIT

JavaScript

在线 Demo：https://nav.929255.xyz

小岛已建好，猫咪正趴在侧栏晒太阳。希望能给同样喜欢干净、轻量体验的朋友带来一点点便利。

域名、小猫与 Purrfit：用 Cloudflare 搭建一个猫咪体重计

Fri, 18 Apr 2025 00:00:00 GMT

不久前偶然注册到了一个 .xx.kg 的免费域名，当时还没想好拿它来做什么。直到前阵子家里迎来了一只新成员——一只可爱的小猫。

看着它每天蹦蹦跳跳、一天天长大，记录它体重变化的诉求变得明确起来。kg（公斤）与体重记录天然契合，这个域名便顺理成章地找到了它的使命。于是，Purrfit 就这样诞生了。

为什么是 Purrfit？#

市面上现有的健康或体重记录应用，要么功能过于繁重，带有各种无意义的社交属性；要么广告漫天，甚至连最基础的数据导出都要收费。

作为开发者，最舒服的解决方式自然是自己动手。我对这个小工具的诉求很纯粹：

轻量与优雅：界面要清爽，支持暗色模式，交互要足够细致（比如动态 Glow 光影与磨砂玻璃气泡）。
零成本运行：无需维护重型服务器，借助 Cloudflare 的 Edge 边缘节点处理一切。
数据完全自主：支持无痛的 CSV 导入导出，不依赖任何第三方平台。

技术架构与实现#

整个项目基于 Cloudflare Workers + KV 构建，零服务器开销，部署极其简单：

后端处理与渲染：单个 Worker 承载了轻量级路由、身份验证以及服务端 HTML 渲染。
数据持久化：使用 Cloudflare KV 存储体重记录与全局配置，读写极其迅捷。
UI & 细节打磨：
- 采用了 Glassmorphism（毛玻璃） 视觉风格，自适应浅色与深色模式。
- 图表部分实现了动态趋势渲染，悬浮气泡具备半透明磨砂质感，能够精准呈现具体日期与备注。
- 内置了中文/英文双语言支持与多猫咪档案管理。

搭建与部署流程#

如果你也想为自家的猫咪搭建一个，整个过程只需要几分钟：

准备 KV 绑定：在 Cloudflare Dashboard 创建一个名为 CAT_KV 的 KV Namespace，并在 Worker 中完成绑定。
环境变量配置：
- ADMIN_USER：后台管理员账号
- ADMIN_PASS：后台管理员密码
- CAT_NAMES：猫咪名字（支持多只，用逗号分隔）
部署代码：将开源的单个 worker.js 代码粘贴至 Worker 编辑器中，保存并发布。
绑定域名：在 Worker 的 Custom Domains 中解析你的专属域名（比如我的 .xx.kg），即可完成部署。

在线体验与开源#

目前 Purrfit 已完全开源，并内置了演示环境：

zaocat

Purrfit

🐱 Purrfit: A minimalist, serverless cat weight tracker built on Cloudflare Workers. ☁️ 一个基于 Cloudflare Workers 构建的简约、精美、无服务器的猫咪体重记录本。

—

MIT

JavaScript

在线 Demo：zao.qzz.io（测试账号：test / 密码：123456）

域名有了归宿，小猫的成长有了记录。如果你也在寻找一个纯粹、安静的猫咪健康追踪工具，不妨也搭一个试试。

早安喵栈

在 Astro Firefly 主题中集成专属 AI 智能助手：从 API 配置到 UI 落地全记录

技术栈选型#

后端 API 接口实现 (src/pages/api/ai.ts)#

前端悬浮挂件与 UI 落地 (Layout.astro 或根布局)#

1. HTML 与样式组件#

2. 交互与无刷新挂载脚本 (<script>)#

避坑指南与核心优化总结#

给 Astro 博客的 CategoryBar 组件添加“特定页面显示”及 Swup 无刷新跳转适配指南

核心痛点分析#

最终解决方案：CSS 显隐控制 + Swup 动态响应#

完整组件代码 (CategoryBar.astro)#

总结#

Astro Iconify 格式图标踩坑指南

坑一：Material Symbols 的命名，真不是直接复制粘贴的！#

怎么破？#

坑二：Telegram 到底算什么分类？别啥都往 fa-solid 塞！#

怎么破？#

顺便附赠：如何写出让部署更稳的 astro.config.mjs#

写在最后#

极简页脚改版：为博客全量引入 Shields.io 徽章图标

🎨 改版效果与思路#

🛠️ 具体实现步骤#

1. 动态版权徽章#

2. 技术栈与部署徽章#

💡 Shields.io 参数微调小结#

📝 完整 Footer.astro 结构参考#

在 GitHub Codespaces 中解决 Vercel + Astro 部署的 pnpm 锁文件报错

第一步：在 GitHub 网页端修改布局文件#

1. 顶部导入 Analytics 组件#

2. 在 body 标签内部插入组件#

第二步：Vercel 部署报错：pnpm 锁文件冲突#

第三步：使用 GitHub Codespaces 妙解锁文件冲突#

1. 召唤云端编辑器#

2. 在云端运行安装命令#

3. 提交并推送更改#

🎉 大功告成#

Astro 博客排坑指南：使用 Qexo 管理时的日期类型校验错误排查

🔍 问题现象与排查#

日志核心提示：#

🛠️ 根源分析#

💡 解决方案：使用 z.coerce.date()#

操作步骤#

修改前代码：#

修改后代码：#

⚠️ 避坑补充指南#

🎉 总结#

让自建 memos 服务完美融合在 Astro 博客里面

使用 Docker 自建 Memos 服务#

1. 编写 Docker Compose 配置文件#

2. 启动容器#

使用 Cloudflare Tunnel 配置内网穿透与 HTTPS#

1. 在 Cloudflare Zero Trust 中创建 Tunnel#

2. 配置 Public Hostname（公网域名）#

在 Astro 博客（Firefly 主题为例）中接入 Memos 数据源#

1. 开启动态页总开关#

2. 修改动态配置文件启用 Memos#

配置项说明：#

效果与特性#

在 Vercel 部署 Astro 的 Firefly 主题模板

为什么选择 Astro + Firefly？#

部署步骤：比想象中更简单#

1. 准备工作与仓库 Fork#

2. 基础配置与个性化#

3. 在 Vercel 上一键托管#

写在最后#

博客迁移 Astro 并接入 Qexo 3.7.0 后台折腾手记

为什么选择 Astro 与 Qexo 3.7.0？#

迁移与部署实录#

1. 部署 Astro 博客前台#

2. 部署 Qexo 3.7.0 后台#

3. 对接与调优：让 Qexo 顺畅管理 Astro#

遇到的一个小插曲#

写在最后#

Vercel 与 Cloudflare 优选 IP 加速完整指南

核心原理解析#

准备工作#

实操配置步骤#

1：在 Vercel 中绑定域名^^www.aichuangshi.com#

2：在 Cloudflare 配置 SaaS（自定义主机名）^^星の住処#

后端 API 接口实现 (`src/pages/api/ai.ts`)#

前端悬浮挂件与 UI 落地 (`Layout.astro` 或根布局)#

2. 交互与无刷新挂载脚本 (`<script>`)#

完整组件代码 (`CategoryBar.astro`)#

坑二：Telegram 到底算什么分类？别啥都往 `fa-solid` 塞！#

顺便附赠：如何写出让部署更稳的 `astro.config.mjs`#

📝 完整 `Footer.astro` 结构参考#

💡 解决方案：使用 `z.coerce.date()`#