方案简介

Firefly（流萤）是一款基于 Astro 框架和 Fuwari 模板开发的清新美观且现代化的个人博客主题模板，专为技术爱好者和内容创作者设计。它融合了现代 Web 技术栈：Astro 负责超快加载速度的静态站点生成与 SEO 优化，Tailwind CSS 提供现代化简洁界面，Swup 提供页面过渡动画，Pagefind 提供基于文章内容索引的客户端全文搜索，TypeScript 保证代码质量。主题提供了丰富的功能模块和高度可定制的界面，让用户能够轻松打造出专业且美观的个人博客网站。适合想要快速搭建静态博客、注重性能与个性化外观的开发者和创作者。

亮点与能力

• 静态站点生成：基于 Astro 的超快加载速度和 SEO 优化
• 流畅动画：Swup 页面过渡动画，提供丝滑的浏览体验
• 响应式设计：完美适配桌面端、平板和移动设备
• 多语言支持：i18n 国际化，UI 支持简体中文、繁体中文、英文、日文、俄语、韩文
• 全文搜索：基于 Pagefind 的客户端搜索，支持文章内容索引
• Markdown 扩展语法：提醒块（Admonitions）、GitHub 仓库卡片、基于 Expressive Code 的增强代码块
• 个性化：动态侧边栏、文章布局（列表/网格/瀑布流）、字体管理、壁纸模式切换、360° 色相调节、亮暗色模式
• 动态功能：本地 Markdown 动态或对接 Memos 作为数据源

组成与分工

• Astro：核心静态站点生成框架，提供超快加载速度和 SEO 优化
• Tailwind CSS：现代化样式方案，实现简洁美观的界面
• TypeScript：项目开发语言
• Swup：页面过渡动画库，提供丝滑的浏览体验
• Pagefind：客户端全文搜索，支持文章内容索引
• Expressive Code：增强代码块与代码高亮
• pnpm：包管理与脚本执行工具
• Fuwari：Firefly 基于的原版模板，保留原版布局可自由切换

前置要求

环境要求：

• Node.js ≥ 22
• pnpm ≥ 11

如果没有安装 pnpm，可先全局安装：

bash
npm install -g pnpm

实施步骤

1. 克隆仓库

bash
git clone https://github.com/Cuteleaf/Firefly.git
cd Firefly

推荐先 Fork 到自己仓库再克隆：

bash
git clone https://github.com/you-github-name/Firefly.git
cd Firefly

2. 安装依赖

bash

安装项目依赖

pnpm install

3. 配置博客

编辑 src/config/ 目录下的配置文件自定义博客设置，例如在 src/config/siteConfig.ts 中设置站点语言：

typescript
// 定义站点语言
const SITE_LANG = "zh_CN";

4. 启动开发服务器

bash
pnpm dev

博客将在 http://localhost:4321 可用。

5. 平台托管部署

参考官方指南将博客部署至 Vercel、Netlify、Cloudflare Pages、EdgeOne Pages 等。框架预设为 Astro，根目录 ./，输出目录 dist，构建命令 pnpm run build，安装命令 pnpm install。

使用与配置要点

• 创建文章：pnpm new-post ，文章使用 Frontmatter 定义标题、发布日期、描述、封面图、标签、分类、置顶、评论等
• 创建动态：pnpm new-d 今天心情不错，出去吃了一顿火锅，动态文件保存在 src/content/dynamic/ 中，一个 Markdown 文件对应一条动态；也可对接 Memos 实时获取动态
• 构建与预览：pnpm build 构建至 ./dist/，pnpm preview 本地预览
• 代码质量：pnpm check 检查代码错误，pnpm format 使用 Biome 格式化代码
• 更多布局配置：Firefly 保留了原版 fuwari 的布局，可在配置文件中自由切换

注意事项与常见问题

• 如果你参考或使用了 Firefly 的组件设计和相关代码，请注明来自 Firefly
• Firefly 支持 i18n 多语言 UI，但除了简体中文，其他语言均为 AI 翻译转换，如有错误欢迎提交 Pull Request 修正
• 设置文章语言 lang 仅当文章语言与 siteConfig.ts 中的网站语言不同时需要设置
• 所有指令均需要在项目根目录执行
• 有好用的功能和优化可以提交 Pull Request

优缺点

• ✓ 超快加载与SEO优化
• ✓ 高度可配置，模块化配置文件
• ✕ 要求 Node.js >= 22、pnp
• ✕ 除简中外多语言为AI翻译

出处

本方案挖掘自开源项目 CuteLeaf/Firefly，方案内容与实施命令均来自其 README 原文。