从Hexo迁移到Astro部署记录

1. 为什么选 Cloudflare Pages#

• 免费额度够用：每月 100 GB 流量，静态博客轻松覆盖；
• 自带全球 CDN：国内节点比 GitHub Pages 快得多；
• 支持自定义域名、自动 HTTPS；
• 和 GitHub 无缝衔接：可以直接连仓库，也可以用 API Token 手动部署。

2. 方案对比：控制台连接 Git vs API Token#

一开始尝试的是 Cloudflare 控制台「连接到 Git」（Workers 和 Pages → 创建 → 连接到 Git → 授权 GitHub → 选仓库），理想情况是自动构建、push 即部署。但实测遇到了几个坑：

• 点「Connect GitHub」后反复跳转到 GitHub 的 App 安装配置页（settings/installations），而不是正常的 OAuth 授权；
• 仓库权限配好后点 Save，授权回调不自动回 CF，仓库列表一直加载不出来；
• 折腾半天走不到选仓库那一步。

为什么改用 API Token 方案：

• 不依赖控制台页面：命令行一条命令完成部署，不碰那个绕圈的 OAuth 流程；
• 可复现、可写进脚本/CI：命令即文档，以后换机器也能一键部署；
• 权限可精确控制：token 只给「Cloudflare Pages → Edit」权限，用完随时在控制台撤销，比账号级授权更安全。

3. 创建 API Token#

在 Cloudflare 控制台右上角头像 → My Profile → API Tokens 页面，点右上角蓝色 Create Token 按钮：

然后选 Custom token，按下面的参数填：

• Token name：随便填，只是标签不影响功能（比如 blog-deploy、blog_deploy 都行）；
• Permissions：Account → Cloudflare Pages → Edit；
• Account resources：Include → 你的账号；
• 其他默认，点 Create 后复制 token（只显示一次）。

注意：token 相当于账号钥匙，不要提交到代码仓库。

以后想改 / 轮换 / 删除 token：Cloudflare 控制台 → 右上角头像 → My Profile → API Tokens，找到对应 token 后点右侧菜单：

• Edit：修改名称、权限、绑定的账号；
• Roll：轮换——生成一个新值，旧值立即失效（token 泄露或想换新时用这个）；
• Delete：彻底删除（部署不再需要时）。

token 只在创建时完整显示一次，Roll 之后记得把新值同步到 GitHub Secrets（见下文第 6 节）。

4. 构建并部署（wrangler）#

本地构建产物在 dist/，用 wrangler 直接推上去（Node 自带 npx，无需全局安装）：

1
# 1. 构建（输出 dist/）
2
pnpm build
3

4
# 2. 配置凭据（Windows PowerShell 用 $env: 前缀，Linux/macOS 用 export）
5
$env:CLOUDFLARE_API_TOKEN = "你的API_TOKEN"      # 上一步创建的
6
$env:CLOUDFLARE_ACCOUNT_ID = "你的账号ID"        # 你的账号ID
7

8
# 3. 创建 Pages 项目（仅首次）
9
npx wrangler pages project create my-firefly-blog --production-branch main
10

11
# 4. 部署 dist 目录
12
npx wrangler pages deploy dist --project-name my-firefly-blog --branch main

部署成功输出（真实记录）：

1
✨ Success! Uploaded 244 files (17.28 sec)
2

3
🌎 Deploying...
4
✨ Deployment complete! Take a peek over at https://ca824054.my-firefly-blog.pages.dev

生产域名：https://my-firefly-blog.pages.dev

5. 验证#

浏览器打开 https://my-firefly-blog.pages.dev，内容和 GitHub Pages 完全一致（同一个 dist 构建产物），国内访问明显更流畅：

Cloudflare 控制台的部署记录页（Production 域名 + 每次部署的提交信息、状态、预览地址）：

6. 后续自动化：push 双平台同步#

目前 GitHub Pages 是 push 自动部署，Cloudflare Pages 是手动 wrangler pages deploy。想做到推一次代码、两个平台同时更新，在仓库新建 .github/workflows/deploy-cloudflare.yml，用官方 cloudflare/wrangler-action@v3：

1
name: Deploy to Cloudflare Pages
2

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

8
jobs:
9
  deploy:
10
    runs-on: ubuntu-latest
11
    permissions:
12
      contents: read
13
    steps:
14
      - name: Checkout
15
        uses: actions/checkout@v4
16

17
      - name: Setup Node.js
18
        uses: actions/setup-node@v4
19
        with:
20
          node-version: '22'
21

22
      - name: Setup pnpm
23
        uses: pnpm/action-setup@v4
24
        with:
25
          version: 11.22.0
26
          run_install: false
27

28
      - name: Install dependencies
29
        run: pnpm install --no-frozen-lockfile
30

31
      - name: Build
32
        run: pnpm run build
33

34
      - name: Deploy to Cloudflare Pages
35
        uses: cloudflare/wrangler-action@v3
36
        with:
37
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
38
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
39
          command: pages deploy dist --project-name my-firefly-blog --branch main

使用前提：把两个值配到 GitHub 仓库的 Secrets 里，步骤如下：

1. 打开 GitHub 仓库页：https://github.com/Lycaonide/lycaonide.github.io；
2. 点顶部 Settings 标签；
3. 左侧菜单 Security → Secrets and variables → Actions；
4. 点绿色的 New repository secret 按钮；
5. Name 填 CLOUDFLARE_API_TOKEN，Secret 填你的 Cloudflare API Token（创建方法见上文第 3 节），点 Add secret；
6. 再点一次 New repository secret：Name 填 CLOUDFLARE_ACCOUNT_ID，Secret 填 Cloudflare 账号 ID，点 Add secret。

注意：workflow 是仓库 .github/workflows/ 目录里的 YAML 配置，声明“每次 push 自动执行哪些步骤”，Name 必须和 workflow 里引用的一致，不能随便起名（名字对不上，workflow 读不到，CF 部署会一直失败）。两个值分别填什么：CLOUDFLARE_API_TOKEN 填你创建的那个新 token 值；CLOUDFLARE_ACCOUNT_ID 填账号 ID——打开 Cloudflare 控制台任意页面，看地址栏 dash.cloudflare.com/ 后面第一段，就是账号 ID。

配好之后，每次 git push 会自动构建并同时部署到 GitHub Pages 和 Cloudflare Pages。仓库 Actions 页面可以看到两个 workflow 同时运行、双双成功：

7. 自定义域名（可选）#

Cloudflare Pages 支持绑定自定义域名（免费，自动 HTTPS），在项目页 → Custom domains 里添加即可。本站暂时用 pages.dev 子域名，等有合适域名再绑。绑定后原 pages.dev 域名依然可用，不影响现有访问。

1. 为什么用 Starlight#

对比过两种方案：一是”手写侧边栏”（自己写文档区 + 侧边栏组件），二是”单独建一个文档站”（另一个仓库/域名）。

408 四科 26 章笔记，用 Starlight 最省事。

2. 安装与接入#

1
pnpm add @astrojs/starlight

在 astro.config.mjs 的 integrations 里加 starlight：

1
// astro.config.mjs（starlight 部分，本站实际配置）
2
starlight({
3
  title: "知识库",                              // 导航名显示"知识库"
4
  disable404Route: true,
5
  sidebar: kbSidebar,                           // 动态侧边栏，见第 5 节
6
  social: [{ icon: "external", label: "返回", href: "/" }],   // 顶栏"返回"回博客首页
7
  components: {
8
    SocialIcons: "./src/components/starlight/SocialIcons.astro",  // 把图标换成文字"返回"
9
  },
10
  customCss: ["./src/styles/starlight.css"],    // 样式对齐博客主题色，见第 6 节
11
  head: [
12
    // AI 问答脚本（第十一章），必须 is:inline，知识库页也有 AI 按钮
13
    { tag: "script", attrs: { src: "/ai-chat.js", is: "inline" } },
14
  ],
15
}),

导航名和 URL 为什么分开：title 显示”知识库”，但访问路径是 /kb/——短路径好记、输入方便，导航名和 URL 互不绑定，改名字不用动链接。

3. 内容目录#

知识库内容在 src/content/docs/，按”知识库 → 考研 → 科目 → 章节”建文件夹，四科章节目录按王道《408 考研复习指导》建：

1
src/content/docs/kb/
2
├── index.md                    # 知识库首页
3
└── 考研/
4
    ├── index.md
5
    ├── 操作系统/       # 5 章：概述 / 进程线程 / 内存 / 文件 / IO
6
    ├── 数据结构/       # 8 章：绪论 / 线性表 / 栈队列数组 / 串 / 树 / 图 / 查找 / 排序
7
    ├── 计算机网络/     # 6 章：体系结构 / 物理 / 数据链路 / 网络 / 传输 / 应用
8
    └── 计算机组成原理/ # 7 章：概述 / 数据运算 / 存储 / 指令 / CPU / 总线 / IO

4. 每章建一个子页#

每个科目一个文件夹 + index.md，每章一个 md 文件。科目首页 index.md 里写章节目录链接（方便从科目页点进章节），章节页是独立的 第N章-xxx.md，Starlight 自动按层级生成侧边栏。

1
<!-- src/content/docs/kb/考研/操作系统/index.md -->
2
---
3
title: 操作系统
4
description: Operating System - 进程/内存/文件/设备管理，配合王道考研
5
sidebar:
6
  hidden: true
7
---
8

9
> 这里放 操作系统 的复习笔记，按章节组织。
10
## 章节目录（王道考研复习指导）
11
- [第1章 计算机系统概述](第1章-计算机系统概述/)
12
- [第2章 进程与线程](第2章-进程与线程/)
13
- ……

sidebar: hidden: true 让科目首页不在侧边栏重复出现（侧边栏只展示章节），章节目录由用户点进科目页看。

5. 动态侧边栏（加新章不用改配置）#

Starlight 默认 sidebar 要手写条目，加一章改一次很烦。本站写了个构建时扫描函数：读 src/content/docs/kb 目录，自动生成侧边栏结构——以后加新章节、新科目，只要把 md 丢进文件夹就行，不用碰 astro.config.mjs：

1
// astro.config.mjs 顶部（本站实际使用）
2
import { readdirSync } from "node:fs";
3
import { join } from "node:path";
4
import { fileURLToPath } from "node:url";
5

6
const __kbDir = fileURLToPath(new URL("./src/content/docs/kb", import.meta.url));
7

8
function kbSlugify(name) {
9
  return name.replace(/\.mdx?$/, "").toLowerCase()
10
    .replace(/[^\p{L}\p{N}\- ]/gu, "").replace(/ +/g, "-");
11
}
12

13
function kbScan(dir, prefix) {
14
  const items = readdirSync(dir, { withFileTypes: true })
15
    .filter((d) => d.isDirectory() || /\.mdx?$/.test(d.name))
16
    .sort((a, b) => a.name.localeCompare(b.name, "zh-CN"));
17
  const out = [];
18
  for (const e of items) {
19
    if (e.isDirectory()) {
20
      const children = kbScan(join(dir, e.name), prefix + "/" + e.name);
21
      if (children.length) out.push({ label: e.name, items: children });
22
    } else if (e.name !== "index.md" && e.name !== "index.mdx") {
23
      out.push({ slug: prefix + "/" + kbSlugify(e.name) });
24
    }
25
  }
26
  return out;
27
}
28

29
const kbSidebar = [
30
  { label: "知识库", items: [{ label: "知识库首页", link: "/kb/" }, ...kbScan(__kbDir, "kb")] },
31
];

之后在 考研/ 下新增 第N章-xxx.md，构建时侧边栏自动出现。index.md 被过滤（只作文件夹首页，不进侧边栏）。

6. 样式对齐博客主题 + 明暗联动#

Starlight 默认是蓝色主题，放在博客里很突兀。用 src/styles/starlight.css 改成博客的青绿主题色（teal，和 Firefly 的 primary 一致）：

1
/* src/styles/starlight.css（本站实际使用） */
2
:root[data-theme="light"] {
3
  --sl-color-accent-high: #0f766e;
4
  --sl-color-accent: #0d9488;
5
  --sl-color-accent-low: #ccfbf1;
6
}
7
:root[data-theme="dark"] {
8
  --sl-color-accent-high: #5eead4;
9
  --sl-color-accent: #2dd4bf;
10
  --sl-color-accent-low: #134e4a;
11
}

明暗联动：博客主题切换存在 localStorage.theme，Starlight 存在 starlight-theme，两边互不相通会割裂。astro.config.mjs 的 starlight head 里加了一段同步脚本（第 2 节配置里有），本地存储变化互相转发——在博客切暗色，知识库跟着变，反之亦然。

7. 顶栏”返回”链接#

Starlight 顶栏右侧默认放社交图标，本站自定义了 src/components/starlight/SocialIcons.astro，把图标换成文字”返回”，点击直接回博客首页——知识库是从博客点进来的，给一个明确的回去入口：

1
---
2
// src/components/starlight/SocialIcons.astro（本站实际使用）
3
import config from "virtual:starlight/user-config";
4
const links = config.social || [];
5
---
6
{
7
  links.length > 0 && (
8
    <>
9
      {links.map(({ label, href }) => (
10
        <a href={href} class="return-link">{label}</a>
11
      ))}
12
    </>
13
  )
14
}
15
<style>
16
  .return-link {
17
    color: var(--sl-color-text-accent);
18
    padding: 0.5em;
19
    margin: -0.5em;
20
    font-size: var(--sl-text-sm);
21
    text-decoration: none;
22
    white-space: nowrap;
23
  }
24
</style>

8. 踩坑记录（实际修过的问题）#

• 标题锚点图标：Starlight 给每个标题自动加 # 锚点图标（点击可定位），博客文章也有一份。看起来”标题后面跟一个 # 加一个链接符号”，实际是自动生成的锚点。用 CSS 隐藏图标、保留锚点定位功能：

  1
  .sl-markdown-content .anchor { display: none; }

• Swup 无刷新冲突：博客用了 Swup 无刷新跳转，但 /kb 是 Starlight 独立布局，走 Swup 会样式错乱。在 swup 配置里排除：ignore: [/^\/kb/]。
• AI 脚本注入：知识库页要显示 AI 按钮，脚本在 starlight head 里注入必须 is: inline（否则 Astro 构建时丢弃引用），和博客布局里同一份 ai-chat.js。

9. Obsidian 编辑 + AI 联动 + 部署#

• Obsidian 编辑：src/content/docs/kb/ 就是一个普通 Markdown 文件夹，直接用 Obsidian 打开就能编辑（双链、大纲都支持）。本地的 .obsidian/ 配置目录已 gitignore，不会进仓库；写完 git push 自动部署上线。
• AI 联动：知识库页面同样有右下角 AI 问答按钮（第 11 章），提问时会把当前章节的正文作为上下文带给大模型——对着笔记章节直接问”这一章的重点是什么”。
• 部署：/kb/ 和博客一起构建、一起被 GitHub Actions / Cloudflare Pages 部署，不需要额外配置。

10. 验证#

1
pnpm dev

浏览器打开 https://my-firefly-blog.pages.dev/kb/：左侧目录树（知识库 → 考研 → 四科）都正常。

1. 开通模型#

火山方舟控制台：console.volcengine.com/ark → 开通管理 → 搜索要用的模型（比如 doubao-seed-2-0）→ 点开通。开通页面能直接看到每个模型的免费额度（50 万 tokens）和计费价格，开通免费。

注意：模型 ID 在开通后控制台可查（如 doubao-seed-2-0-code-preview-260215）。如果控制台提示”余额不足无法开通”，是因为部分模型要求账户有预留金，充 20 元即可（可退）。

2. 创建 API Key#

控制台左侧 API Key 管理 → 创建 API Key，起个名字（如 blog-ai），创建后只显示一次，马上复制保存：

API Key 相当于账号钥匙，不要提交到代码仓库（本教程把它放在 CF 环境变量里，见第 5 节）。

3. 写 Cloudflare Pages Function（后端代理）#

Pages 项目根目录建 functions/api/chat.ts——Cloudflare Pages 会自动把 functions/api/ 下的文件发布成 /api/xxx 接口。作用：前端只把问题发给本站，由这个 Function 带 Key 去请求火山方舟，Key 永远不会暴露到浏览器：

1
// functions/api/chat.ts（本站实际使用版本）
2
export async function onRequestPost(context) {
3
  const { question, context: ctx } = await context.request.json().catch(() => ({}));
4
  if (!question || typeof question !== "string") {
5
    return json({ error: "缺少问题" }, 400);
6
  }
7
  const API_KEY = context.env.ARK_API_KEY;
8
  if (!API_KEY) {
9
    return json({ error: "服务未配置（缺少 ARK_API_KEY）" }, 500);
10
  }
11
  const MODEL = context.env.ARK_MODEL || "doubao-seed-2-0-code-preview-260215";
12
  const system =
13
    "你是本站的 AI 问答助手，根据提供的知识库内容回答用户问题。" +
14
    "如果知识库内容不足以回答，可以结合你的知识补充，并说明哪些来自知识库。回答简洁、条理清晰，使用中文。";
15
  const user =
16
    (ctx && typeof ctx === "string" && ctx.trim()
17
      ? `以下是知识库相关章节的内容（供参考）：\n\n${ctx.slice(0, 6000)}\n\n`
18
      : "") + `用户问题：${question}`;
19
  try {
20
    const resp = await fetch("https://ark.cn-beijing.volces.com/api/v3/chat/completions", {
21
      method: "POST",
22
      headers: {
23
        "Content-Type": "application/json",
24
        Authorization: `Bearer ${API_KEY}`,
25
      },
26
      body: JSON.stringify({
27
        model: MODEL,
28
        messages: [
29
          { role: "system", content: system },
30
          { role: "user", content: user },
31
        ],
32
        max_tokens: 1500,
33
        temperature: 0.6,
34
      }),
35
    });
36
    if (!resp.ok) {
37
      const t = (await resp.text()).slice(0, 300);
38
      return json({ error: `上游接口错误 ${resp.status}: ${t}` }, 502);
39
    }
40
    const data = await resp.json();
41
    const answer = data?.choices?.[0]?.message?.content;
42
    if (!answer) {
43
      return json({ error: "AI 未返回内容" }, 502);
44
    }
45
    // 把本次消耗的 tokens 返回给前端，用于费用提示
46
    const usage = data?.usage
47
      ? { prompt: data.usage.prompt_tokens ?? 0, completion: data.usage.completion_tokens ?? 0, total: data.usage.total_tokens ?? 0 }
48
      : null;
49
    return json({ answer, usage });
50
  } catch (e) {
51
    return json({ error: `请求失败: ${String(e)}` }, 500);
52
  }
53
}
54

55
function json(obj, status) {
56
  return new Response(JSON.stringify(obj), {
57
    status,
58
    headers: { "Content-Type": "application/json; charset=utf-8" },
59
  });
60
}

4. 前端组件#

新建 public/ai-chat.js：右下角浮动按钮 + 聊天弹窗 + 费用提示。核心逻辑：

1
// public/ai-chat.js（核心逻辑，完整文件见仓库）
2
(function () {
3
  // GitHub Pages 没有 Functions 后端，只在 Cloudflare 域名启用
4
  if (location.hostname === "lycaonide.github.io") return;
5

6
  // 1. 创建浮动按钮和弹窗（appendChild 到 body）
7
  // 2. 发送问题时先本地检索博客全文（见第 5 节），把命中片段作为上下文，POST /api/chat
8
  // 3. 回答里如果有 usage.total，就显示"本次消耗 X tokens（免费额度内不扣费）"
9
  // 4. 弹窗底部常驻提示行：
10
  //    "免费额度内不花钱 · 额度用尽后按量计费，余额不足自动停用"
11
})();

然后在布局里引入（注意：必须加 is:inline，否则 Astro 会丢弃对 public 目录脚本的引用，按钮不出来）：

1
<!-- src/layouts/Layout.astro 的 <head> 里 -->
2
<script src="/ai-chat.js" is:inline></script>

如果用了 Starlight 知识库，也要在 astro.config.mjs 的 starlight head 里注入同一份：

1
// astro.config.mjs（starlight 配置里）
2
head: [
3
  { tag: "script", attrs: { src: "/ai-chat.js", is: "inline" } },
4
],

踩坑记录：① Astro 会丢弃非 is:inline 的 public 脚本引用（页面 HTML 里查不到）；② 脚本在 <head> 里立即执行时 document.body 还不存在，要先等 DOMContentLoaded；③ GitHub Pages 没有 Functions 后端，要按域名禁用（location.hostname 判断）。

5. 升级：博客全文本地检索（轻量 RAG）#

第一版只能把”当前页面”内容带给 AI——你在哪个页面问，它参考哪个页面，问”本项目用什么 Node 版本”这种信息在其他文章里的问题就答不上。升级后改成全文检索（轻量 RAG），实测效果（回答会明确区分来源、点名具体篇目）：

• 全文索引：构建时由 scripts/build-blog-index.mjs 把 src/content/posts/ 下所有文章解析成纯文本、按段落分块，生成 public/api/blog-index.json（本站 5 篇约 43KB），已挂进 pnpm build 自动生成；
• 本地检索：提问时浏览器直接读索引，把问题拆成关键词（英文/数字词高权重 + 中文相邻两字 bigram）给每个段落打分，取最相关的 4 段（≤4500 字符，每篇最多 2 段）；
• 只送片段：命中的段落拼进请求发给大模型，AI 基于片段回答——检索在浏览器本地完成不花钱，每次只消耗片段对应的 tokens（实测约 2200 tokens）。

1
// public/ai-chat.js 新增的检索逻辑（核心）
2
fetch("/api/blog-index.json", { cache: "force-cache" })   // 1. 加载索引（缓存复用）
3
  .then(r => r.json()).then(idx => {
4
    // 2. 问题拆词：英文词 + 中文 bigram，标题/正文/标签加权打分
5
    // 3. 取分数最高的 4 段拼成上下文（每篇最多 2 段），并记录命中文章标题
6
    // 4. 片段作为 context、文章标题作为 sources 随问题 POST /api/chat
7
  });

来源标注：前端把命中文章的标题去重后随请求传给后端，后端拼进提示词“参考内容来自以下博客文章：xxx”；后端提示词同时要求 AI——先判断来源（博客文章还是知识库笔记）、回答时点名具体篇目（如“出自《从Hexo迁移到Astro部署记录》”）、只陈述事实不做纠错评论。在知识库页面提问时，回退内容会标注为“知识库笔记”，AI 会说明来自知识库。

为什么不把全文直接塞给 AI：5 篇文章全文约 43KB ≈ 2 万+ tokens，每次问答全量发太费；检索后只发命中片段 ≈ 4500 字符 ≈ 2 千 tokens，省约 10 倍，免费额度能多用很久。

6. 配置环境变量（ARK_API_KEY）#

Cloudflare 控制台 → 你的 Pages 项目 → Settings → Environment variables → Add：

• Type：Text（明文字符串即可，Key 只在服务器端读取，不会发给浏览器）
• Name：ARK_API_KEY
• Value：第 2 步创建的 API Key

想换模型可以再加一个 ARK_MODEL 变量（默认就是 Doubao-Seed-2.0-Code，不配也行）。

7. 费用提示#

前端弹窗里做了两层提示（本站实际效果）：

• 常驻提示行（输入框上方）：免费额度内不花钱 · 额度用尽后按量计费，余额不足自动停用；
• 每次回答后显示本次消耗：本次消耗 927 tokens（免费额度内不扣费）。

控制台（火山方舟 → 费用中心）能看每月账单，个人博客用量远低于 50 万免费额度，基本不产生费用。

8. 验证#

1
# 本地或线上直接测接口（返回 JSON，含 answer 和 usage）
2
curl -X POST https://my-firefly-blog.pages.dev/api/chat ^
3
  -H "Content-Type: application/json" ^
4
  -d "{\"question\":\"进程和线程有什么区别？\"}"

浏览器打开 https://my-firefly-blog.pages.dev，点右下角 ✦ 按钮即可聊天。注意 GitHub Pages 站没有 Functions 后端，AI 按钮自动隐藏（前端已按域名判断）。

9. 后续：向量检索（RAG 进阶）#

现在的轻量 RAG 是关键词/字面匹配（“node”能命中”Node 24”），零成本、够用。以后文章多到几百篇、或想让它理解口语化问法（“node 版本”自动关联”v24.5.0”这类变体表达）时，升级成向量检索：

• 原理：用 embedding 模型把每段文本转成向量存索引，提问时把问题也转成向量，按余弦相似度找最相关的段落——语义层面的匹配，不依赖字面一致；
• 代价：检索前多一步 embedding 调用（火山方舟等平台提供，按 tokens 计费，量很小），实现复杂度也高一些；
• 结论：等文章数量足够多，在 scripts/build-blog-index.mjs 里给每段生成向量、前端检索改成向量相似度即可，上下文接口不用动。

1. 主题原生支持#

主题的 content.config.ts 本身就定义了可选的 updated 字段，PostMeta.astro（文章页元信息）原生支持显示”最后更新于”。默认条件比较严（updated 存在且不等于 published 才显示），我只改了两处：只要写了 updated 就显示，并且删掉了主题在文章底部的大卡片（避免开头结尾重复）。

2. 提交钩子（已入库 scripts/pre-commit.hook）#

钩子内容（文件已放进仓库，方便换机器恢复）：

1
#!/bin/sh
2
command -v node >/dev/null 2>&1 || exit 0
3
SCRIPT_DIR="$(cd "$(dirname "$0")/../../scripts" && pwd)" || exit 0
4
node "$SCRIPT_DIR/auto-updated.mjs" >/dev/null 2>&1
5
exit 0

安装到本机（Git 只认 .git/hooks/ 下的钩子文件）：

1
# Windows（Git Bash 环境）
2
cp scripts/pre-commit.hook .git/hooks/pre-commit

换机器 / 重新克隆仓库后，重新执行上面这一行即可（核心脚本 scripts/auto-updated.mjs 已经在仓库里）。

3. 自动补日期脚本（scripts/auto-updated.mjs）#

核心就三步：取本次提交的文章 → 补 updated: 今天 → 重新暂存。

1
// 1. 取出本次 staged 的博客文章（-z 处理中文/空格文件名）
2
const out = execSync(
3
  'git -c core.quotepath=false diff --cached --name-only -z -- "src/content/posts"',
4
  { cwd: root, encoding: "utf8" },
5
);
6
files = out.split("\0").filter(f => f.endsWith(".md"));
7

8
// 2. 逐篇补 updated: 今天（已有且是今天则跳过）
9
if (/^updated:/m.test(s)) {
10
  s = s.replace(/^updated:.*$/m, `updated: ${today}`);
11
} else {
12
  s = s.replace(/^(published:.*)$/m, `$1\nupdated: ${today}`);
13
}
14

15
// 3. 重新 git add 改过的文件，让提交带上新字段
16
execSync(`git add -- ${changed.map(f => `"${f}"`).join(" ")}`);

4. 以后怎么用#

改文章 → git add → git commit → git push，钩子在 commit 时自动补 updated: 当天，push 后双站部署完，文章页自动显示新的”最后更新于”，全程不用手动写字段。

两个注意点：

• 钩子只管 src/content/posts/ 下的博客文章，知识库笔记（src/content/docs/）不处理；
• 钩子只装在本机 .git/hooks/，换机器 / 重克隆后按第 2 节一行命令重装即可。

1. 在控制台添加站点#

Cloudflare 控制台左侧 Analytics → Web analytics → 右上角 Add a site，填入主域名 lycaonide.github.io（一个 property 可绑多个主机名，备用域名后面想统计再加）：

创建后进 Manage site，页面下方 Install JS Snippet 直接给出一段带 token 的代码，点 Click to copy 复制：

注意：这段代码里的 token 是公开的站点标识，本来就会出现在每个访客的 HTML 里，随便贴、不用当密钥；真正要保密的是第九节那个部署用的 API Token。

2. 把 beacon 加到两处布局#

为什么是两处？博客文章用的是 Firefly 主题自己的 src/layouts/Layout.astro，而知识库 /kb/ 用的是 Starlight 独立布局，两者 <head> 互不相干——只加一处，另一处就不计数。

第一处：博客布局 src/layouts/Layout.astro 的 <head> 里（和 AI 脚本一样必须 is:inline）：

1
<!-- src/layouts/Layout.astro 的 <head> 里 -->
2
<!-- Cloudflare Web Analytics -->
3
<script is:inline type="module" src="https://static.cloudflareinsights.com/beacon.min.js" data-cf-beacon='{"token": "092a891a22f0434890303a58e99052f6"}'></script>
4
<!-- End Cloudflare Web Analytics -->

第二处：知识库 Starlight 布局，加在 astro.config.mjs 的 starlight({ head: [...] }) 数组里（和第十一节 AI 脚本同一个数组）：

1
// astro.config.mjs（starlight 配置的 head 数组里，本站实际使用）
2
{
3
  tag: "script",
4
  attrs: {
5
    src: "https://static.cloudflareinsights.com/beacon.min.js",
6
    type: "module",
7
    "data-cf-beacon":
8
      '{"token": "092a891a22f0434890303a58e99052f6"}',
9
  },
10
},

两处用的是同一个 token，所以博客文章和知识库章节都汇总到同一个 Web Analytics property 里看。

3. 验证#

push 部署后等几分钟，回到 Web Analytics 看板，能看到 PV / 独立访问数、访客国家分布，以及 Core Web Vitals（LCP / INP / CLS，条全绿就是体验健康）：

几个实际踩过的点：

• 数据有几分钟延迟，刚部署完立刻看是空的，正常，过一会儿再刷新就有数了；
• 一定要 is:inline：和第十一节 AI 脚本一个道理，不加 is:inline，Astro 构建时会把这条 <script> 引用丢掉，页面里根本没有，控制台永远收不到数；
• 两个域名想清楚：本站 property 里只配了 lycaonide.github.io（主站），my-firefly-blog.pages.dev 备用域名的访问默认不计入；想一起统计就在 Manage site 的 Configured hostname(s) 里把 pages.dev 也加上；
• 不依赖 Cloudflare 托管也能用：它只是一段前端 beacon，静态站挂哪都行——本站反正已经在 CF Pages 上，顺手开通而已。

1. 从知识库点”返回”，中间多跳了两个页面#

现象：在知识库 /kb/ 章节页点右上角”返回”回博客首页，中间会闪过两个额外页面，有时还短暂白屏。

原因：博客用了 Swup 做站内无刷新过渡（点站内链接只换内容、不整页刷新）。正常站内链接交给 Swup 没问题，但”返回”链接同时叠了两种跳转：

• Swup 拦截这个链接，先做一次 SPA 式半切换；
• 返回按钮的逻辑里又强制整页跳一次。

两者叠加 = 实际跳了两次，中间那两个”页面”就是这么多出来的。

解决：给返回链接加 data-no-swup，Swup 直接放行、完全不碰它，只走一次浏览器原生跳转。代码就在 src/components/starlight/SocialIcons.astro：

1
{/* 知识库顶栏"返回"：必须 data-no-swup，否则和 Swup 叠加跳两次 */}
2
<a href={href} class="return-link" data-no-swup>{label}</a>

经验：用了 Swup 这类过渡库后，所有”特殊跳转”——返回、外链、必须整页刷新的链接——都要显式加 data-no-swup，别让它和库的拦截逻辑打架。

2. 背景视频：清晰度和移动端播放的平衡#

现象：背景视频第一版压到 13MB 后，720p 动画画面明显发糊；后来为了清晰压回 24.27MB（约 875kbps），桌面端没问题，但手机上打开页面点播放，浏览器直接弹下载而不是播放；微信里点分享链接、按播放按钮完全没反应。

原因（两个独立问题）：

• 糊：720p 码率压到约 448kbps（crf 35）太低，带动态细节的动画画面低于约 700kbps 就会糊；
• 手机上变下载 / 微信放不了：Cloudflare Pages 的静态资源不响应 Range 请求（实测带 Range: bytes=0-1023 也返回 200 全量，pages.dev 域名不走 CF 边缘缓存），浏览器没法”边下边播”，超过 ~15MB 就直接转下载；微信内置浏览器（X5/WKWebView）对无 Range 的大视频直接拒绝播放。GitHub Pages 支持 Range（返回 206）所以之前能播，但国内访问慢所以卡。

解决：换思路——降分辨率、保码率密度。降到 854×480 后用 2-pass 精确压到约 410kbps，成品 14.94MB：分辨率减半但每像素码率是 720p@448k 的两倍，手机上（屏幕小）反而更清晰，体积也落在手机浏览器愿意整体缓冲的区间。中间试过的版本：

压制前先用 ffprobe 查源视频参数，确认分辨率和时长（算码率预算要用）：

1
# 查源视频分辨率/时长/码率
2
ffprobe -v error -select_streams v:0 -show_entries stream=width,height,bit_rate \
3
  -show_entries format=duration,size 源视频.mp4
4
# 实际结果：1280x720，时长 245s

最终压制命令（2-pass，Windows 用 NUL，Linux/macOS 用 /dev/null）：

1
# 源视频 1280x720、245s；最终压成 firefly.mp4（14.94MB，854×480）
2
ffmpeg -y -i 源视频.mp4 -vf scale=854:480 -c:v libx264 -preset medium \
3
  -b:v 410k -maxrate 600k -bufsize 1.2M -pass 1 -an -f null NUL
4
ffmpeg -y -i 源视频.mp4 -vf scale=854:480 -c:v libx264 -preset medium \
5
  -b:v 410k -maxrate 600k -bufsize 1.2M -pass 2 \
6
  -c:a aac -b:a 96k -movflags +faststart firefly.mp4

参数：-vf scale=854:480 降到 480p——手机屏幕小，分辨率减半不影响观感，码率密度翻倍反而更清晰；-b:v 410k 目标视频码率，2-pass 先跑一遍摸清画面复杂度再精确分配码率，比 CRF 更能卡体积（配合 -maxrate 600k 防码率尖峰）；-movflags +faststart 把索引放到文件头，浏览器能边下边播；-pix_fmt yuv420p 兼容性最好。

配套的加载优化：背景视频不做首屏自动加载，而是挂在导航栏”播放背景视频”按钮上，点击时才给 <video> 赋 src——访客不点就不下载这 15MB，首屏更快也更省流量：

1
// BackgroundPlayer：点击播放才赋 src，访客不点就不下载
2
const video = document.querySelector("video");
3
playBtn.addEventListener("click", () => {
4
  if (!video.src) video.src = "/assets/videos/firefly.mp4";
5
  video.play();
6
});

另外 <video> 标签要加移动端内联播放属性，否则 iOS Safari 全屏、微信 X5 内核不播：

1
<video preload="metadata" playsinline webkit-playsinline
2
  x5-playsinline x5-video-player-type="h5" ...></video>

经验：① 动画类 720p 码率别低于 700kbps，否则动态细节必糊；② CF Pages 静态资源不响应 Range 请求，移动端大视频会变下载、微信放不了——要么控制在 ~15MB 内让浏览器整体缓冲，要么绑自定义域名走 CDN 缓存；③ 清晰度看”每像素码率”：降分辨率 + 足码率，小屏上比高分辨率低码率更清晰；④ 体积 / 清晰 / 加载速度三者不可兼得，按场景取舍。