流萤 / Firefly

一款清新美观的 Astro 静态博客主题模板

QQ交流群：1087127207

---

📖 README： 简体中文 | 繁體中文 | English | 日本語 | Русский

🚀 快速指南： 🖥️在线预览 / 📝使用文档 / 🍀我的博客

⚡ 静态站点生成: 基于Astro的超快加载速度和SEO优化

🎨 现代化设计: 简洁美观的界面，支持自定义主题色

📱 移动友好: 完美的响应式体验，移动端专项优化

🔧 高度可配置: 大部分功能模块均可通过配置文件自定义

Tip

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

在重要的布局上，Firefly 创新性地增加了左右双侧边栏、文章网格(多列)布局、瀑布流布局。

增加了站点统计、日历、文章目录、音乐播放器、快捷分类导航等小组件，让侧边栏和整体页面布局更加丰富。

同时也增加了分享海报、相关文章推荐、随机文章等组件，让文章页面内容更丰富。

如果你参考或使用了 Firefly 以上组件设计和相关代码，请注明来自 Firefly。

Firefly 也保留了原版 fuwari 的布局，可根据自己的喜好在配置文件中自由切换。

更多布局配置及演示请查看：Firefly 布局系统详解

Firefly 支持i18n多语言UI，但除了简体中文，其他语言均为AI翻译转换，如有错误，欢迎提交 Pull Request 修正。

✨ 功能特性

核心功能

• Astro + Tailwind CSS - 基于现代技术栈的超快静态站点生成
• 流畅动画 - Swup 页面过渡动画，提供丝滑的浏览体验
• 响应式设计 - 完美适配桌面端、平板和移动设备
• 多语言支持 - i18n 国际化，UI支持简体中文、繁体中文、英文、日文、俄语
• 全文搜索 - 基于 Pagefind 的客户端搜索，支持文章内容索引

个性化

• 动态侧边栏 - 支持配置单侧边栏、双侧边栏
• 文章布局 - 支持配置(单列)列表、网格(多列/瀑布流)布局
• 字体管理 - 支持自定义字体，丰富的字体选择器
• 页脚配置 - HTML 内容注入，完全自定义
• 亮暗色模式 - 支持亮色/暗色/跟随系统三种模式
• 导航栏自定义 - Logo、标题、链接全面自定义
• 壁纸模式切换 - 横幅壁纸、全屏透明壁纸、纯色背景
• 主题色自定义 - 360° 色相调节

如果你有好用的功能和优化，请提交 Pull Request

🚀 快速开始

环境要求

• Node.js ≥ 22
• pnpm ≥ 11

本地开发部署

1. 克隆仓库：

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

   先 Fork 到自己仓库再克隆（推荐），记得先点 Star 在 Fork 哦！

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

2. 安装依赖：

   # 如果没有安装 pnpm，先安装仓库要求的版本
   npm install -g pnpm@11.14.0
   
   # 安装项目依赖
   pnpm install

3. 配置博客：

   • 编辑 src/config/ 目录下的配置文件自定义博客设置

4. 启动开发服务器：

   pnpm dev

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

平台托管部署

• 参考官方指南将博客部署至 Vercel, Netlify, Cloudflare Pages, EdgeOne Pages 等。

• Vercel、Netlify 等主流平台自动部署，会根据环境自动选择适配器。

• 本仓库当前通过 Cloudflare Pages 部署。

  框架预设： Astro

  根目录： ./

  输出目录： dist

  构建命令： pnpm run build

  安装命令： pnpm install

  

搜索引擎收录

• 站点地图索引位于生产域名的 /sitemap-index.xml。
• Google Search Console 和 Bing Webmaster Tools 提交站点地图索引。
• 百度搜索资源平台优先提交生产域名的 /sitemap-0.xml。
• Cloudflare Pages 的浏览器缓存与 pages.dev 防重复索引规则位于 public/_headers。

📖 配置说明

📚 详细配置文档: 查看 Firefly使用文档 获取完整的配置指南

设置网站语言

要设置博客的默认语言，请编辑 src/config/siteConfig.ts 文件：

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

支持的语言代码：

• zh_CN - 简体中文
• zh_TW - 繁体中文
• en - 英文
• ja - 日文
• ru - 俄文

配置文件结构

src/
├── config/
│   ├── index.ts              # 配置索引文件
│   ├── siteConfig.ts         # 站点基础配置
│   ├── backgroundWallpaper.ts # 背景壁纸配置
│   ├── profileConfig.ts      # 用户资料配置
│   ├── commentConfig.ts      # 评论系统配置
│   ├── announcementConfig.ts # 公告配置
│   ├── licenseConfig.ts      # 许可证配置
│   ├── footerConfig.ts       # 页脚配置
│   ├── FooterConfig.html     # 页脚HTML内容
│   ├── expressiveCodeConfig.ts # 代码高亮配置
│   ├── sakuraConfig.ts       # 樱花特效配置
│   ├── fontConfig.ts         # 字体配置
│   ├── sidebarConfig.ts      # 侧边栏布局配置
│   ├── navBarConfig.ts       # 导航栏配置
│   ├── musicConfig.ts        # 音乐播放器配置
│   ├── pioConfig.ts          # 看板娘配置
│   ├── adConfig.ts           # 广告配置
│   ├── friendsConfig.ts      # 友链配置（友链数据在 src/data/friends.csv）
│   ├── galleryConfig.ts      # 相册配置
│   ├── sponsorConfig.ts      # 赞助配置
│   └── coverImageConfig.ts  # 文章封面图配置

⚙️ 文章 Frontmatter

---
title: My First Blog Post
published: 2023-09-09
description: This is the first post of my new Astro blog.
image: ./cover.jpg # 或使用 "api" 来启用随机封面图
tags: [Foo, Bar]
category: Front-end
draft: false
lang: zh-CN # 仅当文章语言与 `siteConfig.ts` 中的网站语言不同时需要设置
pinned: false # 置顶
comment: true # 是否允许评论
---

📝 使用 Pages CMS 管理内容

本仓库支持通过 Pages CMS 在线编辑博客内容，采用 staging → master 双分支工作流避免每次保存触发 Cloudflare Pages 生产构建。

工作流程

1. 日常编辑 — 在 Pages CMS 中切换到 staging 分支进行文章修改
   • 访问 https://pagescms.org/repos/{你的用户名}/{仓库名}/?branch=staging
   • 每次保存只会 commit 到 staging 分支，不会触发 Cloudflare Pages 生产构建
2. 发布上线 — 修改完成后，在 Pages CMS 侧边栏点击 "发布到生产环境" 按钮
   • 自动触发 GitHub Actions 将 staging 分支合并到 master
   • Cloudflare Pages 检测到 master 变更后自动构建部署
3. 自动同步 — 当 master 通过其他方式（如 PR 合并）更新时，会通过 GitHub Actions 自动合并到 staging，保持两个分支同步

首次使用

1. 在 Pages CMS 中授权 GitHub 账户
2. 打开 Pages CMS 并选择本仓库（指定 ?branch=staging 参数）
3. 开始编辑内容

配置说明

CMS 配置文件为根目录的 .pages.yml，定义了可编辑的内容模型、媒体资源路径，以及 "发布到生产环境" 按钮（actions 配置，触发 .github/workflows/publish.yml）。

可编辑的内容包括：文章集合、关于页面、友链页面、留言板、友链 CSV 数据，以及学习数据（src/data/study-data.json）。友链数据目前使用 CSV 代码编辑器维护，表头必须保持 title,imgurl,desc,siteurl,tags,weight,enabled；enabled 列填 true 才会在友链页面显示，tags 列用英文分号分隔多个标签，如 Blog;Tech。学习数据可在 Pages CMS 中通过课程和学习记录字段编辑。

Pages CMS 当前版本的 CSV datagrid 保存存在已知问题，因此友链配置明确使用代码编辑器，避免出现表格界面修改后内容没有写回 CSV 的情况。

注意：

• 如果你 Fork 此仓库，.pages.yml 中的配置会自动生效，无需额外修改。
• Pages CMS 的 actions 按钮通过 workflow_dispatch 触发工作流时，会强制附带一个 payload 输入（包含 sha、条目路径等上下文信息）。因此被触发的工作流必须在 on.workflow_dispatch.inputs 中声明 payload，否则 GitHub API 会报错 Unexpected inputs provided: ["payload"]。

🧩 Markdown 扩展语法

除了 Astro 默认支持的 GitHub Flavored Markdown 之外，还包含了一些额外的 Markdown 功能：

• 提醒块（Admonitions） - 支持 GitHub, Obsidian, VitePress 三种风格主题配置 (预览和用法)
• GitHub 仓库卡片 (预览和用法)
• 基于 Expressive Code 的增强代码块 (预览 / 文档)

🧞 指令

下列指令均需要在项目根目录执行：

Command	Action
pnpm install	安装依赖
pnpm dev	在 localhost:4321 启动本地开发服务器
pnpm build	构建网站至 ./dist/
pnpm preview	本地预览已构建的网站
pnpm check	检查代码中的错误
pnpm format	使用Biome格式化您的代码
pnpm new-post <filename>	创建新文章
pnpm astro ...	执行 astro add, astro check 等指令
pnpm astro --help	显示 Astro CLI 帮助

🙏 致谢

非常感谢 saicaca 开发的 fuwari 模板，Firefly 就是基于这个模板二次开发

流萤部分相关图片素材版权归游戏 《崩坏：星穹铁道》 开发商 米哈游 所有

技术栈

• Astro
• Tailwind CSS
• Iconify

灵感项目

• fuwari
• hexo-theme-shoka
• astro-koharu
• Mizuki

其他参考

• 博主霞葉的 Bangumi 收藏 页面组件
• 哔哩哔哩up主 公公的日常 的Q版 流萤看板娘Spine切片数据

📝 许可协议

本项目遵循 MIT license 开源协议，详细查看 LICENSE 文件

最初 Fork 自 saicaca/fuwari，感谢原作者的贡献

版权声明：

• Copyright (c) 2024 saicaca - fuwari
• Copyright (c) 2025 CuteLeaf - Firefly

根据 MIT 开源协议，你可以自由使用、修改、分发代码，但需保留上述版权声明。

🍀 贡献者

感谢以下贡献者对本项目做出的贡献，如有问题或建议，请提交 Issue 或 Pull Request。

感谢以下贡献者对原项目 fuwari 做出的贡献，为本项目奠定了基础。

⭐ Star History