Coldairboy学习笔记

1. 从零开始部署 Firefly（流萤）Astro 博客并上线 GitHub Pages

Tue, 24 Mar 2026 00:00:00 GMT

直接给你最简可用版，照着复制粘贴就行

1. 项目地址#

GitHub：https://github.com/cccoder159/astro-firefly （如果觉得项目不错，给作者点个 ⭐ 吧！）

2. 环境准备（小白必看）#

在开始之前，需要先安装两个工具：

2.1 安装 Git#

Windows 用户：

访问 https://git-scm.com/download/win
下载最新版本，一路点击”Next”即可
安装完成后，打开命令行输入 git --version 验证

macOS 用户：

打开终端，输入：

Terminal window

1
git --version

如果没有安装，会提示你安装 Xcode Command Line Tools。

2.2 安装 Node.js#

Windows / macOS / Linux 用户：

访问 https://nodejs.org/
下载 LTS（长期支持版）推荐版本
双击安装包安装

安装完成后，打开命令行验证：

Terminal window

1
node --version
2
npm --version

看到版本号表示安装成功。

3. 本地快速运行#

先确保装了 Node.js（18+ 版本）

Terminal window

1
# 克隆项目
2
git clone https://github.com/cccoder159/astro-firefly.git
3
cd astro-firefly
4

5
# 安装依赖
6
npm install
7

8
# 本地预览
9
npm run dev

打开浏览器访问：http://localhost:4321

4. 基本配置（改个人信息）#

打开文件：src/config/siteConfig.ts

4.1 网站基本信息#

配置项	说明	示例
`title`	网站标题	”我的博客”
`subtitle`	网站副标题	”记录生活点滴”
`site_url`	网站域名	”https://example.com”
`description`	网站描述（SEO用）	“这是一个个人博客”

1
title: "我的博客",
2
subtitle: "记录生活点滴",
3
site_url: "https://example.com",
4
description: "这是一个个人博客",

4.2 导航栏配置#

配置项	说明
`navbar.title`	导航栏显示的标题
`navbar.logo`	logo 图标（可换图标）

4.3 功能开关#

配置项	说明
`pages.friends`	友链页面
`pages.sponsor`	赞助页面
`pages.guestbook`	留言板
`pages.bangumi`	番剧页面
`pages.gallery`	相册页面

设为 true 开启，false 关闭。

4.4 主题颜色#

1
themeColor: {
2
    hue: 250,        // 主题色相（0-360）
3
    fixed: false,    // 是否固定主题色
4
    defaultMode: "system",  // 默认模式：light/dark/system
5
},

4.5 其他常用配置#

配置项	说明
`categoryBar`	是否显示分类栏
`showLastModified`	是否显示最后修改时间
`sharePoster`	是否开启分享海报
`siteStartDate`	网站成立日期

5. 写文章#

文章放在：src/content/posts/xxx.md

格式示例：

1
---
2
title: 文章标题
3
date: 2026-04-18
4
categories: [分类]
5
tags: [标签1, 标签2]
6
---
7

8
这里写正文

6. 部署到 GitHub Pages#

方法一：使用 GitHub Actions 自动部署#

1. 创建 GitHub 仓库

在 GitHub 上创建一个新仓库，例如：astro-firefly

2. 上传代码到仓库

Terminal window展开收起

1
# 初始化 git
2
git init
3

4
# 添加所有文件
5
git add .
6

7
# 提交
8
git commit -m "first commit"
9

10
# 添加远程仓库（替换为你的仓库地址）
11
git remote add origin https://github.com/你的用户名/astro-firefly.git
12

13
# 推送
14
git branch -M main
15
git push -u origin main

展开收起

3. 创建 GitHub Actions 工作流

在仓库中创建文件：.github/workflows/deploy.yml

1
name: Deploy to GitHub Pages
2

3
on:
4
  push:
5
    branches: [main]
6

7
jobs:
8
  build:
9
    runs-on: ubuntu-latest
10
    steps:
11
      - uses: actions/checkout@v4
12

13
      - name: Setup Node
14
        uses: actions/setup-node@v4
15
        with:
16
          node-version: 20
17

18
      - name: Install pnpm
19
        uses: pnpm/action-setup@v2
20
        with:
21
          version: 8
22

23
      - name: Install dependencies
24
        run: pnpm install
25

26
      - name: Build
27
        run: pnpm run build
28

29
      - name: Upload Pages artifact
30
        uses: actions/upload-pages-artifact@v3
31
        with:
32
          path: dist
33

34
  deploy:
35
    needs: build
36
    runs-on: ubuntu-latest
37
    permissions:
38
      pages: write
39
      id-token: write
40
    environment:
41
      name: github-pages
42
      url: ${{ steps.deployment.outputs.page_url }}
43
    steps:
44
      - name: Deploy to GitHub Pages
45
        id: deployment
46
        uses: actions/deploy-pages@v4

展开收起

4. 配置 GitHub Pages

进入仓库 Settings → Pages：

Source 选择 GitHub Actions

5. 推送代码触发部署

Terminal window

1
git add .
2
git commit -m "add deploy workflow"
3
git push

等待几分钟后，你的博客就会上线：https://你的用户名.github.io/astro-firefly

方法二：手动部署#

Terminal window

1
# 构建项目
2
npm run build
3

4
# 安装 gh-pages（如果没安装）
5
npm install -g gh-pages
6

7
# 部署到 GitHub Pages
8
gh-pages -d dist

32.本周 GitHub 热门 AI 开源项目盘点（2026年9月第3周）

Mon, 07 Sep 2026 00:00:00 GMT

本周 GitHub 热门 AI 开源项目盘点（2026年9月第3周）#

每周精选 GitHub 上最值得关注的 AI 开源项目，帮你快速了解社区动态和技术趋势。

📊 本周概览#

排名	项目	Stars	语言	亮点
1	Cline	60K+	TypeScript	VS Code 里的自主编程 Agent，Plan/Act 双模式实战标杆
2	OpenCode	45K+	TypeScript	终端原生、模型无关的开源编程 Agent
3	RAGFlow	70K+	Python	深度文档理解的开源 RAG 引擎，企业知识库首选
4	aider	35K+	Python	Git 原生的终端结对编程，提交历史即工作记录
5	LightRAG	30K+	Python	港大出品，图谱增强 RAG 的轻量高性价方案
6	RAGAS	15K+	Python	RAG 系统的”单元测试框架”，LLM 评测标准工具

🔥 重点项目详解#

1. Cline — VS Code 里的自主编程 Agent#

仓库： cline/cline ⭐ 60,000+

Cline 是目前最流行的 IDE 内编程 Agent：在 VS Code 侧边栏里，它能读工程、改代码、跑终端命令、修报错，全程每一步都可以人工审批。本周社区热议的是它的”实战工作流”——Plan 模式先对齐方案、Act 模式再动手执行，配合检查点（Checkpoint）一键回滚，被很多人认为是”敢把 Agent 放进真实项目”的关键设计。

核心特性：

Plan/Act 双模式：先讨论方案再执行，避免”上来就改”的失控感
检查点与回滚：每次修改自动建快照，改坏了随时还原
模型无关：Anthropic / OpenAI / 本地 Ollama / 任意 OpenAI 兼容端点均可
MCP 生态：官方 Marketplace 一键接入外部工具与数据源

实战建议： 从”小步快跑”开始——一次只给一个明确任务，开启审批模式观察它的每一步操作，熟悉后再逐步放权。

2. OpenCode — 终端原生的开源编程 Agent#

仓库： sst/opencode ⭐ 45,000+

由 SST 团队打造的 OpenCode 是终端编程 Agent 里的当红炸子鸡：纯 TUI 交互、客户端/服务器架构、750K+ 周下载量，本周还拿到了 Anthropic 与 OpenAI 模型方的公开推荐。它把 Claude Code 式的体验做成了开源、可换模型、可远程驱动的版本——Agent 跑在服务器上，你在手机、桌面或终端里随时接管会话。

核心特性：

终端优先的 TUI 体验，支持会话共享与远程接管
接入 75+ 模型提供商，支持订阅账号（Claude Pro/Max、ChatGPT）直连
LSP 集成：Agent 改完代码立刻拿到语言服务器的诊断反馈
开源协议，插件与主题生态活跃

适合谁： 不想被单一厂商锁定、习惯终端工作流、需要”远程跑 Agent”的开发者。

3. RAGFlow — 深度文档理解的开源 RAG 引擎#

仓库： infiniflow/ragflow ⭐ 70,000+

RAGFlow 的口号是”基于深度文档理解的下一代 RAG”。它解决的是 RAG 落地最痛的一环：PDF、Word、Excel、扫描件里的表格、图片、版式怎么切分。内置多种可解释的切分模板（DeepDoc），切分结果可视化可调，答案自带原文引用，本周因 Agent 工作流与内存（Memory）功能的合入再次冲上趋势榜。

核心特性：

DeepDoc 版面分析：表格、图片、正文分开解析，减少”垃圾进垃圾出”
切分过程可视化：人工干预模板，答案质量可追溯
引用溯源：每条回答标注来源片段，企业场景刚需
本周新增：Agent 工作流编排 + 多轮对话记忆，向”企业级知识中枢”演进

适合谁： 要做内部知识库、文档问答、合规检索的团队——自托管、数据不出内网。

4. aider — Git 原生的终端结对编程#

仓库： Aider-AI/aider ⭐ 35,000+

老牌终端编程助手 aider 依然稳居热度榜。它的哲学和重型 Agent 相反：不做全自动，而是”结对”——你描述需求，它改代码并自动生成本地 git 提交，每一步都落在版本历史里。仓库地图（Repo Map）功能让它对大项目的上下文理解始终又快又省 token。

核心特性：

自动 git 提交：每次修改一个 commit，回滚就是 git revert
Repo Map：用 tree-sitter 索引全仓库，上下文精准且省 token
支持语音输入、图片输入（截图直接变成需求）
benchmark 套件开源，模型选型有据可依

实战建议： 适合”你有明确想法、需要快速落地”的场景；配合弱模型跑简单任务、强模型攻复杂重构，成本可以压得很低。

5. LightRAG — 图谱增强 RAG 的轻量方案#

仓库： HKUDS/LightRAG ⭐ 30,000+

港大 HKUDS 团队的 LightRAG（EMNLP 2025 论文）本周因新版检索策略发布再度上榜。它把 GraphRAG 式的”实体关系图谱 + RAG”做轻了：抽取实体关系建图，检索时融合低层实体与高层主题两种粒度，成本只有全量 GraphRAG 的一小部分，更新增量友好，不用每次重建索引。

核心特性：

图 + 向量混合检索：跨文档的”关系型问题”回答明显更稳
四种检索模式：local / global / hybrid / mix，按需选档
支持多模态：图片、表格也能入图检索
部署门槛低：几十行代码即可接入现有知识库

适合谁： 被”传统向量 RAG 答不好关系型问题”困扰，又不想承担 GraphRAG 重建成本的团队。

6. RAGAS — RAG 系统的”单元测试框架”#

仓库： explodinggradients/ragas ⭐ 15,000+

本周 RAG 榜单上最有”工程化信号”的项目。RAGAS 解决的是”我的 RAG 到底好不好”这个灵魂问题：不用人工一条条看答案，它用 LLM 自动给检索与生成打分——忠实度、答案相关性、上下文精度等指标一键产出，还能从原始文档自动生成测试数据集。本周它把无参考评估（reference-free）和 Agent 评测做进了同一套 API。

核心特性：

核心指标：faithfulness / answer relevancy / context precision 开箱即用
测试集自动生成：从你的文档反向合成问答对
支持 RAG 与 Agent 两类系统的回归评测
与主流框架集成：LangChain / LlamaIndex / DeepEval 生态互通

实战建议： 把 RAGAS 跑进 CI——每次改切分策略或换 embedding 模型，指标自动对比，调参不再靠感觉。

📈 本周趋势观察#

1. 编程 Agent 进入”实战方法论”阶段#

工具已经够多，本周社区讨论的重心明显转向”怎么用”：Plan/Act 分离、审批模式、检查点回滚、小步任务拆分。共识正在形成——可控性比自动化程度更重要，能随时接管、随时回滚的 Agent 才敢用在真实项目里。

2. 终端成为编程 Agent 的主战场#

OpenCode、aider 双双在榜，加上各家 CLI 混战：终端因为”离 git 和 shell 最近”，正在成为 Agent 工作流的最佳宿主。IDE 插件负责”看得见”，终端 Agent 负责”跑得动”。

3. RAG 从”检索增强”走向”结构增强”#

RAGFlow 的版面理解、LightRAG 的关系图谱，本质都是同一件事：纯向量检索的天花板已到，把文档结构、实体关系显式建模正在成为新一代 RAG 的标配。

4. 评测驱动（Evaluation-Driven）开始流行#

RAGAS 上榜是个标志性信号：大家不再满足于”跑个 demo 感觉挺像”，而是给 RAG/Agent 建立指标、测试集和 CI 回归。AI 应用工程化，缺的从来不是模型，是”怎么证明它好用”。

🛠️ 值得一试的小工具#

项目	简介	链接
qmd	本地 Markdown 笔记检索引擎，BM25+向量+LLM 重排三合一，Agent 的记忆外挂	GitHub
promptfoo	Prompt 与 RAG 的回归测试框架，配置即测试，可跑进 CI	GitHub
nano-graphrag	约 1100 行的极简 GraphRAG 实现，读懂图谱增强 RAG 原理的最佳教材	GitHub

💡 写在最后#

本周的两条主线拼在一起，是 AI 开源社区的一个缩影：编程 Agent 在学”守规矩”，RAG 在学”讲结构”。

前者用 Plan/Act、审批、回滚换来了生产环境的信任；后者用版面解析、知识图谱、自动评测换来了答案质量的确定性。当”能跑”不再是卖点，可控、可查、可评估才是新项目上榜的真正原因。

挑一个感兴趣的，动手试试吧！

📅 下期预告：9 月第四周，我们将关注本地推理引擎与开源语音模型的最新进展。敬请关注！

30.本周 GitHub 热门 AI 开源项目盘点（2026年9月第1周）

Thu, 03 Sep 2026 00:00:00 GMT

本周 GitHub 热门 AI 开源项目盘点（2026年9月第1周）#

每周精选 GitHub 上最值得关注的 AI 开源项目，帮你快速了解社区动态和技术趋势。

📊 本周概览#

排名	项目	Stars	语言	亮点
1	khoj	45K+	Python	本地优先的 AI 第二大脑，支持语义搜索与自动化
2	crush	42K+	TypeScript	命令行 AI 代码审查助手
3	OpenHands	38K+	Python	全自动 AI 软件工程师
4	Raycast	11K+	TypeScript	终端脚本生态的 AI 化升级
5	LocalAI	30K+	Go	本地 LLM 推理与兼容层
6	LangGraph	28K+	Python	图结构 Agent 编排框架

🔥 重点项目详解#

1. khoj — 本地优先的 AI 第二大脑#

仓库： khoj-ai/khoj ⭐ 45,200+

Khoj 是一个自托管的 AI 个人知识库工具，它把笔记、文档、PDF、网页书签统一索引起来，支持语义搜索、自动问答和每日摘要。数据完全保留在本地，隐私可控，是”把 AI 用在个人知识管理”的代表项目。

核心特性：

本地优先：所有索引和对话默认在本地运行，数据不出设备
多模态输入：支持 Markdown、PDF、图片、音频笔记
语义搜索 + 自动摘要：不用记住关键词，自然语言就能找到内容
跨平台客户端：桌面端、网页端、Obsidian 插件、终端均可接入

适用场景： 个人知识管理、研究笔记整理、团队内网知识库、离线环境下的大模型问答。

2. crush — 命令行 AI 代码审查#

仓库： chamkank/crush ⭐ 42,000+

Crush 是一款直接跑在终端里的 AI 代码审查工具。它把代码差异（diff）发送给大模型，返回逐行的审查意见，包括潜在 Bug、安全隐患和性能问题，不需要打开浏览器，也不需要配置复杂的 CI。

核心特性：

零配置：装好后直接审查本地 Git 仓库的未提交改动
逐行意见：定位到具体行号，方便直接修改
支持 OpenAI / Anthropic / 本地 Ollama 模型
与 Git 深度集成：支持 crush review、crush fix 等子命令

为什么火： 把”让 AI 审代码”的成本降到了最低——装一个 CLI，剩下的交给模型。

3. OpenHands — 全自动 AI 软件工程师#

仓库： All-Hands-AI/OpenHands ⭐ 38,000+

OpenHands（原 OpenDevin）是一个能自动完成软件开发任务的 AI Agent 平台：给它一个 GitHub Issue，它就能自己写代码、跑测试、修 Bug、提 PR。本周它发布了新的多 Agent 协作模式，热度再次攀升。

核心特性：

端到端任务执行：从理解需求到提交 PR 全程自动化
沙箱隔离：每个任务在独立 Docker 沙箱中运行，安全可控
多 Agent 分工：规划、编码、测试由不同 Agent 角色协作完成
支持接入 GitHub / GitLab / Slack 等工具链

适合谁： 想体验”AI 员工”的开发团队、研究 Agent 软件开发的研究者、以及想自动化处理简单 Issue 的个人开发者。

4. Raycast Script Commands — 终端脚本生态的 AI 化#

仓库： raycast/script-commands ⭐ 11,000+

Raycast 的官方脚本命令仓库本周发布了大量 AI 增强脚本：用自然语言触发 Shell 命令、把 AI 回复直接渲染成操作按钮、一键让大模型改写剪贴板内容。它让”效率工具 + AI”的组合变得更顺手。

核心特性：

数百个现成脚本，覆盖文件管理、系统控制、文本处理
新增 AI 动作模板：翻译、总结、重写、提取结构化数据
脚本用 TypeScript / Shell / Swift 编写，二次开发成本低
配合 Raycast AI 可在本地直接调用大模型

为什么火： 它证明了”AI 不一定要做成聊天框”——把 AI 塞进日常操作流里，效率提升更直接。

5. LocalAI — 本地 LLM 推理与兼容层#

仓库： mudler/LocalAI ⭐ 30,000+

LocalAI 是一个开源的本地推理服务器，提供与 OpenAI API 完全兼容的接口，背后可以接 Llama、Qwen、Mistral 等任意开源模型。它无需 GPU 也能跑（支持 CPU 推理），是”把云 API 换成本地模型”的最省事方案。

核心特性：

OpenAI API 兼容：改一行 base_url 即可切换
多后端支持：llama.cpp、vLLM、TensorRT 等推理引擎均可接入
支持文本、图片生成（Stable Diffusion）、语音转录
容器化部署，一条命令启动

实用价值： 数据敏感的团队和个人可以用它把推理完全收归本地，同时保留切换回云 API 的灵活性。

6. LangGraph — 图结构 Agent 编排框架#

仓库： langchain-ai/langgraph ⭐ 28,000+

LangGraph 用”图”来定义 Agent 的工作流：节点是工具调用或 LLM 步骤，边是状态流转，支持循环、条件分支、人工介入等复杂编排。本周它推出的流式工具调用和持久化会话功能获得大量关注。

核心特性：

显式状态机：每一步都可视、可调试、可回放
支持人机协同：关键节点可暂停等待人工确认
持久化：会话状态可保存、恢复，适合长时任务
与 LangChain 生态无缝衔接

适合谁： 需要把 Agent 工作流做成”看得懂、控得住”的生产级应用的团队。

📈 本周趋势观察#

1. “本地优先”成为新的关键词#

从 khoj 的本地知识库到 LocalAI 的本地推理，本周榜单上多个项目都把”数据不出本地”当作核心卖点。隐私意识加上开源模型的成熟，正在推动 AI 工具从”云端优先”转向”本地优先”。

2. AI 代码工具从”补全”走向”审查”和”执行”#

crush 做代码审查、OpenHands 直接写完整个功能——AI 编程工具正在从”帮你敲代码”进化到”帮你干活”，开发者角色的重心也在从写代码转向做验收。

3. 编排层的重要性上升#

LangGraph 持续上榜说明：随着 Agent 越来越多，大家开始关心”怎么把多个步骤和多个 Agent 稳定地串起来”。编排框架正在成为新的基础设施层。

4. 终端工具的 AI 化#

crush 和 Raycast 脚本说明 AI 正在从”网页里的聊天框”走向开发者每天真正待着的终端。小而美的命令行 AI 工具，正在成为社区的新宠。

🛠️ 值得一试的小工具#

项目	简介	链接
gh-browse	GitHub CLI 扩展，用 AI 总结任意仓库的 README 和近期动态	GitHub
PromptLint	静态检查 Prompt 的规则引擎，团队统一 Prompt 风格用	GitHub
AnyDoc2	把 PDF/Office 转成 Markdown 的本地命令行工具，速度快	GitHub

💡 写在最后#

本周的 GitHub AI 热榜释放出一个明确信号：AI 正在全面进入工程化的”落地周”。

不再只是”谁家模型更强”，而是：

怎么让 AI 在本地安全地跑起来？
怎么让 AI 真正帮我写完一个功能、审完一段代码？
怎么把多个 Agent 编排成稳定可靠的工作流？

这些问题的答案，就藏在上面这些项目里。挑一个感兴趣的，动手试试吧！

📅 下期预告：9 月第二周，我们将关注视频生成模型和 AI Agent 记忆系统的最新进展。敬请关注！

29.本周 GitHub 热门 AI 开源项目盘点（2026年8月第4周）

Mon, 31 Aug 2026 00:00:00 GMT

本周 GitHub 热门 AI 开源项目盘点（2026年8月第4周）#

每周精选 GitHub 上最值得关注的 AI 开源项目，帮你快速了解社区动态和技术趋势。

📊 本周概览#

排名	项目	Stars	语言	亮点
1	crawl4ai	80K+	Python	LLM 友好的网页爬虫与抓取框架
2	last30days-skill	60K+	Python	时间感知型 Agent 技能插件
3	GitNexus	46K+	TypeScript	Git 原生 AI Agent 协作协议
4	OpenMAIC	24K+	TypeScript	清华出品多智能体互动课堂
5	freellmapi	22K+	TypeScript	免费 LLM API 智能路由与故障转移
6	livekit/agents	13K+	Python	实时语音 AI Agent 开发框架

🔥 重点项目详解#

1. crawl4ai — LLM 友好的网页爬虫#

仓库： unclecode/crawl4ai ⭐ 80,383

Crawl4AI 是目前 GitHub 上最受关注的 AI 基础设施项目之一。它专为 LLM 应用设计，提供搜索、抓取、解析、爬取、站点地图和交互等一站式 API，将过去需要拼接多个工具才能完成的 Web 数据采集流程统一为一个简洁的接口。

核心特性：

对 LLM 输出友好：自动清洗 HTML、提取正文、保留语义结构
支持动态页面渲染（JS 渲染、SPA 抓取）
内置 Markdown / JSON / 结构化数据多种输出格式
可自托管，也可作为云服务使用

适用场景： RAG 知识库构建、竞品监控、新闻聚合、AI Agent 联网能力接入。

2. last30days-skill — 让 Agent 拥有时间记忆#

仓库： mvanhorn/last30days-skill ⭐ 60,632

这是一个为 AI Agent 设计的”时间感知”技能插件，让 Agent 能够记住并检索过去 30 天内的对话、任务和上下文信息。解决了当前大多数 Agent “每次对话都是全新开始”的痛点。

核心特性：

自动记录近 30 天的交互历史
支持自然语言时间查询（“上周我们讨论了什么？”）
轻量级本地存储，无需外部数据库
兼容主流 Agent 框架（LangChain、AutoGen 等）

为什么火： 填补了 Agent 短期记忆与长期记忆之间的空白，实现成本低但体验提升明显。

3. GitNexus — Git 原生 Agent 协作协议#

仓库： abhigyanpatwari/GitNexus ⭐ 46,647

GitNexus 提出了一种全新的 AI Agent 协作范式：用 Git 仓库本身作为 Agent 团队的协调中枢。不需要服务器、不需要数据库，任何能执行 git push 的 Agent 都可以参与协作。

核心特性：

仅用 4 个 JSON 文件定义任务分配、状态同步和通信协议
完全去中心化，无单点故障
天然支持版本回溯和审计
MIT 开源协议

适合谁： 多 Agent 编排研究者、想在 CI/CD 中嵌入 Agent 工作流的团队、对 A2A / MCP 协议感兴趣的开发者。

4. OpenMAIC — 清华多智能体互动课堂#

仓库： THU-MAIC/OpenMAIC ⭐ 24,839

清华大学推出的开放多智能体互动课堂平台，一键部署即可获得沉浸式多 Agent 学习体验。多个 AI 角色（教师、助教、同学）协同授课，支持实时问答、小组讨论和个性化辅导。

核心特性：

预设多种教学场景模板
支持自定义 Agent 角色和课程大纲
前端交互流畅，TypeScript 全栈实现
中文优化，国内访问无障碍

教育意义： 展示了多 Agent 在教育领域的落地可能性，不只是聊天机器人，而是真正的”AI 课堂”。

5. freellmapi — 免费 LLM API 智能路由#

仓库： tashfeenahmed/freellmapi ⭐ 22,986

一个开源的 LLM API 网关，提供智能路由、自动故障转移和密钥加密管理。当你有多个 LLM 提供商（免费 + 付费）时，它可以自动选择最优路径，某个服务挂了会自动切换备选方案。

核心特性：

支持 OpenAI / Claude / DeepSeek / Qwen / Ollama 等 20+ 提供商
基于延迟、成本、可用性的智能路由策略
API Key 加密存储，不暴露明文
TypeScript 编写，部署简单

实用价值： 降低 LLM 调用成本、提高可用性，特别适合个人开发者和小团队。

6. livekit/agents — 实时语音 AI Agent 框架#

仓库： livekit/agents ⭐ 13,838

LiveKit 出品的实时语音 AI Agent 开发框架，专注于低延迟的语音对话场景。支持 STT → LLM → TTS 全链路流式处理，适合构建客服机器人、语音助手、会议转录等应用。

核心特性：

端到端延迟 < 500ms
支持 WebRTC / SIP / PSTN 多种接入方式
内置 VAD（语音活动检测）和打断处理
Python SDK，与 LangChain / OpenAI 无缝集成

📈 本周趋势观察#

1. Agent 基础设施持续升温#

从 crawl4ai 的数据采集到 freellmapi 的 API 路由，再到 GitNexus 的协作协议——社区正在补齐 Agent 生态的每一块拼图。不再是”做一个更好的 Chatbot”，而是”让 Agent 真正融入工程体系”。

2. 记忆系统成为标配#

last30days-skill 的爆火说明：用户已经不满足于无状态的对话了。无论是短期记忆（30天）还是长期知识图谱，记忆能力正在从”加分项”变成”必选项”。

3. 教育 + 多 Agent = 新赛道#

OpenMAIC 代表了多 Agent 应用的一个重要方向：不是替代人，而是创造新的交互形式。教育、培训、模拟演练等场景可能是多 Agent 最先规模化落地的领域。

4. 开源模型生态加速#

本周榜单中多个项目都强调了对 Qwen、DeepSeek、Llama 等开源模型的深度支持。闭源 API 不再是唯一选择，本地部署 + 开源模型的组合正在成为主流。

🛠️ 值得一试的小工具#

项目	简介	链接
Bumblebee	Perplexity 出品的供应链安全扫描器，支持 MCP Server 审计	GitHub
Firecrawl	AI Agent 专用 Web 上下文 API，已进入 GitHub Top 100	GitHub
anydoc	Rust 编写的文档转换库，Office/PDF/EPUB → Markdown	GitHub

💡 写在最后#

本周的 GitHub AI 热榜呈现出一个清晰的信号：AI 开源社区正在从”模型竞赛”转向”工程落地”。

大家不再只关注谁的 benchmark 更高，而是关心：

怎么让 Agent 稳定地跑在生产环境里？
怎么降低 LLM 的使用门槛和成本？
怎么让多个 Agent 像团队一样协作？

这些问题的答案，就藏在上面这些项目里。挑一个感兴趣的，动手试试吧！

📅 下期预告：9 月第一周，我们将关注 AI Code Review 工具和新一代 RAG 框架的最新进展。敬请关注！

28.Hermes Agent 完整安装部署指南

Mon, 20 Apr 2026 00:00:00 GMT

Hermes Agent 完整安装部署指南#

Hermes Agent 是 Nous Research 推出的一款可成长的 AI Agent，主打自主学习、多层记忆架构和丰富的工具系统。这篇指南将带你从零开始完成安装部署。

项目简介#

项目	说明
开发团队	Nous Research
开源协议	MIT（完全免费）
核心卖点	闭环学习系统 + 四层记忆架构 + 40+ 内置工具
支持平台	Linux、macOS、WSL2、Android（Termux）
消息平台	Telegram、Discord、Slack、WhatsApp、飞书
支持模型	Claude、OpenRouter、DeepSeek、Qwen、Ollama 本地模型等

官方资源：

官网：https://hermes-agent.nousresearch.com
GitHub：https://github.com/NousResearch/hermes-agent

本文导航：

一、系统要求
二、环境准备
三、Windows WSL2 安装详解
四、快速安装（推荐）
五、手动安装（折腾版）
六、Docker 安装（零依赖）
七、配置 LLM 模型
八、常见问题排查（Windows WSL 专篇）
九、开始使用

一、系统要求 {#一系统要求}#

1.1 硬件配置#

配置项	最低要求	推荐配置
CPU	2 核	4 核以上
内存	4GB	8GB+
磁盘	2GB 可用	10GB+ 可用
网络	能访问 API	稳定宽带

1.2 操作系统支持#

✅ Linux（推荐 Ubuntu 22.04+）
✅ macOS（推荐 Sonoma 及以上）
✅ Windows（需通过 WSL2，详见第三章）
❌ 原生 Windows（不支持）

二、环境准备 {#二环境准备}#

2.1 安装 Git#

Git 是唯一需要手动安装的依赖，其他依赖都会由安装脚本自动处理。简单来说，Git 是一个版本控制工具，用来从 GitHub 下载和管理代码——你只需要装好它，后面的事情安装脚本会帮你搞定。

Linux（Ubuntu/Debian）：

Terminal window

1
sudo apt update
2
sudo apt install git -y

Linux（CentOS/RHEL）：

Terminal window

1
sudo yum install git -y

macOS： macOS 通常自带 Git，可通过以下命令验证：

Terminal window

1
git --version

如果没有安装，会提示安装 Xcode Command Line Tools，按提示操作即可。

Windows（WSL2）： 先安装 WSL2，然后在 WSL2 中安装 Git：

Terminal window

1
sudo apt update
2
sudo apt install git -y

2.2 中国大陆网络加速（可选）#

如果你在中国大陆，建议提前配置镜像源以加速安装：

Git 镜像：

Terminal window

1
git config --global url."https://mirror.ghproxy.com/https://github.com".insteadOf "https://github.com"

pip 镜像：

Terminal window

1
pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/
2
pip config set install.trusted-host mirrors.aliyun.com

npm 镜像：

Terminal window

1
npm config set registry https://mirrors.cloud.tencent.com/npm/ --global

三、Windows WSL2 安装详解 {#三windows-wsl2-安装详解}#

Windows 用户需要通过 WSL2（Windows Subsystem for Linux）来运行 Hermes Agent。这是目前 Windows 上最稳定的运行方式。

3.1 安装 WSL2#

方法一：自动安装（推荐）

以管理员身份打开 PowerShell，运行：

Terminal window

1
wsl --install

这会安装 WSL2 和默认的 Ubuntu 发行版。安装完成后重启电脑，然后设置 Ubuntu 用户名和密码。

方法二：手动安装

如果自动安装失败，可以手动安装：

Terminal window

1
# 启用 WSL
2
wsl --install --no-distribution
3

4
# 查看可用的 Linux 发行版
5
wsl --list --online
6

7
# 安装 Ubuntu 22.04
8
wsl --install -d Ubuntu-22.04

验证 WSL 安装：

Terminal window

1
wsl --version
2
wsl --list --verbose

3.2 配置 WSL2（性能优化）#

WSL2 默认配置可能占用较多内存，建议创建 .wslconfig 文件进行优化。

在用户目录（C:\Users\你的用户名）创建 .wslconfig 文件：

1
[wsl2]
2
# 限制 WSL2 最大内存使用
3
memory=4GB
4

5
# 限制 WSL2 处理器使用
6
processors=2
7

8
# 设置 WSL2 交换文件大小
9
swap=2GB
10

11
# 开启 localhost 转发
12
localhostForwarding=true
13

14
# 设置 WSL2 为默认版本
15
defaultVersion=2

展开收起

配置完成后，在 PowerShell 中重启 WSL：

Terminal window

1
wsl --shutdown
2
wsl

3.3 WSL2 基础配置#

进入 WSL2 后，先更新系统：

Terminal window

1
sudo apt update && sudo apt upgrade -y

设置时区（重要）：

Terminal window

1
# 查看当前时区
2
date
3

4
# 设置为中国时区
5
sudo timedatectl set-timezone Asia/Shanghai
6

7
# 验证
8
date

配置中文显示（可选）：

Terminal window

1
# 安装中文语言包
2
sudo apt install language-pack-zh-hans -y
3

4
# 设置 locale
5
sudo locale-gen zh_CN.UTF-8
6
sudo update-locale LANG=zh_CN.UTF-8

3.4 WSL2 文件互访#

在 Windows 中访问 WSL 文件：

在文件资源管理器地址栏输入：

1
\\wsl$\Ubuntu\home\你的用户名

在 WSL 中访问 Windows 文件：

Terminal window

1
# Windows C盘
2
cd /mnt/c
3

4
# Windows D盘
5
cd /mnt/d
6

7
# 用户目录
8
cd /mnt/c/Users/你的用户名

⚠️ 重要提示：

在 WSL 中处理文件比在 Windows 中访问 WSL 文件性能更好
建议将项目文件放在 WSL 的 home 目录下（/home/用户名）
Hermes Agent 的配置和数据最好都保存在 WSL 内部

3.5 安装 Windows Terminal（推荐）#

Windows Terminal 提供了更好的终端体验，支持多标签页、自定义主题等。

安装方法：

打开 Microsoft Store
搜索 “Windows Terminal”
点击安装

配置默认启动 WSL：

打开 Windows Terminal 设置（Ctrl + ,），将默认配置文件设置为 Ubuntu。

四、快速安装（推荐） {#四快速安装推荐}#

这是最简单的安装方式，一键脚本自动处理所有依赖。

4.1 Linux / macOS / WSL2#

打开终端，执行以下命令：

Terminal window

1
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

或者使用 wget：

Terminal window

1
wget -qO- https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

中国大陆用户推荐使用中文社区镜像：

Terminal window

1
curl -fsSL https://res1.hermesagent.org.cn/install.sh | bash

脚本会自动完成以下操作：

检测系统架构（x86_64 / arm64）
安装 uv、Python 3.11、Node.js v22
克隆 Hermes Agent 仓库
创建 Python 虚拟环境并安装依赖
注册 hermes 全局命令

安装完成后，必须重新加载 shell 配置：

这是因为安装脚本修改了 shell 配置文件（~/.bashrc），需要让终端重新读取才能识别 hermes 命令。你也可以直接关闭终端再重新打开，效果一样。

Terminal window

1
# bash 用户
2
source ~/.bashrc
3

4
# zsh 用户（macOS 默认）
5
source ~/.zshrc

验证安装：

Terminal window

1
hermes --version

如果输出了版本号，说明安装成功！

4.2 Windows 原生 PowerShell#

如果你不想安装 WSL2，可以直接使用 PowerShell 版本：

Terminal window

1
irm https://res1.hermesagent.org.cn/install.ps1 | iex

安装完成后，关闭并重新打开 PowerShell，然后输入：

Terminal window

1
hermes

五、手动安装（折腾版） {#五手动安装折腾版}#

如果你想完全掌控安装过程，可以选择手动安装。

5.1 克隆仓库#

Terminal window

1
git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git
2
cd hermes-agent

如果克隆时忘了 --recurse-submodules，补一下：

Terminal window

1
git submodule update --init --recursive

5.2 安装 uv 和虚拟环境#

uv 是一个用 Rust 写的超快速 Python 包管理器，比传统的 pip 快 10-100 倍。虚拟环境则是一个独立的 Python 运行空间，避免 Hermes 的依赖和你系统上其他 Python 项目的依赖互相干扰。

Terminal window

1
curl -LsSf https://astral.sh/uv/install.sh | sh
2
uv venv venv --python 3.11

5.3 安装依赖#

Terminal window

1
export VIRTUAL_ENV="$(pwd)/venv"
2
uv pip install -e ".[all]"

各模块说明：

模块	功能	安装命令
核心	基础功能	`uv pip install -e "."`
messaging	Telegram/Discord 网关	`uv pip install -e ".[messaging]"`
cron	定时任务	`uv pip install -e ".[cron]"`
voice	麦克风+音频播放	`uv pip install -e ".[voice]"`
mcp	MCP 支持	`uv pip install -e ".[mcp]"`
slack	Slack 消息	`uv pip install -e ".[slack]"`
honcho	AI 原生记忆	`uv pip install -e ".[honcho]"`

5.4 创建配置目录和文件#

Terminal window

1
mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills,pairing,hooks,image_cache,audio_cache,whatsapp/session}
2
cp cli-config.yaml.example ~/.hermes/config.yaml
3
touch ~/.hermes/.env

5.5 添加 API Key#

编辑 ~/.hermes/.env 文件，添加你的 API Key：

Terminal window

1
echo 'OPENROUTER_API_KEY=sk-or-v1-your-key-here' >> ~/.hermes/.env

5.6 添加到 PATH#

PATH 是系统用来查找可执行程序的目录列表。这一步把 hermes 命令所在的目录加到 PATH 中，这样你在任何位置输入 hermes 都能运行，而不需要每次切换到安装目录。

Terminal window

1
mkdir -p ~/.local/bin
2
ln -sf "$(pwd)/venv/bin/hermes" ~/.local/bin/hermes
3

4
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
5
source ~/.bashrc

5.7 验证安装#

Terminal window

1
hermes version   # 检查命令是否可用
2
hermes doctor    # 运行诊断
3
hermes chat -q "Hello! What tools do you available?"  # 测试对话

六、Docker 安装（零依赖） {#六docker-安装零依赖}#

如果你不想安装 Python 环境，可以使用 Docker。前提是你已经安装了 Docker Desktop 或 Docker Engine——如果还没装，先去 docker.com 下载安装。

6.1 拉取镜像#

Terminal window

1
docker pull nousresearch/hermes-agent:latest

6.2 交互式运行#

Terminal window

1
docker run -it --rm \
2
  -v ~/.hermes:/home/hermes/.hermes \
3
  -v ~/.ssh:/home/hermes/.ssh:ro \
4
  -e OPENROUTER_API_KEY=sk-or-xxx \
5
  nousresearch/hermes-agent:latest

6.3 使用 Docker Compose#

创建 docker-compose.yml：

1
version: '3'
2
services:
3
  hermes:
4
    image: nousresearch/hermes-agent:latest
5
    volumes:
6
      - ~/.hermes:/home/hermes/.hermes
7
      - ~/.ssh:/home/hermes/.ssh:ro
8
    environment:
9
      - OPENROUTER_API_KEY=sk-or-xxx
10
    stdin_open: true
11
    tty: true

然后运行：

Terminal window

1
docker compose up -d
2
docker compose exec hermes hermes

七、配置 LLM 模型 {#七配置-llm-模型}#

安装好之后，需要配置 LLM 提供商。

7.1 使用交互式向导#

Terminal window

1
hermes setup

这会启动一个交互式向导，引导你完成：

选择模型提供商
输入 API Key
基本偏好设置

7.2 常用模型提供商#

新手推荐： 国内用户首选 DeepSeek（注册简单、性价比高），海外用户可选 OpenRouter（注册即送额度，支持模型多）。如果你注重隐私或想完全免费，可以选 Ollama 本地部署。

提供商	配置方式	说明
Nous Portal	OAuth 登录，零配置	官方订阅服务，最简单
Anthropic Claude	API Key 或 Claude Code 授权	注意：目前尚未被封禁
OpenRouter	API Key	支持 200+ 模型，灵活度高
DeepSeek	API Key	国内用户友好，性价比高
阿里云 DashScope	API Key	支持 Qwen 系列
Ollama	本地运行	完全离线，隐私优先
自定义端点	OpenAI 兼容 API	vLLM、SGLang 等

7.3 配置示例#

使用 DeepSeek：

Terminal window

1
hermes config set model deepseek/deepseek-chat
2
hermes config set DEEPSEEK_API_KEY sk-your-key-here

使用 Ollama 本地模型：

Terminal window

1
# 先启动 Ollama
2
ollama serve
3

4
# 配置 Hermes 使用本地模型
5
hermes config set model ollama/llama3

八、常见问题排查（Windows WSL 专篇） {#八常见问题排查windows-wsl-专篇}#

8.1 WSL2 安装问题#

问题 1：WSL 安装失败，提示 “无法解析服务器名称或地址”

原因： 网络问题或 DNS 解析失败。

解决：

Terminal window

1
# 以管理员身份运行 PowerShell
2
# 重置 Winsock
3
netsh winsock reset
4

5
# 重置网络适配器
6
netsh int ip reset
7

8
# 刷新 DNS
9
ipconfig /flushdns
10

11
# 重启电脑

问题 2：WSL2 启动失败，提示 “参考的对象类型不支持尝试的操作”

原因： 其他虚拟化软件（如 VMware、VirtualBox）冲突。

解决：

Terminal window

1
# 以管理员身份运行 PowerShell
2
# 禁用 Hyper-V 独占模式
3
bcdedit /set hypervisorlaunchtype auto
4

5
# 重启电脑

问题 3：WSL 提示 “Error: 0x80040306”

原因： WSL 内核版本过旧。

解决：

Terminal window

1
# 更新 WSL
2
wsl --update
3

4
# 如果更新失败，手动下载安装
5
# 访问 https://aka.ms/wsl2kernel 下载并安装

8.2 WSL2 性能问题#

问题：WSL2 占用内存过大，导致 Windows 卡顿

解决： 配置 .wslconfig 限制资源使用：

1
[wsl2]
2
memory=4GB
3
processors=2
4
swap=2GB
5
localhostForwarding=true

然后执行：

Terminal window

1
wsl --shutdown

问题：文件访问速度很慢

原因： 跨系统（Windows ↔ WSL）文件访问性能较差。

解决：

将项目文件放在 WSL 内部（/home/用户名）
避免在 Windows 文件系统中运行 WSL 程序
使用 wsl --mount 挂载磁盘（如果需要访问 Windows 磁盘）

8.3 网络连接问题#

问题 1：WSL2 无法访问网络

解决：

Terminal window

1
# 在 WSL 中执行
2
sudo rm /etc/resolv.conf
3
sudo bash -c 'echo "nameserver 8.8.8.8" > /etc/resolv.conf'
4
sudo bash -c 'echo "nameserver 114.114.114.114" >> /etc/resolv.conf'
5
sudo chattr +i /etc/resolv.conf

问题 2：Hermes 无法连接到 API

原因： 防火墙或代理问题。

解决：

Terminal window

1
# 测试 API 连接
2
curl -v https://api.openai.com/v1/models
3

4
# 如果需要代理
5
export https_proxy=http://your-proxy:port
6
export http_proxy=http://your-proxy:port
7

8
# 添加到 ~/.bashrc 使其永久生效
9
echo 'export https_proxy=http://your-proxy:port' >> ~/.bashrc
10
source ~/.bashrc

8.4 Hermes 安装问题#

问题 1：hermes: command not found

原因： 没有重新加载 shell 配置，或 PATH 配置有误。

解决：

Terminal window

1
# 重新加载 shell
2
source ~/.bashrc  # 或 source ~/.zshrc
3

4
# 检查 PATH
5
echo $PATH
6

7
# 手动添加 PATH
8
export PATH="$HOME/.local/bin:$PATH"
9

10
# 永久添加到 PATH
11
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
12
source ~/.bashrc

问题 2：安装脚本执行失败

原因： 权限问题或网络问题。

解决：

Terminal window

1
# 手动下载脚本
2
curl -fsSL https://res1.hermesagent.org.cn/install.sh -o install.sh
3

4
# 查看脚本内容（可选）
5
cat install.sh
6

7
# 执行脚本
8
chmod +x install.sh
9
bash install.sh

问题 3：Python 版本不兼容

解决：

Terminal window展开收起

1
# 检查 Python 版本
2
python3 --version
3

4
# 如果版本低于 3.11，需要升级
5
# 安装 pyenv 管理 Python 版本
6
curl https://pyenv.run | bash
7

8
# 添加到 shell 配置
9
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
10
echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
11
echo 'eval "$(pyenv init -)"' >> ~/.bashrc
12
source ~/.bashrc
13

14
# 安装 Python 3.11
15
pyenv install 3.11.9
16
pyenv global 3.11.9

展开收起

问题 4：API key not set

原因： 没有配置模型提供商。

解决：

Terminal window

1
# 运行模型配置向导
2
hermes model
3

4
# 或直接设置
5
hermes config set OPENROUTER_API_KEY your_key
6

7
# 验证配置
8
hermes config get OPENROUTER_API_KEY

8.5 运行时报错#

问题 1：“ModuleNotFoundError” 或 “ImportError”

原因： 依赖包安装不完整。

解决：

Terminal window

1
# 进入 Hermes 安装目录
2
cd ~/hermes-agent
3

4
# 激活虚拟环境
5
source venv/bin/activate
6

7
# 重新安装依赖
8
uv pip install -e ".[all]"
9

10
# 验证安装
11
hermes doctor

问题 2：“Permission denied” 错误

解决：

Terminal window

1
# 修复权限
2
sudo chown -R $USER:$USER ~/.hermes
3
sudo chmod -R 755 ~/.hermes
4

5
# 如果问题持续，检查 SELinux/AppArmor
6
sudo apt install apparmor-utils
7
sudo aa-disable /etc/apparmor.d/hermes

问题 3：内存不足导致程序崩溃

解决：

Terminal window

1
# 检查内存使用
2
free -h
3

4
# 清理缓存
5
sudo sync && sudo sysctl -w vm.drop_caches=3
6

7
# 增加 WSL2 内存限制（在 .wslconfig 中）
8
# memory=8GB
9

10
# 重启 WSL
11
wsl --shutdown

8.6 配置问题#

问题：Hermes 无法保存配置

原因： 配置目录权限问题。

解决：

Terminal window

1
# 创建配置目录
2
mkdir -p ~/.hermes
3

4
# 设置权限
5
chmod 755 ~/.hermes
6

7
# 验证配置目录
8
ls -la ~/.hermes
9

10
# 手动创建配置文件
11
touch ~/.hermes/config.yaml
12
touch ~/.hermes/.env

问题：时区不正确导致日志时间错误

解决：

Terminal window

1
# 设置时区
2
sudo timedatectl set-timezone Asia/Shanghai
3

4
# 验证
5
date
6

7
# 同步时间
8
sudo apt install ntpdate
9
sudo ntpdate time.windows.com

九、开始使用 {#九开始使用}#

配置好后，直接输入：

Terminal window

1
hermes

即可进入全交互式终端界面，开始和 Agent 对话。

常用命令：

命令	说明
`hermes`	启动交互式 CLI 聊天
`hermes setup`	运行完整设置向导
`hermes model`	切换模型提供商和模型
`hermes tools`	配置启用的工具
`hermes gateway`	启动消息网关（Telegram 等）
`hermes update`	更新到最新版本
`hermes doctor`	诊断问题

8.7 实用技巧与命令#

WSL2 常用命令速查：

Terminal window展开收起

1
# PowerShell 中执行
2

3
# 查看 WSL 状态
4
wsl --status
5

6
# 列出所有发行版
7
wsl --list --verbose
8

9
# 关闭所有 WSL 发行版
10
wsl --shutdown
11

12
# 终止特定发行版
13
wsl -t Ubuntu
14

15
# 导出 WSL 备份
16
wsl --export Ubuntu D:\backup\ubuntu.tar
17

18
# 导入 WSL 备份
19
wsl --import UbuntuNew D:\WSL\UbuntuNew D:\backup\ubuntu.tar
20

21
# 设置默认发行版
22
wsl --set-default Ubuntu
23

24
# 设置 WSL 版本
25
wsl --set-version Ubuntu 2

展开收起

Hermes 常用诊断命令：

Terminal window展开收起

1
# 检查 Hermes 状态
2
hermes doctor
3

4
# 查看配置
5
hermes config list
6

7
# 测试模型连接
8
hermes chat -q "Hello"
9

10
# 查看日志
11
tail -f ~/.hermes/logs/hermes.log
12

13
# 更新 Hermes
14
cd ~/hermes-agent
15
git pull
16
source venv/bin/activate
17
uv pip install -e ".[all]"

展开收起

Windows 与 WSL 协同技巧：

在 Windows 中打开 WSL 目录：
Terminal window
```
1
explorer.exe \\wsl$\Ubuntu\home\用户名
```

在 WSL 中打开 Windows 程序：

Terminal window

1
notepad.exe filename.txt
2
code .  # VS Code
3
explorer.exe .  # 文件资源管理器

使用 VS Code 远程开发（推荐）：
- 在 Windows 安装 VS Code
- 安装 “WSL” 扩展
- 在 WSL 中运行 code . 即可在 Windows 上编辑 WSL 文件

写在最后#

Hermes Agent 在 WSL2 上运行非常稳定，配合 Windows Terminal 和 VS Code 可以获得很好的开发体验。如果在安装过程中遇到问题，建议：

先确保 WSL2 本身能正常运行
网络连接畅通（可以访问 GitHub 和 API）
按照本文的常见问题排查步骤逐一检查
必要时查看官方文档或 GitHub Issues

记忆系统和技能系统是这个 Agent 的亮点——不是简单的对话历史，而是会主动整理和沉淀知识。技能系统也挺好用，学到的东西可以跨会话复用。

当然，作为开源项目，它还在快速迭代中，有些功能还在完善。感兴趣的可以试试，有问题可以去 GitHub 提 Issue。

祝你使用愉快！

27. 首页框体调整指南

Sun, 19 Apr 2026 00:00:00 GMT

首页框体调整指南#

Firefly（流萤）博客的首页布局非常灵活，你可以根据自己的喜好调整各种框体的位置和顺序。本指南将详细介绍如何调整首页的各种组件布局。

一、侧边栏布局配置#

1. 核心配置文件#

所有侧边栏的布局配置都在这个文件中：

1
src/config/sidebarConfig.ts

2. 右侧边栏组件顺序#

右侧边栏的组件顺序可以通过修改 rightComponents 数组的顺序来调整。

示例配置：

1
// 右侧边栏组件配置列表
2
rightComponents: [
3
    {
4
        // 组件类型：公告组件
5
        type: "announcement",
6
        // 是否启用该组件
7
        enable: true,
8
        // 组件位置
9
        position: "top",
10
        // 是否在文章详情页显示
11
        showOnPostPage: true,
12
    },
13
    {
14
        // 组件类型：日历组件
15
        type: "calendar",
16
        // 是否启用该组件
17
        enable: true,
18
        // 组件位置
19
        position: "top",
20
        // 是否在文章详情页显示
21
        showOnPostPage: false,
22
    },
23
    {
24
        // 组件类型：站点统计组件
25
        type: "stats",
26
        // 是否启用该组件
27
        enable: true,
28
        // 组件位置
29
        position: "top",
30
        // 是否在文章详情页显示
31
        showOnPostPage: true,
32
    },
33
    // 其他组件...
34
],

展开收起

3. 组件位置的重要性#

关键知识点：

position: "top" - 固定在顶部的组件
position: "sticky" - 会跟随页面滚动的组件

重要规则：

所有 top 位置的组件会优先于 sticky 位置的组件渲染

这意味着：

如果一个组件是 top 位置，另一个是 sticky 位置，无论它们在数组中的顺序如何，top 位置的组件都会显示在上面
只有当两个组件都是相同位置类型时，才会按照数组顺序渲染

4. 实际调整步骤#

步骤 1：打开配置文件

Terminal window

1
# 用 VS Code 打开
2
type src/config/sidebarConfig.ts
3

4
# 或用记事本打开
5
notepad src/config/sidebarConfig.ts

步骤 2：调整组件顺序

将你想显示在前面的组件移到数组的前面。

步骤 3：统一位置类型

如果想严格按照数组顺序显示，确保所有组件的 position 属性相同（都设为 top 或都设为 sticky）。

步骤 4：保存并刷新

保存文件后，刷新浏览器即可看到效果。

二、常见布局调整需求#

1. 公告显示在最顶部#

1
rightComponents: [
2
    {
3
        type: "announcement",
4
        position: "top",
5
        // 其他配置...
6
    },
7
    // 其他组件...
8
],

2. 站点统计显示在公告下方#

1
rightComponents: [
2
    {
3
        type: "announcement",
4
        position: "top",
5
    },
6
    {
7
        type: "stats",
8
        position: "top",
9
    },
10
    // 其他组件...
11
],

3. 日历显示在中间#

1
rightComponents: [
2
    {
3
        type: "announcement",
4
        position: "top",
5
    },
6
    {
7
        type: "calendar",
8
        position: "top",
9
    },
10
    {
11
        type: "stats",
12
        position: "top",
13
    },
14
    // 其他组件...
15
],

展开收起

三、左侧边栏布局#

1. 左侧边栏组件配置#

左侧边栏的配置类似，修改 leftComponents 数组：

1
// 左侧边栏组件配置列表
2
leftComponents: [
3
    {
4
        // 组件类型：用户资料组件
5
        type: "profile",
6
        position: "top",
7
        // 其他配置...
8
    },
9
    {
10
        // 组件类型：音乐播放器
11
        type: "music",
12
        position: "sticky",
13
        // 其他配置...
14
    },
15
    // 其他组件...
16
],

展开收起

2. 左侧边栏常用组件#

profile - 用户资料卡片
music - 音乐播放器
categories - 分类列表
tags - 标签云

四、移动端布局#

1. 移动端底部组件#

在移动端（<768px），侧边栏会变成底部组件，配置在 mobileBottomComponents 数组中：

1
// 移动端底部组件配置列表
2
mobileBottomComponents: [
3
    {
4
        type: "profile",
5
        // 其他配置...
6
    },
7
    {
8
        type: "announcement",
9
        // 其他配置...
10
    },
11
    // 其他组件...
12
],

2. 移动端布局特点#

组件会水平排列在页面底部
只显示图标，不显示文字
点击图标会展开对应的功能

五、高级布局调整#

1. 响应式布局配置#

平板端配置：

1
// 平板端(769-1279px)显示哪侧侧边栏
2
// left: 平板端显示左侧边栏
3
// right: 平板端显示右侧边栏
4
tabletSidebar: "left",

双侧边栏配置：

1
// 侧边栏位置
2
// left: 仅显示左侧边栏
3
// right: 仅显示右侧边栏
4
// both: 双侧边栏
5
position: "both",
6

7
// 文章详情页是否显示双侧边栏
8
showBothSidebarsOnPostPage: true,

2. 组件显示控制#

每个组件都可以控制在不同页面的显示：

1
{
2
    type: "calendar",
3
    enable: true,
4
    position: "top",
5
    // 是否在文章详情页显示
6
    showOnPostPage: false,
7
    // 是否在非文章详情页显示
8
    showOnNonPostPage: true,
9
},

六、常见问题解答#

Q: 为什么我调整了顺序但没有生效？#

A: 检查组件的 position 属性，确保它们是相同的类型（都为 top 或都为 sticky）。

Q: 如何隐藏某个组件？#

A: 将组件的 enable 属性设置为 false：

1
{
2
    type: "advertisement",
3
    enable: false,
4
    // 其他配置...
5
},

Q: 移动端的组件顺序可以调整吗？#

A: 可以，修改 mobileBottomComponents 数组的顺序即可。

Q: 组件的 `position` 有什么区别？#

top - 固定在侧边栏顶部，不会跟随滚动
sticky - 会跟随页面滚动，保持在视野内

七、布局调整最佳实践#

1. 右侧边栏推荐顺序#

1
rightComponents: [
2
    // 1. 公告（重要信息）
3
    { type: "announcement", position: "top" },
4
    // 2. 站点统计（展示数据）
5
    { type: "stats", position: "top" },
6
    // 3. 日历（辅助功能）
7
    { type: "calendar", position: "top" },
8
    // 4. 目录（文章页专用）
9
    { type: "sidebarToc", position: "sticky" },
10
],

2. 左侧边栏推荐顺序#

1
leftComponents: [
2
    // 1. 用户资料（个人信息）
3
    { type: "profile", position: "top" },
4
    // 2. 音乐播放器（娱乐功能）
5
    { type: "music", position: "sticky" },
6
    // 3. 分类和标签（导航功能）
7
    { type: "categories", position: "sticky" },
8
    { type: "tags", position: "sticky" },
9
],

3. 移动端推荐顺序#

1
mobileBottomComponents: [
2
    { type: "profile" },
3
    { type: "categories" },
4
    { type: "music" },
5
    { type: "tags" },
6
],

八、实际调整案例#

案例 1：公告 + 日历 + 站点统计#

目标： 公告显示在最顶部，然后是日历，最后是站点统计

配置：

1
rightComponents: [
2
    {
3
        type: "announcement",
4
        position: "top",
5
    },
6
    {
7
        type: "calendar",
8
        position: "top",  // 注意：这里要设为 top
9
    },
10
    {
11
        type: "stats",
12
        position: "top",
13
    },
14
    // 其他组件...
15
],

展开收起

案例 2：站点统计 + 公告 + 日历#

目标： 站点统计显示在最顶部，然后是公告，最后是日历

配置：

1
rightComponents: [
2
    {
3
        type: "stats",
4
        position: "top",
5
    },
6
    {
7
        type: "announcement",
8
        position: "top",
9
    },
10
    {
11
        type: "calendar",
12
        position: "top",
13
    },
14
    // 其他组件...
15
],

展开收起

九、总结#

调整首页框体布局的核心是：

修改配置文件 - src/config/sidebarConfig.ts
调整数组顺序 - 数组越前面的组件显示越靠前
统一位置类型 - 确保组件的 position 属性相同
保存并刷新 - 查看调整效果

通过合理的布局调整，你可以打造出更加个性化的博客首页，提升用户体验。

希望本指南对你有所帮助！如果有任何问题，欢迎在评论区留言讨论。

26. SEO 与 RSS 订阅配置指南

Sat, 18 Apr 2026 00:00:00 GMT

SEO 与 RSS 订阅配置指南#

这篇讲的是博客后期非常实用的一组能力：

RSS 订阅
robots.txt
sitemap
页面 OG 信息

你可以把它们理解成：

RSS：给读者订阅
robots / sitemap：给搜索引擎理解你的网站
OG：让分享链接时看起来更完整

一、RSS 是什么#

RSS 可以让别人用阅读器订阅你的博客更新。

这个项目已经内置了 RSS 页面和 RSS XML 文件。

访问地址#

1
/rss/
2
/rss.xml

二、RSS 里哪些文章会被收录#

通常普通公开文章都会被收录。
如果文章设置了密码保护，RSS 里一般不会直接输出完整内容。

所以密码文章和普通文章的表现不一样，这是正常的。

三、robots.txt 是什么#

它是给搜索引擎爬虫看的一个说明文件。

项目里有相关文件：

1
src/pages/robots.txt.ts

不过你这个仓库里同时还有：

1
public/robots.txt

最终生效时，通常要以你实际部署输出的结果为准。

四、sitemap 是什么#

sitemap 可以理解成“网站地图”，帮助搜索引擎知道你有哪些页面。

这个项目构建后会生成：

1
sitemap-index.xml

这个文件对搜索引擎收录很有帮助。

五、OG 信息是什么#

OG 就是你把文章链接发到社交平台时，显示出来的：

标题
描述
图片

这些信息主要在页面布局里生成：

1
src/layouts/Layout.astro

六、SEO 最基础该改哪些地方#

对于个人博客来说，优先把这几个改好就很够用：

1. 站点标题和描述#

位置：

1
src/config/siteConfig.ts

重点字段：

1
title
2
description
3
keywords
4
site_url

2. 每篇文章的标题和简介#

每篇文章最好都写：

1
title: 文章标题
2
description: 一句话简介

3. 文章封面图#

如果文章有封面图，分享出去通常也更完整。

七、RSS 对新手最实用的意义#

很多新手会觉得 RSS 很“老”，其实它依然很有用。

尤其适合：

技术博客
学习笔记站
不想依赖平台推荐流量的人

八、建议你实际怎么做#

第一步#

先确认 siteConfig.ts 里的这些信息都写完整：

1
title: "Coldairboy学习笔记"
2
site_url: "https://blogboy.eu.cc"
3
description: "Coldairboy 的个人博客样板，用来记录学习笔记与折腾记录。"
4
keywords: ["Coldairboy", "学习笔记", "Astro", "Firefly", "博客"]

第二步#

每篇文章尽量补齐：

title
description
image
published

第三步#

构建一次看看有没有正常生成：

Terminal window

1
cd E:\GITHUB\firefly-replica
2
pnpm build

第四步#

部署后访问这些地址检查：

1
/rss/
2
/rss.xml
3
/sitemap-index.xml

九、常见问题#

Q: RSS 页面能打开，但订阅器读不到？#

先检查：

/rss.xml 能不能直接访问
域名是不是已经正确部署
构建是不是成功过

Q: 搜索引擎为什么还没收录？#

这不一定是配置错了，也可能只是还没来得及抓取。

先做这些事：

确保域名可正常访问
确保 sitemap 可以访问
页面标题和描述写完整
持续更新内容

Q: 分享链接为什么没有图片？#

一般先检查：

文章有没有封面图
站点地址 site_url 是否正确
主题是否开启了 OG 图相关配置

十、最后总结#

如果你只想记住最关键的点，就记这几个：

siteConfig.ts 决定站点基础 SEO 信息
/rss.xml 是订阅地址
sitemap-index.xml 对收录有帮助
每篇文章最好写完整标题、简介和封面

SEO 不用一上来就研究很深。
先把这些基础项配好，你的博客就已经比“只会发文章”更完整了。

25. 相册页面配置指南

Fri, 17 Apr 2026 00:00:00 GMT

相册页面配置指南#

这个项目自带相册功能，但默认不一定开启。

如果你想把图片单独做成“相册页”，而不是只塞进文章里，这篇就很适合你。

一、相册功能开关在哪#

先看：

1
src/config/siteConfig.ts

你要确保这里打开：

1
pages: {
2
  gallery: true,
3
}

如果这里是 false，即使你配了相册内容，页面也不会正常作为站点功能开放。

二、相册配置文件在哪#

1
src/config/galleryConfig.ts

你现在这个项目里已经有一个示例相册。

三、相册图片应该放哪里#

1
public/gallery/

每一个相册都对应这里的一个子目录。

比如配置里写：

1
id: "firefly-2026"

那么图片目录就应该是：

1
public/gallery/firefly-2026/

四、怎么添加一个相册#

在 galleryConfig.ts 里加一个数组项即可：

1
albums: [
2
  {
3
    id: "my-trip-2026",
4
    name: "我的旅行相册",
5
    description: "记录一次旅行中的照片",
6
    location: "杭州",
7
    date: "2026-04-23",
8
    tags: ["旅行", "摄影"],
9
  },
10
]

然后在下面这个目录里放图片：

1
public/gallery/my-trip-2026/

五、封面图规则怎么理解#

有 3 种情况：

情况 1：你手动写了 `cover`#

1
cover: "cover.avif"

那它会优先用你指定的封面。

情况 2：你没写 `cover`，但目录里有 `cover.*`#

比如：

1
cover.avif
2
cover.webp
3
cover.jpg

系统会优先把这个当封面。

情况 3：前两种都没有#

系统通常会用第一张图片当封面。

六、支持哪些图片格式#

常见支持：

jpg
png
webp
avif
gif

如果你只是日常用，推荐优先用：

webp
avif

因为体积更小。

七、访问地址怎么理解#

相册总页#

1
/gallery/

单个相册页#

1
/gallery/相册id/

比如：

1
/gallery/my-trip-2026/

八、列数和瀑布流怎么调#

在 galleryConfig.ts 里：

1
columnWidth: 240

这个值的意思可以简单理解成：

数值越小，同屏列数越多
数值越大，同屏列数越少

如果你觉得图片太挤，就把它调大一点。

九、新手最稳的添加步骤#

建议按这个顺序做：

先在 siteConfig.ts 打开 gallery: true
在 galleryConfig.ts 新增一个相册
去 public/gallery/相册id/ 放图片
刷新本地页面检查
没问题再推送

十、常见问题#

Q: 相册页打不开？#

先检查：

pages.gallery 有没有开启
galleryConfig.ts 有没有写对
相册 id 和目录名是不是一致

Q: 图片不显示？#

通常是因为：

图片没放到 public/gallery/对应目录/
文件名写错
图片格式不对

Q: 封面图不对？#

优先检查：

有没有手动写 cover
目录里有没有 cover.*
第一张图片是不是你想要的那张

最后总结#

相册功能其实很好记：

相册信息写在 galleryConfig.ts
相册图片放在 public/gallery/
每个相册一个目录

如果你后面想把博客做得更完整，这个功能非常值得补上。

24. 文章加密、版权协议与分享海报指南

Thu, 16 Apr 2026 00:00:00 GMT

文章加密、版权协议与分享海报指南#

这篇讲的是文章页里比较实用的“增强功能”：

想让某篇文章加密码才能看
想给文章加版权协议
想启用分享海报按钮

这些都不是必须，但学会之后会明显更像一个完整博客。

一、密码文章怎么做#

这个项目支持文章加密，核心字段有两个：

1
password: "123456"
2
passwordHint: "密码提示"

直接写法示例#

1
---
2
title: 这是一篇加密文章
3
published: 2026-04-22
4
description: 只有输入密码后才能查看
5
tags: [学习笔记]
6
category: 博客搭建
7
author: Coldairboy
8
image: ./images/firefly1.avif
9
password: "coldairboy"
10
passwordHint: "和博客作者名字有关"
11
---

开启后会发生什么#

文章列表里仍然能看到标题
进入文章页后，会先显示输入密码界面
输入正确密码后，正文才会显示

不想加密时怎么办#

直接删掉：

1
password:
2
passwordHint:

或者不要写这两个字段。

二、版权协议怎么配#

这个项目支持文章底部显示版权信息。

默认版权配置文件#

1
src/config/licenseConfig.ts

你现在这个项目里默认是：

1
export const licenseConfig = {
2
  enable: true,
3
  name: "CC BY-NC-SA 4.0",
4
  url: "https://creativecommons.org/licenses/by-nc-sa/4.0/",
5
}

单篇文章自定义版权#

如果你想给某篇文章单独设置，可以在文章头信息里写：

1
licenseName: "CC BY-NC-SA 4.0"
2
licenseUrl: "https://creativecommons.org/licenses/by-nc-sa/4.0/"

如果想关闭版权区块#

全站关闭：

1
enable: false

三、分享海报是什么#

分享海报就是文章页里的一个按钮，点开后会生成一张适合分享的海报图。

海报里通常会带上：

标题
描述
日期
作者
二维码

分享海报开关在哪#

在：

1
src/config/siteConfig.ts

你要看这个字段：

1
sharePoster: true

如果想关闭#

1
sharePoster: false

分享海报会用到哪些内容#

生成海报时，通常会读取文章里的这些信息：

title
description
published
image
author

所以如果你想让海报更好看，建议每篇文章尽量把这些都写完整。

一份适合新手的完整示例#

1
---
2
title: 我的隐藏教程
3
published: 2026-04-22
4
description: 这是一篇只有输入密码后才能查看的文章
5
tags: [学习笔记]
6
category: 博客搭建
7
author: Coldairboy
8
image: ./images/firefly1.avif
9
password: "coldairboy"
10
passwordHint: "和站长名字有关"
11
licenseName: "CC BY-NC-SA 4.0"
12
licenseUrl: "https://creativecommons.org/licenses/by-nc-sa/4.0/"
13
---

常见问题#

Q: 我写了 `password`，为什么还没加密？#

先检查：

是不是写在文章头信息里
引号有没有写错
本地页面有没有刷新

Q: 分享海报按钮为什么不显示？#

通常是因为：

siteConfig.ts 里的 sharePoster 被关了
当前页面不是文章详情页
本地缓存没刷新

Q: 版权信息怎么换成自己的？#

如果想全站统一改，就改 licenseConfig.ts。
如果想只改某一篇，就在那篇文章头信息里单独写。

最后总结#

这三个功能可以这样理解：

password：控制“谁能看”
license：说明“别人怎么转载”
sharePoster：帮助“别人更方便分享”

它们都不是写文章的基础功能，但非常适合你在博客稳定后逐步加上。

23. 侧边栏、目录、站点统计与广告位配置指南

Wed, 15 Apr 2026 00:00:00 GMT

侧边栏、目录、站点统计与广告位配置指南#

这个项目的侧边栏功能比很多主题都细，能控制：

左右侧栏怎么排
哪些组件显示
哪些组件只在文章页显示
站点统计开不开
广告位放不放

主要配置文件#

1
src/config/sidebarConfig.ts

这是最核心的文件。

侧边栏布局先看这几个参数#

1
export const sidebarLayoutConfig = {
2
  enable: true,
3
  position: "both",
4
  tabletSidebar: "left",
5
  showBothSidebarsOnPostPage: true,
6
}

它们分别是什么意思#

enable：是否启用侧边栏
position：左侧、右侧还是双侧
tabletSidebar：平板显示哪一侧
showBothSidebarsOnPostPage：文章页要不要双侧栏

左右侧栏里的组件怎么控制#

文件里会看到类似这种结构：

1
leftComponents: [
2
  {
3
    type: "profile",
4
    enable: true,
5
    position: "top",
6
    showOnPostPage: true,
7
  },
8
]

你只要先理解 4 个字段就够了：

type：组件类型
enable：开关
position：top 或 sticky
showOnPostPage：文章页显不显示

文章目录怎么开#

文章目录组件类型是：

1
type: "sidebarToc"

示例：

1
{
2
  type: "sidebarToc",
3
  enable: true,
4
  position: "sticky",
5
  showOnPostPage: true,
6
  showOnNonPostPage: false,
7
}

这表示：

只在文章详情页显示
跟随滚动吸附

站点统计组件怎么开#

组件类型是：

1
type: "stats"

示例：

1
{
2
  type: "stats",
3
  enable: true,
4
  position: "top",
5
  showOnPostPage: true,
6
}

它一般会显示：

文章数量
最近更新
站点运行时间

广告位怎么开#

广告组件本身是在侧边栏里控制开关，具体广告内容在另一个文件里写：

1
src/config/adConfig.ts

第一步：在 `sidebarConfig.ts` 里启用广告组件#

1
{
2
  type: "advertisement",
3
  enable: true,
4
  position: "sticky",
5
  showOnPostPage: true,
6
  configId: "ad1",
7
}

第二步：在 `adConfig.ts` 里写广告内容#

比如纯图片广告：

1
export const adConfig1 = {
2
  image: {
3
    src: "assets/images/cover.avif",
4
    alt: "广告横幅",
5
    link: "#",
6
    external: true,
7
  },
8
  closable: true,
9
  displayCount: -1,
10
}

或者带文字和按钮：

1
export const adConfig2 = {
2
  title: "支持博主",
3
  content: "如果你觉得本站内容对你有帮助，欢迎支持创作。",
4
  link: {
5
    text: "支持一下",
6
    url: "about/",
7
    external: false,
8
  },
9
}

`top` 和 `sticky` 有什么区别#

这是新手很容易看懵的地方。

`top`#

适合：

个人资料
公告
站点统计

特点：

显示在侧栏上方
更像“固定在最前面的内容块”

`sticky`#

适合：

目录
分类
标签
广告

特点：

会随着页面滚动保持可见

我建议新手这样配#

如果你现在刚开始用，先用这套最稳：

左侧栏#

个人资料
音乐播放器
分类
标签

右侧栏#

公告
站点统计
文章目录

这样信息会比较清楚，不容易太乱。

常见问题#

Q: 我开了目录，但文章页没有显示？#

先检查：

type 写的是不是 sidebarToc
enable 是不是 true
showOnPostPage 是不是 true
当前文章里有没有足够的标题层级

Q: 广告位为什么没显示？#

一般是因为：

侧边栏里没启用广告组件
configId 写错了
adConfig.ts 里内容不完整

Q: 站点统计为什么不对？#

通常先检查：

文章发布时间有没有乱填
siteStartDate 有没有写对
页面是不是刷新成功了

最后总结#

这个项目的侧边栏不是“固定死”的，而是可以自己搭。

你可以把它理解成：

sidebarConfig.ts 决定“放什么、放哪边、什么时候显示”
adConfig.ts 决定“广告具体长什么样”

先把布局逻辑搞明白，后面调整就会很轻松。

22. 文章置顶指南

Tue, 14 Apr 2026 00:00:00 GMT

文章置顶指南#

这个项目自带文章置顶功能，不需要另外装插件。

你只要在文章头信息里加上一行：

1
pinned: true

这篇文章就会被排到普通文章前面。

先说结论#

如果你只想马上用起来，直接照这个写：

1
---
2
title: 你的文章标题
3
published: 2026-04-20
4
description: 一句话简介
5
tags: [学习笔记]
6
category: 博客搭建
7
author: Coldairboy
8
image: ./images/firefly1.avif
9
pinned: true
10
---

保存后刷新页面，这篇文章就会优先显示。

这个项目为什么确定支持置顶#

我已经帮你查过代码了，结论很明确：

文章数据模型里已经定义了 pinned 字段
文章排序逻辑会先判断 pinned
页面上还会显示“置顶”标记

也就是说，这不是“可能支持”，而是已经做好的功能。

正确用法#

1. 打开你要置顶的文章#

这个项目真正读取的文章目录是：

1
src/content/posts/

比如你要置顶第 21 篇文章，就打开：

1
src/content/posts/21.md

2. 在文章头信息里加入 `pinned: true`#

1
---
2
title: 21. B站视频嵌入指南
3
published: 2026-04-19
4
description: 博客B站视频嵌入教程
5
tags: [博客配置]
6
category: 博客搭建
7
author: Coldairboy
8
image: ./images/firefly1.avif
9
pinned: true
10
---

3. 保存并本地预览#

Terminal window

1
cd E:\GITHUB\firefly-replica
2
pnpm dev

然后刷新浏览器，看首页文章列表是不是已经跑到前面了。

4. 确认没问题后再推送#

Terminal window

1
cd E:\GITHUB\firefly-replica
2
.\publish-blog.bat

取消置顶怎么做#

有两种方式都可以：

方法一：直接删除这一行#

1
pinned: true

方法二：改成 `false`#

1
pinned: false

一般来说，直接删掉最省事。

置顶后的实际效果#

这个项目的逻辑是：

先看文章是不是置顶
置顶文章排在前面
如果都是置顶，或者都不是置顶，再按发布日期排序

所以你可以理解成：

pinned: true 的文章，会优先排到前面
普通文章，再按日期新旧排序

页面上会怎么显示#

置顶文章通常会有两种变化：

在文章列表里排得更靠前
在文章信息区域显示“置顶”标记

所以如果你看到文章顺序变了，同时页面上还有“置顶”字样，说明功能已经正常生效。

新手最常见的错误#

1. 把 `sticky: true` 当成置顶#

这个项目文章置顶认的是：

1
pinned: true

不是：

1
sticky: true

sticky 这个词在项目里主要是给导航栏、侧边栏那类布局用的，不是文章置顶字段。

2. 改错目录#

这个项目真正读取的是：

1
src/content/posts/

如果你只改了 src/content/ 里的镜像文件，但没改 src/content/posts/，页面可能不会按你预期变化。

3. 改完了没刷新#

有时候不是置顶没生效，而是浏览器还没刷新出来。

先试这几个动作：

保存文件
刷新本地页面
如果还没变化，重启一次 pnpm dev

4. 以为所有页面都会按置顶排序#

这里有个细节很重要：

首页 / 普通文章列表：会看置顶
归档页：按纯发布时间排序，不受置顶影响

也就是说，如果你在归档页面看到顺序没变，不代表置顶失效。

最适合你的使用方式#

如果你现在只是想让一篇重点文章长期挂在最前面，最简单的做法就是：

打开那篇文章
在头信息里加 pinned: true
本地预览确认
推送到 GitHub

就这么简单。

不建议滥用#

如果你很多文章都设置成置顶，会出现两个问题：

首页前面全是置顶，看起来会很乱
新文章会被压到后面，不容易被看到

比较稳的做法是只保留 1 到 3 篇置顶文章。

一份可直接复制的模板#

1
---
2
title: 文章标题
3
published: 2026-04-20
4
description: 一句话简介
5
tags: [学习笔记]
6
category: 博客搭建
7
author: Coldairboy
8
image: ./images/firefly1.avif
9
pinned: true
10
---

最后总结#

这个项目有原生文章置顶功能，而且用法非常简单。

你只需要记住一句话：

1
pinned: true

写上它，就是置顶。删掉它，或者改成 false，就是取消置顶。

21. B站视频嵌入指南

Mon, 13 Apr 2026 00:00:00 GMT

视频说明： 测试

出处： 哔哩哔哩 - 喜多川

B站视频嵌入指南#

在博客文章中嵌入 B 站视频可以丰富内容形式，提升用户体验。本指南将详细介绍如何在 Firefly（流萤）Astro 博客中嵌入 B 站视频。

1. 获取视频嵌入代码#

方法一：B站分享按钮获取#

打开 B 站视频页面
点击视频下方的「分享」按钮
选择「嵌入代码」
复制生成的 iframe 代码

方法二：手动构造嵌入URL#

1
//player.bilibili.com/player.html?bvid=视频BV号&page=1

2. 响应式视频嵌入#

为了在不同设备上显示良好，建议使用响应式嵌入：

1
<style>
2
.video-container {
3
  position: relative;
4
  padding-bottom: 56.25%;
5
  height: 0;
6
  overflow: hidden;
7
}
8
.video-container iframe {
9
  position: absolute;
10
  top: 0;
11
  left: 0;
12
  width: 100%;
13
  height: 100%;
14
}
15
</style>
16

17
<div class="video-container">
18
  <iframe
19
    src="//player.bilibili.com/player.html?bvid=BV1EZ4y1o74Z&page=1&high_quality=1&autoplay=false"
20
    scrolling="no"
21
    border="0"
22
    frameborder="no"
23
    framespacing="0"
24
    allowfullscreen="true"
25
  >
26
  </iframe>
27
</div>

展开收起

3. 常用参数说明#

参数	说明	示例值
`bvid`	视频 BV 号	`BV1EZ4y1o74Z`
`aid`	视频 AV 号	`12345678`
`page`	视频分 P 数	`1`
`high_quality`	高质量播放	`1`
`autoplay`	自动播放	`true` / `false`

4. 其他视频平台#

YouTube#

1
<iframe
2
  src="https://www.youtube.com/embed/VIDEO_ID"
3
  frameborder="0"
4
  allowfullscreen
5
  style="width: 100%; height: 400px;"
6
>
7
</iframe>

腾讯视频#

1
<iframe
2
  src="//v.qq.com/iframe/player.html?vid=abc123&tiny=0&auto=0"
3
  frameborder="0"
4
  allowfullscreen
5
  style="width: 100%; height: 400px;"
6
>
7
</iframe>

5. 常见问题#

视频不显示？

检查网络连接
确认视频可公开访问
验证嵌入代码正确

视频加载慢？

使用懒加载
限制同一页面视频数量
考虑使用视频封面图替代

希望本指南能帮助你在博客中更好地使用视频内容！

20. 常见问题排查指南

Sun, 12 Apr 2026 00:00:00 GMT

常见问题排查指南#

基本概念#

在博客搭建和运行过程中，遇到问题是正常的。本指南将帮助你快速识别和解决常见问题，确保博客的稳定运行。

构建错误#

1. 依赖安装失败#

症状：

npm install 失败
依赖冲突
网络错误

解决方案：

Terminal window

1
# 清除缓存
2
npm cache clean --force
3

4
# 重新安装
5
tnpm install
6

7
# 如果使用 pnpm
8
pnpm install
9

10
# 如果使用 yarn
11
yarn install

常见错误：

ETIMEDOUT - 网络超时，检查网络连接
EACCES - 权限不足，使用管理员权限
ENOTFOUND - 依赖包不存在，检查 package.json

2. 构建命令失败#

症状：

npm run build 失败
构建过程中报错
生成的文件不完整

解决方案：

Terminal window

1
# 检查错误信息
2
npm run build
3

4
# 检查 TypeScript 类型错误
5
npm run typecheck
6

7
# 检查代码 lint 错误
8
npm run lint

常见错误：

语法错误 - 检查代码语法
类型错误 - 检查 TypeScript 类型
路径错误 - 检查文件路径

3. 开发服务器启动失败#

症状：

npm run dev 失败
端口被占用
依赖缺失

解决方案：

Terminal window

1
# 检查端口是否被占用
2
netstat -ano | findstr :4321
3

4
# 杀死占用端口的进程
5
Taskkill /PID <PID> /F
6

7
# 重新启动开发服务器
8
npm run dev

部署问题#

1. GitHub Pages 部署失败#

症状：

GitHub Actions 构建失败
页面显示 404
资源加载失败

解决方案：

检查 GitHub Actions 日志
确认配置文件
检查 base URL

配置示例：

.github/workflows/deploy.yml展开收起

1
name: Deploy to GitHub Pages
2

3
on:
4
  push:
5
    branches:
6
      - main
7

8
jobs:
9
  deploy:
10
    runs-on: ubuntu-latest
11
    steps:
12
      - uses: actions/checkout@v3
13
      - uses: actions/setup-node@v3
14
        with:
15
          node-version: 18
16
      - run: npm install
17
      - run: npm run build
18
      - uses: peaceiris/actions-gh-pages@v3
19
        with:
20
          github_token: ${{ secrets.GITHUB_TOKEN }}
21
          publish_dir: ./dist

展开收起

2. Vercel 部署失败#

症状：

构建失败
环境变量缺失
依赖安装失败

解决方案：

检查构建日志
配置环境变量
调整构建命令

Vercel 配置：

Framework Preset: Astro
Build Command: npm run build
Output Directory: dist
Install Command: npm install

3. 域名配置问题#

症状：

域名无法访问
SSL 证书错误
重定向问题

解决方案：

检查 DNS 配置
确认域名解析
设置 SSL 证书

DNS 记录示例：

A 记录: @ → 服务器 IP
CNAME 记录: www → your-username.github.io

性能问题#

1. 页面加载缓慢#

症状：

首屏加载时间长
图片加载慢
脚本执行时间长

解决方案：

图片优化
- 使用 WebP 格式
- 压缩图片
- 懒加载图片
代码优化
- 代码分割
- 按需加载
- 减少第三方脚本
服务器优化
- 启用 Gzip 压缩
- 使用 CDN
- 缓存策略

2. 构建时间过长#

症状：

npm run build 耗时过长
内存使用过高
构建过程卡住

解决方案：

Terminal window

1
# 增加内存限制
2
NODE_OPTIONS="--max-old-space-size=4096" npm run build
3

4
# 优化构建配置
5
# astro.config.mjs
6
import { defineConfig } from 'astro/config';
7

8
export default defineConfig({
9
  build: {
10
    minify: true,
11
    inlineStylesheets: 'auto',
12
  },
13
});

3. 运行时性能问题#

症状：

页面滚动卡顿
交互响应慢
内存泄漏

解决方案：

使用浏览器开发者工具
- Performance 面板分析
- Memory 面板检查内存
- Network 面板分析网络请求
代码优化
- 减少 DOM 操作
- 使用防抖和节流
- 优化事件监听器

SEO 问题#

1. 搜索引擎不收录#

症状：

网站在搜索结果中不显示
索引状态异常
抓取错误

解决方案：

提交站点地图
- 创建 sitemap.xml
- 提交到 Google Search Console
- 提交到 Bing Webmaster Tools
检查 robots.txt
```
1
User-agent: *
2
Allow: /
```
检查页面元数据
- 标题和描述
- 结构化数据
- canonical URL

2. 排名下降#

症状：

搜索排名突然下降
流量减少
关键词排名变化

解决方案：

检查 Google Search Console
- 查看抓取错误
- 检查安全问题
- 分析性能报告
内容优化
- 更新内容
- 修复死链接
- 优化关键词
技术优化
- 提高页面速度
- 修复移动友好性
- 改善用户体验

3. 结构化数据错误#

症状：

富摘要不显示
结构化数据验证失败
搜索结果异常

解决方案：

使用结构化数据测试工具
- Google 结构化数据测试工具
- Rich Results Test

修复结构化数据

1
{
2
  "@context": "https://schema.org",
3
  "@type": "BlogPosting",
4
  "headline": "文章标题",
5
  "description": "文章描述",
6
  "image": "https://example.com/image.jpg",
7
  "author": {
8
    "@type": "Person",
9
    "name": "作者名称"
10
  },
11
  "datePublished": "2026-04-24",
12
  "dateModified": "2026-04-24"
13
}

功能问题#

1. 评论系统不工作#

症状：

评论框不显示
评论提交失败
评论数据丢失

解决方案：

检查评论系统配置
- 确认 API 密钥
- 检查域名配置
- 验证权限设置
常见评论系统问题
- Giscus: 检查 GitHub App 权限
- Disqus: 确认 shortname 正确
- Waline: 检查服务端配置

2. 搜索功能不工作#

症状：

搜索框不显示
搜索结果为空
搜索功能无响应

解决方案：

检查搜索配置
- 确认搜索方法设置
- 检查索引生成
- 验证搜索组件
PageFind 搜索
- 确保已运行 npm run build
- 检查索引文件生成
- 验证搜索组件配置

3. 图片显示异常#

症状：

图片不显示
图片加载失败
图片变形

解决方案：

检查图片路径
- 确认相对路径正确
- 检查文件存在性
- 验证文件权限
图片格式问题
- 确认浏览器支持
- 检查图片编码
- 测试不同格式

环境问题#

1. Node.js 版本问题#

症状：

依赖安装失败
构建过程出错
运行时错误

解决方案：

Terminal window

1
# 检查 Node.js 版本
2
node -v
3

4
# 使用 nvm 管理版本
5
nvm use 18
6

7
# 或使用 n
8
n 18

推荐版本：

Node.js 18.x 或 20.x
npm 9.x 或更高

2. 操作系统兼容性#

症状：

Windows 特定错误
Linux 路径问题
macOS 权限问题

解决方案：

Windows
- 使用 PowerShell 或 WSL
- 注意路径分隔符
- 以管理员身份运行
Linux/macOS
- 检查文件权限
- 使用 bash 或 zsh
- 安装必要的依赖

3. 网络环境问题#

症状：

依赖安装超时
CDN 资源加载失败
外部 API 调用失败

解决方案：

网络连接
- 检查网络连接
- 尝试使用 VPN
- 配置代理

镜像源

Terminal window

1
# npm 镜像
2
npm config set registry https://registry.npmmirror.com
3

4
# yarn 镜像
5
yarn config set registry https://registry.npmmirror.com

安全问题#

1. XSS 攻击#

症状：

页面注入恶意脚本
用户数据泄露
会话劫持

解决方案：

输入验证
- 过滤用户输入
- 转义特殊字符
- 使用安全的模板系统

Content Security Policy

1
<meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self' https://trusted-cdn.com;">

2. CSRF 攻击#

症状：

未授权的请求
账户被恶意操作
数据被篡改

解决方案：

CSRF 令牌
- 使用 CSRF 令牌
- 验证请求来源
- 检查 Referer 头

SameSite Cookie

1
res.cookie('session', sessionId, {
2
  sameSite: 'strict',
3
  secure: true,
4
  httpOnly: true
5
});

3. 依赖安全漏洞#

症状：

依赖包存在漏洞
安全扫描失败
构建警告

解决方案：

Terminal window

1
# 检查依赖漏洞
2
npm audit
3

4
# 修复漏洞
5
npm audit fix
6

7
# 更新依赖
8
npm update

调试技巧#

1. 浏览器开发者工具#

常用功能：

Console - 查看错误信息
Network - 分析网络请求
Elements - 检查 DOM 结构
Application - 查看存储和缓存
Performance - 分析性能
Memory - 检查内存使用

2. 日志分析#

日志位置：

构建日志
服务器日志
浏览器控制台
分析工具日志

分析方法：

查找错误关键词
检查堆栈跟踪
定位问题来源
重现错误场景

3. 断点调试#

使用 VS Code 调试：

launch.json

1
{
2
  "version": "0.2.0",
3
  "configurations": [
4
    {
5
      "type": "node",
6
      "request": "launch",
7
      "name": "Debug Astro",
8
      "runtimeExecutable": "npm",
9
      "runtimeArgs": ["run", "dev"],
10
      "console": "integratedTerminal"
11
    }
12
  ]
13
}

最佳实践#

1. 预防措施#

定期更新依赖
备份代码和数据
监控网站状态
测试功能完整性
保持环境一致性

2. 问题排查流程#

复现问题 - 确认问题的具体表现
收集信息 - 查看日志和错误信息
分析原因 - 定位问题的根本原因
尝试解决方案 - 应用可能的解决方法
验证结果 - 确认问题是否解决
记录解决方案 - 为未来参考

3. 工具推荐#

调试工具：

Chrome DevTools - 浏览器调试
VS Code Debugger - 代码调试
Postman - API 测试
Lighthouse - 性能分析
PageSpeed Insights - 速度测试

监控工具：

UptimeRobot - 网站监控
Google Search Console - SEO 监控
Sentry - 错误监控
New Relic - 性能监控

常见错误代码#

1. 404 错误#

原因：

页面不存在
路由配置错误
链接错误

解决方案：

检查 URL 拼写
确认页面存在
配置 404 页面

2. 500 错误#

原因：

服务器内部错误
代码异常
资源不足

解决方案：

检查服务器日志
修复代码错误
增加服务器资源

3. 403 错误#

原因：

权限不足
访问被拒绝
防火墙阻止

解决方案：

检查文件权限
验证访问控制
调整防火墙设置

4. 429 错误#

原因：

请求过于频繁
API 速率限制
服务器限流

解决方案：

减少请求频率
实现请求队列
缓存 API 响应

总结#

遇到问题是博客维护过程中的正常现象，关键是要有系统的排查方法和解决思路。通过本指南的方法，你可以快速定位和解决常见问题，确保博客的稳定运行。

建议：

保持学习心态
记录常见问题和解决方案
定期维护和更新
寻求社区帮助

希望本指南能帮助你更好地管理和维护你的博客！

19. 备份和恢复指南

Sat, 11 Apr 2026 00:00:00 GMT

备份和恢复指南#

基本概念#

备份是保护博客数据的重要措施，可以：

防止数据丢失
快速恢复网站
迁移到新服务器
回滚到之前的版本

备份内容#

1. 核心文件#

文件/目录	内容	重要性
`src/`	源代码	高
`public/`	静态资源	高
`package.json`	依赖配置	高
`astro.config.mjs`	Astro 配置	高
`tsconfig.json`	TypeScript 配置	中
`tailwind.config.js`	Tailwind 配置	中
`src/config/`	网站配置	高
`src/content/`	文章内容	高
`src/components/`	自定义组件	中
`src/layouts/`	布局模板	中

2. 数据文件#

文章 Markdown 文件
图片和媒体文件
配置文件
主题自定义文件

备份方法#

1. Git 版本控制#

步骤：

初始化 Git 仓库
创建 .gitignore 文件
定期提交更改
推送到远程仓库

推荐 .gitignore：

1
# 依赖
2
node_modules/
3
npm-debug.log*
4
yarn-debug.log*
5
yarn-error.log*
6
pnpm-debug.log*
7

8
# 构建产物
9
dist/
10

11
# 环境变量
12
.env
13
.env.local
14
.env.development.local
15
.env.test.local
16
.env.production.local
17

18
# 编辑器
19
.vscode/
20
.idea/
21
*.swp
22
*.swo
23
*~
24

25
# 系统
26
.DS_Store
27
Thumbs.db
28

29
# 日志
30
logs
31
*.log
32

33
# 缓存
34
.cache/
35
.parcel-cache/
36
.next/
37
.nuxt/
38
.vuepress/dist
39
.serverless/
40
.fusebox/
41
.dynamodb/
42
.tern-port
43
.vscode-test
44
.yarn/cache
45
.yarn/unplugged
46
.yarn/build-state.yml
47
.yarn/install-state.gz
48
.pnp.*

展开收起

2. 手动备份#

步骤：

压缩项目目录
存储到安全位置
定期更新备份

命令：

Terminal window

1
# Windows
2
Compress-Archive -Path . -DestinationPath blog-backup-$(Get-Date -Format "yyyy-MM-dd").zip
3

4
# Linux/macOS
5
zip -r blog-backup-$(date +%Y-%m-%d).zip . -x "node_modules/*" "dist/*" ".git/*"

3. 自动化备份#

使用 GitHub Actions：

1
name: Backup Blog
2

3
on:
4
  schedule:
5
    - cron: '0 0 * * *'  # 每天凌晨执行
6
  push:
7
    branches:
8
      - main
9

10
jobs:
11
  backup:
12
    runs-on: ubuntu-latest
13
    steps:
14
      - uses: actions/checkout@v3
15
        with:
16
          fetch-depth: 0
17

18
      - name: Create backup
19
        run: |
20
          zip -r blog-backup-$(date +%Y-%m-%d).zip . -x "node_modules/*" "dist/*" ".git/*"
21

22
      - name: Upload backup to GitHub Releases
23
        uses: softprops/action-gh-release@v1
24
        with:
25
          files: blog-backup-*.zip
26
          name: Backup ${{ github.ref_name }} $(date +%Y-%m-%d)
27
          tag_name: backup-$(date +%Y-%m-%d)
28
          body: Automated backup

展开收起

4. 云存储备份#

使用 rclone：

Terminal window

1
# 安装 rclone
2
curl https://rclone.org/install.sh | sudo bash
3

4
# 配置 rclone
5
rclone config
6

7
# 同步备份
8
rclone sync ./ blog-backup:blog-backup/$(date +%Y-%m-%d)

恢复方法#

1. 从 Git 恢复#

步骤：

克隆仓库
安装依赖
构建网站

Terminal window

1
# 克隆仓库
2
git clone https://github.com/yourusername/your-blog.git
3

4
# 进入目录
5
cd your-blog
6

7
# 安装依赖
8
npm install
9

10
# 构建网站
11
npm run build
12

13
# 本地预览
14
npm run preview

2. 从备份文件恢复#

步骤：

解压备份文件
安装依赖
构建网站

Terminal window

1
# 解压备份
2
unzip blog-backup-2026-04-24.zip
3

4
# 进入目录
5
cd blog-backup-2026-04-24
6

7
# 安装依赖
8
npm install
9

10
# 构建网站
11
npm run build

3. 从云存储恢复#

步骤：

下载备份
解压文件
安装依赖
构建网站

Terminal window

1
# 从云存储下载
2
rclone copy blog-backup:blog-backup/2026-04-24 ./blog-backup
3

4
# 进入目录
5
cd blog-backup
6

7
# 安装依赖
8
npm install
9

10
# 构建网站
11
npm run build

数据迁移#

1. 迁移到新服务器#

步骤：

备份原网站
在新服务器克隆仓库
安装依赖
构建部署

注意事项：

保持环境一致性
配置相同的 Node.js 版本
迁移域名和 DNS 设置
测试功能完整性

2. 迁移到新平台#

步骤：

导出内容
适配新平台格式
导入内容
测试功能

支持的平台：

Vercel
Netlify
GitHub Pages
Cloudflare Pages
自建服务器

灾难恢复#

1. 紧急恢复流程#

评估损失：确定哪些文件受损
选择备份：选择最近的完整备份
恢复文件：从备份中恢复受损文件
验证功能：测试网站功能
预防措施：加强备份策略

2. 常见灾难场景#

场景	原因	解决方案
代码错误	代码修改导致网站崩溃	回滚到之前的版本
服务器故障	服务器宕机或数据丢失	从备份恢复到新服务器
域名问题	域名过期或被抢注	备份网站内容，重新配置域名
安全漏洞	被黑客攻击	从备份恢复，修复漏洞
数据损坏	数据库或文件损坏	从备份恢复数据

最佳实践#

1. 备份策略#

定期备份：每周至少备份一次
多份备份：在不同位置存储备份
版本控制：使用 Git 进行版本管理
自动化：设置自动备份任务
验证备份：定期测试备份的有效性

2. 存储位置#

存储位置	特点	适用场景
本地硬盘	快速访问	日常备份
外部硬盘	离线存储	重要备份
云存储	安全可靠	长期备份
GitHub Releases	版本控制	代码备份
NAS	本地网络存储	家庭用户

3. 备份频率#

内容	备份频率
文章内容	每次更新
配置文件	每次修改
完整网站	每周
数据库	每天

4. 安全措施#

加密备份：使用密码保护备份文件
访问控制：限制备份文件的访问权限
定期更新：更新备份工具和策略
监控：监控备份任务的执行状态

工具推荐#

1. 备份工具#

工具	平台	特点
Git	全平台	版本控制，代码备份
rclone	全平台	云存储同步
rsync	Linux/macOS	增量备份
Robocopy	Windows	Windows 备份
Duplicati	全平台	加密备份

2. 云存储服务#

服务	特点	适用场景
GitHub Releases	免费，版本控制	代码和配置备份
Google Drive	免费空间，易用	个人备份
Dropbox	同步功能，可靠	团队备份
OneDrive	微软生态，集成	Windows 用户
阿里云 OSS	稳定，国内访问快	国内用户

3. 监控工具#

工具	功能	适用场景
UptimeRobot	网站监控	监控网站可用性
GitHub Actions	自动化备份	定期备份执行
Cronitor	任务监控	监控备份任务
Healthchecks.io	任务监控	备份任务状态

常见问题#

Q: 备份文件太大？#

排除不必要的文件（node_modules, dist等）
使用增量备份
压缩备份文件
只备份关键文件

Q: 备份失败？#

检查存储空间
检查网络连接
检查权限设置
查看错误日志

Q: 恢复后网站异常？#

检查依赖版本
检查配置文件
清除浏览器缓存
检查服务器环境

Q: 备份耗时太长？#

使用增量备份
优化备份策略
选择更快的存储媒介
合理安排备份时间

Q: 如何验证备份有效性？#

定期测试恢复流程
检查备份文件完整性
验证关键文件是否存在
测试网站功能

高级配置#

1. 自动化备份脚本#

Windows 脚本：

backup.ps1展开收起

1
$date = Get-Date -Format "yyyy-MM-dd"
2
$backupDir = "D:\Backups\Blog"
3
$backupFile = "blog-backup-$date.zip"
4
$projectDir = "E:\GITHUB\firefly-replica"
5

6
# 创建备份目录
7
if (!(Test-Path $backupDir)) {
8
    New-Item -ItemType Directory -Path $backupDir -Force
9
}
10

11
# 压缩备份
12
Compress-Archive -Path $projectDir -DestinationPath "$backupDir\$backupFile" -CompressionLevel Optimal
13

14
# 保留最近30天的备份
15
Get-ChildItem $backupDir -Filter "*.zip" |
16
    Where-Object { $_.LastWriteTime -lt (Get-Date).AddDays(-30) } |
17
    Remove-Item -Force
18

19
Write-Host "备份完成: $backupFile"

展开收起

Linux/macOS 脚本：

backup.sh展开收起

1
#!/bin/bash
2
date=$(date +%Y-%m-%d)
3
backup_dir="/backups/blog"
4
backup_file="blog-backup-$date.zip"
5
project_dir="/home/user/blog"
6

7
# 创建备份目录
8
mkdir -p $backup_dir
9

10
# 压缩备份
11
zip -r "$backup_dir/$backup_file" $project_dir -x "node_modules/*" "dist/*" ".git/*"
12

13
# 保留最近30天的备份
14
find $backup_dir -name "*.zip" -mtime +30 -delete
15

16
echo "备份完成: $backup_file"

展开收起

2. 多环境备份#

开发环境备份：

包含所有开发文件
备份频率：每次代码提交

生产环境备份：

只包含生产必要文件
备份频率：每天

测试环境备份：

包含测试数据
备份频率：每次测试前

3. 数据库备份#

如果使用数据库：

Terminal window

1
# MySQL 备份
2
mysqldump -u username -p database_name > backup-$(date +%Y-%m-%d).sql
3

4
# SQLite 备份
5
cp database.db backup-$(date +%Y-%m-%d).db
6

7
# MongoDB 备份
8
mongodump --db database_name --out backup-$(date +%Y-%m-%d)

4. 备份监控#

使用 Healthchecks.io：

1
#!/bin/bash
2
# 执行备份
3
./backup.sh
4

5
# 通知 Healthchecks.io
6
curl -fsS --retry 3 https://hc-ping.com/your-uuid

总结#

备份是博客安全的重要保障，通过建立完善的备份策略，可以有效防止数据丢失，快速恢复网站。

建议：

建立定期备份习惯
使用多种备份方式
测试备份的有效性
存储备份到多个位置
自动化备份流程

希望本指南能帮助你建立可靠的备份和恢复系统，保障博客的安全运行！

18. 图片上传和管理指南

Fri, 10 Apr 2026 00:00:00 GMT

图片上传和管理指南#

基本概念#

图片是博客内容的重要组成部分，合理的图片管理可以：

提升文章的视觉效果
提高页面加载速度
优化SEO效果
节省存储空间

图片存储位置#

1. 本地存储#

存储路径：

public/assets/images/ - 公共图片
src/content/posts/images/ - 文章相关图片
src/content/posts/guide/ - 指南相关图片

优点：

完全控制
不依赖外部服务
访问速度快

缺点：

增加仓库大小
占用带宽
备份复杂

2. 图床存储#

推荐图床：

GitHub Pages
阿里云 OSS
腾讯云 COS
七牛云
Imgur
SM.MS

优点：

节省本地空间
提供 CDN 加速
便于管理

缺点：

依赖外部服务
可能有访问限制
部分服务需要付费

本地图片上传#

1. 上传步骤#

创建目录：在 public/assets/images/ 下创建相应的子目录
上传图片：将图片文件复制到对应目录
引用图片：在 Markdown 中使用相对路径引用

2. 图片引用格式#

1
<!-- 引用公共图片 -->
2
![图片描述](/assets/images/example.jpg)
3

4
<!-- 引用文章相关图片 -->
5
![图片描述](./images/example.jpg)

3. 目录结构示例#

1
public/
2
└── assets/
3
    └── images/
4
        ├── firefly1.avif
5
        ├── firefly2.avif
6
        ├── firefly3.avif
7
        └── posts/
8
            └── 2026/
9
                ├── post1.jpg
10
                └── post2.jpg

图床使用#

1. GitHub Pages 图床#

步骤：

创建专门的图片仓库
上传图片到仓库
使用 GitHub Pages 链接

链接格式：

1
https://username.github.io/repo-name/images/example.jpg

2. 阿里云 OSS#

步骤：

注册阿里云账号
创建 OSS Bucket
上传图片
获取访问链接

链接格式：

1
https://bucket-name.oss-cn-region.aliyuncs.com/images/example.jpg

3. 七牛云#

步骤：

注册七牛云账号
创建存储空间
上传图片
获取访问链接

链接格式：

1
https://domain-name.example.com/images/example.jpg

4. SM.MS#

步骤：

访问 SM.MS
上传图片
复制生成的链接

链接格式：

1
https://i.loli.net/2026/04/24/example.jpg

图片格式优化#

1. 推荐图片格式#

格式	特点	适用场景
WebP	高压缩率，支持透明	网站图片，头像
AVIF	更高压缩率	高质量图片
JPEG	广泛支持	照片，复杂图像
PNG	支持透明	图标，简单图形
SVG	矢量图形	图标，标志

2. 图片压缩#

在线工具：

本地工具：

ImageMagick
GraphicsMagick
Photoshop

3. 批量处理#

使用 Node.js 脚本：

1
const sharp = require('sharp');
2
const fs = require('fs');
3
const path = require('path');
4

5
const inputDir = './images';
6
const outputDir = './optimized';
7

8
if (!fs.existsSync(outputDir)) {
9
    fs.mkdirSync(outputDir);
10
}
11

12
fs.readdirSync(inputDir).forEach(file => {
13
    if (file.match(/\.(jpg|jpeg|png|webp)$/i)) {
14
        const inputPath = path.join(inputDir, file);
15
        const outputPath = path.join(outputDir, path.parse(file).name + '.webp');
16

17
        sharp(inputPath)
18
            .webp({ quality: 85 })
19
            .toFile(outputPath)
20
            .then(() => {
21
                console.log(`Optimized ${file}`);
22
            });
23
    }
24
});

展开收起

图片加载优化#

1. 懒加载#

HTML 原生懒加载：

1
<img src="./images/example.jpg" alt="示例" loading="lazy">

JavaScript 懒加载：

1
// 使用 Intersection Observer
2
const images = document.querySelectorAll('img[data-src]');
3

4
const observer = new IntersectionObserver((entries) => {
5
    entries.forEach(entry => {
6
        if (entry.isIntersecting) {
7
            const img = entry.target;
8
            img.src = img.dataset.src;
9
            observer.unobserve(img);
10
        }
11
    });
12
});
13

14
images.forEach(img => observer.observe(img));

2. 响应式图片#

使用 srcset：

1
<img
2
    src="./images/example-small.jpg"
3
    srcset="./images/example-small.jpg 400w, ./images/example-medium.jpg 800w, ./images/example-large.jpg 1200w"
4
    sizes="(max-width: 600px) 400px, (max-width: 1200px) 800px, 1200px"
5
    alt="示例"
6
>

使用 picture 元素：

1
<picture>
2
    <source srcset="./images/example.avif" type="image/avif">
3
    <source srcset="./images/example.webp" type="image/webp">
4
    <img src="./images/example.jpg" alt="示例">
5
</picture>

3. 预加载#

关键图片预加载：

1
<link rel="preload" href="./images/hero.jpg" as="image">

字体图标预加载：

1
<link rel="preload" href="./fonts/iconfont.woff2" as="font" type="font/woff2" crossorigin>

图片 SEO 优化#

1. 文件名优化#

建议：

使用描述性文件名
用连字符分隔单词
包含关键词
避免特殊字符

示例：

好：blog-setup-guide.jpg
坏：IMG_1234.jpg

2. Alt 文本优化#

建议：

简短描述图片内容
包含关键词
避免重复页面标题
对于装饰性图片使用空 alt

示例：

1
![Firefly 主题博客搭建指南](./images/blog-setup-guide.jpg)

3. 图片 sitemap#

创建图片 sitemap：

1
<?xml version="1.0" encoding="UTF-8"?>
2
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:image="http://www.google.com/schemas/sitemap-image/1.1">
3
  <url>
4
    <loc>https://your-blog.com/posts/setup-guide/</loc>
5
    <image:image>
6
      <image:loc>https://your-blog.com/assets/images/blog-setup-guide.jpg</image:loc>
7
      <image:caption>Firefly 主题博客搭建指南</image:caption>
8
      <image:title>博客搭建指南</image:title>
9
    </image:image>
10
  </url>
11
</urlset>

4. 结构化数据#

添加图片结构化数据：

1
{
2
  "@context": "https://schema.org",
3
  "@type": "BlogPosting",
4
  "image": [
5
    "https://your-blog.com/assets/images/blog-setup-guide.jpg"
6
  ],
7
  "url": "https://your-blog.com/posts/setup-guide/",
8
  "headline": "Firefly 主题博客搭建指南",
9
  "description": "详细的 Firefly 主题博客搭建教程"
10
}

常见问题#

Q: 图片不显示？#

检查图片路径是否正确
确认图片文件是否存在
检查图片格式是否支持
清除浏览器缓存
检查服务器权限

Q: 图片加载慢？#

压缩图片大小
使用 WebP 或 AVIF 格式
启用图片懒加载
使用 CDN 加速
优化服务器配置

Q: 图片在移动端显示异常？#

使用响应式图片
设置 max-width: 100%
测试不同设备的显示效果
调整图片尺寸

Q: 图床图片失效？#

选择可靠的图床服务
定期备份图片
考虑使用多个图床
检查图床服务状态

Q: 图片 SEO 效果不好？#

优化图片文件名
添加描述性 alt 文本
创建图片 sitemap
添加结构化数据
确保图片加载速度

最佳实践#

1. 图片管理#

建立目录结构：按年份、类别组织图片
统一命名规范：使用描述性文件名
定期清理：删除未使用的图片
备份策略：定期备份图片文件

2. 性能优化#

格式选择：根据图片类型选择合适格式
压缩处理：使用工具压缩图片
懒加载：启用图片懒加载
CDN 加速：使用 CDN 分发图片

3. SEO 优化#

alt 文本：为所有图片添加 alt 文本
文件名：使用关键词丰富的文件名
结构化数据：添加图片结构化数据
sitemap：创建图片 sitemap

4. 安全性#

版权检查：确保图片使用合法
水印添加：为重要图片添加水印
防盗链：设置图片防盗链
隐私保护：避免敏感信息

5. 工具推荐#

图片处理工具：

在线工具：TinyPNG, Squoosh, Compress PNG
本地工具：ImageMagick, GraphicsMagick, Photoshop
批量处理：Sharp (Node.js), ImageOptim (Mac)

图床工具：

浏览器插件：PicGo, uPic
命令行工具：img-uploader
自动化：GitHub Actions 自动上传

高级技巧#

1. 图片 CDN 配置#

使用 Cloudflare CDN：

注册 Cloudflare 账号
添加域名
配置 DNS
启用 CDN 加速

CDN 缓存策略：

1
Cache-Control: public, max-age=31536000, immutable

2. 图片处理服务#

使用 imgix：

注册 imgix 账号
配置源站
使用 imgix URL 处理图片

示例：

1
https://your-imgix-domain.imgix.net/images/example.jpg?w=800&h=600&fit=crop&auto=format

3. 自动化工作流#

GitHub Actions 自动化：

1
name: Optimize Images
2

3
on:
4
  push:
5
    paths:
6
      - 'public/assets/images/**'
7

8
jobs:
9
  optimize:
10
    runs-on: ubuntu-latest
11
    steps:
12
      - uses: actions/checkout@v3
13
      - name: Install dependencies
14
        run: npm install sharp
15
      - name: Optimize images
16
        run: node scripts/optimize-images.js
17
      - name: Commit changes
18
        run: |
19
          git config --global user.name 'GitHub Actions'
20
          git config --global user.email 'actions@github.com'
21
          git add public/assets/images/
22
          git commit -m 'chore: optimize images'
23
          git push

展开收起

4. 图片懒加载库#

使用 lazysizes：

1
<script src="https://cdn.jsdelivr.net/npm/lazysizes@5.3.2/lazysizes.min.js"></script>
2
<img data-src="./images/example.jpg" class="lazyload" alt="示例">

使用 lozad.js：

1
<script src="https://cdn.jsdelivr.net/npm/lozad@1.16.0/dist/lozad.min.js"></script>
2
<script>
3
  const observer = lozad();
4
  observer.observe();
5
</script>
6
<img data-src="./images/example.jpg" class="lozad" alt="示例">

总结#

图片管理是博客优化的重要环节，通过合理的图片存储、格式优化和加载策略，可以显著提升博客的用户体验和SEO效果。

建议：

选择合适的图片存储方案
优化图片格式和大小
启用懒加载和响应式图片
重视图片的SEO优化
建立良好的图片管理习惯

希望本指南能帮助你更好地管理博客图片，提升博客的整体质量！

17. Markdown 文章写作指南

Thu, 09 Apr 2026 00:00:00 GMT

Markdown写作指南#

这篇文章不是纯语法手册，而是给新手看的实操版说明。你可以把它理解成一份“照着做就能写出一篇博客”的速查表。

先记住这 6 条#

Markdown 本质上就是“用简单符号排版普通文字”。
标题前面用 #，列表前面用 - 或 1.。
代码块一定单独成段，不要和正文挤在同一行。
图片、表格、引用前后最好空一行，排版更稳定。
不确定语法时，先本地预览，看到对了再发布。
新手最常见问题不是“不会写”，而是“少了空行、少了反引号、路径写错了”。

新手发布一篇文章的最短流程#

如果你只是想尽快发一篇文章，先照下面做一遍。

第 1 步：启动本地预览#

Terminal window

1
cd E:\GITHUB\firefly-replica
2
pnpm dev

启动后，浏览器打开本地地址，看着页面边改边预览。

第 2 步：新建或编辑文章文件#

这个项目真正读取的是：

1
src/content/posts/

你可以在这个目录里新建一个 Markdown 文件，比如：

1
src/content/posts/22.md

第 3 步：先写好文章头信息#

1
---
2
title: 文章标题
3
published: 2026-04-19
4
description: 用一句话说明这篇文章写什么
5
tags: [学习笔记]
6
category: 博客搭建
7
author: Coldairboy
8
image: ./images/firefly1.avif
9
---

第 4 步：按这个结构写正文#

1
# 文章大标题
2

3
开头先用 1 到 2 句话说明这篇文章讲什么。
4

5
## 第一部分
6

7
正文内容……
8

9
## 第二部分
10

11
- 要点 1
12
- 要点 2
13
- 要点 3
14

15
## 总结
16

17
最后写一句总结。

展开收起

第 5 步：检查效果#

重点看这几个地方：

标题有没有层级错乱
列表有没有挤在同一行
代码块有没有完整包住
图片能不能正常显示
链接能不能点开

第 6 步：推送到 GitHub Pages#

如果你已经改好内容，直接运行：

Terminal window

1
cd E:\GITHUB\firefly-replica
2
.\publish-blog.bat

如果你之前已经提交过，只是推送失败了，就运行：

Terminal window

1
cd E:\GITHUB\firefly-replica
2
.\push-only.bat

最常用的 Markdown 语法#

新手前期不用全学，先把下面这些用熟就够了。

1. 标题#

1
# 一级标题
2
## 二级标题
3
### 三级标题
4
#### 四级标题

提醒：

一篇文章通常只保留一个 # 一级标题
不要一级标题后直接跳到四级标题
层级尽量按顺序来，看起来更清楚

2. 强调文字#

1
**粗体**
2
*斜体*
3
***粗斜体***
4
~~删除线~~
5
`行内代码`

适合怎么用：

粗体：强调重点
行内代码：写命令、文件名、变量名时很好用
不要一整段都加粗，不然反而看不出重点

3. 无序列表#

1
- 第一项
2
- 第二项
3
- 第三项

4. 有序列表#

1
1. 第一步
2
2. 第二步
3
3. 第三步

提醒：

1. 后面要有空格
如果序号写在同一行，Markdown 可能不会正确识别
子列表要缩进

1
1. 第一步
2
2. 第二步
3
   1. 子步骤一
4
   2. 子步骤二
5
3. 第三步

5. 链接#

1
[OpenAI](https://openai.com)
2
[GitHub](https://github.com "GitHub 官网")

提醒：

方括号里放显示文字
小括号里放网址
地址最好复制后顺手点开试一次

6. 图片#

1
![图片说明](./images/example.jpg)

提醒：

! 不能漏
图片说明建议写上，方便阅读和 SEO
路径写错是最常见问题

7. 引用#

1
> 这是一段引用内容
2
> 可以连续写多行

适合用在：

摘录一句原话
写提示语
写总结结论

8. 代码块#

普通代码块：

1
```
2
这里放普通代码
3
```

带语法高亮的代码块：

1
```javascript
2
console.log("Hello");
3
```
4

5
```bash
6
pnpm dev
7
```

提醒：

代码块前后空一行更稳
开始和结束的反引号数量必须一致
写命令推荐用 bash 或 powershell
写配置推荐用 json、yaml、html、css

9. 表格#

1
| 名称 | 说明 | 备注 |
2
| --- | --- | --- |
3
| title | 文章标题 | 必填 |
4
| published | 发布日期 | 必填 |
5
| tags | 标签 | 可选 |

提醒：

表头和分隔线不要漏
列太多时，手机上会不太好看
新手前期不建议做太复杂的表格

10. 分隔线#

1
---

适合用来分开两个大段落，但不要一篇文章到处乱插。

博客里常用的扩展语法#

如果只是普通写文章，下面这些够用了。

1. 任务列表#

1
- [x] 已完成
2
- [ ] 未完成
3
- [ ] 待补充

适合写待办清单、教程步骤进度。

2. 脚注#

1
这里有一个说明[^1]
2

3
[^1]: 这是脚注内容

适合补充说明，不打断正文阅读。

3. 数学公式#

行内公式：

1
$E = mc^2$

块级公式：

1
$$
2
E = mc^2
3
$$

4. Mermaid 图表#

1
```mermaid
2
graph TD
3
    A[开始] --> B[写文章]
4
    B --> C[本地预览]
5
    C --> D[推送发布]
6
```

适合画简单流程图。第一次使用时，如果页面不显示，先检查主题是否已开启 Mermaid 支持。

5. 提示框#

1
::: tip
2
这是提示信息
3
:::
4

5
::: warning
6
这是警告信息
7
:::

适合把“重点提醒”单独强调出来。

新手最好直接套用的文章模板#

不会写结构时，直接复制下面这份最稳。

1
---
2
title: 文章标题
3
published: 2026-04-19
4
description: 一句话简介
5
tags: [学习笔记]
6
category: 博客搭建
7
author: Coldairboy
8
image: ./images/firefly1.avif
9
---
10

11
# 文章标题
12

13
先用一小段话告诉读者：这篇文章解决什么问题。
14

15
## 背景
16

17
为什么写这篇文章。
18

19
## 操作步骤
20

21
### 1. 第一步
22

23
写步骤说明。
24

25
### 2. 第二步
26

27
继续写步骤说明。
28

29
## 注意事项
30

31
- 注意点 1
32
- 注意点 2
33
- 注意点 3
34

35
## 总结
36

37
最后总结一下。

展开收起

发布前检查清单#

每次发文章前，快速过一遍下面这些，能少踩很多坑。

标题有没有写错别字
published 日期有没有填错
description 有没有写
代码块有没有正常闭合
图片路径是不是相对当前文章文件
外链能不能正常打开
手机端看起来会不会太挤
有没有模板残留内容没改掉

新手最容易踩的坑#

1. 少空行#

错误示例：

1
## 标题
2
- 列表1
3
- 列表2

虽然有时也能显示，但复杂一点时容易乱。更稳的写法是段落之间留空行。

2. 代码块没关上#

如果少了结尾的三个反引号，后面整段内容都可能跑进代码框。

3. 把中文符号当成英文符号#

最常见的是：

把 ` 写成中文引号
把 : 写成中文冒号
把 () 写成全角括号

这些都会影响语法识别。

4. 图片路径写错#

如果文章和图片不在同一目录，路径就不能随便写。看不到图片时，优先检查路径，而不是先怀疑主题坏了。

5. Frontmatter 写串行#

比如这种就是错的：

1
author: Coldairboy image: ./images/firefly1.avif

正确写法必须一行一个字段：

1
author: Coldairboy
2
image: ./images/firefly1.avif

6. 文件改了，但网页没变#

这在这个项目里通常有 3 个原因：

你改的是 src/content/，但站点实际读取的是 src/content/posts/
本地服务没刷新成功
改完了但还没推送到 GitHub

常见问题#

Q: 为什么我写了序号，却没有显示成列表？#

先检查这 3 点：

1. 后面有没有空格
每一项是不是单独一行
前后有没有被代码块包住

Q: 为什么代码没有高亮？#

通常是因为没有写语言标记，比如：

1
```bash
2
pnpm dev
3
```

Q: 为什么图片不显示？#

按这个顺序检查最省事：

文件在不在
路径对不对
文件名大小写对不对
本地预览能不能看到

Q: 为什么文章顺序不对？#

文章列表主要看 published 日期。日期越晚，通常越靠前。

给新手的最后建议#

前期先学会标题、列表、链接、图片、代码块这 5 个核心语法
每次只学一个新语法，马上在文章里用一次
本地预览看到正常，再推送上线
语法记不住很正常，写博客本来就可以边查边写

Markdown 不难，真正重要的是把内容写清楚。先保证“能看懂、结构清楚、步骤完整”，再慢慢追求更漂亮的排版。

16. 国际化配置指南

Wed, 08 Apr 2026 00:00:00 GMT

国际化配置指南#

基本概念#

国际化（Internationalization，简称 i18n）是指让网站支持多种语言的能力。通过国际化配置，你的博客可以：

支持多语言内容
自动切换语言
提供更好的用户体验
扩大全球受众

配置文件位置#

1. 语言配置#

src/config/siteConfig.ts 中的 lang 字段：

1
export const siteConfig: SiteConfig = {
2
    // 网站语言
3
    lang: "zh_CN",
4
};

2. 语言文件#

语言文件通常位于：

src/locales/ 目录
每个语言一个文件，如 zh-CN.ts、en.ts 等

语言文件结构#

1. 基本结构#

src/locales/zh-CN.ts展开收起

1
export const zhCN = {
2
    common: {
3
        home: "首页",
4
        about: "关于",
5
        archive: "归档",
6
        search: "搜索",
7
        category: "分类",
8
        tag: "标签",
9
        comments: "评论",
10
        share: "分享",
11
        more: "更多",
12
        backToTop: "回到顶部",
13
    },
14

15
    nav: {
16
        home: "首页",
17
        about: "关于",
18
        archive: "归档",
19
        categories: "分类",
20
        tags: "标签",
21
        friends: "友链",
22
        sponsor: "赞助",
23
        guestbook: "留言板",
24
    },
25

26
    post: {
27
        published: "发布于",
28
        updated: "更新于",
29
        author: "作者",
30
        category: "分类",
31
        tags: "标签",
32
        readingTime: "阅读时间",
33
        wordCount: "字数",
34
        comments: "评论",
35
        share: "分享",
36
        relatedPosts: "相关文章",
37
        prevPost: "上一篇",
38
        nextPost: "下一篇",
39
    },
40
};

展开收起

2. 英文语言文件#

src/locales/en.ts展开收起

1
export const en = {
2
    common: {
3
        home: "Home",
4
        about: "About",
5
        archive: "Archive",
6
        search: "Search",
7
        category: "Category",
8
        tag: "Tag",
9
        comments: "Comments",
10
        share: "Share",
11
        more: "More",
12
        backToTop: "Back to top",
13
    },
14

15
    nav: {
16
        home: "Home",
17
        about: "About",
18
        archive: "Archive",
19
        categories: "Categories",
20
        tags: "Tags",
21
        friends: "Friends",
22
        sponsor: "Sponsor",
23
        guestbook: "Guestbook",
24
    },
25

26
    post: {
27
        published: "Published on",
28
        updated: "Updated on",
29
        author: "Author",
30
        category: "Category",
31
        tags: "Tags",
32
        readingTime: "Reading time",
33
        wordCount: "Word count",
34
        comments: "Comments",
35
        share: "Share",
36
        relatedPosts: "Related posts",
37
        prevPost: "Previous post",
38
        nextPost: "Next post",
39
    },
40
};

展开收起

启用多语言支持#

1. 配置语言选项#

在 src/config/i18nConfig.ts 中：

1
export const i18nConfig = {
2
    // 支持的语言列表
3
    languages: [
4
        {
5
            code: "zh-CN",
6
            name: "中文",
7
            default: true,
8
        },
9
        {
10
            code: "en",
11
            name: "English",
12
        },
13
    ],
14

15
    // 语言切换器配置
16
    switcher: {
17
        show: true,
18
        position: "navbar", // navbar, sidebar, footer
19
    },
20
};

展开收起

2. 导入语言文件#

在需要使用翻译的组件中：

1
import { zhCN, en } from '@/locales';
2

3
// 根据当前语言选择翻译
4
const t = currentLang === 'zh-CN' ? zhCN : en;

翻译内容#

1. 静态内容翻译#

1
// 在组件中使用
2
<h1>{t.nav.home}</h1>
3
<p>{t.post.published}</p>

2. 动态内容翻译#

对于文章内容，通常有两种方式：

方法 A：多语言文件

为每种语言创建单独的文章文件
如 post-zh.md、post-en.md

方法 B：前端翻译

使用翻译函数动态翻译内容
适合简短的动态内容

3. 路由国际化#

为不同语言创建不同的路由：

中文：/posts/my-post/
英文：/en/posts/my-post/

语言切换#

1. 语言切换组件#

src/components/i18n/LanguageSwitcher.astro展开收起

1
---
2
import { i18nConfig } from '@/config/i18nConfig';
3

4
const { languages } = i18nConfig;
5
---
6

7
<div class="language-switcher">
8
  {languages.map(lang => (
9
    <button
10
      key={lang.code}
11
      class={`lang-button ${lang.default ? 'active' : ''}`}
12
    >
13
      {lang.name}
14
    </button>
15
  ))}
16
</div>

展开收起

2. 语言切换逻辑#

1
// 切换语言
2
function switchLanguage(langCode) {
3
    // 保存语言偏好到 localStorage
4
    localStorage.setItem('language', langCode);
5

6
    // 重新加载页面
7
    window.location.reload();
8
}
9

10
// 获取当前语言
11
function getCurrentLanguage() {
12
    return localStorage.getItem('language') || 'zh-CN';
13
}

日期和时间国际化#

1. 日期格式化#

1
// 格式化日期
2
function formatDate(date, lang) {
3
    const options = {
4
        year: 'numeric',
5
        month: 'long',
6
        day: 'numeric'
7
    };
8
    return new Intl.DateTimeFormat(lang, options).format(date);
9
}

2. 时间格式化#

1
// 格式化时间
2
function formatTime(date, lang) {
3
    const options = {
4
        hour: '2-digit',
5
        minute: '2-digit'
6
    };
7
    return new Intl.DateTimeFormat(lang, options).format(date);
8
}

SEO 国际化#

1. 多语言 SEO 最佳实践#

hreflang 标签：在头部添加语言 alternate 链接
** canonical URLs**：为每个语言版本设置规范 URL
语言特定内容：为每种语言创建独特的内容
本地化关键词：使用语言特定的关键词

2. hreflang 标签#

1
<link rel="alternate" hreflang="zh-CN" href="https://your-blog.com/posts/my-post/" />
2
<link rel="alternate" hreflang="en" href="https://your-blog.com/en/posts/my-post/" />
3
<link rel="alternate" hreflang="x-default" href="https://your-blog.com/posts/my-post/" />

常见问题#

Q: 语言切换不生效？#

检查语言文件是否正确导入
确认 localStorage 是否正确设置
检查语言切换逻辑是否正确
清除浏览器缓存

Q: 翻译内容不显示？#

检查语言文件中的键是否正确
确认当前语言是否正确
检查翻译函数是否正确调用
清除浏览器缓存

Q: 日期格式不正确？#

检查 Intl.DateTimeFormat 配置
确认语言代码是否正确
测试不同浏览器的兼容性

Q: 如何添加新语言？#

创建新的语言文件（如 ja.ts）
在 i18nConfig.ts 中添加语言配置
翻译所有需要的内容
测试新语言是否正常显示

Q: 如何处理 RTL 语言？#

为 RTL 语言添加特殊样式
使用 CSS direction: rtl
调整布局和排版
测试 RTL 显示效果

最佳实践#

1. 内容管理#

保持一致性：确保所有语言版本的内容结构一致
专业翻译：使用专业的翻译服务，避免机器翻译
定期更新：确保所有语言版本同步更新
文化适配：考虑不同文化的差异

2. 技术实现#

使用标准：遵循 i18n 最佳实践和标准
性能优化：按需加载语言文件
缓存策略：缓存语言偏好设置
错误处理：处理语言文件加载失败的情况

3. 用户体验#

自动检测：根据浏览器设置自动选择语言
明确切换：提供清晰的语言切换选项
保存偏好：记住用户的语言选择
回退机制：当翻译不存在时使用默认语言

4. SEO 优化#

多语言站点地图：为每种语言创建单独的站点地图
语言特定 URL：使用语言代码作为 URL 前缀
本地化内容：为每种语言创建独特的元数据
结构化数据：使用语言特定的结构化数据

高级配置#

1. 自动翻译工具#

可以使用以下工具辅助翻译：

Google Translate API
DeepL API
i18next
react-i18next

2. 翻译管理系统#

对于大型博客，可以使用专业的翻译管理系统：

Lokalise
Crowdin
Transifex
POEditor

3. 动态内容翻译#

对于用户生成的内容，可以使用：

实时翻译：使用翻译 API 实时翻译
人工审核：结合机器翻译和人工审核
社区翻译：允许社区贡献翻译

4. 语言检测#

1
// 检测浏览器语言
2
function detectBrowserLanguage() {
3
    return navigator.language || navigator.userLanguage;
4
}
5

6
// 检测用户语言偏好
7
function detectUserLanguage() {
8
    return localStorage.getItem('language') || detectBrowserLanguage() || 'zh-CN';
9
}

通过合理配置国际化，可以使你的博客面向全球用户，提供更好的多语言体验！

15. 分类和标签配置指南

Tue, 07 Apr 2026 00:00:00 GMT

分类和标签配置指南#

基本概念#

分类（Category）：文章的主要分类，通常是层级化的，每个文章通常只有一个主分类
标签（Tags）：文章的关键词，通常是扁平化的，每个文章可以有多个标签

文章分类设置#

1. 单个分类#

1
---
2
title: 我的文章
3
category: 博客搭建
4
---

2. 多级分类#

1
---
2
title: 我的文章
3
category: 技术笔记/前端开发
4
---

文章标签设置#

1. 单个标签#

1
---
2
title: 我的文章
3
tags: [前端开发]
4
---

2. 多个标签#

1
---
2
title: 我的文章
3
tags: [前端开发, React, TypeScript]
4
---

分类栏配置#

1. 启用分类栏#

在 src/config/siteConfig.ts 中：

1
export const siteConfig: SiteConfig = {
2
    // 启用分类栏
3
    categoryBar: true,
4
};

2. 分类栏显示位置#

分类栏默认显示在导航栏下方，包含所有文章的分类。

分类页配置#

1. 分类页生成#

系统会自动为每个分类生成对应的分类页：

分类页 URL：/category/分类名称/
分类页会显示该分类下的所有文章

2. 分类页标题#

分类页标题默认为分类名称，可以在分类配置中自定义。

标签页配置#

1. 标签页生成#

系统会自动为每个标签生成对应的标签页：

标签页 URL：/tag/标签名称/
标签页会显示包含该标签的所有文章

2. 标签云#

标签云会显示在侧边栏或其他位置，按标签使用频率显示大小。

分类和标签排序#

1. 文章排序#

在分类页和标签页中，文章默认按发布日期倒序排列（最新的在前）。

2. 分类排序#

分类的显示顺序：

按分类名称字母顺序
可以在配置中自定义排序

3. 标签排序#

标签的显示顺序：

按标签使用频率（使用次数多的在前）
可以在配置中自定义排序

自定义分类和标签#

1. 分类配置文件#

可以创建分类配置文件来自定义分类信息：

src/config/categoryConfig.ts展开收起

1
export const categoryConfig = {
2
    categories: [
3
        {
4
            id: "blog-setup",
5
            name: "博客搭建",
6
            description: "关于博客搭建的教程和经验",
7
            order: 1,  // 排序权重
8
        },
9
        {
10
            id: "front-end",
11
            name: "前端开发",
12
            description: "前端开发相关内容",
13
            order: 2,
14
        },
15
    ],
16
};

展开收起

2. 标签配置文件#

可以创建标签配置文件来自定义标签信息：

src/config/tagConfig.ts

1
export const tagConfig = {
2
    tags: [
3
        {
4
            id: "react",
5
            name: "React",
6
            description: "React 相关内容",
7
        },
8
        {
9
            id: "typescript",
10
            name: "TypeScript",
11
            description: "TypeScript 相关内容",
12
        },
13
    ],
14
};

分类和标签的 SEO 优化#

1. 分类页 SEO#

标题：包含分类名称和网站名称
描述：分类的详细描述
关键词：分类相关的关键词
** canonical URL**：避免重复内容

2. 标签页 SEO#

标题：包含标签名称和网站名称
描述：标签的详细描述
关键词：标签相关的关键词
** canonical URL**：避免重复内容

常见问题#

Q: 分类和标签不显示？#

检查文章 frontmatter 中分类和标签格式是否正确
确保分类栏已启用（categoryBar: true）
清除浏览器缓存
检查是否有 CSS 样式隐藏了分类栏

Q: 分类页显示 404？#

确保至少有一篇文章使用了该分类
检查分类名称是否包含特殊字符
重新构建网站
检查路由配置

Q: 如何删除分类？#

从所有文章中移除该分类
重新构建网站
分类会自动从分类栏中消失

Q: 如何合并分类？#

将所有文章的分类统一修改为新分类
重新构建网站
旧分类会自动消失

Q: 标签云不显示？#

确保至少有文章使用了标签
检查侧边栏配置中标签云组件是否启用
清除浏览器缓存
检查是否有 CSS 样式隐藏了标签云

最佳实践#

1. 分类体系#

保持简洁：分类数量不宜过多（建议 5-10 个）
层级合理：最多 2-3 级分类
命名规范：使用清晰、准确的分类名称
避免重叠：分类之间避免内容重叠

2. 标签使用#

相关性：标签应与文章内容相关
一致性：使用统一的标签命名规范
数量控制：每篇文章标签数量控制在 3-5 个
避免重复：避免使用同义词作为不同标签

3. 内容组织#

分类为主：使用分类作为主要组织方式
标签为辅：使用标签作为补充和细化
定期整理：定期检查和整理分类和标签
用户体验：确保分类和标签导航清晰易用

4. SEO 优化#

分类页面：为每个分类创建独特的描述
标签页面：为每个标签创建独特的描述
内部链接：在文章中合理使用分类和标签链接
sitemap：确保分类和标签页包含在站点地图中

高级配置#

1. 自定义分类页面模板#

可以创建自定义的分类页面模板：

src/pages/category/[slug].astro展开收起

1
---
2
import Layout from '@/layouts/Layout.astro';
3
import { getCollection } from 'astro:content';
4

5
const { slug } = Astro.params;
6
const posts = await getCollection('posts', ({ data }) =>
7
  data.category === slug
8
);
9
---
10

11
<Layout title={`分类：${slug}`}>
12
  <h1>分类：{slug}</h1>
13
  <ul>
14
    {posts.map(post => (
15
      <li>
16
        <a href={`/posts/${post.slug}/`}>{post.data.title}</a>
17
      </li>
18
    ))}
19
  </ul>
20
</Layout>

展开收起

2. 自定义标签页面模板#

可以创建自定义的标签页面模板：

src/pages/tag/[slug].astro展开收起

1
---
2
import Layout from '@/layouts/Layout.astro';
3
import { getCollection } from 'astro:content';
4

5
const { slug } = Astro.params;
6
const posts = await getCollection('posts', ({ data }) =>
7
  data.tags && data.tags.includes(slug)
8
);
9
---
10

11
<Layout title={`标签：${slug}`}>
12
  <h1>标签：{slug}</h1>
13
  <ul>
14
    {posts.map(post => (
15
      <li>
16
        <a href={`/posts/${post.slug}/`}>{post.data.title}</a>
17
      </li>
18
    ))}
19
  </ul>
20
</Layout>

展开收起

3. 分类和标签统计#

可以在首页或侧边栏显示分类和标签的文章数量：

1
// 分类统计
2
const categoryStats = {};
3
posts.forEach(post => {
4
  const category = post.data.category;
5
  if (category) {
6
    categoryStats[category] = (categoryStats[category] || 0) + 1;
7
  }
8
});
9

10
// 标签统计
11
const tagStats = {};
12
posts.forEach(post => {
13
  const tags = post.data.tags || [];
14
  tags.forEach(tag => {
15
    tagStats[tag] = (tagStats[tag] || 0) + 1;
16
  });
17
});

展开收起

通过合理配置分类和标签，可以使博客内容更加组织化，提高用户体验和SEO效果！

14. 站点分析配置指南

Mon, 06 Apr 2026 00:00:00 GMT

站点分析配置指南#

配置文件位置#

src/config/siteConfig.ts

基本配置#

1
export const siteConfig: SiteConfig = {
2
    // 站点分析配置
3
    analytics: {
4
        // Google Analytics
5
        googleAnalyticsId: "",
6

7
        // Microsoft Clarity
8
        microsoftClarityId: "",
9

10
        // Umami Analytics
11
        umamiAnalytics: {
12
            websiteId: "",
13
            scriptUrl: "https://cloud.umami.is/script.js",
14
            trackOutboundLinks: true,
15
            collectWebVitals: false,
16
            relpays: {
17
                enabled: false,
18
                sampleRate: 0.15,
19
                maskLevel: "moderate",
20
                maxDuration: 300000,
21
                blockSelector: "",
22
            },
23
        },
24

25
        // La51 Analytics
26
        la51Analytics: {
27
            Id: "",
28
            sdkUrl: "",
29
            ck: "",
30
            autoTrack: false,
31
            hashMode: false,
32
            screenRecord: true,
33
        },
34
    },
35
};

展开收起

Google Analytics 配置#

1. 获取 Google Analytics ID#

访问 Google Analytics
创建或选择项目
选择 “网站” 作为媒体资源类型
填写网站信息
复制生成的 G-XXXXXX 格式的跟踪 ID

2. 配置 Google Analytics#

1
alytics: {
2
    googleAnalyticsId: "G-XXXXXXXXXX",
3
},

3. 验证安装#

部署网站
访问网站
在 Google Analytics 后台查看实时数据
确认数据是否正常采集

Microsoft Clarity 配置#

1. 获取 Clarity 项目 ID#

访问 Microsoft Clarity
创建新项目
填写网站信息
复制生成的项目 ID

2. 配置 Clarity#

1
alytics: {
2
    microsoftClarityId: "XXXXXXXX",
3
},

3. 功能特点#

热图：可视化用户点击、滚动行为
会话录制：记录用户浏览过程
漏斗分析：分析用户转化路径
用户行为分析：了解用户如何与网站交互

Umami Analytics 配置#

1. 获取 Umami 配置#

方法 A：使用 Umami 云服务#

访问 Umami Cloud
创建账号和网站
获取 websiteId
复制默认的 scriptUrl

方法 B：自托管 Umami#

按照 Umami 文档部署
获取自托管的 scriptUrl
创建网站并获取 websiteId

2. 配置 Umami#

1
alytics: {
2
    umamiAnalytics: {
3
        websiteId: "your-website-id",
4
        scriptUrl: "https://your-umami-instance.com/script.js",
5
        trackOutboundLinks: true,  // 跟踪外部链接点击
6
        collectWebVitals: true,    // 收集 Core Web Vitals 数据
7
    },
8
},

3. 高级配置#

1
umamiAnalytics: {
2
    // ... 基本配置 ...
3
    relpays: {
4
        enabled: true,           // 启用会话录制
5
        sampleRate: 0.5,         // 采样率（0-1）
6
        maskLevel: "moderate",   // 隐私保护级别
7
        maxDuration: 300000,     // 最大录制时长（毫秒）
8
        blockSelector: ".privacy-sensitive",  // 排除元素选择器
9
    },
10
},

La51 Analytics 配置#

1. 获取 La51 配置#

访问 La51 Analytics
创建账号和项目
获取 Id、sdkUrl 和 ck 参数

2. 配置 La51#

1
alytics: {
2
    la51Analytics: {
3
        Id: "your-la51-id",
4
        sdkUrl: "https://your-la51-sdk-url.com",
5
        ck: "your-la51-ck",
6
        autoTrack: true,        // 自动跟踪
7
        hashMode: false,        // 是否使用哈希模式
8
        screenRecord: true,      // 启用屏幕录制
9
    },
10
},

分析工具比较#

工具	类型	价格	特点
Google Analytics	综合分析	免费	功能全面，集成Google生态
Microsoft Clarity	用户行为	免费	热图和会话录制
Umami	轻量分析	免费/付费	隐私友好，界面简洁
La51 Analytics	综合分析	付费	深度用户行为分析

最佳实践#

1. 隐私合规#

添加隐私政策：在网站添加隐私政策页面
Cookie 同意：实现 Cookie 同意弹窗
数据最小化：只收集必要的分析数据
GDPR 合规：确保符合数据保护法规

2. 性能优化#

延迟加载：分析脚本使用 defer 或 async
选择轻量工具：优先选择 Umami 等轻量分析工具
合理采样：对于会话录制，设置适当的采样率
避免过多工具：不要同时使用多个分析工具

3. 数据解读#

设置目标：定义关键业务目标
定期分析：定期查看分析报告
A/B 测试：基于数据进行优化
用户反馈：结合分析数据和用户反馈

常见问题#

Q: 分析数据不显示？#

检查配置是否正确
确认网站已部署
等待数据采集延迟（通常 24-48 小时）
检查浏览器隐私设置
验证跟踪代码是否正确加载

Q: 分析工具影响网站速度？#

使用 defer 或 async 加载脚本
选择轻量分析工具（如 Umami）
启用浏览器缓存
考虑使用 CDN 加速

Q: 如何排除特定页面？#

Google Analytics：使用 gtag('config', 'G-XXXXXX', { 'page_path': '/exclude' });
Umami：在页面添加 data-umami-ignore 属性
Clarity：在 Clarity 后台设置排除规则

Q: 如何跟踪转化目标？#

Google Analytics：设置目标和转化
Umami：使用自定义事件
Clarity：设置漏斗分析

Q: 移动端数据不准确？#

确保响应式设计正常
检查移动设备网络连接
验证移动端跟踪代码
考虑使用移动应用分析工具

测试和验证#

1. 本地测试#

Terminal window

1
# 构建网站
2
npm run build
3

4
# 预览构建结果
5
npm run preview

2. 验证方法#

浏览器控制台：检查分析脚本是否加载
网络请求：确认分析数据是否发送
分析后台：查看实时数据
测试事件：触发目标事件验证跟踪

3. 调试技巧#

使用浏览器开发者工具
检查网络请求和响应
查看控制台错误信息
测试不同设备和浏览器

通过合理配置站点分析工具，可以深入了解用户行为，优化网站体验，提升博客的整体质量！

13. 搜索功能配置指南

Sun, 05 Apr 2026 00:00:00 GMT

搜索功能配置指南#

配置文件位置#

src/config/navbarConfig.ts

基本配置#

1
export const navBarSearchConfig: NavBarSearchConfig = {
2
    // 搜索方法：PageFind = 0
3
    method: NavBarSearchMethod.PageFind,
4
};

搜索方法#

PageFind 搜索（默认）#

PageFind 是一个静态网站搜索工具，无需后端服务，适合中小型博客。

特点：

纯静态，无需后端服务
自动索引网站内容
支持全文搜索
响应速度快
支持中文搜索

启用搜索功能#

1. 确保搜索框显示#

在 navbarConfig.ts 中配置：

1
export const navBarSearchConfig: NavBarSearchConfig = {
2
    method: NavBarSearchMethod.PageFind,
3
};

2. 构建时生成索引#

PageFind 会在构建过程中自动生成搜索索引：

Terminal window

1
# 构建网站（自动生成搜索索引）
2
npm run build

搜索功能优化#

1. 搜索结果显示优化#

PageFind 会自动处理搜索结果的显示，包括：

关键词高亮
相关度排序
内容摘要
标题和链接

2. 搜索范围配置#

默认搜索范围：

文章标题
文章内容
标签和分类
页面标题

排除特定内容：

在页面或文章的 frontmatter 中添加：

1
---
2
title: 我的文章
3
search: false  # 排除此页面不被搜索
4
---

高级配置#

1. 自定义搜索框样式#

在 src/styles/global.css 中修改：

1
/* 搜索框样式 */
2
.search-input {
3
    border: 1px solid var(--border-color);
4
    border-radius: 8px;
5
    padding: 8px 12px;
6
    width: 200px;
7
    transition: all 0.3s ease;
8
}
9

10
.search-input:focus {
11
    width: 250px;
12
    border-color: var(--primary);
13
    box-shadow: 0 0 0 2px rgba(var(--primary-rgb), 0.2);
14
}

2. 搜索快捷键#

PageFind 支持以下快捷键：

Ctrl/Cmd + K - 聚焦搜索框
Esc - 关闭搜索结果
Enter - 打开第一个搜索结果
Arrow keys - 导航搜索结果

集成其他搜索服务#

1. Algolia 搜索（可选）#

优点：

更强大的搜索功能
实时搜索建议
更精准的结果排序
支持更多高级搜索特性

集成步骤：

创建 Algolia 账号
- 访问 Algolia
- 创建应用和索引

安装依赖

Terminal window

1
npm install algoliasearch instantsearch.js

创建搜索组件

src/components/search/AlgoliaSearch.astro

1
import algoliasearch from 'algoliasearch';
2
import { InstantSearch, SearchBox, Hits } from 'instantsearch.js';
3

4
const searchClient = algoliasearch(
5
  'YOUR_APP_ID',
6
  'YOUR_SEARCH_API_KEY'
7
);
8

9
// 初始化 InstantSearch
10
const search = InstantSearch({
11
  indexName: 'YOUR_INDEX_NAME',
12
  searchClient,
13
});

配置 Algolia 爬虫
- 在 Algolia 后台配置爬虫
- 定期抓取网站内容

2. Google 站点搜索（可选）#

优点：

利用 Google 的搜索能力
无需维护索引
支持高级搜索语法

集成步骤：

创建 Google 自定义搜索
- 访问 Google 自定义搜索
- 创建搜索引擎
获取搜索 ID
- 复制搜索引擎 ID

添加搜索框

1
<form action="https://cse.google.com/cse.js" method="get">
2
  <input type="hidden" name="cx" value="YOUR_SEARCH_ENGINE_ID">
3
  <input type="search" name="q" placeholder="搜索...">
4
  <button type="submit">搜索</button>
5
</form>

搜索功能测试#

1. 本地测试#

Terminal window

1
# 构建网站（生成搜索索引）
2
npm run build
3

4
# 预览构建结果
5
npm run preview

2. 测试搜索功能#

打开网站
点击搜索图标
输入关键词测试
检查搜索结果是否准确

常见问题#

Q: 搜索结果不显示？#

确保已运行 npm run build 生成搜索索引
检查页面是否被排除在搜索之外
清除浏览器缓存
检查 PageFind 配置

Q: 搜索速度慢？#

减少页面内容大小
优化图片和资源
考虑使用 Algolia 等专业搜索服务
检查网络连接

Q: 中文搜索效果不好？#

PageFind 对中文支持良好
确保文章使用 UTF-8 编码
避免使用过于生僻的词汇
考虑使用专门的中文搜索服务

Q: 如何排除特定内容？#

在页面 frontmatter 中添加 search: false
在 pagefind.yml 配置文件中设置排除规则
使用 data-pagefind-ignore 属性标记元素

Q: 搜索框不显示？#

检查 navbarConfig.ts 中搜索配置是否正确
确认导航栏是否有足够空间显示搜索框
检查 CSS 样式是否隐藏了搜索框
清除浏览器缓存

最佳实践#

保持内容质量：高质量的内容有利于搜索结果的准确性
使用合适的标题：清晰的标题有助于搜索匹配
添加描述：文章摘要可以提高搜索相关性
使用标签和分类：有助于搜索结果的分类显示
定期更新：保持内容新鲜度，提高搜索体验
测试搜索功能：定期测试搜索效果，优化搜索体验

通过合理配置搜索功能，可以帮助访客快速找到所需内容，提升博客的用户体验！

12. 字体配置指南

Sat, 04 Apr 2026 00:00:00 GMT

字体配置指南#

配置文件位置#

src/config/fontConfig.ts

基本配置#

1
export const fontConfig = {
2
    // 是否启用自定义字体功能
3
    enable: false,
4

5
    // 是否预加载字体文件
6
    preload: true,
7

8
    // 当前选择的字体，支持多个字体组合
9
    selected: ["misans-regular"],
10
};

内置字体#

1. 系统字体#

1
system: {
2
    id: "system",
3
    name: "系统字体",
4
    src: "", // 系统字体无需 src
5
    family: "system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, sans-serif",
6
},

2. Google Fonts - Zen Maru Gothic#

1
"zen-maru-gothic": {
2
    id: "zen-maru-gothic",
3
    name: "Zen Maru Gothic",
4
    src: "https://fonts.googleapis.com/css2?family=Zen+Maru+Gothic:wght@300;400;500;700;900&display=swap",
5
    family: "Zen Maru Gothic",
6
    display: "swap" as const,
7
},

3. Google Fonts - Inter#

1
inter: {
2
    id: "inter",
3
    name: "Inter",
4
    src: "https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap",
5
    family: "Inter",
6
    display: "swap" as const,
7
},

4. 小米字体 - MiSans#

字体变体	字重	适用场景
misans-normal	400	正文文本
misans-regular	500	标题、强调文本
misans-semibold	600	大标题、重要按钮

启用自定义字体#

1. 启用字体功能#

1
// 启用自定义字体
2
enable: true,

2. 选择字体#

1
// 选择单个字体
2
selected: ["inter"],
3

4
// 选择多个字体（按顺序 fallback）
5
selected: ["misans-regular", "inter"],

添加自定义字体#

方法1：使用 Google Fonts#

访问 Google Fonts
选择喜欢的字体
复制 embed 代码
在 fonts 对象中添加：

1
"my-font": {
2
    id: "my-font",
3
    name: "我的字体",
4
    src: "https://fonts.googleapis.com/css2?family=字体名称:wght@300;400;500;600;700&display=swap",
5
    family: "字体名称",
6
    display: "swap" as const,
7
},

方法2：使用本地字体#

注意：本地字体需要进行子集化处理，否则会导致页面加载缓慢。

将字体文件放在 public/fonts/ 目录
在 fonts 对象中添加：

1
"local-font": {
2
    id: "local-font",
3
    name: "本地字体",
4
    src: "/fonts/my-font.woff2",
5
    family: "本地字体名称",
6
    weight: 400,
7
    display: "swap" as const,
8
},

字体加载优化#

1. 预加载字体#

1
// 启用字体预加载
2
preload: true,

2. 字体显示策略#

策略	说明	适用场景
swap	立即使用系统字体，字体加载后替换	优先显示内容
block	阻塞显示直到字体加载完成	视觉一致性要求高
fallback	短暂阻塞后使用系统字体	平衡方案
optional	仅在字体可用时使用	性能优先

3. 字体子集化#

对于中文字体，建议使用：

FontTools 进行子集化
Google Fonts 中文优化

字体大小和行高#

调整全局字体大小#

在 src/styles/global.css 中修改：

1
:root {
2
    --font-size-base: 16px;
3
    --font-size-small: 14px;
4
    --font-size-large: 18px;
5
    --line-height-base: 1.6;
6
}

响应式字体#

1
/* 移动端 */
2
@media (max-width: 768px) {
3
    :root {
4
        --font-size-base: 14px;
5
    }
6
}
7

8
/* 桌面端 */
9
@media (min-width: 1200px) {
10
    :root {
11
        --font-size-base: 17px;
12
    }
13
}

常见问题#

Q: 字体不显示？#

检查 enable 是否为 true
检查 selected 中字体 ID 是否正确
检查字体 CDN 链接是否可访问
清除浏览器缓存

Q: 页面加载缓慢？#

启用 preload: true
使用 display: "swap"
对中文字体进行子集化处理
选择字重较少的字体变体

Q: 字体在不同设备显示不一致？#

使用字体回退列表
确保字体支持所需语言
测试不同操作系统和浏览器

Q: 中文字体显示问题？#

使用专门的中文字体：
- Noto Sans SC（Google Fonts）
- 思源黑体
- 小米字体 MiSans

字体配置示例：

1
selected: ["misans-regular", "zen-maru-gothic", "system"],

Q: 如何测试字体效果？#

使用浏览器开发者工具
调整 selected 数组测试不同字体
在不同设备上预览
使用 Font Playground 工具

最佳实践#

性能优先：优先使用系统字体或 CDN 字体
可读性：选择清晰易读的字体
一致性：整个网站使用统一的字体体系
响应式：在不同设备上测试字体显示
兼容性：提供适当的字体回退
加载优化：合理使用预加载和显示策略

通过精心的字体配置，可以提升博客的视觉效果和用户体验！

11. 主题颜色配置指南

Fri, 03 Apr 2026 00:00:00 GMT

主题颜色配置指南#

配置文件位置#

src/config/siteConfig.ts

基本配置#

1
export const siteConfig: SiteConfig = {
2
    // 主题颜色配置
3
    themeColor: {
4
        // 色相值（0-360）
5
        hue: 250,
6

7
        // 是否固定主题模式
8
        fixed: false,
9

10
        // 默认主题模式：'system'=跟随系统, 'light'=浅色, 'dark'=深色
11
        defaultMode: "system",
12
    },
13
};

详细配置#

1. 色相值调整#

色相值决定了网站的主色调，范围是 0-360：

色相值	颜色
0-20	红色
20-40	橙色
40-60	黄色
60-160	绿色
160-260	蓝色
260-320	紫色
320-360	粉色

示例：

蓝色系：hue: 210
绿色系：hue: 120
紫色系：hue: 280
红色系：hue: 10

2. 主题模式设置#

跟随系统（推荐）#

1
themeColor: {
2
    fixed: false,
3
    defaultMode: "system",
4
},

固定浅色模式#

1
themeColor: {
2
    fixed: true,
3
    defaultMode: "light",
4
},

固定深色模式#

1
themeColor: {
2
    fixed: true,
3
    defaultMode: "dark",
4
},

3. 高级配置#

禁用主题切换按钮#

如果设置了 fixed: true，主题切换按钮会自动隐藏。

强制全站使用同一主题#

适用于企业网站或品牌网站，确保一致的视觉体验：

1
themeColor: {
2
    hue: 180,  // 青色
3
    fixed: true,
4
    defaultMode: "light",  // 固定浅色模式
5
},

常见问题#

Q: 主题颜色不生效？#

检查 hue 值是否在 0-360 范围内
保存配置文件后刷新页面
清除浏览器缓存

Q: 如何预览不同色相效果？#

打开浏览器开发者工具

在控制台输入：

1
document.documentElement.style.setProperty('--hue', '120');  // 测试绿色

调整数值实时预览效果

Q: 深色模式下文字看不清楚？#

主题会自动调整文字颜色对比度，确保在深色背景下的可读性。如果仍有问题：

调整 hue 值，选择更深的颜色
检查是否有自定义 CSS 覆盖了主题样式

Q: 主题切换不流畅？#

主题切换使用了平滑过渡动画，这是正常现象。如果想要更快的切换速度：

可以在浏览器设置中关闭动画效果
或修改 CSS 变量的过渡时间

Q: 移动设备上主题显示异常？#

检查移动设备的系统主题设置
确保网站响应式设计正常
清除移动浏览器缓存

最佳实践#

品牌一致性：选择与品牌色调一致的色相值
用户体验：默认使用 system 模式，尊重用户系统设置
可访问性：确保文字与背景的对比度符合 WCAG 标准
测试：在不同设备和浏览器上测试主题效果
备份：修改前备份原始配置，以便随时恢复

通过合理的主题颜色配置，可以打造出既美观又符合品牌形象的博客界面！

10. 导航栏、公告与页脚配置指南

Thu, 02 Apr 2026 00:00:00 GMT

导航栏、公告与页脚配置指南#

这三个地方属于“访客一眼就能看到”的区域，所以非常值得优先改。

你可以把它们理解成：

导航栏：站点入口
公告栏：站点提示
页脚：站点收尾信息

导航栏改哪里#

菜单链接配置文件#

1
src/config/navBarConfig.ts

标题、Logo 等基础设置#

1
src/config/siteConfig.ts

修改导航菜单#

当前项目的导航菜单列表在：

1
const links = [
2
  {
3
    name: "首页",
4
    url: "/",
5
  },
6
  {
7
    name: "关于",
8
    url: "/about/",
9
  },
10
]

常见能改的内容#

菜单名称
菜单地址
是否外链
菜单图标

外链示例#

1
{
2
  name: "GitHub",
3
  url: "https://github.com/coldairboys",
4
  external: true,
5
  icon: "fa7-brands:github",
6
}

导航栏标题和 Logo 改哪里#

在 src/config/siteConfig.ts：

1
navbar: {
2
  logo: {
3
    type: "icon",
4
    value: "material-symbols:auto-awesome-outline",
5
    alt: "Logo",
6
  },
7
  title: "Coldairboy学习笔记",
8
}

Logo 支持什么类型#

有 3 种：

icon：图标库图标
image：本地图片
url：网络图片

用图标最简单#

1
logo: {
2
  type: "icon",
3
  value: "material-symbols:home-outline-rounded",
4
}

用本地图片示例#

1
logo: {
2
  type: "image",
3
  value: "src/assets/images/avatar.avif",
4
  alt: "Coldairboy Logo",
5
}

公告栏改哪里#

配置文件：

1
src/config/announcementConfig.ts

最常见配置#

1
export const announcementConfig = {
2
  title: "公告",
3
  content: "Hi，欢迎来到 Coldairboy学习笔记。",
4
  closable: true,
5
  link: {
6
    enable: true,
7
    text: "了解更多",
8
    url: "/about/",
9
    external: false,
10
  },
11
}

你最常改的就是这几个#

title
content
closable
link.text
link.url

如果不想显示链接#

1
link: {
2
  enable: false,
3
}

如果想做外链公告#

1
link: {
2
  enable: true,
3
  text: "访问 GitHub",
4
  url: "https://github.com/coldairboys",
5
  external: true,
6
}

页脚改哪里#

基础开关文件#

1
src/config/footerConfig.ts

自定义 HTML 文件#

1
src/config/FooterConfig.html

默认情况下页脚 HTML 注入是关闭的：

1
export const footerConfig = {
2
  enable: false,
3
}

如果你想加备案号、自定义说明、额外链接，就改成：

1
export const footerConfig = {
2
  enable: true,
3
}

然后再去编辑：

1
src/config/FooterConfig.html

一个简单示例#

1
<p>这里是 Coldairboy 的个人博客</p>
2
<p>记录学习、折腾和踩坑过程</p>

新手最推荐的修改顺序#

建议按这个顺序来：

先改导航栏标题和菜单
再改公告内容
最后按需开启页脚自定义

这样最不容易乱。

常见问题#

Q: 我改了导航栏，但没生效？#

先检查：

改的是不是 src/config/navBarConfig.ts
标题相关是不是改到了 src/config/siteConfig.ts
本地页面有没有刷新

Q: 公告为什么没显示？#

可能原因：

公告内容为空
公告组件在侧边栏配置里被关了
页面还没刷新

Q: 页脚 HTML 改了没变化？#

通常是因为：

footerConfig.enable 还是 false
你改错文件了
本地缓存没刷新

最后总结#

如果你想让博客更像你自己的站，最应该优先改的就是：

导航栏
公告栏
页脚

因为这三块最容易被访客注意到，而且改完后整个站的“个人味道”会明显强很多。

9. 看板娘配置指南

Wed, 01 Apr 2026 00:00:00 GMT

看板娘配置指南#

配置文件位置#

src/config/pioConfig.ts

看板娘类型#

博客支持两种看板娘模型：

类型	说明
Spine	骨骼动画，配置更灵活
Live2D	平面建模，资源丰富

Spine 看板娘配置#

启用/禁用#

1
export const spineModelConfig: SpineModelConfig = {
2
    // Spine 看板娘开关
3
    enable: true,  // true=启用, false=禁用
4
    // ...
5
}

模型配置#

1
model: {
2
    // Spine模型文件路径
3
    path: "/pio/models/spine/firefly/1310.json",
4
    // 模型缩放比例
5
    scale: 1.0,
6
    // X轴偏移
7
    x: 0,
8
    // Y轴偏移
9
    y: 0,
10
},

位置配置#

1
position: {
2
    // 显示位置
3
    // bottom-left=左下角, bottom-right=右下角
4
    // top-left=左上角, top-right=右上角
5
    corner: "bottom-left",
6
    // 距离边缘0px
7
    offsetX: 0,
8
    // 距离下边缘0px
9
    offsetY: 0,
10
},

注意：右下角可能会挡住返回顶部按钮。

尺寸配置#

1
size: {
2
    // 容器宽度
3
    width: 135,
4
    // 容器高度
5
    height: 165,
6
},

交互配置#

1
interactive: {
2
    // 交互功能开关
3
    enabled: true,
4
    // 点击时随机播放的动画列表
5
    clickAnimations: [
6
        "emoji_0",
7
        "emoji_1",
8
        "emoji_2",
9
        "emoji_3",
10
        "emoji_4",
11
        "emoji_5",
12
    ],
13
    // 点击时随机显示的文字消息
14
    clickMessages: [
15
        "你好呀！我是流萤~",
16
        "今天也要加油哦！✨",
17
        "想要一起去看星空吗？🌟",
18
        "记得要好好休息呢~",
19
        "有什么想对我说的吗？💫",
20
    ],
21
    // 文字显示时间（毫秒）
22
    messageDisplayTime: 3000,
23
    // 待机动画列表
24
    idleAnimations: ["idle", "emoji_0", "emoji_1", "emoji_3", "emoji_4"],
25
    // 待机动画切换间隔（毫秒）
26
    idleInterval: 8000,
27
},

展开收起

响应式配置#

1
responsive: {
2
    // 在移动端隐藏
3
    hideOnMobile: true,
4
    // 移动端断点
5
    mobileBreakpoint: 768,
6
},

层级与透明度#

1
// 层级
2
zIndex: 1000,
3

4
// 透明度
5
opacity: 1.0,

Live2D 看板娘配置#

启用/禁用#

1
export const live2dModelConfig: Live2DModelConfig = {
2
    // Live2D 看板娘开关
3
    enable: false,  // true=启用, false=禁用
4
    // ...
5
}

模型配置#

1
model: {
2
    // Live2D模型文件路径
3
    path: "/pio/models/live2d/snow_miku/model.json",
4
    // 也可以使用其他模型
5
    // path: "/pio/models/live2d/illyasviel/illyasviel.model.json",
6
},

其他配置#

Live2D 的位置、尺寸、交互等配置与 Spine 相同，参考上面的说明。

切换看板娘类型#

启用 Spine#

1
spineModelConfig: {
2
    enable: true,
3
},
4
live2dModelConfig: {
5
    enable: false,
6
},

启用 Live2D#

1
spineModelConfig: {
2
    enable: false,
3
},
4
live2dModelConfig: {
5
    enable: true,
6
},

常见问题#

Q: 看板娘不显示？#

检查对应类型的 enable 是否为 true
检查模型文件路径是否正确
检查浏览器控制台是否有错误

Q: 看板娘挡住内容？#

调整 position.corner 切换位置：

1
corner: "bottom-left",  // 改到左下角

或调整 zIndex 降低层级：

1
zIndex: 100,

Q: 移动端也想显示看板娘？#

1
responsive: {
2
    hideOnMobile: false,  // 在移动端显示
3
},

Q: 如何自定义对话内容？#

修改 clickMessages 数组：

1
clickMessages: [
2
    "你的第一条消息",
3
    "你的第二条消息",
4
    "你的第三条消息",
5
],

Q: 待机动画不切换？#

检查 idleAnimations 是否配置了有效的动画名称。

Q: 点击没有反应？#

检查 interactive.enabled 是否为 true
检查 clickAnimations 是否配置了有效的动画

8. 关于页、留言板与赞助页配置指南

Tue, 31 Mar 2026 00:00:00 GMT

关于页、留言板与赞助页配置指南#

这三个页面都很适合新手尽早配好，因为它们会直接影响访客对你博客的第一印象。

这篇会带你搞懂：

关于页改哪里
留言板改哪里
赞助页怎么开、怎么关、怎么放收款码

一眼看懂：这 3 个页面分别是什么#

关于页#

作用：

介绍你是谁
告诉别人这个站写什么
放你的定位、兴趣、折腾方向

留言板#

作用：

让访客直接留言
适合打招呼、交流、提建议

赞助页#

作用：

展示赞助方式
放收款码或赞助链接
可在文章页底部显示“赞助”按钮

关于页怎么改#

文件位置#

1
src/content/spec/about.md

你现在这个项目里的关于页内容#

就是直接从这个文件读取的，所以你想改文字，只要改这里就行。

一个最简单的示例#

1
# 关于本站
2

3
这里是 Coldairboy 的学习博客。
4

5
这个站主要记录：
6

7
- 学习笔记
8
- 博客折腾记录
9
- AI 工具使用心得
10
- 遇到问题后的排查过程

改完后访问哪里看#

1
/about/

留言板怎么改#

文件位置#

1
src/content/spec/guestbook.md

页面开关位置#

1
src/config/siteConfig.ts

你要确保这里是开启状态：

1
pages: {
2
  guestbook: true,
3
}

留言板内容怎么写#

留言板页面上方的说明文字，就来自这个 Markdown 文件。

你可以写得更像自己，比如：

1
---
2
title: "留言板"
3
description: "欢迎来这里打个招呼"
4
---
5

6
- 欢迎留言、交流、串门
7
- 如果你也在折腾博客、AI 工具、NAS、Docker，特别欢迎交流
8
- 有推荐的教程、项目或者踩坑经验，也可以直接分享

留言板评论从哪里来#

留言板底部的评论区，走的是你全站当前启用的评论系统。

也就是说：

你如果启用了 Giscus
留言板下方就会显示 Giscus 评论区

留言板访问地址#

1
/guestbook/

赞助页怎么改#

第一步：确认赞助页开关开启#

在 src/config/siteConfig.ts 里：

1
pages: {
2
  sponsor: true,
3
}

第二步：改赞助页内容#

在 src/config/sponsorConfig.ts 里可以改：

页面标题
页面描述
赞助用途说明
赞助方式
收款码图片
是否显示赞助者列表
是否在文章底部显示赞助按钮

最常改的配置#

1
export const sponsorConfig = {
2
  usage: "你的赞助将用于服务器续费、内容创作和功能维护。",
3
  showSponsorsList: true,
4
  showComment: true,
5
  showButtonInPost: true,
6
}

赞助方式怎么配#

示例：

1
methods: [
2
  {
3
    name: "微信",
4
    icon: "fa7-brands:weixin",
5
    qrCode: "/assets/images/sponsor/wechat.png",
6
    description: "使用微信扫码赞助",
7
    enabled: true,
8
  },
9
]

收款码应该放哪里#

放在：

1
public/assets/images/sponsor/

然后在配置里写对应路径，比如：

1
/assets/images/sponsor/wechat.png

文章页底部的赞助按钮怎么控制#

在 src/config/sponsorConfig.ts 里：

1
showButtonInPost: true

如果你不想在每篇文章底部都显示赞助按钮，就改成：

1
showButtonInPost: false

这三个页面最推荐的处理方式#

如果你是个人博客，建议这样配：

关于页：认真写，像个人介绍页
留言板：打开，方便互动
赞助页：看你自己需求，没准备好就先关

常见问题#

Q: 我改了关于页内容，为什么页面没变化？#

先检查：

你改的是不是 src/content/spec/about.md
本地页面有没有刷新
你是不是改到了别的目录

Q: 留言板为什么没有评论区？#

通常是因为：

评论系统没启用
评论配置没填完整
页面还没刷新

Q: 赞助页打开是空的？#

一般是因为：

页面开关没开
methods 里都设置成了 enabled: false
收款码路径写错了

最后总结#

这三个页面其实很好理解：

关于页负责“介绍你是谁”
留言板负责“让别人能跟你聊”
赞助页负责“让愿意支持你的人知道怎么支持”

对于个人博客来说，它们都属于很值得早点配好的基础页面。

7. 文章封面图与随机封面配置

Mon, 30 Mar 2026 00:00:00 GMT

随机封面图配置指南#

配置文件位置#

src/config/coverImageConfig.ts

基本配置#

1
export const coverImageConfig: CoverImageConfig = {
2
    // 是否在文章详情页显示封面图
3
    enableInPost: true,
4

5
    randomCoverImage: {
6
        // 随机封面图功能开关
7
        enable: false,
8
        // 封面图API列表
9
        apis: [
10
            "https://t.alcy.cc/pc",
11
            "https://www.dmoe.cc/random.php",
12
            "https://uapis.cn/api/v1/random/image?category=acg&type=pc",
13
        ],
14
        // API失败时的回退图片路径
15
        fallback: "assets/images/cover.avif",
16
        // 是否显示加载动画
17
        showLoading: false,
18
    },
19
}

展开收起

启用随机封面图#

1. 开启随机封面图功能#

将 randomCoverImage.enable 设置为 true：

1
randomCoverImage: {
2
    enable: true,  // 开启随机封面图
3
    // ...
4
},

2. 在文章中启用#

在需要使用随机封面图的文章 frontmatter 中设置：

1
---
2
title: 我的文章
3
image: "api"
4
---

设置 image: "api" 后，系统会使用配置的 API 随机获取封面图。

API 配置#

内置免费 API#

博客已内置几个免费图床 API：

1
apis: [
2
    "https://t.alcy.cc/pc",
3
    "https://www.dmoe.cc/random.php",
4
    "https://uapis.cn/api/v1/random/image?category=acg&type=pc",
5
],

添加自定义 API#

如果想使用自己的图床，可以添加自定义 API：

1
apis: [
2
    "https://你的API1.com/random",
3
    "https://你的API2.com/random",
4
],

系统会按顺序尝试每个 API，第一个失败则切换下一个。

API 要求#

返回图片 URL
或返回图片二进制数据
支持 HTTPS

回退图片配置#

当所有 API 都失败时，使用回退图片：

1
fallback: "assets/images/cover.avif",

确保这个图片文件存在于 src/assets/images/ 目录下。

文章详情页封面图开关#

控制是否在文章详情页显示封面图：

1
// 显示封面图
2
enableInPost: true,
3

4
// 不显示封面图
5
enableInPost: false,

显示加载动画#

1
showLoading: true,  // 显示加载动画
2
showLoading: false, // 不显示加载动画

常见问题#

Q: 随机封面图不显示？#

检查 randomCoverImage.enable 是否为 true
检查文章 frontmatter 是否设置 image: "api"
检查 API 是否可访问
检查控制台错误信息

Q: 图片加载很慢？#

使用加载速度更快的图床 API
将常用图片上传到自己的图床
开启 CDN 加速

Q: 部分 API 失效？#

系统会自动切换到下一个 API，确保至少有一个可用即可。

Q: 如何禁用单篇文章的封面图？#

1
---
2
title: 我的文章
3
image: ""  # 不使用封面图
4
---

或者设置 image: false

6. 樱花特效配置指南

Sun, 29 Mar 2026 00:00:00 GMT

樱花特效配置指南#

配置文件位置#

src/config/sakuraConfig.ts

基本配置#

1
export const sakuraConfig: SakuraConfig = {
2
    // 是否启用樱花特效
3
    enable: true,
4

5
    // 樱花数量
6
    sakuraNum: 21,
7

8
    // 樱花越界限制次数，-1为无限循环
9
    limitTimes: -1,
10
}

启用/禁用樱花特效#

1
// 启用
2
enable: true,
3

4
// 禁用
5
enable: false,

樱花数量配置#

1
// 樱花数量
2
sakuraNum: 21,  // 数量越多，性能消耗越大

樱花尺寸配置#

1
size: {
2
    // 樱花最小尺寸倍数
3
    min: 0.5,
4
    // 樱花最大尺寸倍数
5
    max: 1.1,
6
},

樱花透明度配置#

1
opacity: {
2
    // 樱花最小不透明度
3
    min: 0.3,
4
    // 樱花最大不透明度
5
    max: 0.9,
6
},

樱花速度配置#

1
speed: {
2
    // 水平移动
3
    horizontal: {
4
        // 水平移动速度最小值
5
        min: -1.7,
6
        // 水平移动速度最大值
7
        max: -1.2,
8
    },
9
    // 垂直移动
10
    vertical: {
11
        // 垂直移动速度最小值
12
        min: 1.5,
13
        // 垂直移动速度最大值
14
        max: 2.2,
15
    },
16
    // 旋转速度
17
    rotation: 0.03,
18
    // 消失速度，不应大于最小不透明度
19
    fadeSpeed: 0.03,
20
},

展开收起

层级配置#

1
// 层级，确保樱花在合适的层级显示
2
zIndex: 100,

常见问题#

Q: 樱花特效不显示？#

检查 enable 是否设置为 true
检查浏览器控制台是否有错误
尝试刷新页面或清除缓存

Q: 如何减少性能消耗？#

减少 sakuraNum 数量
增大樱花尺寸（尺寸大，数量可以减少）

Q: 樱花挡住内容怎么办？#

调整 zIndex 值，确保樱花在内容下方：

1
zIndex: 100,  // 值越小，层级越低

Q: 如何让樱花只飘落有限次数？#

修改 limitTimes：

1
limitTimes: 5,  // 飘落5次后停止

5. 音乐播放器配置指南

Sat, 28 Mar 2026 00:00:00 GMT

音乐播放器配置指南#

配置文件位置#

src/config/musicConfig.ts

基本配置#

1
export const musicPlayerConfig: MusicPlayerConfig = {
2
    // 是否在导航栏显示音乐播放器入口
3
    showInNavbar: true,
4

5
    // 播放模式：'meting'=使用 Meting API, 'local'=使用本地音乐
6
    mode: "meting",
7

8
    // 默认音量 (0-1)
9
    volume: 0.7,
10

11
    // 播放模式：'list'=列表循环, 'one'=单曲循环, 'random'=随机播放
12
    playMode: "list",
13

14
    // 是否显示歌词
15
    showLyrics: true,
16
},

展开收起

Meting API 模式（推荐）#

Meting API 可以解析网易云音乐、QQ音乐等平台的歌单。

1. 获取网易云音乐歌单 ID#

打开网易云音乐网页版
进入你想要使用的歌单
查看浏览器地址栏中的 URL：
```
1
https://music.163.com/#/playlist?id=9493047202
```
歌单 ID 是 9493047202

2. 配置示例#

1
meting: {
2
    // Meting API 地址（默认使用官方 API）
3
    api: "https://api.i-meto.com/meting/api?server=:server&type=:type&id=:id&r=:r",
4

5
    // 音乐平台：netease=网易云音乐, tencent=QQ音乐, kugou=酷狗音乐
6
    server: "netease",
7

8
    // 类型：song=单曲, playlist=歌单, album=专辑, artist=艺术家
9
    type: "playlist",
10

11
    // 歌单 ID（替换为你自己的）
12
    id: "9493047202",
13

14
    // 认证 token（通常留空）
15
    auth: "",
16

17
    // 备用 API（当主 API 失败时使用）
18
    fallbackApis: [
19
        "https://api.injahow.cn/meting/?server=:server&type=:type&id=:id",
20
        "https://api.moeyao.cn/meting/?server=:server&type=:type&id=:id",
21
    ],
22
},

展开收起

3. 其他平台配置#

QQ 音乐：

1
server: "tencent",
2
type: "playlist",
3
id: "你的QQ音乐歌单ID",

酷狗音乐：

1
server: "kugou",
2
type: "playlist",
3
id: "你的酷狗音乐歌单ID",

本地音乐模式#

如果不想使用在线歌单，可以使用本地音乐文件。

1. 准备音乐文件#

将 MP3 文件放在 public/assets/music/ 目录下。

2. 配置示例#

1
mode: "local",
2

3
local: {
4
    playlist: [
5
        {
6
            name: "歌曲名称",
7
            artist: "歌手名称",
8
            url: "/assets/music/歌曲名称.mp3",
9
            cover: "/assets/music/cover/封面.jpg",
10
            // 歌词（可选）
11
            lrc: "[00:00.00]歌词内容...",
12
        },
13
    ],
14
},

3. 歌词文件配置#

歌词支持两种方式：

方式一：直接写入歌词内容

1
lrc: "[00:00.00]第一句歌词\n[00:05.00]第二句歌词",

方式二：引用外部 LRC 文件

1
lrc: "/assets/music/lrc/歌曲名.lrc",

播放器显示控制#

导航栏入口#

1
// 是否在导航栏显示播放器入口
2
showInNavbar: true,  // true=显示, false=隐藏

侧边栏组件#

在 src/config/sidebarConfig.ts 中配置侧边栏音乐组件：

1
{
2
    component: "MusicPlayer",
3
    enable: true,  // true=启用, false=禁用
4
},

常见问题#

Q: 播放器不显示？#

检查 showInNavbar 是否为 true
检查侧边栏配置中 MusicPlayer 是否启用
检查浏览器控制台是否有错误

Q: 歌曲无法播放？#

确认歌单 ID 是否正确
部分歌曲因版权原因可能无法播放
尝试更换备用 API

Q: 如何获取歌词？#

网易云音乐歌曲页面可以找到歌词
使用在线工具搜索 LRC 文件
手动编写 LRC 格式歌词

Q: 歌单显示不正确？#

检查 type 配置是否正确：

单曲：type: "song"
歌单：type: "playlist"
专辑：type: "album"
艺术家：type: "artist"

Q: 音乐加载缓慢？#

可以配置多个备用 API，当主 API 失败时自动切换：

1
fallbackApis: [
2
    "https://api.injahow.cn/meting/?server=:server&type=:type&id=:id",
3
    "https://api.moeyao.cn/meting/?server=:server&type=:type&id=:id",
4
],

4. 评论系统配置指南

Fri, 27 Mar 2026 00:00:00 GMT

评论系统配置指南#

配置文件位置#

src/config/commentConfig.ts

支持的评论系统#

评论系统	说明	难度
Giscus	基于 GitHub Discussions	简单
Twikoo	腾讯云开发版	简单
Waline	Vercel 部署版	中等
Artalk	自建后端版	较难
Disqus	国外老牌评论系统	简单
none	不启用评论系统	-

Giscus 配置（推荐）#

Giscus 是一个基于 GitHub Discussions 的评论系统，免费、稳定、易用。

1. 安装 GitHub App#

访问 https://github.com/apps/giscus ，点击 “Install” 安装到你的 GitHub 仓库。

2. 配置仓库#

安装后，在仓库的 Settings → Pages 中：

Source 选择 GitHub Actions

3. 获取配置参数#

访问 https://giscus.app/zh-CN ，填写你的仓库信息，获取以下参数：

1
giscus: {
2
    // 设置 Giscus 评论系统仓库（格式：用户名/仓库名）
3
    repo: "你的用户名/你的仓库名",
4
    // 仓库 ID（从 giscus.app 获取）
5
    repoId: "R_xxxxxxxxxxxx",
6
    // 评论分类名称
7
    category: "General",
8
    // 分类 ID（从 giscus.app 获取）
9
    categoryId: "DIC_xxxxxxxxxxxx",
10
    // 映射方式：pathname, URL, title 等
11
    mapping: "pathname",
12
    // 是否启用 reactions
13
    reactionsEnabled: "1",
14
    // 评论输入位置：bottom, top
15
    inputPosition: "bottom",
16
    // 语言：zh-CN, en 等
17
    lang: "zh-CN",
18
},

展开收起

4. 更多配置项#

1
giscus: {
2
    // 严格模式
3
    strict: "0",
4
    // 是否发送元数据
5
    emitMetadata: "0",
6
    // 加载方式：lazy, eager
7
    loading: "lazy",
8
},

Twikoo 配置#

Twikoo 是一个基于腾讯云开发的评论系统，部署简单。

1. 获取环境 ID#

进入 https://console.cloud.tencent.com/tcb
创建一个云开发环境
在云开发控制台中，开通「云函数」服务
创建一个环境后，在环境设置中获取环境 ID

2. 配置示例#

1
twikoo: {
2
    // 环境 ID
3
    envId: "your-env-id-xxxxx",
4
    // 语言
5
    lang: "zh-CN",
6
    // 是否启用访问量统计
7
    visitorCount: true,
8
},

Waline 配置#

Waline 是一个基于 Vercel 部署的评论系统。

1. 部署 Waline 服务#

Fork https://github.com/walinejs/waline 到你的 GitHub
在 Vercel 中导入该项目
配置环境变量：
- LEAN_ID: LeanCloud 应用 ID
- LEAN_KEY: LeanCloud 应用 Key
- LEAN_MASTER_KEY: LeanCloud Master Key
部署后获取服务 URL

2. 配置示例#

1
waline: {
2
    // Waline 服务地址
3
    serverURL: "https://your-waline.vercel.app",
4
    // 语言
5
    lang: "zh-CN",
6
    // 登录模式
7
    login: "enable",
8
    // 表情包配置
9
    emoji: [
10
        "https://unpkg.com/@waline/emojis@1.4.0/weibo",
11
        "https://unpkg.com/@waline/emojis@1.4.0/bilibili",
12
    ],
13
    // 访问量统计
14
    visitorCount: true,
15
},

展开收起

切换评论系统#

在 commentConfig.ts 中修改 type 字段：

1
export const commentConfig: CommentConfig = {
2
    // 切换评论系统
3
    type: "giscus",  // 可选: giscus, twikoo, waline, artalk, disqus, none
4
    // ...
5
},

禁用评论功能#

方法一：设置 type 为 none

1
type: "none",

方法二：在文章 frontmatter 中单独禁用

1
---
2
title: 我的文章
3
comment: false  // 这篇文章禁用评论
4
---

常见问题#

Q: 评论不显示？#

检查浏览器控制台是否有错误
确认配置参数是否正确
确认评论系统服务是否正常运行

Q: 如何开启访问量统计？#

在对应评论系统的配置中设置 visitorCount: true

Q: 如何修改评论框语言？#

在配置中找到 lang 字段，设置为 zh-CN（中文）或 en（英文）

3. 博客首页打字机文案配置

Thu, 26 Mar 2026 00:00:00 GMT

首页文字打字机效果配置#

配置文件位置#

src/config/backgroundWallpaper.ts

配置位置#

在 banner.homeText.typewriter 部分：

1
homeText: {
2
    enable: true,
3
    switchable: true,
4
    title: "Coldairboy'学习笔记",
5
    titleSize: "4rem",
6
    subtitle: ["欢迎来到我的博客，大家一起学习、成长吧！"],
7
    subtitleSize: "1.35rem",
8
    typewriter: {
9
        enable: true,      // true = 启用，false = 禁用
10
        speed: 100,       // 打字速度（毫秒/字符）
11
        deleteSpeed: 50,  // 删除速度（毫秒/字符）
12
        pauseTime: 2000,  // 显示完整后的停顿时间（毫秒）
13
    },
14
},

参数说明#

参数	说明	默认值	建议值
`enable`	是否启用打字机效果	`false`	`true`
`speed`	打字速度（毫秒/字符）	100	50-150
`deleteSpeed`	删除速度（毫秒/字符）	50	30-100
`pauseTime`	显示完整后的停顿时间（毫秒）	2000	1000-3000

效果说明#

启用后，首页横幅副标题会以打字机效果显示：

文字逐字显示（速度由 speed 控制）
显示完整后停顿（由 pauseTime 控制）
逐字删除（由 deleteSpeed 控制）
循环重复

修改副标题文字#

在 subtitle 数组中修改：

1
subtitle: ["你的副标题文字"],

支持多行文字，会按顺序逐行显示。

2. 博客首页横幅图片与轮播配置

Wed, 25 Mar 2026 00:00:00 GMT

博客首页顶部轮播图片配置#

图片位置#

首页顶部轮播图片分为移动端和桌面端两个版本：

端	路径	说明
移动端	`src/assets/images/MobileWallpaper/`	手机/平板等移动设备显示
桌面端	`src/assets/images/DesktopWallpaper/`	电脑等桌面设备显示

配置文件位置#

src/config/backgroundWallpaper.ts

配置说明#

1
src: {
2
    desktop: [
3
        "assets/images/DesktopWallpaper/d1.avif",
4
        "assets/images/DesktopWallpaper/d2.avif",
5
        "assets/images/DesktopWallpaper/d3.avif",
6
        "assets/images/DesktopWallpaper/d4.avif",
7
    ],
8
    mobile: [
9
        "assets/images/MobileWallpaper/m1.avif",
10
        "assets/images/MobileWallpaper/m2.avif",
11
        "assets/images/MobileWallpaper/m3.avif",
12
        "assets/images/MobileWallpaper/m4.avif",
13
    ],
14
},

图片格式要求#

推荐格式：AVIF#

优势：更高的压缩率，更小的文件体积，支持透明度和 HDR
兼容性：现代浏览器普遍支持

推荐工具：Squoosh#

在线图片转换工具：https://squoosh.app/

使用步骤：

打开 Squoosh 网站
将你的图片拖入页面
在左侧面板选择输出格式为 AVIF
调整质量滑块（建议 75-85%）
点击下载按钮

其他可选工具#

工具	网址	特点
CloudConvert	https://cloudconvert.com/	支持批量转换，格式全面
Convertio	https://convertio.co/	界面简洁，操作方便
ezGIF	https://ezgif.com/	支持 GIF 和图片互转

图片尺寸建议#

端	推荐尺寸	宽高比
移动端	1080 × 1578	约 2:3
桌面端	2560 × 1440	16:9

轮播配置#

在 backgroundWallpaper.ts 中的 banner.carousel 部分：

1
carousel: {
2
    enable: true,           // 是否启用轮播
3
    interval: 5000,         // 轮播间隔（毫秒）
4
    switchable: true,       // 是否允许用户手动切换
5
},

替换图片步骤#

准备好新的 AVIF 格式图片
根据目标设备，将图片放入对应文件夹：
- 移动端：src/assets/images/MobileWallpaper/
- 桌面端：src/assets/images/DesktopWallpaper/
刷新页面即可看到效果
如缓存未更新，按 Ctrl + Shift + R 强制刷新

注意事项#

文件名需与配置文件中的路径一致
图片会经过 Astro 自动优化，生成 WebP/AVIF 多种格式
替换后如未显示新图片，请清除浏览器缓存或重启开发服务器