为什么走服务端代理#

Ech0 的 CORS 是开放的，实测它会回显任意 Origin，理论上前端直接 fetch m.081531.xyz 就能用。但我还是选择了和 Memos 一样的方案：写一个服务端适配器，数据经 /api/ech0.json 同源代理吐给前端。原因有三个。

第一，动态页的消费端契约是 DynamicEntry，里面有一个已经渲染好的 html 字段。Markdown 转 HTML 这一步目前依赖 marked，跑在服务端。如果前端直连，要么把渲染逻辑搬进浏览器白白增加打包体积，要么每个消费组件各渲染一遍——两条路都比多写一个适配器难看。

第二，代理端点可以挂缓存头。我给的是 Cache-Control: public, max-age=60, stale-while-revalidate=300，热页面上新内容最多延迟一分钟，冷门时段先吐旧缓存、后台刷新。关键是这个端点是运行时按需执行的，不是构建时产物——我在 Ech0 发条说说，博客不用重新构建，下次请求就是新的。

第三，顺便把实例地址藏在了服务端，前端只见 /api/ech0.json，请求数也被代理端的去重逻辑收拢了。

数据怎么拿#

Ech0 对外的查询入口是 POST /api/echo/query，body 长这样：

1
{
2
  "page": 1,
3
  "pageSize": 100,
4
  "search": "",
5
  "tagIds": [],
6
  "sortBy": "created_at",
7
  "sortOrder": "desc",
8
  "dateFrom": 0,
9
  "dateTo": 0
10
}

返回 data.items 和 data.total。适配器做的事就是循环翻页拉全量，然后逐条转成动态系统的统一格式：

1
// fetchEchoPage 带三次重试，超时错误不重试——
2
// 上游响应慢的时候重试只会成倍拖长代理端点的等待时间
3
const { items, total: queryTotal } = await fetchEchoPage(apiUrl, {
4
  page,
5
  pageSize,
6
  search: "",
7
  tagIds: [],
8
  sortBy: "created_at",
9
  sortOrder: "desc",
10
  dateFrom: 0,
11
  dateTo: 0,
12
});
13
allEchos = allEchos.concat(items);
14
total = queryTotal || allEchos.length;
15
if (allEchos.length >= total || items.length < pageSize) break;

单条 Echo 转换的核心就是字段映射：content 丢给 marked 出 html，created_at 乘 1000 变毫秒，tags 从对象数组抽成名字数组，fav_count 透传成 likes，extension 原样透传。图片单独提出来放进 images 数组，交给现有的画廊组件。

Markdown 渲染用的 marked 实例和 Memos 适配器保持同一套配置：GFM 开、单换行转 <br>、链接强制新标签页打开。有个细节是图片渲染器置空——Markdown 里的图片语法不直接输出 <img>，而是用 lexer 把图片 token 摘出来塞进 images 数组，最后由画廊统一渲染，避免正文和画廊出现两张一样的图。

扩展卡片：透传，不要在服务端拼 HTML#

Ech0 的说说可以挂扩展：extension 字段带着 type 和 payload。六种类型的 payload 我逐个确认过：

第一反应是在适配器里直接把卡片拼成 HTML 塞进正文，零前端代码。但很快发现走不通：推文卡片靠 platform.twitter.com/widgets.js 渲染，脚本必须客户端加载；音乐卡片要调 Meting API 解析出真实音频地址。既然音乐和推文注定要写客户端代码，干脆六种卡片全部结构化透传，由一个 <dynamic-extension> 自定义元素在前端按 type 分发渲染。适配器保持干净，卡片样式走博客自己的主题变量，明暗模式白送。

其中 LOCATION 是个例外：它不渲染卡片，而是映射到卡片 meta 行的位置字段，用博客现成的位置样式展示。同一个信息渲染两遍没有意义。

音乐卡片的实现是中庸路线：先用和 Ech0 同源的规则解析出 server/type/id（网易云和 QQ 音乐两套正则），再去 Meting API 换封面、歌名、歌手和音频直链，原生 <audio> 播放。Ech0 站内那个带歌词滚动的完整播放器在说说卡片场景里太重了，而且博客本身已有全局音乐播放器，没必要重复建设。Meting 全挂或者音频加载失败，就降级成一个跳转链接卡。

踩到的坑#

服务端把 pageSize 钳到 100。 我一开始传 500 想一页拉完，响应看起来也正常，实际只回了 100 条。查源码才发现 QueryEchos 里有硬钳位：if queryDto.PageSize > 100 { queryDto.PageSize = 100 }。所以翻页循环必须老老实实按 100 一页走，终止条件用 total 和「短页」双重判断。

created_at 是 Unix 秒，不是毫秒。 直接 new Date(echo.created_at) 会得到 1970 年，年份筛选直接全军覆没。乘 1000 才对。

匿名请求拿不到私密说说。 echo/query 是 optional auth 的路由，不带 token 时服务端只返回公开内容。这对博客来说恰好是对的——但联调时如果发现某条说说在博客上不出现，先去 Ech0 检查它是不是设了私密，别急着查代码。

推文嵌入必须准备降级。 platform.twitter.com 在国内网络基本是玄学，能加载出来体验最好，加载不出来不能留白。我的做法是卡片渲染时才懒加载 widgets.js，起一个 6 秒的定时器，到点还没出现 iframe 就把整个卡片替换成 @username 的链接卡。Ech0 前端用的也是同一套思路，阈值直接抄了。

内嵌 HTML 是原样输出的。 marked 对正文里的 HTML 不做转义直接透传，Ech0 的内容里也确实会有 HTML 片段。这里没有做 sanitize——数据源是我自己的实例、我自己发的内容，信任边界是清晰的。但如果要做一个多人共用的方案，这一层必须补上，不能照抄。

原生点赞有限流。 PUT /api/echo/like/{id} 是公开接口，但服务端做了按 id 的幂等限流（每小时窗口内每个说说最多两次）。正常点一下完全够用，连续狂点会被拒——前端本来就有 localStorage 防重复，两层加起来正好。要说明的是 localStorage 只是软限制，清了浏览器数据就能再点，这类无身份方案的天花板就这样，够用。

数据源切换的优先级要定死。 配置里同时存在 ech0.enable 和 memos.enable 两个开关，判定链是 ech0 > memos > apiUrl。不搞混排——两个来源的说说排序、锚点、点赞语义都不一样，混在一起是自找麻烦。想换数据源，改一个布尔值就行。

收尾#

现在动态页的数据链路是：Ech0 实例 → 服务端适配器（marked 渲染 + 字段映射）→ /api/ech0.json（60 秒缓存）→ 前端卡片流。扩展卡片结构化透传给自定义元素渲染，点赞双轨制——Ech0 的说说用原生计数，本地和其他数据源继续走 star-vote，按钮长一个样。

整套东西都是配置驱动的，dynamicConfig.ech0.enable 一个开关决定生死，关掉就自动回落 Memos，不残留任何请求。代码在 kmoretti/Firefly 的 src/utils/ech0-adapter.ts 和 src/components/pages/dynamic/dynamic-extensions.ts，想抄作业的自取。

思路：一份配置说了算#

组件被压得很薄——配置决定「有什么」，运行时决定「显示什么、放哪」，CSS 只负责「藏」和「放」。

配置长这样：

1
export const contextMenuConfig: ContextMenuConfig = {
2
  enable: true,
3
  minWidth: 1024,
4
  // 在输入框/文本域/可编辑元素内右键时展示原版菜单
5
  showNativeInEditable: true,
6
  // 搜索选中内容用的搜索引擎，{query} 会被替换成选中文本
7
  searchEngine: "https://www.baidu.com/s?wd={query}",
8
  contextItems: {
9
    copySelection: true, // 有选中文本：复制
10
    searchSelection: true, // 有选中文本：搜索
11
    openLink: true, // 右键链接：新窗口打开
12
    copyLink: true, // 右键链接：复制地址
13
    openImage: true, // 右键图片：打开图片
14
    copyImage: true, // 右键图片：复制地址
15
  },
16
  items: [
17
    { action: "history-back" },
18
    { action: "history-forward" },
19
    { action: "reload", divider: true },
20
    { action: "music-toggle-play" },
21
    { action: "music-prev" },
22
    { action: "music-next" },
23
    { action: "music-volume" },
24
    { action: "toggle-theme", divider: true },
25
    { action: "reading-mode" },
26
    { action: "back-to-comment" },
27
    { action: "back-to-top" },
28
    { action: "copy-url" },
29
  ],
30
};

items 里每项是一个内置 action，divider 控制分组分隔线。想加外链或自定义行为，用 action: "custom" 配 link 或者一段函数体，图标不指定时组件会按 item.icon ?? 默认图标 兜底。类型在 src/types/contextMenuConfig.ts 里收着，配置写错了构建期就能报出来。

早期版本试过直接在模板里堆菜单节点，结果改个顺序要动模板，加一项要动模板，上下文显隐逻辑还散落在各处。收进配置之后，这些痛苦全消失了——这也是我坚持「配置驱动」最大的理由：改配置的心智负担和改组件完全不是一个量级。

拦截：先想清楚什么时候「不管」#

写自定义菜单，最先要想清楚的不是怎么接管，而是什么时候不管。放行条件比拦截条件好写——前者每条都是独立的，后者要把所有反例串成一长串否定。

我的放行条件就三条：

1
document.addEventListener("contextmenu", (e) => {
2
  if (e.ctrlKey) return; // Ctrl+右键：放行原版菜单
3
  if (window.innerWidth < minWidth) return; // 窄屏：没这个交互
4
  const target = e.target instanceof Element ? e.target : null;
5
  const isFormField =
6
    !!target?.closest("input, textarea, select") ||
7
    (target instanceof HTMLElement && target.isContentEditable);
8
  if (isFormField && showNativeInEditable) return; // 输入框里：原版菜单更好用
9
  e.preventDefault();
10
});

流程画出来是这样：

另外两个工程细节：绑定前先检查 window.__fireflyContextMenu 防止重复挂监听（Astro 页面脚本在某些跳转场景会重新执行，不设防会越绑越多）；关菜单的途径比开菜单多得多——点遮罩、Esc、窗口失焦、滚动、resize、路由跳转全都要收尾，其中滚动监听用 capture 加 passive 就够了，反正目的只是把菜单收起来。

这段代码里埋着本篇坑二的祸根，先按下不表。

上下文感知：两组标记类#

探测上下文，说穿了就是把一堆布尔判断折算成根元素上的类名：

1
// 右键位置：点在哪
2
menu.classList.toggle("show-selection", hasSelection);
3
menu.classList.toggle("show-link", !!link);
4
menu.classList.toggle("show-image", !!img);
5
// 页面能力：这页有什么
6
menu.classList.toggle("ctx-has-music", typeof music()?.getState === "function");
7
menu.classList.toggle("ctx-has-comments", !!document.getElementById("post-comments"));
8
menu.classList.toggle("ctx-has-reading", isReadingModeAvailable());

两组前缀语义不同：show-* 描述「右键点在哪」，每次打开都重新探测；ctx-has-* 描述「这个页面有什么能力」。CSS 那边配合很机械——扩展项默认藏起来，标记类出现才放行：

1
#context-menu
2
    .ctx-need-selection
3
        display: none
4
    &.show-selection
5
        .ctx-need-selection
6
            display: flex

注意第三行的 &，它是坑一的主角，后面细说。

能力探测里有几个值得展开的点：

音乐播放器是 Svelte island，把实例挂到 window.__fireflyMusic 上。但 island 水合有时机问题——页面刚开就右键，这个全局对象可能还不存在；就算存在了，也得确认它真能用。所以探测写成 typeof getState === "function" 而不是简单判存在：对象在、方法还没挂上的窗口期里，单纯判存在会误报。

评论区探测最朴素：document.getElementById("post-comments") 找得到节点就有评论。因为评论区只渲染在文章页，这一行天然把「文章页」的语义带上了，不用再判断路径。

阅读模式的判断和站内阅读模式按钮共用同一个谓词：路径在 /posts/ 下且视口够宽。两处逻辑一个标准，避免「按钮说能进、菜单里却没有」的尴尬。

定位：先隐身，量完再现身#

弹出位置看着五分钟搞定，实际有个经典陷阱：菜单贴近屏幕右缘时，音量条那组二级菜单会探出屏幕。等渲染出来再发现溢出，视觉上就是闪一下。

做法是显示之前先隐身量尺寸：

1
const SUBMENU_SPACE = 240; // 给二级菜单留的空间
2

3
menu.classList.remove("hidden", "ctx-flip-left");
4
menu.style.visibility = "hidden";
5
const rect = menu.getBoundingClientRect();
6
const flipLeft = x + rect.width + SUBMENU_SPACE > vw;
7
if (flipLeft) menu.classList.add("ctx-flip-left");
8
menu.style.visibility = "";

关键在用 visibility: hidden 而不是 display: none——前者占据布局、能量出真实尺寸，后者量出来全是 0。量完该翻转就加 ctx-flip-left 让二级菜单朝左开，最后再去掉隐身。整个过程在同一帧内完成，肉眼看不到闪。

明暗适配#

这部分反而最省心：颜色全部走站内 CSS 变量，var(--card-bg)、var(--btn-regular-bg-hover) 这类，主题切换时变量一变菜单自动跟上。唯一手写的是深色模式下的文字颜色，站内惯例是 :global(.dark) 里配一个半透明白，照抄即可。

踩坑清单#

下面按踩到的顺序讲三个坑。共同点是：每一个的现象都在暗示「代码是对的」，而真凶全在别处。

1
#context-menu[data-astro-cid-mdguodk3] .ctx-has-music .ctx-need-music {
2
  display: flex;
3
}

1
<div id="context-menu" class="ctx-has-music" data-astro-cid-mdguodk3>
2
  <div class="ctx-need-music">音量</div>
3
</div>

1
#context-menu
2
    .ctx-has-music
3
        .ctx-need-music
4
            display: flex

1
#context-menu
2
    &.ctx-has-music
3
        .ctx-need-music
4
            display: flex

1
#context-menu[data-astro-cid-mdguodk3].ctx-has-music .ctx-need-music {
2
  display: flex;
3
}

1
if (isFormField && !showNativeInEditable) return; // [!code --]
2
if (isFormField && showNativeInEditable) return; // [!code ++]

写在最后#

右键菜单是典型的「平时没人看，写起来细节不少」的功能。回头看，思路层面就三件事：放行条件先于拦截条件想清楚、状态折算成标记类交给 CSS、量完尺寸再显示。剩下的坑大多出在源码和运行时之间的那些层上——Stylus 会编译选择器，Astro 会改写选择器，preview 伺服的是历史产物。每一层都在帮忙，也都在让你离真相远一步。

主题完整代码在这里：

swpp 是什么：规则驱动的缓存#

swpp（npm 包叫 swpp-backends，文档在 https://swpp.kmar.top/）跟 Workbox 最大的区别在心智模型上。Workbox 默认生成一份资源清单，把「要不要缓存、什么时候过期」交给一套运行时逻辑；swpp 反着来——默认不缓存，每个请求进不进缓存、进了怎么失效，都由一段显式的判定函数说了算。

1
// 返回 false —— 不缓存，每次照常走网络
2
// 返回 -1  —— 永久缓存，且不参与 swpp 的版本更新检查
3
function matchCacheRule(url: URL): number | false;

1
const CACHE_NAME = "kmarBlogCache";
2
const UPDATE_JSON_URL = "swpp/update.json";
3
const VERSION_PATH = "https://id.v3/"; // 版本元数据以特殊 key 存在 Cache Storage
4
const INVALID_KEY = "X-Swpp-Invalid";  // 失效标记，打在待更新的缓存 entry 上
5
const UPDATE_CD = 600000;              // 两次版本检查的最小间隔（10 分钟）

白名单怎么定：一份判断，两端执行#

规则是协议的核心，所以它不能只活在浏览器里。swpp 要求把判定函数写进配置，让 Node 端（构建期算增量） 和 浏览器端（运行时真拦截） 各有一份实现，这就是 defineCrossDep 的由来：

1
defineCrossDep({
2
  matchCacheRule: {
3
    // 浏览器端实现：swpp 通过 toString() 将此函数序列化进 sw.js
4
    runOnBrowser: (url: URL): number | false => {
5
      const { pathname } = url;
6
      if (url.origin !== self.location.origin) return false; // 跨域永不缓存
7
      if (pathname.startsWith("/api/")) return false;        // 动态接口不缓存
8
      if (pathname.startsWith("/_astro/") || pathname.startsWith("/pagefind/")) {
9
        return -1; // 文件名即版本，永久缓存
10
      }
11
      if (pathname.endsWith("/") || pathname.endsWith(".html")) return -1;
12
      if (/\.(?:html|woff2?|ttf|otf|png|jpe?g|webp|avif|svg|gif|ico)$/i.test(pathname)) {
13
        return -1; // 字体、图片等静态媒体
14
      }
15
      return false;
16
    },
17
    // Node 端实现：构建时计算增量更新规则，允许复用模块作用域
18
    runOnNode: (url: URL) => matchCacheRuleByUrl(url, SITE_ORIGIN),
19
  },
20
});

具体到我们这个站，白名单就三条线：

1. 跨域直接放行。友链头像、第三方图床这些资源，SW 管不着也不该管
2. /_astro/* 与 /pagefind/* 给 -1。这些是构建产物，文件名带内容哈希，命中即永远命中
3. HTML 与静态媒体给 -1。媒体靠哈希、靠 CDN 头；HTML 不靠哈希，靠的是上面那套版本号机制来失效

构建编排：注入与产物#

swpp-backends 的构建期产物是固定的：站点根目录的 sw.js，加 swpp/ 目录下的 update.json、tracker.json、dom.js。其中 dom.js 是官方提供的前端更新接收脚本：页面加载后如果 SW 已接管，就发个 update 信号；收到「有更新」的消息后，配合 Pjax 先热替换改动的 <script>/<link>，再 location.reload()——刷新前写 sessionStorage 标记，防止 reload 死循环。

剩下还有两件事得自己编排，我写在 scripts/build-swpp.ts 里：

第一，把注册脚本注入每个 HTML。 位置和 swpp CLI 保持一致：<script>(${registry})()</script> 紧跟 <head> 开标签之后，<script defer src="/swpp/dom.js"> 贴在 </head> 之前：

1
const registry: string = runtimeData.domConfig.read("registry");
2
const registryScript = `<script>(${registry})()</script>`;
3
const domScript = `<script defer src="/swpp/dom.js"></script>`;
4

5
// 幂等：已包含 dom.js 引用说明注入过，跳过
6
if (html.includes(DOM_JS_URL)) continue;

第二，留一条撤退路线。 配置里 enable: false 时不生成 swpp 产物，而是往 sw.js 写一段「自杀 SW」：activate 时清空全部缓存、注销自身、刷新所有受控页面。想下掉这个功能，改一行配置、重新构建部署，老访客下次打开就自动回归无 SW 状态，不用等任何 TTL。

出问题点#

流程捋顺了，下面这些坑是实际集成时一个一个踩出来的，按折磨程度排序。

1
const files = await builder.buildFiles();
2
// saveFiles 对已存在的文件会抛 file_duplicate，先清掉上次构建可能遗留的产物
3
await Promise.all(
4
  files.map((file) => fs.rm(file.path.absPath, { force: true })),
5
);
6
await builder.saveFiles();

1
const openTag = /<head[^>]*>/i.exec(html);
2
if (!openTag) return null;
3
const closeStart = html.toLowerCase().lastIndexOf("</head>");
4
if (closeStart < openEnd) return null;

1
⚠ Skipped ${file}: no <head> found

1
/sw.js
2
  Cache-Control: no-cache, must-revalidate
3
/swpp/*
4
  Cache-Control: no-cache, must-revalidate
5
/_astro/*
6
  Cache-Control: public, max-age=31536000, immutable

写在最后#

回头看，swpp 真正的门槛不在配置，而在心智转换：它默认什么都不缓存，规则返回值的每个分支都要你回答「这份资源变了以后，靠什么失效」——靠文件名哈希、靠版本号机制，还是根本不缓存。把这个问题想清楚，剩下的实现都是水到渠成；想不清楚，就会在「怎么不生效」「怎么老不更新」之间反复横跳。

集成期的坑也大多长在这个心智缝隙里：序列化的函数没有闭包、永久缓存不等于永不变、HTTP 头能废掉版本检查、SW 的验证天然慢半拍。每一个都是「某一层帮你做了件事，但没告诉你」。

swpp 本身是个很克制也很完整的方案，作者 kmar 的文档写得值得通读，仓库在 EmptyDreams/swpp-backends。博客这边从配置到构建编排的完整实现都在：

数据：frontmatter 里躺一个字段#

没搞单独的 JSON 文件，也没上云端函数，直接在内容集合的 schema 里加了个可选字段：

1
const postsCollection = defineCollection({
2
  loader: glob({ pattern: "**/*.{md,mdx}", base: "./src/content/posts" }),
3
  schema: z.object({
4
    title: z.string(),
5
    published: z.date(),
6
    description: z.string().optional().default(""),
7
    aiSummary: z.string().optional().default(""),
8
    // ...
9
  }),
10
});

字段可选、默认空串，没生成摘要的文章 entry.data.aiSummary 就是空串，页面判断一下就能决定显不显示。

为什么存 frontmatter：

• 跟着文章走，换主题、迁移仓库，摘要不会丢
• 构建期 astro:content 直接能读到，不需要额外请求

生成脚本：一次调用，写回文件#

脚本是一个交互式 CLI，pnpm ai-summary 跑起来长这样：

1
[AI-SUMMARY] 可处理的文章：
2

3
  1. AI 文章摘要：从生成脚本到打字机组件的折腾记录
4
  2. 国内外分流实践：Cloudflare + EdgeOne 双端部署的踩坑记录 （已有摘要，将重写）
5

6
输入要处理的序号（多选用逗号分隔，如 1,3,5）：

已生成过的文章会标「已有摘要，将重写」，想重写哪篇直接再选一次就行。draft 状态和带密码的文章直接跳过，不列出。

1
function parseEnvFile(content: string): EnvVars {
2
  const vars: EnvVars = {};
3
  for (const rawLine of content.split(/\r?\n/)) {
4
    const line = rawLine.trim();
5
    if (!line || line.startsWith("#")) continue;
6
    const eq = line.indexOf("=");
7
    if (eq <= 0) continue;
8
    const key = line.slice(0, eq).trim();
9
    let value = line.slice(eq + 1).trim();
10
    if (
11
      (value.startsWith('"') && value.endsWith('"')) ||
12
      (value.startsWith("'") && value.endsWith("'"))
13
    ) {
14
      value = value.slice(1, -1);
15
    }
16
    vars[key] = value;
17
  }
18
  return vars;
19
}

1
const response = await fetch(
2
  `${baseUrl.replace(/\/$/, "")}/chat/completions`,
3
  {
4
    method: "POST",
5
    headers: {
6
      "Content-Type": "application/json",
7
      Authorization: `Bearer ${apiKey}`,
8
    },
9
    body: JSON.stringify({
10
      model, // 默认 Qwen/Qwen3-8B
11
      messages: [
12
        { role: "system", content: PROMPT },
13
        { role: "user", content: `文章标题：${title}\n\n正文内容：${body}` },
14
      ],
15
      temperature: 0.5,
16
      max_tokens: 300,
17
      stream: false,
18
      enable_thinking: false,
19
    }),
20
    signal: AbortSignal.timeout(60_000),
21
  },
22
);

1
function upsertAiSummary(raw: string, summary: string): string {
2
  const normalized = raw.replace(/\r\n/g, "\n");
3
  const fmMatch = normalized.match(/^---\n([\s\S]*?)\n---\n?/);
4
  const lines = fmMatch[1].split("\n");
5
  let replaced = false;
6
  const output: string[] = [];
7
  for (const line of lines) {
8
    if (/^aiSummary\s*:/.test(line)) {
9
      output.push(`aiSummary: ${toYamlDoubleQuoted(summary)}`);
10
      replaced = true;
11
      continue;
12
    }
13
    output.push(line);
14
  }
15
  if (!replaced) output.push(`aiSummary: ${toYamlDoubleQuoted(summary)}`);
16
  return `---\n${output.join("\n")}\n---\n${normalized.slice(fmMatch[0].length)}`;
17
}

1
[AI-SUMMARY] 处理完成汇总：
2
  成功 1 篇
3
    - AI 文章摘要：从生成脚本到打字机组件的折腾记录
4
  失败 0 篇

展示：打字机动画，和一场折叠裁切的血案#

1
// SSR 先渲染完整文本，水合后再启动动画，避免空白与布局跳动
2
let displayed = $state(summary);

1
let isFolded = $state(true); // 一开始折叠
2
// [!code --]
3
let isFolded = $state(summary.length > foldThresholdChars); // 只有超阈值才折叠
4
// [!code ++]

1
<Icon icon="material-symbols:smart-toy-outline" style="font-size: 13px" />

接入：加密文章不放#

在文章页 [...slug].astro 里，正文之前渲染：

1
{entry.data.aiSummary && aiSummaryConfig.enable && (
2
  <PostAiSummary
3
    client:visible
4
    summary={entry.data.aiSummary}
5
    label={aiSummaryConfig.label}
6
    badge={aiSummaryConfig.badge}
7
    typingSpeedMs={aiSummaryConfig.typingSpeedMs}
8
    foldThresholdChars={aiSummaryConfig.foldThresholdChars}
9
  />
10
)}

加密文章走的是另一个分支（EncryptedPost），那里不渲染摘要——不然密码锁着的内容先被摘要剧透完了。

踩坑清单#

按时间顺序：

1. dev 服务器内容不更新：改完 frontmatter 或 schema，旧的 dev 进程内存里的内容存储感知不到变更，页面上死活没有卡片。折腾半天，重启 dev server 就好了，不用删缓存。
2. CI 的 biome 检查红了：本地 pnpm lint 带 --write 会自动修格式，CI 里跑的是 biome ci，只检查不修复。Svelte 的 <script> 块内容要求顶格，本地格式化完没事，推送上去就红了。写完整跑一遍 pnpm exec biome ci ./src 再推。
3. 折叠裁切：上面说的，短摘要被裁且没有展开按钮，血的教训。
4. 离线图标：别看到 material-symbols:xxx 就觉得有，先确认它在 icons-data.json 里。

写在最后#

成本方面，Qwen3-8B 很便宜，一次摘要花不了几分钱，生成一次能管到文章大改。静态摘要的取舍也简单：确定性强、无网络依赖、构建期就有；代价是文章改版后摘要可能过时——重跑一次脚本覆盖就行。

这套东西就长在这个博客里，想照着搬的可以看仓库：

最终架构#

先说清楚域名关系，这是后面所有配置的基础：

• kemeow.top —— 根域名，DNS 托管在 Cloudflare
• b.kemeow.top —— 博客主站，Cloudflare Pages
• cn.b.kemeow.top —— 国内入口，EdgeOne Pages

整体流程是这样的：

1
PagesCMS 改文章
2
  → push master
3
  → GitHub Actions 构建（一次）
4
  → 同时部署到 Cloudflare Pages + EdgeOne Pages
5
  → 国内用户访问 b.kemeow.top，302 跳到 cn.b.kemeow.top
6
  → 其他地区用户正常访问 Cloudflare

GitHub Actions：一次构建，双端部署#

EdgeOne Pages 有一个坑：平台侧每个月只有 500 次构建额度。如果你让 EdgeOne 自己连仓库构建，文章一多、推送一频繁，额度很快就见底。

所以正确姿势是：工作流里自己构建，然后把产物直接推上去（EdgeOne 叫 Direct Upload / 直接上传）。

工作流改造很简单，在原有的 Cloudflare 部署步骤后面再加一步：

1
- name: Deploy to EdgeOne Pages
2
  env:
3
    EDGEONE_API_TOKEN: ${{ secrets.EDGEONE_API_TOKEN }}
4
  run: npx --yes edgeone pages deploy ./dist -n "$EDGEONE_PAGES_PROJECT" -t "$EDGEONE_API_TOKEN" -e production

PagesCMS 的工作方式完全不变，还是 push master 触发工作流，只是多了一个部署目标。

最大的坑：备案#

这是整套方案里绕不开的一道坎。

EdgeOne Pages 对自定义域名有一条硬性规定：

• 加速区域选 中国大陆可用区 或 全球可用区（含中国大陆） → 绑定自定义域名必须 ICP 备案
• 没备案 → 只能选 全球可用区（不含中国大陆）
• 选了这个区域，默认分配的 Pages 域名在国内访问大概率返回 401，所以必须绑自己的自定义域名

所以情况就是：

还有个细节：如果你的域名在别家已经备案过，在腾讯云这边用，需要做「接入备案」，不是重新备案一遍，但也要走流程。

EdgeOne 侧配置#

1. 创建项目，方式选直接上传，加速区域选「全球可用区（不含中国大陆）」
2. 手动先部署一次（上传 dist），确认项目可用
3. 域名管理里添加 cn.b.kemeow.top，按提示做归属校验
4. 开启 HTTPS，然后开启强制 HTTPS
   • HTTP → HTTPS 的重定向方式选 301（永久跳转，符合语义）
5. 创建 API Token，权限包含 Pages 部署
6. 把 Token 配到 GitHub 仓库 Secrets，名字叫 EDGEONE_API_TOKEN

Cloudflare 侧配置#

1
类型：CNAME
2
名称：cn.b
3
目标：（EdgeOne 控制台提供的 CNAME 值）
4
代理状态：DNS only（灰色云朵）

1
(ip.geoip.country eq "CN" and http.host eq "b.kemeow.top")

1
concat("https://cn.b.kemeow.top", http.request.uri.path)

踩坑汇总#

按我实际踩的顺序整理一下，全是真金白银换来的：

1. 项目建完发现区域选错，只能删了重建 —— 没备案别选含中国大陆的区域，选完改不了
2. 默认 Pages 域名国内 401 —— 未备案区域下，必须绑自定义域名，别指望默认域名能用
3. 把 API Token 写进代码 —— 绝对不要。放 GitHub Secrets，工作流里通过 ${{ secrets.EDGEONE_API_TOKEN }} 引用
4. CNAME 名称填成 cn —— 正确是 cn.b，指向 cn.b.kemeow.top
5. DNS 开了 Cloudflare 代理 —— 必须 DNS only，否则双重代理、证书错乱、重定向循环都可能来
6. 想用 URL 重写规则代替重定向 —— 不行，重写不改变浏览器地址栏，跨域跳转只能走 Redirect Rules
7. 匹配方式选成”所有传入请求” —— 会把全球所有地区都跳过去，必须用自定义筛选表达式限定国内 IP
8. 301 用太早 —— 浏览器缓存跳转结果，调试期务必用 302

写在最后#

这套方案做完，代码侧的改动其实很小，大头全在控制台配置。而且最后要诚实地说一句：没备案的话，EdgeOne 没有国内节点，分流只是给国内用户换了一条线路，能不能更快取决于 EdgeOne 对国内的连通性，未必有质的飞跃。

如果你的诉求是”国内访问必须快”，那还是老老实实备案，走含中国大陆的区域。如果只是想要个双线冗余，那这套方案完全够用。

权当给同样在折腾的人一个参考。