2.1 静态站点 vs 动态站点#

2.2 Astro 的「Islands 架构」#

Astro 的核心创新是 Islands Architecture（群岛架构）：

1
页面 = 静态内容海（默认）+ 交互岛屿（按需加载 JS）
2

3
┌──────────────────────────────────┐
4
│  ███████ 静态 HTML ████████████  │  ← 服务端渲染，0 JS
5
│  ██████████████████████████████  │
6
│  ████ [搜索框] ████████████████  │  ← Svelte Island，按需加载 JS
7
│  ██████████████████████████████  │
8
│  ██████ [评论区] ██████████████  │  ← 另一个 Island
9
│  ██████████████████████████████  │
10
└──────────────────────────────────┘

原理：

• 默认情况下，Astro 在构建时将所有内容渲染为纯 HTML，不发送任何 JavaScript 到浏览器
• 只有当组件需要交互时（如搜索框、评论区、主题切换），才会将其标记为”岛屿”
• 每个岛屿独立加载，互不影响

为什么这很重要：更少的 JavaScript = 更快的加载速度 = 更好的 SEO = 更低的带宽消耗。

2.3 Tailwind CSS — 实用优先的 CSS 框架#

Tailwind 采用「原子化 CSS」理念：

1
<!-- 传统 CSS：定义类名，写样式 -->
2
<div class="card">
3
  <h2 class="card-title">标题</h2>
4
</div>
5

6
<!-- Tailwind：直接用工具类组合 -->
7
<div class="bg-white rounded-lg shadow-md p-6">
8
  <h2 class="text-xl font-bold text-gray-900">标题</h2>
9
</div>

原理：Tailwind 在构建时扫描你的模板文件，只生成你用到的 CSS 类，最终产出的 CSS 文件通常只有几 KB。

3.1 Node.js 是什么#

Node.js 是一个 JavaScript 运行时，基于 Chrome 的 V8 引擎。它让你可以在服务器/本地运行 JavaScript 代码。

1
你的 .js/.ts 代码
2
    ↓
3
Node.js 运行时 (V8 引擎 + API)
4
    ↓
5
操作系统 (Windows/macOS/Linux)

3.2 包管理器：npm vs pnpm#

• npm：Node.js 默认包管理器。将依赖下载到 node_modules/，每个项目独立一份。
• pnpm：更高效的包管理器。使用硬链接（hard link）和内容寻址存储来共享相同版本的包，节省磁盘空间和安装时间。

1
npm 模式：             pnpm 模式：
2
projectA/node_modules  projectA/node_modules/.pnpm/react@18 → 全局存储/react@18
3
  └── react (500MB)    projectB/node_modules/.pnpm/react@18 → 同一个全局存储 ↑
4
projectB/node_modules
5
  └── react (500MB)    ← 又存了一份！

pnpm 的内容寻址存储原理：

1. 所有包存储在全局仓库（~/.pnpm-store）
2. 每个包的存储位置由其内容的哈希值决定
3. 项目中的 node_modules 通过硬链接指向全局存储
4. 相同内容只存储一次，不同项目共享

3.3 版本要求#

• Node.js ≥ 22：Firefly 使用了最新的 ES 特性和 Astro 6.x，需要较新版本的 Node.js
• pnpm ≥ 9：项目配置了 packageManager: "pnpm@9.14.4"，使用 only-allow pnpm 强制使用 pnpm

4.1 为什么使用模板#

Firefly 模板基于 Fuwari 二次开发，已经集成了：

• 完整的 Astro 配置（Markdown 插件、Expressive Code 代码高亮、Katex 数学公式等）
• 响应式布局（双侧边栏、网格/瀑布流）
• 多语言支持（i18n）
• 全文搜索（Pagefind）
• 评论系统集成（Twikoo/Waline/Giscus/Disqus/Artalk）
• 主题系统（亮色/暗色/跟随系统）
• 动画效果（Swup 页面过渡）

使用模板可以让你站在巨人的肩膀上，专注于内容创作而非基础设施搭建。

4.2 Git 克隆与版本控制#

1
# 从 GitHub 克隆
2
git clone https://github.com/CuteLeaf/Firefly.git
3
cd Firefly
4

5
# 或从 Gitee 镜像克隆（国内访问更快）
6
git clone https://gitee.com/CuteLeaf/Firefly.git
7
cd Firefly

Git 原理简述：

• Git 是一个分布式版本控制系统
• .git/ 目录包含完整的版本历史
• 每次 commit 创建一个快照（snapshot），记录文件的变化
• 远程仓库（GitHub/Gitee）是代码的中央存储和协作平台

5.1 Astro 的基于文件的路由#

Astro 使用 文件系统路由：

1
src/pages/
2
├── index.astro        →  https://yoursite.com/
3
├── about.astro        →  https://yoursite.com/about/
4
├── posts/
5
│   └── [slug].astro   →  https://yoursite.com/posts/hello-world/
6
├── archive.astro      →  https://yoursite.com/archive/
7
└── rss.xml.js         →  https://yoursite.com/rss.xml

原理：Astro 在构建时扫描 src/pages/ 目录，为每个 .astro、.md、.mdx 文件生成对应的 HTML 页面。[slug] 是动态路由参数，可以匹配任意路径段。

5.2 内容集合（Content Collections）#

Astro 的内容集合系统让你以类型安全的方式管理 Markdown 内容：

1
const postsCollection = defineCollection({
2
  type: 'content',
3
  schema: z.object({
4
    title: z.string(),
5
    published: z.date(),
6
    tags: z.array(z.string()),
7
    draft: z.boolean().default(false),
8
  }),
9
});
10

11
export const collections = { posts: postsCollection };

原理：Astro 在构建时读取 src/content/posts/ 下的所有 Markdown 文件，根据 schema 验证 frontmatter，并提供类型安全的查询 API。

6.1 TypeScript 配置的优势#

Firefly 使用 TypeScript 编写配置文件，提供：

• 编译时类型检查：配置错误在构建时就暴露，不会等到运行时才发现
• IDE 智能提示：编辑器自动补全配置项
• 结构化组织：相关配置集中管理

6.2 关键配置说明#

1
export const siteConfig: SiteConfig = {
2
  title: "CC's Blog",           // 站点标题
3
  site_url: "https://...",       // 站点 URL（用于 RSS、sitemap）
4
  themeColor: {
5
    hue: 165,                    // 主题色相（0-360，HSL 色彩空间）
6
    defaultMode: "system",       // 亮色/暗色/跟随系统
7
  },
8
  // ...
9
};

1
// 组件类型
2
type WidgetComponentType =
3
  | "profile"       // 个人资料
4
  | "announcement"  // 公告
5
  | "music"         // 音乐播放器
6
  | "categories"    // 分类
7
  | "tags"          // 标签
8
  | "stats"         // 站点统计
9
  | "calendar"      // 日历
10
  | "sidebarToc"    // 文章目录
11
  | "advertisement" // 广告

7.1 Markdown 基础#

Markdown 是一种轻量级标记语言，旨在用纯文本格式编写可读性强的文档。

1
# 一级标题
2
## 二级标题
3

4
**粗体** *斜体* ~~删除线~~
5

6
[链接](https://example.com)
7
![图片](image.jpg)
8

9
- 无序列表
10
1. 有序列表
11

12
> 引用
13

14
`行内代码`
15

16
​```javascript
17
// 代码块
18
console.log("Hello");
19
​```

7.2 Frontmatter — 文章元数据#

Markdown 文件顶部的 YAML 格式元数据：

1
---
2
title: 文章标题
3
published: 2026-01-01       # 发布日期
4
pinned: true                 # 置顶
5
description: 文章摘要
6
tags: [标签1, 标签2]         # 标签
7
category: 分类名称
8
draft: false                 # true=草稿，不发布
9
image: ./cover.jpg           # 封面图
10
---

原理：gray-matter 库在构建时解析 frontmatter，将 YAML 转换为 JavaScript 对象，供模板使用。

7.3 Firefly 的 Markdown 扩展#

Firefly 通过 Astro 的 remark/rehype 插件系统扩展了标准 Markdown：

• GitHub 风格提醒框（Admonitions）：:::note、:::warning、:::danger 等
• GitHub 仓库卡片：::github{repo="owner/repo"}
• 数学公式：通过 Katex 渲染 LaTeX 公式
• Mermaid 图表：通过 Mermaid 渲染流程图、时序图等
• 代码高亮：通过 Expressive Code 实现增强的代码块

7.4 remark 与 rehype 处理管道#

Markdown 的处理分为两个阶段：

1
Markdown 文本
2
    ↓
3
[remark 插件]  ← 处理 Markdown AST (mdast)
4
    ↓
5
[转换层]  ← mdast → hast
6
    ↓
7
[rehype 插件]  ← 处理 HTML AST (hast)
8
    ↓
9
HTML 输出

• remark：操作 Markdown 抽象语法树（例如：提取阅读时间、解析自定义指令）
• rehype：操作 HTML 抽象语法树（例如：添加 heading id、外部链接处理）

8.1 构建流程#

1
🚀 pnpm run build
2
    │
3
    ├─ 1. 图标生成 (generate-icons.js)
4
    │    扫描源码 → 提取图标引用 → 生成 icons.ts
5
    │
6
    ├─ 2. Astro 构建 (astro build)
7
    │    ├─ 解析内容集合 (Content Collections)
8
    │    ├─ 编译 Astro/Svelte 组件
9
    │    ├─ 静态路由生成 (SSG)
10
    │    │   ├─ /index.html          (首页)
11
    │    │   ├─ /posts/*/index.html  (文章页)
12
    │    │   ├─ /archive/index.html  (归档页)
13
    │    │   ├─ /about/index.html    (关于页)
14
    │    │   └─ ... (15+ 页面)
15
    │    ├─ 图像优化 (Sharp)
16
    │    │   原始图片 → WebP/AVIF 多种尺寸
17
    │    └─ 资源打包 (Vite)
18
    │        JS/CSS 打包、压缩、哈希命名
19
    │
20
    └─ 3. Pagefind 索引 (pagefind --site dist)
21
         扫描 HTML → 提取文本 → 构建搜索索引

8.2 图像优化的原理#

Astro 内置的图像优化基于 Sharp（高性能 Node.js 图像处理库）：

1
原始图片 (avif, 300KB)
2
    ↓
3
Sharp 处理
4
    ├─ 调整尺寸 (响应式：320w, 640w, 1280w, 1920w)
5
    ├─ 格式转换 (avif → webp 或保留 avif)
6
    └─ 压缩 (quality: 85)
7
    ↓
8
输出多种尺寸 + srcset 属性

响应式图像原理：

1
<img
2
  src="/_astro/photo_1x.webp"
3
  srcset="
4
    /_astro/photo_320w.webp   320w,
5
    /_astro/photo_640w.webp   640w,
6
    /_astro/photo_1280w.webp 1280w
7
  "
8
  sizes="(max-width: 768px) 100vw, 50vw"
9
  alt="..."
10
/>

浏览器根据屏幕宽度和设备像素比自动选择最佳图片，移动端加载小图，桌面端加载大图。

8.3 Pagefind 全文搜索原理#

Pagefind 是一个客户端全文搜索工具：

1
构建时：
2
  dist/*.html → Pagefind 扫描 → 提取文本 → 构建倒排索引 → dist/pagefind/
3

4
运行时：
5
  用户输入关键词 → JS 加载索引片段 → 本地搜索 → 返回结果（含上下文摘要）

为什么不需要后端：

• 索引文件是静态的，存储在 CDN 上
• 搜索在浏览器本地执行
• 只在用户搜索时才按需加载索引片段（不是一次性加载全部）

9.1 Astro 组件#

.astro 文件是 Astro 的专有组件格式，分为两部分：

1
---
2
// 组件脚本（服务端，构建时执行）
3
// 可以访问文件系统、数据库等
4
import { getCollection } from 'astro:content';
5
const posts = await getCollection('posts');
6
---
7
<!-- 模板（生成的 HTML） -->
8
<div>
9
  {posts.map(post => <PostCard post={post} />)}
10
</div>

关键区别：--- 之间的代码在构建时在服务端执行，不会发送到浏览器。这保证了敏感逻辑和数据永远不会暴露给客户端。

9.2 Svelte 交互组件#

当需要交互时，Firefly 使用 Svelte（编译型 UI 框架）：

1
<script>
2
  let isDark = $state(false);
3

4
  function toggle() {
5
    isDark = !isDark;
6
    document.documentElement.dataset.theme = isDark ? 'dark' : 'light';
7
  }
8
</script>
9

10
<button onclick={toggle}>
11
  {isDark ? '🌙' : '☀️'}
12
</button>

为什么选择 Svelte 而不是 React/Vue：

• 编译时：Svelte 在构建时将组件编译为高效的 DOM 操作代码
• 无运行时：不需要加载 React/Vue 运行时库
• 更小的包体积：交互组件打包后通常只有几 KB

9.3 Swup 页面过渡#

Swup 是一个页面过渡库，实现 SPA 般的平滑过渡效果：

1
用户点击链接
2
    ↓
3
Swup 拦截点击
4
    ↓
5
fetch 新页面 HTML
6
    ↓
7
解析并提取内容
8
    ↓
9
CSS 过渡动画 (fade/swipe)
10
    ↓
11
替换页面内容
12
    ↓
13
更新浏览器 URL

原理：Swup 使用 History API 修改 URL，通过 AJAX 加载新页面内容，配合 CSS 过渡实现无刷新页面切换。

9.4 Iconify 图标系统#

Iconify 是一个统一的图标框架：

1
<!-- 使用任意图标集的任意图标 -->
2
<Icon name="fa7-brands:github" />    <!-- Font Awesome -->
3
<Icon name="material-symbols:home" /> <!-- Material Symbols -->
4
<Icon name="simple-icons:astro" />    <!-- Simple Icons -->

原理：

1. 构建时解析所有 Icon 组件的使用
2. 只提取实际用到的图标数据
3. 以 SVG sprite 或内联 SVG 的方式输出
4. 不会加载整个图标库（可能数百 MB）

10.1 静态站点的安全优势#

静态博客天生比动态博客更安全，因为：

• 没有数据库 → 无法进行 SQL 注入
• 没有服务端代码执行 → 无法上传 WebShell
• 没有用户认证系统 → 无账户接管风险
• 没有插件系统 → 无第三方代码执行风险

但仍需要防范以下问题。

10.2 HTTP 安全头详解#

1
Content-Security-Policy: default-src 'self';
2
  script-src 'self' 'unsafe-inline';
3
  style-src 'self' 'unsafe-inline';
4
  img-src 'self' data: https:;
5
  font-src 'self' https://fonts.gstatic.com;
6
  frame-src 'self' https:;
7
  object-src 'none';
8
  base-uri 'self';
9
  form-action 'self';

1
# 防止点击劫持
2
X-Frame-Options: DENY
3

4
# 防止 MIME 类型嗅探
5
X-Content-Type-Options: nosniff
6

7
# 启用浏览器 XSS 过滤器
8
X-XSS-Protection: 1; mode=block
9

10
# 控制 Referer 信息泄露
11
Referrer-Policy: strict-origin-when-cross-origin
12

13
# 限制浏览器功能权限
14
Permissions-Policy: camera=(), microphone=(), geolocation=()
15

16
# 强制 HTTPS 连接
17
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload

1
用户首次访问 https://example.com
2
    ↓
3
服务器返回: Strict-Transport-Security: max-age=31536000
4
    ↓
5
浏览器记录：此域名在未来 1 年内必须使用 HTTPS
6
    ↓
7
即使之后用户输入 http://example.com
8
    ↓
9
浏览器自动内部重定向到 https://example.com
10
    ↓
11
中间人无法降级到 HTTP 进行攻击

10.3 邮件地址保护#

Firefly 使用 base64 编码保护页面上的邮件地址：

1
原始 HTML:  <a href="mailto:user@example.com">Email</a>
2
编码后:     <a href="mailto:dXNlckBleGFtcGxlLmNvbQ==">Email</a>

虽然简单，但可以有效防止大多数自动化爬虫收集邮件地址。

10.4 内容安全策略（CSP）深入#

CSP 采用白名单机制：

1
加载脚本时：
2
  → 检查 script-src 列表
3
  → 如果域名在列表中 → 允许加载
4
  → 如果不在列表中 → 阻止 + 上报违规
5

6
检测到 XSS 注入时：
7
  <script>alert('xss')</script>  ← 内联脚本（不在白名单中）
8
  → CSP 阻止执行
9
  → 攻击失败

11.1 为什么选择 Cloudflare Pages#

核心优势：Cloudflare 在全球拥有 330+ 数据中心（边缘节点），用户访问的是离自己最近的节点，延迟极低。

11.2 CDN 的工作原理#

1
无 CDN：
2
用户在中国 → 直接访问美国服务器 → 延迟 200ms+
3

4
有 CDN (Cloudflare)：
5
用户在中国 → 访问最近的边缘节点（香港/东京）→ 延迟 <50ms
6
    ↓ (如果缓存命中)
7
    直接返回缓存内容（无需回源）
8
    ↓ (如果缓存未命中)
9
    从源站拉取 → 缓存到边缘 → 返回给用户

11.3 部署方式对比#

1
1. 推送代码到 GitHub
2
       ↓
3
2. Cloudflare Pages 检测到推送
4
       ↓
5
3. 自动执行构建：pnpm install → pnpm run build
6
       ↓
7
4. 自动部署：dist/ → Cloudflare 全球 CDN
8
       ↓
9
5. 自动分配域名：xxx.pages.dev

1
# 安装 Wrangler
2
npm install -g wrangler
3

4
# 登录 Cloudflare
5
wrangler login
6

7
# 部署
8
wrangler pages deploy dist --project-name=my-blog

11.4 自定义域名与 DNS#

1
域名注册 (例如 Namecheap/阿里云)
2
    ↓
3
配置 DNS 解析
4
    ↓
5
将域名的 Nameserver 指向 Cloudflare
6
    ↓
7
Cloudflare 管理 DNS + CDN + SSL + 安全
8
    ↓
9
用户访问 yourdomain.com → Cloudflare CDN → 返回博客

DNS 解析过程：

1
用户在浏览器输入 https://yourblog.com
2
    ↓
3
1. 浏览器缓存检查 → 未命中
4
    ↓
5
2. 操作系统缓存 (hosts 文件) → 未命中
6
    ↓
7
3. 路由器缓存 → 未命中
8
    ↓
9
4. ISP DNS 服务器
10
    ↓
11
5. 根 DNS 服务器 (.)
12
    ↓
13
6. .com 顶级域名服务器 (TLD)
14
    ↓
15
7. yourblog.com 权威 DNS (Cloudflare)
16
    ↓
17
8. 返回 IP 地址（Cloudflare Anycast IP）
18
    ↓
19
9. 浏览器连接最近的 Cloudflare 边缘节点

12.1 DDoS 攻击的类型#

1
Layer 7 (应用层)
2
  ├── HTTP Flood：发送大量 HTTP 请求
3
  ├── Slowloris：维持大量慢速连接
4
  └── DNS Query Flood：大量 DNS 查询
5

6
Layer 4 (传输层)
7
  ├── SYN Flood：发送大量 TCP SYN 包（不完成三次握手）
8
  └── UDP Flood：发送大量 UDP 包
9

10
Layer 3 (网络层)
11
  ├── ICMP Flood (Ping Flood)
12
  └── IP Fragmentation Attack

12.2 Cloudflare 的 DDoS 防护原理#

1
                    攻击流量
2
                 /    |    \
3
                /     |     \
4
          [节点A]  [节点B]  [节点C]  ...
5
           (少量)  (少量)   (少量)
6

7
每个节点只承担总量的一小部分

1
攻击者 ←→ Cloudflare 边缘节点 (防护层) ←→ 源服务器
2
           │
3
           ├ 分析流量模式
4
           ├ 挑战可疑请求 (JS Challenge / CAPTCHA)
5
           ├ 丢弃恶意流量
6
           └ 转发合法流量到源站

1
同一 IP：
2
  ├── 正常用户：10-30 请求/分钟 → 放行
3
  ├── 可疑行为：100+ 请求/分钟 → JS 挑战
4
  └── 明显攻击：1000+ 请求/分钟 → 直接阻断

12.3 针对静态博客的最佳防护策略#

对于静态博客，推荐使用以下组合防护：

1
层级 1：Cloudflare DDoS Protection (免费)
2
  → 自动缓解 Layer 3/4 攻击
3

4
层级 2：Cloudflare WAF (Web Application Firewall)
5
  → OWASP Top 10 防护规则
6
  → 自定义规则（限制特定路径访问频率）
7

8
层级 3：HTTP 安全头
9
  → CSP、HSTS、X-Frame-Options 等
10

11
层级 4：速率限制
12
  → 限制 API 端点访问频率
13
  → 限制搜索端点
14

15
层级 5：源站保护
16
  → 只允许 Cloudflare IP 访问源站
17
  → 关闭所有不必要的端口

13.1 Git + Cloudflare Pages 的自动化流程#

1
# .github/workflows/deploy.yml (可选，Cloudflare Pages 自带 CI)
2
工作流程：
3
  push 到 main 分支
4
    ↓
5
  Cloudflare Pages 自动检测
6
    ↓
7
  拉取最新代码
8
    ↓
9
  执行构建命令 (pnpm run build)
10
    ↓
11
  部署到预览环境 (*.pages.dev)
12
    ↓
13
  (可选) 合并到 production 分支 → 部署到生产环境

13.2 预览部署#

Cloudflare Pages 为每个 Pull Request 自动创建预览环境：

1
PR #1 → https://abc123.myblog.pages.dev
2
PR #2 → https://def456.myblog.pages.dev
3

4
✅ 在合并前预览变更效果
5
✅ 与团队成员分享进行 review
6
✅ 不影响生产环境

14.1 站点监控#

• Cloudflare Analytics：流量、带宽、安全事件
• Google Analytics / Umami：用户行为分析
• Microsoft Clarity：用户行为录屏和热力图

14.2 内容维护#

1
# 创建新文章
2
pnpm new-post my-article
3

4
# 本地预览
5
pnpm dev
6

7
# 格式化代码
8
pnpm format
9

10
# 构建检查
11
pnpm check
12

13
# 生产构建
14
pnpm build

14.3 版本更新#

1
# 更新依赖到最新版本
2
pnpm update --latest
3

4
# 检查安全漏洞
5
pnpm audit
6

7
# 更新后务必测试构建
8
pnpm build

关键技术栈总结#

Q1: 构建时出现 bangumi API 连接失败？#

原因：Bangumi (bgm.tv) API 在某些网络环境下不可访问。

解决：在 siteConfig.ts 中设置 pages.bangumi: false，或在构建时配置代理。

Q2: 如何添加自定义字体？#

在 src/config/fontConfig.ts 中配置，支持 Google Fonts 和本地字体。

Q3: 如何启用评论系统？#

1. 部署评论后端（如 Twikoo 使用 Vercel 部署）
2. 在 commentConfig.ts 中填入后端地址
3. 设置 type 为对应的评论系统

Q4: 图片加载慢怎么办？#

1. 使用 WebP/AVIF 格式
2. 在 siteConfig.ts 中降低 imageOptimization.quality
3. 利用 Cloudflare CDN 的自动优化功能（Polish、Mirage）

Q5: 如何实现完全免费的部署？#

• 代码托管：GitHub (免费)
• 构建部署：Cloudflare Pages (免费，无限带宽)
• 域名：使用默认的 *.pages.dev 域名（免费），或购买自定义域名（约 ¥50/年）
• 评论系统：Twikoo + Vercel (免费) 或 Giscus + GitHub Discussions (免费)

📚 参考资料

• Astro 官方文档
• Firefly 使用文档
• Cloudflare Pages 文档
• Cloudflare DDoS 防护
• MDN Web 安全指南
• Content Security Policy 参考