站点配置

站点配置是 Firefly 主题的核心配置文件，控制站点的基本信息、主题色、页面开关等全局设置。

配置文件

src/config/siteConfig.ts

基础信息

属性	类型	默认值	说明
`title`	`string`	`"Firefly"`	站点标题
`subtitle`	`string`	`"Demo site"`	站点副标题
`site_url`	`string`	-	站点 URL
`description`	`string`	-	站点描述，用于 `<meta name="description">`
`keywords`	`string[]`	-	站点关键词，用于 `<meta name="keywords">`
`lang`	`string`	`"zh_CN"`	站点语言，支持 `zh_CN`、`zh_TW`、`en`、`ja`、`ru`、`ko`。可用环境变量 `PUBLIC_SITE_LANG` 覆盖（见下方提示）

export const siteConfig: SiteConfig = {
  title: "Firefly",
  subtitle: "Demo site",
  site_url: "https://firefly.cuteleaf.cn",
  description: "Firefly 是一款基于 Astro 框架...",
  keywords: ["Firefly", "Astro", "博客"],
  lang: "zh_CN",
};

环境变量覆盖站点语言

lang 可以用环境变量 PUBLIC_SITE_LANG 覆盖，优先级高于配置文件。例如在部署平台（Vercel / Cloudflare 等）设置 PUBLIC_SITE_LANG=en 即可让整个站点（含导航栏、页面文案）以英文构建，无需修改配置文件。支持 en / zh_cn / zh_tw / ja / ja_jp / ru / ko 等取值，大小写不敏感；无法识别时回退到配置文件里的默认值。

主题色

属性	类型	默认值	说明
`themeColor.hue`	`number`	`165`	主题色色相，范围 0-360。红色：0，青色：200，蓝绿色：250，粉色：345
`themeColor.defaultMode`	`string`	`"system"`	默认模式：`"light"` 亮色、`"dark"` 暗色、`"system"` 跟随系统

themeColor: {
  hue: 165,
  defaultMode: "system",
},

页面宽度

属性	类型	默认值	说明
`pageWidth`	`number`	`100`	页面整体最大宽度，单位 `rem`。数值越大页面内容区域越宽

// 页面整体宽度（单位：rem）
// 数值越大可以让页面内容区域更宽
pageWidth: 100,

卡片样式

属性	类型	默认值	说明
`card.border`	`boolean`	`true`	是否开启卡片边框和阴影，开启后让网站更有立体感
`card.followTheme`	`boolean`	`false`	卡片背景是否在浅色模式下跟随主题色相

card: {
  border: true,
  followTheme: false,
},

导航栏

属性	类型	默认值	说明
`navbar.logo`	`object`	-	导航栏 Logo，详见下方
`navbar.title`	`string`	`"Firefly"`	导航栏标题
`navbar.widthFull`	`boolean`	`false`	导航栏是否占满屏幕宽度
`navbar.menuAlign`	`string`	`"center"`	桌面端导航菜单对齐方式：`"left"` 或 `"center"`
`navbar.followTheme`	`boolean`	`false`	导航栏图标和标题是否跟随主题色
`navbar.navbarMode`	`"static" \| "fixed" \| "dynamic"`	`"fixed"`	导航栏模式：`static` 不固定随页滚动；`fixed` 固定在顶部常显；`dynamic` 固定在顶部，下滑隐藏、轻微上滑显示

Logo 支持四种类型：

Astro 图标库：{ type: "icon", value: "material-symbols:home-pin-outline" }
public 目录图片（不优化）：{ type: "image", value: "/assets/images/logo.webp", alt: "Logo" }
src 目录图片（自动优化，推荐）：{ type: "image", value: "assets/images/logo.webp", alt: "Logo" }
网络图片：{ type: "url", value: "https://example.com/logo.png", alt: "Logo" }

属性	类型	默认值	说明
`logo.type`	`string`	-	`"icon"`、`"image"` 或 `"url"`
`logo.value`	`string`	-	图标名、图片路径或图片 URL
`logo.valueDark`	`string`	-	暗色模式下使用的另一张图片，仅 `image` 和 `url` 类型生效
`logo.alt`	`string`	-	图片的 alt 文本

设置 valueDark 后，亮色和暗色模式会分别显示两张不同的图片，切换主题时即时生效；不设置则两种模式共用 value。图标库（type: "icon"）会跟随文字颜色，无需单独配置暗色版本。

navbar: {
  logo: {
    type: "image",
    value: "assets/images/firefly.png",
    // 暗色模式下换用另一张图片（可选）
    valueDark: "assets/images/firefly-dark.png",
    alt: "🍀",
  },
  title: "Firefly",
  widthFull: false,
  menuAlign: "center",
  followTheme: false,
  navbarMode: "fixed",
},

TIP

分享海报顶部会显示导航栏的 Logo 和站点标题。由于海报背景固定为白色，海报中始终使用亮色版本的 Logo。

Favicon

favicon: [
  {
    src: "/favicon/favicon.ico",
    // theme: "light",  // 可选，指定主题 'light' | 'dark'
    // sizes: "32x32",  // 可选，图标大小
  },
],

日期与时区

属性	类型	默认值	说明
`siteStartDate`	`string`	-	站点开始日期（`YYYY-MM-DD`），用于统计运行天数
`timezone`	`string`	`"Asia/Shanghai"`	IANA 时区字符串，用于格式化日期时间

提醒框（Admonitions）

属性	类型	默认值	说明
`rehypeCallouts.theme`	`string`	`"github"`	提醒框主题：`"github"`、`"obsidian"`、`"vitepress"`、`"docusaurus"`
`rehypeCallouts.enablePythonMarkdownAdmonitions`	`boolean`	`false`	是否启用 Python Markdown 风格的提醒框语法（使用 `!!!` 代替 `> [!NOTE]`）

TIP

修改此配置后需要重启开发服务器才能生效。

文章配置

属性	类型	默认值	说明
`post.showLastModified`	`boolean`	`true`	是否显示文章底部的"上次编辑时间"卡片
`post.outdatedThreshold`	`number`	`30`	文章过期阈值（天数），超过此天数才显示"上次编辑"卡片
`post.share`	`boolean`	`true`	是否显示文章页的分享按钮
`post.postNavigation`	`boolean`	`true`	是否显示上一篇/下一篇文章导航
`post.relatedPosts`	`boolean`	`true`	是否显示相关文章推荐
`post.randomPosts`	`boolean`	`true`	是否显示随机文章推荐
`post.generateOgImages`	`boolean`	`false`	是否生成 OpenGraph 图片（开启后构建时间较长）

文章列表布局

属性	类型	默认值	说明
`postListLayout.defaultMode`	`string`	`"list"`	默认布局：`"list"` 列表模式，`"grid"` 网格模式
`postListLayout.mobileDefaultMode`	`string`	`-`	移动端默认布局：`"list"` 或 `"grid"`，不设置时跟随 `defaultMode`
`postListLayout.coverPosition`	`string`	`"right"`	列表模式下封面图位置：`"right"` 右侧，`"left"` 左侧。网格模式封面固定在卡片顶部，不受此项影响
`postListLayout.descriptionLines`	`number`	`2`	文章简介显示行数，设为 `0` 则不截断
`postListLayout.showStatsIcons`	`boolean`	`true`	文章卡片底部统计（发布日期、字数、阅读时长）是否显示图标
`postListLayout.tagsPosition`	`string`	`"meta"`	标签显示位置：`"meta"` 显示在标题下的元数据行，`"bottom"` 显示在卡片底部（将替换 stats 显示，二者只能选其一）。`"bottom"` 时标签数超出 `meta.tagCount` 会追加一个 `+N` 标记，鼠标悬停可查看被折叠的标签
`postListLayout.tagsBottomStyle`	`string`	`"chip"`	底部标签样式，仅在 `tagsPosition` 为 `"bottom"` 时生效：`"chip"` 带底色的按钮，形状跟随 `tagStyle`；`"text"` 无底色，只有文字
`postListLayout.grid.masonry`	`boolean`	`false`	是否开启瀑布流布局
`postListLayout.grid.columnWidth`	`number`	`320`	网格模式卡片最小宽度(px)，浏览器根据容器宽度自动计算列数
`postListLayout.grid.coverFullWidth`	`boolean`	`false`	网格模式封面是否撑满卡片贴边。`true` 时封面顶到卡片上、左、右边缘，只有上面两角是圆角；`false` 时封面按卡片内边距内缩，上、左、右留出间距，四角都是圆角（间距随屏幕宽度变化，与卡片内边距一致）

PostMeta 元数据显示控制

控制文章卡片标题下方元数据行中各元素的显示。

属性	类型	默认值	说明
`postListLayout.meta.showPublished`	`boolean`	`true`	是否显示发布日期
`postListLayout.meta.showCategory`	`boolean`	`true`	是否显示分类
`postListLayout.meta.showTags`	`boolean`	`true`	是否显示标签
`postListLayout.meta.tagCount`	`number`	`1`	标签数量，设为 `0` 则不限制。`tagsPosition` 为 `"bottom"` 时，超出的标签会折叠成一个 `+N` 标记
`postListLayout.meta.showWords`	`boolean`	`true`	是否显示字数
`postListLayout.meta.showReadingTime`	`boolean`	`true`	是否显示阅读时间

PostStats 底部统计显示控制

控制文章卡片底部统计栏中各元素的显示。当 tagsPosition 设置为 "bottom" 时，stats 将不显示。

属性	类型	默认值	说明
`postListLayout.stats.showPublished`	`boolean`	`true`	是否显示发布日期
`postListLayout.stats.showWords`	`boolean`	`true`	是否显示字数
`postListLayout.stats.showReadingTime`	`boolean`	`true`	是否显示阅读时间

分类与标签样式

分类导航栏按钮和标签 chip 都可以在「胶囊」和「矩形」两种形状之间切换，两项互相独立。

属性	类型	默认值	说明
`categoryStyle`	`string`	`"rectangle"`	分类导航栏按钮样式：`"pill"` 胶囊，`"rectangle"` 矩形
`tagStyle`	`string`	`"pill"`	标签样式：`"pill"` 胶囊（主题色底），`"pill-gray"` 胶囊（中性灰底），`"rectangle"` 矩形（主题色底）

categoryStyle: "rectangle",
tagStyle: "pill",

categoryStyle

只改变形状，不改变配色 —— "rectangle" 沿用胶囊的全部配色（含 hover、当前分类高亮、文章数徽章），仅把圆角收小。

作用范围仅限分类导航栏（首页和归档页顶部，由 categoryBar 控制是否显示）。友链、相册、书签导航页的筛选按钮不受影响，始终保持胶囊。

tagStyle

取值	外观
`"pill"`	全圆角胶囊，主题色底（`--btn-content` 淡色调），hover 时加深并变为主题强调色
`"pill-gray"`	全圆角胶囊，中性灰底，hover 时变为主题色底
`"rectangle"`	小圆角矩形，直接使用主题色底（`--btn-regular-bg`），hover / 按下有深浅变化

同时作用于三处标签：

文章列表卡片的标签（元数据行内，以及 tagsPosition: "bottom" 时的底部标签，包含 +N 折叠标记）
标签页 /tags 的标签及其文章数徽章
侧边栏标签 widget

TIP

postListLayout.tagsBottomStyle 设为 "text" 时底部标签没有底色，tagStyle 对它不生效；其他两处标签仍按 tagStyle 渲染。

分页配置

属性	类型	默认值	说明
`pagination.postsPerPage`	`number`	`10`	每页显示的文章数量

页面开关

属性	类型	默认值	说明
`pages.friends`	`boolean`	`true`	友链页面开关
`pages.sponsor`	`boolean`	`true`	打赏页面开关
`pages.guestbook`	`boolean`	`true`	留言板页面开关（需配置评论系统）
`pages.bangumi`	`boolean`	`true`	番组计划页面开关
`pages.vndb`	`boolean`	`true`	VNDB 页面开关
`pages.gallery`	`boolean`	`true`	相册页面开关
`pages.bilibili`	`boolean`	`true`	哔哩哔哩追番页面开关
`pages.dynamic`	`boolean`	`true`	动态页面开关，同时控制动态导航入口和动态侧边栏
`pages.booknav`	`boolean`	`true`	书签导航页面开关
`pages.mal`	`boolean`	`true`	MyAnimeList 页面开关
`categoryBar`	`boolean`	`true`	分类导航栏开关，在首页和归档页顶部显示分类快捷导航

环境变量覆盖

所有页面开关都可以用环境变量覆盖，优先级高于配置文件。例如在部署平台（Vercel / Cloudflare 等）设置 PUBLIC_PAGES_BILIBILI=true 即可开启哔哩哔哩页面，无需修改配置文件；设置 PUBLIC_PAGES_FRIENDS=false 即可关闭友链页面。取值为 true / 1 / on 等表示开启，false / 0 / off 等表示关闭。

显示设置面板

显示设置面板是导航栏中的齿轮图标打开的设置面板，允许访客自定义主题色、壁纸模式、卡片样式等。

详见显示设置面板。

Bangumi 配置

属性	类型	默认值	说明
`bangumi.userId`	`string`	-	Bangumi 用户 ID
`bangumi.mode`	`"static" \| "dynamic"`	`"dynamic"`	数据模式。`static` 在构建时获取数据并静态渲染；`dynamic` 在浏览器中实时请求 API，始终显示最新数据
`bangumi.apiUrl`	`string`	`"https://api.bangumi.one"`	Bangumi API 地址
`bangumi.subjectBaseUrl`	`string`	`"https://bangumi.one/subject/"`	条目详情页地址
`bangumi.categoryOrder`	`string[]`	`["anime", "book", "music", "game"]`	条目类型排序，数组中的类型将按顺序优先展示。可选值：`"anime"` `"book"` `"music"` `"game"` `"real"`
`bangumi.nsfw`	`"off" \| "blur" \| "hide"`	`"off"`	NSFW 处理：`off` 全部显示，`blur` 模糊封面，`hide` 隐藏条目

TIP

static 模式下，dev 调试时只获取一页数据，build 才会获取全部数据。dynamic 模式下数据在浏览器中实时获取，始终为最新状态。

VNDB 配置

属性	类型	默认值	说明
`vndb.userId`	`string`	`""`	VNDB 用户 ID，形如 `u2`
`vndb.mode`	`"static" \| "dynamic"`	`"static"`	数据模式。`static` 在构建时获取数据并静态渲染；`dynamic` 在浏览器中实时请求 API，始终显示最新数据
`vndb.downloadCovers`	`boolean`	`false`	构建时下载并压缩封面到 `public/vndb-covers`，图片由本站服务器提供，仅 `static` 模式生效
`vndb.apiUrl`	`string`	`"https://api.vndb.org/kana"`	VNDB API 地址
`vndb.vnBaseUrl`	`string`	`"https://vndb.org/"`	条目详情页地址，末尾需要带 `/`
`vndb.apiToken`	`string`	`""`	私密列表访问令牌，仅 `static` 模式生效。不要把真实令牌提交到公开仓库
`vndb.nsfw`	`"off" \| "blur" \| "hide"`	`"blur"`	NSFW 处理：`off` 全部显示，`blur` 模糊封面，`hide` 隐藏条目

详见 VNDB。

统计分析

属性	类型	默认值	说明
`analytics.googleAnalyticsId`	`string`	`""`	Google Analytics ID
`analytics.microsoftClarityId`	`string`	`""`	Microsoft Clarity ID
`analytics.umamiAnalytics.websiteId`	`string`	`""`	Umami 网站 ID
`analytics.umamiAnalytics.scriptUrl`	`string`	`"https://cloud.umami.is/script.js"`	Umami 跟踪脚本地址（支持自建 Umami）
`analytics.umamiAnalytics.replaysScriptUrl`	`string`	`"https://cloud.umami.is/recorder.js"`	Umami 会话回放脚本地址（支持自建 Umami）
`analytics.umamiAnalytics.trackOutboundLinks`	`boolean`	`true`	是否自动为站外链接添加 Umami 出站点击事件
`analytics.umamiAnalytics.collectWebVitals`	`boolean`	`false`	是否开启 `data-performance="true"` 以收集核心网页指标
`analytics.umamiAnalytics.replays.enabled`	`boolean`	`false`	是否开启 Umami 会话回放
`analytics.umamiAnalytics.replays.sampleRate`	`number`	`0.15`	回放采样率，范围 `0` 到 `1`，例如 `0.15` 表示录制 15% 的会话
`analytics.umamiAnalytics.replays.maskLevel`	`"moderate" \| "strict"`	`"moderate"`	隐私遮罩级别；`moderate` 遮罩输入框，`strict` 额外遮罩页面全部文本
`analytics.umamiAnalytics.replays.maxDuration`	`number`	`300000`	单次录制最大时长（毫秒），默认 5 分钟
`analytics.umamiAnalytics.replays.blockSelector`	`string`	`""`	要完全排除录制的元素 CSS 选择器；留空时不会输出该属性
`analytics.la51Analytics.Id`	`string`	`""`	51la 统计 ID
`analytics.la51Analytics.sdkUrl`	`string`	`""`	自定义 SDK 地址（留空使用默认地址）
`analytics.la51Analytics.ck`	`string`	`""`	多个统计 ID 的数据分离标识
`analytics.la51Analytics.autoTrack`	`boolean`	`false`	是否开启事件分析功能
`analytics.la51Analytics.hashMode`	`boolean`	`false`	是否开启 Hash 路由模式
`analytics.la51Analytics.screenRecord`	`boolean`	`true`	是否开启网站录屏功能

analytics: {
  googleAnalyticsId: "",
  microsoftClarityId: "",
  umamiAnalytics: {
    websiteId: "",
    scriptUrl: "https://cloud.umami.is/script.js",
    replaysScriptUrl: "https://cloud.umami.is/recorder.js",
    trackOutboundLinks: true,
    collectWebVitals: false,
    replays: {
      enabled: false,
      sampleRate: 0.15,
      maskLevel: "moderate",
      maxDuration: 300000,
      blockSelector: "",
    },
  },
  la51Analytics: {
    Id: "",
    sdkUrl: "",
    ck: "",
    autoTrack: false,
    hashMode: false,
    screenRecord: true,
  },
},

如果你使用自建 Umami，请将 analytics.umamiAnalytics.scriptUrl 和 analytics.umamiAnalytics.replaysScriptUrl 改为你自己的脚本地址。

图像优化

属性	类型	默认值	说明
`imageOptimization.formats`	`string`	`"webp"`	输出格式：`"avif"`、`"webp"`、`"both"`（推荐）
`imageOptimization.quality`	`number`	`85`	压缩质量 (1-100)，推荐 70-85
`imageOptimization.noReferrerDomains`	`string[]`	`[]`	需要添加防盗链处理的域名列表，支持通配符 `*`

WARNING

Astro 仅能对 src 目录下的图像进行优化。src 目录下的图像越多，构建时间越长。

防盗链处理

部分图床或 CDN（如 B站图床）会通过检查 Referer 请求头来实施防盗链策略，导致在博客中引用这些图片时返回 403 错误。

配置 noReferrerDomains 后，Firefly 会自动为匹配域名的 <img> 标签添加 referrerpolicy="no-referrer" 属性，使浏览器在请求图片时不发送 Referer 头，从而绕过防盗链限制。

imageOptimization: {
  formats: "webp",
  quality: 85,
  noReferrerDomains: [
    "i0.hdslb.com",     // B站图床
    "i1.hdslb.com",
    "i2.hdslb.com",
    "*.bilibili.com",   // 支持通配符
  ],
},

TIP

仅对 http:// 或 https:// 开头的外部图片生效，不影响本地图片
仅影响匹配域名的 <img> 标签，不影响其他链接的 referrer 行为
Markdown 中带有 alt 文本的图片仍然会正常生成 <figcaption>

站点配置 ​

配置文件 ​

基础信息 ​

主题色 ​

页面宽度 ​

卡片样式 ​

导航栏 ​

Favicon ​

日期与时区 ​

提醒框（Admonitions） ​

文章配置 ​

文章列表布局 ​

PostMeta 元数据显示控制 ​

PostStats 底部统计显示控制 ​

分类与标签样式 ​

categoryStyle ​

tagStyle ​

分页配置 ​

页面开关 ​

显示设置面板 ​

Bangumi 配置 ​

VNDB 配置 ​

统计分析 ​

图像优化 ​

防盗链处理 ​