https://mstzuomu.space/ 左沐の手册 热爱是拯救无趣人生的唯一途径 2026-10-05T00:00:00.000Z 陌殊途左沐 Firefly v6.16.8 https://mstzuomu.space/posts/azuma.zuomu-blog-19/ 导航栏 UI 改造全记录：卡片边框、悬浮胶囊、三段收拢与 PC 收拢态快捷面板（附完整复现指南） 2026-10-05T00:00:00.000Z 2026-10-05T00:00:00.000Z 左沐 一次连续迭代的完整复盘——从卡片边框体系、悬浮胶囊导航，到三段结构拆分、下滑收拢动画，再到 PC 收拢态汉堡的控件快捷面板与"行点击原位弹卡"的两处根因修复，追加 PC 搜索控件图标化与收拢动画卡顿的逐帧诊断修复。每个批次改了哪些文件、为什么这么改、踩了哪些坑（CSS 层序、正圆公式、包含块、Vite 缓存、Playwright headless 动画冻结），附 git 重放与手工重做两条复现路径及验收清单

导航栏 UI 改造全记录：卡片边框、悬浮胶囊、三段收拢与 PC 收拢态快捷面板（附完整复现指南）#

本文记录 Firefly 博客一次连续的导航栏/卡片 UI 改造：六个已合并提交 + 一条被回滚的实验分支，时间跨度 2026-10-04 至 2026-10-05。写给两类读者：

  • 未来的维护者（包括新会话的 AI 助手）：读完应知道每一批改了什么、为什么、当时的验证结论与未尽事项；
  • 希望复现的访客：文末给出两条复现路径——git 一次重放，或按批次手工重做，全部关键代码在正文中可照抄。

〇、概览：最终形态与提交清单#

改造完成后的导航栏最终形态：

  1. 卡片边框体系：开启 enable-card-border 后，全站卡片与导航栏是 2px 纯黑（暗色自动切白）边框，粗细可在显示设置面板用 0–5px 滑块实时调节，持久化到 localStorage。
  2. 悬浮胶囊导航栏：高度从 4.5rem 压扁到 4rem，圆角 9999px，整条导航栏通过 wrapper 的 padding-top: 0.75rem 悬浮于顶部之下，间隙条点击穿透。
  3. 三段独立胶囊 + 下滑收拢动画：导航栏拆为左（logo/站名）、中（菜单）、右（控件）三个独立胶囊；向下滚动超过 80px 时左右两段帘式收起为正圆，中段菜单常显不收；上滑或回顶恢复。
  4. PC 收拢态快捷面板：收拢后右段只剩一个汉堡按钮（PC 端此时才显示），点击弹出「控件快捷面板」——搜索/音乐/播放/显示设置/亮暗五行；点任意行导航栏保持收拢，原控件的子卡片在原位弹出。移动端汉堡仍开导航链接菜单，两菜单互斥。
  5. 移动端菜单样式可配置：siteConfig.nav.mobileMenuStyle 支持 "card"（旧版浮层卡片，默认）与 "drawer"（全屏抽屉）。
  6. PC 搜索图标化：PC 端导航栏不再内嵌搜索输入框，与移动端统一为一个搜索图标；点击弹出搜索卡片，打开后光标自动落入卡内输入框。
  7. 收拢动画卡顿修复：PC 右段收拢成圆不再「弹一下→冻结→猛缩」——汉堡由 display 切换改为 width 连续过渡，控件组 max-width 去掉 30rem 死区；亮暗图标切主题时交叉淡化（第十三节）。
提交日期内容规模
7468034110-04卡片边框默认 2px 纯黑，显示设置新增边框粗细滑块11 文件 +107/−4
2a00a60210-04导航栏改为悬浮胶囊样式并压扁高度4 文件 +33/−25
f6b3d06010-04导航栏接入卡片边框，边框色亮黑暗白跟随主题2 文件 +16/−12
b7cce68210-05三段拆分、收拢动画、移动菜单配置、PC 快捷面板（含”原位弹卡”修复）17 文件 +500/−157
04197b8210-05PC 搜索收成图标按钮，输入统一走搜索面板（第十二节）4 文件 +37/−72
d7d3b62c10-05修复 PC 收拢动画卡顿（第十三节）2 文件 +29/−20

基线提交为 020533ee（其后是 74680341），全部改动可用 git diff 020533ee..d7d3b62c 一次性查看。

另有一次液态玻璃（liquid glass）导航栏原型：做出可运行版本后按要求整体回滚删除（含 index.html 原型与 banner-home.css 改动），未进入任何提交，仅在此备忘——若将来重做，需从零开始，git 历史里没有可恢复的痕迹。

一、环境与验证基线#

  • 技术栈：Astro 7 + Svelte 5 + TypeScript，包管理 pnpm（preinstall 强制），样式为 Tailwind v4 + 分层 CSS（navbar.css、main.css 等以 @import 进主入口，未分层）。
  • 本地开发：pnpm dev（默认 http://localhost:4321，绑 ::1，测试用 localhost 不要用 127.0.0.1）。
  • 检查三件套（每批改完必跑）：
Terminal window
1
npx biome check <改动文件>   # 格式/静态检查（只读，不用 pnpm lint——会波及无关文件）
2
pnpm type-check               # tsc --noEmit --isolatedDeclarations
3
pnpm check                    # Astro 诊断；基线 = 12 个存量错误（anime.astro 11 + vndb.astro 1）

pnpm check 的验收标准是「仍为 12，无新增」，不是零错误。

  • 验证分工：AI 负责代码层与自动化断言；视觉验收由人完成。自动化用 Playwright（本文第八节列出它在本项目的三个特有坑）。

二、批次一：卡片边框体系（74680341）#

目标#

把「卡片边框」从主题色细分线（--line-divider，1px 半透明）改为可调粗细的纯黑描边，默认 2px，并在显示设置面板提供滑块。

改动明细#

1. src/styles/main.css — 三条边框规则统一接变量：

1
/* 开启边框和阴影效果时的样式（宽度由 --card-border-width 控制，默认 2px，可在显示设置面板调节） */
2
.enable-card-border .card-base {
3
    @apply transition-all duration-300 border border-black shadow-xs;
4
    border-width: var(--card-border-width, 2px);
5
}
6
/* .card-base-transparent、.btn-card 同理，共三处 */

2. src/utils/setting-utils.ts — 新增四个函数（+51 行）：getDefaultCardBorderWidth() 返回 2；getStoredCardBorderWidth() 读 localStorage.cardBorderWidth 并 clamp 到 0–5；applyCardBorderWidthToDocument(width) 写 document.documentElement.style.setProperty("--card-border-width", ...)；setCardBorderWidth(width) 持久化 + 应用。

3. src/layouts/Layout.astro — 首屏内联脚本（FOUC 防护）中追加：读 localStorage.cardBorderWidth，校验 0–5 后在解析 HTML 期间就把 --card-border-width 写到 <html> 上，避免滑块值加载后闪一下默认边框。

4. src/components/controls/DisplaySettingsIntegrated.svelte — 「卡片样式」区块新增滑块（+36 行）：

1
let cardBorderWidth = $state(getStoredCardBorderWidth());
2
// ...
3
<div class="rounded-md bg-(--btn-regular-bg) p-2">
4
    <div class="flex items-center justify-between mb-1">
5
        <span class="text-xs font-medium ...">{i18n(I18nKey.cardBorderWidth)}</span>
6
        <span class="text-xs ...">{cardBorderWidth}px</span>
7
    </div>
8
    <input type="range" min={0} max={5} step={0.5} value={cardBorderWidth}
9
        oninput={(e) => { cardBorderWidth = Number(e.currentTarget.value); }}
10
        class="slider w-full overlay-slider" />
11
</div>

同时接入三处状态机：$effect(() => setCardBorderWidth(cardBorderWidth)) 实时生效；cardSettingsIsDefault 加入宽度默认判断；resetCardSettings() 恢复默认宽度并 requestAnimationFrame(refreshAllRangeProgress) 刷新滑块进度条。

5. i18n — I18nKey.cardBorderWidth 键 + 7 个语言文件（en/ja/ko/ru/zh_CN/zh_TW…）各加一行，中文为「边框粗细」。

复现要点#

按上面 1→5 顺序做即可。注意 clampNumber 是 setting-utils.ts 里已有的工具函数，直接复用；滑块 step={0.5}，但正圆公式依赖的 CSS 变量能接受小数。

三、批次二：悬浮胶囊化（2a00a602）#

目标#

导航栏从「贴顶方角条」改为「悬浮圆角胶囊」，并整体压扁一档。

改动明细#

1. 高度 4.5rem → 4rem（三处 + 联动）：

  • HeaderTopRow.astro：fixed 态类名 h-18 → h-16；
  • Navbar.astro：容器 h-18 → h-16；
  • layout-base.css：#top-row 的 sticky/fixed 固定高度 4.5rem → 4rem（两处 + 移动端一处），banner 首页占位 calc(var(--banner-height-home) - 4.5rem) → - 4rem。

2. 圆角全模式统一 9999px（navbar.css）：bar 本体、#navbar 阴影载体、以及 semi/semifull/亮暗各壁纸态的 !important 圆角覆盖，全部由 0 0 0.75rem 0.75rem 改为 9999px。

3. 悬浮间距放 wrapper：

1
/* 间距放在 wrapper 的 padding-top 而非 bar 的 margin：
2
   navbar-hidden 的 -translate-y-full 按 wrapper 自身高度平移，
3
   padding 计入高度，下移多少就能完整隐藏多少，不会在顶部残留 12px 边缘。
4
   pointer-events：间隙条是 wrapper 的 padding，整体设为 none 让点击穿透到下层，
5
   bar 自身设回 auto（未分层选择器优先于 Tailwind 工具类） */
6
#navbar-wrapper {
7
    padding-top: 0.75rem;
8
    pointer-events: none;
9
}

配套给 bar（#navbar>div）加 pointer-events: auto——否则悬浮间隙条会把点击吃掉，导航栏上的按钮和下拉面板全部点不到。这两行是一对，必须同时改。

4. 移动端成形（<768px）：组件里 top-row 是 px-0，bar 会贴屏幕边缘，胶囊两端没留空就不成形——删掉旧的「移动端去圆角」规则，改为给 #top-row 补 padding-left/right: 0.75rem。

为什么间距不能用 margin#

见上面代码注释：-translate-y-full 的隐藏动画按 wrapper 自身高度平移，margin 不计入 wrapper 高度，会残留一条边；padding 计入，隐藏才干净。

四、批次三：亮黑暗白边框（f6b3d060）#

目标#

纯黑边框在暗色主题下不可见，需要亮色纯黑、暗色纯白地跟随主题，并让导航栏与卡片共用同一套边框变量。

改动明细#

1. src/styles/variables.styl — 亮暗两段各加一个变量：

1
/* 亮色段 */
2
--card-border-color: black
3
/* 暗色段 */
4
--card-border-color: white

2. src/styles/main.css — 三处卡片规则 border-black 改 border-(--card-border-color)；导航栏规则改为：

1
.enable-card-border #navbar > div:not(.absolute) {
2
    @apply transition-all duration-300 border shadow-xs;
3
    /* 与卡片边框同款：颜色跟随 --card-border-color（亮黑/暗白），宽度跟随 --card-border-width 滑块
4
       （!important 压过 navbar.css 的未分层 1px 透明边框） */
5
    border-color: var(--card-border-color) !important;
6
    border-width: var(--card-border-width, 2px) !important;
7
}

3. 删除两组「防闪现」旧规则：原实现里 banner 玻璃态与 fullscreen 模式各有 border: none !important，目的是防止切页瞬间边框从无到有闪一下。边框改为刻意设计的常驻元素后，「闪现」的定义变了——常驻即无闪现，过渡期由 .is-wallpaper-transitioning 的透明边框规则兜底。因此删除 banner 的 border: none 组，fullscreen 只保留 outline: none。删除行全部有意，复现时不要当作误删恢复。

本批次踩坑：Vite dev 编译缓存丢更新#

现象：改了 variables.styl 暗色白值 + main.css 导航栏引用，磁盘文件正确，浏览器里暗色边框仍是黑的，刷新无效。

根因：dev server 同一轮里各写入了两次文件，Vite watcher 只吃到了每个文件的第一次写入，第二次的失效事件丢失——served 编译产物残缺。

处置：重存文件踢一脚强制重编译（或重启 pnpm dev）。诊断手段：curl http://localhost:4321/src/styles/xxx 直接取模块编译产物，对比磁盘源码。

结论：纯本地 dev 现象。Cloudflare 构建从磁盘全新编译，线上不复现。以后遇到「CSS 改了不生效/只生效一半」，先重启 pnpm dev。

五、批次四：三段拆分与下滑收拢动画（b7cce682 上半）#

5.1 结构：三段独立胶囊#

src/components/layout/Navbar.astro：

  • #navbar 改为 grid grid-cols-[1fr_auto_1fr]（类名里保留 z-50 等），三个直接子 div 各带 .navbar-seg：
    • .navbar-seg-left（justify-self-start）：logo + 站名，站名包一层 <span class="navbar-title-text">；
    • .navbar-seg-center（col-start-2，hidden lg:flex）：菜单 DropdownMenu 列表，是否居中由 siteConfig.nav.menuAlign 决定；
    • .navbar-seg-right（col-start-3 justify-self-end）：内含 .navbar-right-controls 控件组（搜索、音乐、播放、显示设置、亮暗 + 各浮层面板）与组外的汉堡按钮 #nav-menu-switch。
  • 原先「面板挂在 body 级 / 控件散放」的结构改为面板随控件进右段（音乐面板等成为控件组子元素）。

src/styles/navbar.css：

  • 全部原 #navbar>div 表面规则（背景、透明边框、毛玻璃 ::before）retarget 为 #navbar>.navbar-seg，并在其上补一行注释掉的 position: relative——它同时是内部浮层面板的定位包含块（后文第八节第 3 条会再用到）；
  • sticky 滚动投影从元素 box-shadow 移到 ::after 伪元素（各壁纸态规则会覆盖元素级阴影，伪元素不参与那场竞争）；
  • 移动端 top-row 补左右留边（承接批次二第 4 条）。

src/styles/main.css：31 处选择器从 >div retarget 到 >.navbar-seg；边框规则同步接 --card-border-color / --card-border-width。

src/styles/layout-base.css：top-row 高度相关 calc 基准同步为 4rem。

5.2 动画：下滑收拢为正圆#

触发（src/utils/scroll-utils.ts）——把滚动方向 delta 从 dynamic 分支上提为共用计算：

1
const delta = scrollTop - lastScrollTop;
2
lastScrollTop = scrollTop;
3


4
// 三段胶囊收拢：向下滚动且超过 80px 时左右段收成圆形，上滑或回顶恢复
5
if (navbarElement) {
6
    operations.push(() => {
7
        navbarElement.classList.toggle("navbar-collapsed", scrollTop > 80 && delta > 0);
8
    });
9
}

语义：收拢 = 向下滚且 >80px；恢复 = 上滑或回顶。中段菜单永不参与。

切页清态（src/utils/swup-transitions.ts）：astro 换页钩子里 navbar.classList.remove("navbar-collapsed")——收拢态不跨页残留，新页滚动逻辑按新滚动位置重新判断。

形变规则（src/styles/navbar.css）：

1
/* 站名帘式收起 */
2
#navbar.navbar-collapsed .navbar-seg-left .navbar-title-text {
3
    max-width: 0;
4
    opacity: 0;
5
}
6
/* logo 外边距归零（图标盒固定 1.75rem，保证两种 logo 形态收拢宽度一致） */
7
#navbar.navbar-collapsed .navbar-seg-left .navbar-logo { margin-right: 0; }
8
/* 左右段内边距收成正圆所需的值 */
9
#navbar.navbar-collapsed .navbar-seg-left {
10
    padding-left: calc(1.125rem - var(--card-border-width, 2px));
11
    padding-right: calc(1.125rem - var(--card-border-width, 2px));
12
}
13
.navbar-right-controls { max-width: 30rem; overflow: hidden; /* ...过渡见批次六 */ }
14
#navbar.navbar-collapsed .navbar-right-controls { max-width: 0; }
15
#navbar.navbar-collapsed .navbar-seg-right {
16
    padding-left: calc(0.625rem - var(--card-border-width, 2px));
17
    padding-right: calc(0.625rem - var(--card-border-width, 2px));
18
}
展开收起

正圆公式推导（box-sizing: border-box，高度 4rem 含边框）：

1
宽度 = padding-left + 内容 + padding-right + 2×边框宽  ≡ 高度 4rem
2
左段内容 = logo 图标盒 1.75rem
3
  → padding = (4rem − 2×边框 − 1.75rem) / 2 = 1.125rem − 边框宽
4
右段内容 = 汉堡按钮 2.75rem
5
  → padding = (4rem − 2×边框 − 2.75rem) / 2 = 0.625rem − 边框宽

两个注意点：边框宽取变量 --card-border-width，用户用滑块调粗后圆依然精确；rem 在 <768px 是 14px（根元素 text-[14px] md:text-[16px]），写死 px 会在移动端错位——所以全部用 rem + calc。

汉堡按钮显隐（PC 专用）：

1
/* 移动端常显；≥1024px 仅收拢态显示 */
2
@media (min-width: 1024px) {
3
    #navbar:not(.navbar-collapsed) .navbar-seg-right #nav-menu-switch {
4
        display: none;
5
    }
6
}

这里有个关键决策：最初把 lg:hidden! 写在按钮的类名上，结果 Tailwind 分层内 important 在层序反转下必胜（utilities 层的 !important 压过未分层的普通规则），收拢态想让汉堡出现的覆盖规则永远赢不了——表现为 PC 收拢后右段无图标、只剩细条、点不到。解法是放弃 important 角力：按钮类名去掉 lg:hidden!，显隐完全交给上面这条普通规则，由特异性与层序自然接管。

5.3 本批次的行为语义（验收用）#

  • 向下滚（>80px）：左段收成圆（logo 存活、站名消失）、右段收成圆（只剩汉堡）、中段菜单纹丝不动；
  • 上滑或回顶：全部恢复；
  • 切页：立即恢复完整态；
  • PC 非收拢态：汉堡隐藏；PC 收拢态：汉堡显示；移动端：汉堡始终显示。

六、批次五：移动端菜单样式可配置（b7cce682 一部分）#

目标#

上游主题把移动端汉堡菜单重构成了全屏抽屉（MD3 侧滑 + 遮罩），但旧版「锚定导航栏下方右侧的圆角卡片」更贴合本博客的胶囊风格——做成配置项，两种都保留。

改动明细#

1. 配置项（src/config/siteConfig.ts + src/types/siteConfig.ts）：

1
nav: {
2
    // 移动端汉堡菜单样式："card" 浮层卡片（旧版）/"drawer" 全屏抽屉（上游重构版）
3
    mobileMenuStyle: "card",
4
    // 类型：mobileMenuStyle?: "card" | "drawer";
5
}

2. src/components/layout/NavMenuPanel.astro 双分支渲染：

  • card 分支：复刻历史版本（git show a65c6576^:src/components/layout/NavMenuPanel.astro 可拿到原貌），根类带 nav-menu--card 标记，样式为 fixed right-4 top-21 圆角浮层卡片、max-h-[80vh] overflow-y-auto；
  • drawer 分支：保留全屏 fixed inset-0 抽屉，所有抽屉专属样式规则加 .nav-menu--drawer 作用域，避免两个分支互相污染。

3. 关闭机制（src/utils/layout-init.ts）：卡片模式依赖 click-outside 关闭；抽屉模式面板全屏覆盖、点击恒在面板内、该监听永不触发——两种模式都注册注册即可，无副作用。代码注释里写明了这一点。

切换方法#

改 siteConfig.ts 的 mobileMenuStyle 为 "drawer" 重启 dev 即可切到抽屉版。

七、批次六：PC 收拢态快捷面板与「原位弹卡」修复（b7cce682 下半）#

这是整个系列里迭代轮次最多的一块，经历了「实现 → 验收发现逻辑不对 → 定位两处根因 → 修复」的完整过程，值得完整记录。

7.1 需求#

收拢态下 PC 端右段只剩汉堡（中段菜单已常显导航链接，所以汉堡不该再开链接菜单），期望：

  1. 汉堡点击打开**「右段被隐藏控件」的快捷面板**——搜索/音乐/播放/显示设置/亮暗五行；
  2. 点击任意行，导航栏保持收拢，弹出「原来点击控件时会弹出的那张子卡片」（搜索面板、音乐面板、显示设置、亮暗菜单）；
  3. 移动端行为不变：汉堡开导航链接菜单；两菜单互斥。

7.2 快捷面板本体#

Navbar.astro 右段新增：

1
<div id="navbar-quick-panel"
2
     class="float-panel float-panel-closed absolute top-full right-0 mt-2 w-max min-w-52 p-1.5 z-50"
3
     data-floating-panel data-floating-panel-trigger="nav-menu-switch"
4
     inert aria-hidden="true">
5
    <button data-quick-action="search">…</button>   <!-- 音乐/播放/显示/亮暗同构，按配置条件渲染 -->
6
</div>

要点：w-max 必不可少——面板锚在收拢后只有约 64px 宽的右段里，绝对定位的收缩宽度会被包含块钳制，没有 w-max 就会被压扁；data-floating-panel 让它接入统一的 inert/Esc 管理。

分流逻辑（loadButtonScript 内汉堡 onclick）：

1
let isDesktop = window.matchMedia("(min-width: 1024px)").matches;
2
if (isDesktop && quickPanel) {
3
    quickPanel.classList.toggle("float-panel-closed");
4
    navPanel && navPanel.classList.add("float-panel-closed");   // 互斥
5
} else if (navPanel) {
6
    navPanel.classList.toggle("float-panel-closed");
7
    quickPanel && quickPanel.classList.add("float-panel-closed");
8
}

7.3 第一版的 bug 与两处根因#

现象：在快捷面板里逐个点搜索/音乐/显示设置/亮暗——导航栏重新展开，子卡片却不弹出。

根因一（展开）：行点击处理器里有一句 navbar.classList.remove("navbar-collapsed")。它的本意是「控件组收拢时被 opacity: 0 藏住了，展开才能看见子卡」——方向就错了，需求是保持收拢。

根因二（子卡秒关）：layout-init.ts 用 setClickOutsideToClose 给每个面板注册了 document 级点击关闭监听，它注册得比快捷面板的行点击处理器更晚。DOM 事件按注册顺序派发，于是同一个点击事件里：

1
行点击处理器：打开子卡 ✓
2
→ 后注册的 click-outside 监听器继续跑：点击目标（快捷面板的行）在子卡之外 → 把刚打开的子卡关掉 ✗

两口锅叠加，用户看到的就是「只展开了导航栏，什么卡都没弹」。

修复（Navbar.astro 行点击处理器重写）：

1
document.addEventListener("click", function (event) {
2
    if (!(event.target instanceof Element)) return;
3
    const row = event.target.closest("#navbar-quick-panel [data-quick-action]");
4
    if (!row) return;
5
    event.stopImmediatePropagation();   // ← 挡掉注册更晚的 document click-outside，防同事件秒关
6


7
    const action = row.getAttribute("data-quick-action");
8
    const triggerByAction = { search: "search-switch", music: "music-player-switch",
9
                              video: "bg-player-toggle", display: "display-settings-switch",
10
                              theme: "scheme-switch" };
11


12
    // 有子卡的行：关快捷卡、换弹子卡；video 只切换播放没有子卡，快捷卡留着当状态面板
13
    if (action !== "video") {
14
        document.getElementById("navbar-quick-panel")?.classList.add("float-panel-closed");
15
    }
16
    document.getElementById(triggerByAction[action])?.click();   // 程序化点击原控件按钮
17


18
    // 搜索子卡在桌面端复用面板内输入框（见 7.5）；inert 在微任务里解除，焦点延到宏任务再给
19
    if (action === "search") {
20
        setTimeout(() => {
21
            document.querySelector("#search-bar-inside input")?.focus();
22
        }, 0);
23
    }
24
});
展开收起

stopImmediatePropagation 的安全性论证（复现时按此检查）：Navbar.astro 自带的面板关闭监听注册在本处理器之前，此刻子卡尚未打开、必为空操作；layout-init 的监听注册在之后，被挡掉正是目的；两者的忽略列表本就不依赖这次事件。无论两侧注册顺序如何翻转，结论都成立。

7.4 收拢态子卡可见性：:has 守卫#

子卡（搜索/音乐/显示/亮暗面板）是控件组 .navbar-right-controls 的后代，而收拢规则给控件组加了 opacity: 0——opacity 作用于整棵子树，绝对定位的子卡也会一起隐身。第一版「展开导航栏」的错误修复就是在绕这个问题。

正确解法是把「形变」与「淡出」拆成两条规则，淡出加守卫（navbar.css）：

1
/* 形变：始终收拢——flow 子元素（按钮们）被 max-width:0 + overflow:hidden 裁掉 */
2
#navbar.navbar-collapsed .navbar-right-controls {
3
    max-width: 0;
4
}
5
/* 淡出：仅在没有任何子浮层面板打开时启用 */
6
#navbar.navbar-collapsed:not(:has(.navbar-right-controls .float-panel:not(.float-panel-closed))) .navbar-right-controls {
7
    opacity: 0;
8
}

两个前提成立才有效，复现时缺一不可：

  • max-width: 0 裁不到子卡：子卡是绝对定位，包含块是 position: relative 的 .navbar-seg（不是静态的控件组），静态祖先的 overflow: hidden 不裁切「包含块在其外部」的绝对定位后代；
  • :has 状态即时：float-panel-closed 类名一变，:has 匹配结果同步翻转（已实测：class 移除当帧 matches() 即为 false），无需额外 JS 状态同步。

附带收益：「子卡开着时再下滚，面板随控件组一起被藏起」这个此前登记在案的边缘情况被一并修掉了——现在子卡开着时收拢，守卫命中、控件组不淡出，面板保持可见可交互。

7.5 搜索子卡在桌面端的输入问题#

PC 正常态的搜索输入在导航栏内的 #search-bar（hidden lg:flex），收拢后被帘式收起；而搜索面板里的 #search-bar-inside 是给移动端的（lg:hidden）。若不处理，PC 点搜索行会弹出一张没有输入框的空卡。

修复（navbar.css）：

1
/* 收拢态从快捷面板唤起搜索时，面板内给移动端用的输入框顶上 */
2
#navbar.navbar-collapsed #search-bar-inside {
3
    display: flex;
4
}

未分层规则对 Tailwind utilities 层的普通 lg:hidden 自然占优，不需要 important。加上 7.2 里 setTimeout 自动聚焦，PC 收拢态点搜索 = 面板弹出、光标已就位、直接打字出结果（dev 环境 Pagefind 走 mock 数据，npm run build && npm preview 才能测真搜索）。回顶恢复后该规则因 :not(.navbar-collapsed) 失效，输入框回到 lg:hidden，无残留。

注意：本节方案已被第十二节取代（2026-10-05 追加批次）：PC 内嵌的 #search-bar 已整体删除，#search-bar-inside 去掉 lg:hidden 全端常驻——本节的收拢态补丁规则随之变成死规则、已删。历史过程保留在此供参考，复现以第十二节为准。

7.6 video 行的误关与忽略名单#

video 行没有子卡，它程序化 .click() 的是 #bg-player-toggle——这个合成 click 会冒泡到 document，被快捷面板自己的 click-outside 监听判定为「点外面」，把快捷面板关了（卡面板行无所谓，反正主动关；video 行就变成了「点一下菜单自己消失」）。

修复（src/utils/layout-init.ts）——把五个控件触发按钮全部加进快捷面板的忽略名单：

1
setClickOutsideToClose("navbar-quick-panel", [
2
    "navbar-quick-panel",
3
    "nav-menu-switch",
4
    "search-switch",
5
    "music-player-switch",
6
    "bg-player-toggle",
7
    "display-settings-switch",
8
    "scheme-switch",
9
]);

理由写进了注释：这些按钮的程序化点击不算「点外面」。真实用户点不到它们（收拢态下被裁切），所以不影响任何正常交互。

7.7 配套 i18n#

快捷面板两个新行名需要文案：I18nKey.displaySettings（显示设置）、I18nKey.lightDarkMode（亮暗模式），7 个语言文件各加两行。

7.8 本批次最终行为矩阵（自动化实测通过）#

操作期望结果
PC 下滚收拢 → 点汉堡快捷面板弹开，导航链接菜单关闭（互斥）
点搜索行导航栏保持收拢；快捷卡关；搜索卡开、inert 解除、焦点在面板输入框；控件组 max-width: 0 但 opacity: 1
点音乐/显示/亮暗行同上（子卡各自弹出），导航栏保持收拢
点 video 行快捷卡保持打开（无子卡），播放状态切换
子卡打开时点外部子卡关，控件组 opacity 回 0，导航栏仍收拢
快捷卡打开时点外部快捷卡关
回顶导航栏恢复完整、汉堡隐藏、面板内输入框回 lg:hidden
移动端点汉堡开导航链接菜单，快捷卡不开；再点关闭

八、跨批次踩坑合集#

改造过程中沉淀的九条硬结论，单独成节，任何一条都值得后来者抄走：

1. Tailwind 分层与 important 的层序反转。 本项目 navbar.css 等样式文件未分层，Tailwind utilities 在 @layer utilities 里。普通规则未分层胜分层；但 utilities 里的 !important 反转层序、必胜未分层的普通覆盖。想覆盖 lg:hidden! 这类带 bang 的工具类，靠写更狠的 important 是死路——把 bang 从类名上删掉，改用一条普通规则才是正解（汉堡显隐即是案例）。

2. border-box 下的正圆公式。 高度含边框时，宽度分量必须把边框计入再对半分，且内边距要写成 calc(半径差 - var(--card-border-width))，滑块调粗边框圆才不破。rem 别写死 px：根字号在移动端是 14px。

3. 绝对定位子卡的包含块是 .navbar-seg，不是控件组。 position: relative 挂在段上（且段有 overflow-visible!），静态控件组的 overflow: hidden / max-width: 0 裁不到子卡——这是「收拢态弹子卡」方案能成立的几何前提。改结构时若把 position: relative 挪走或给段加上 overflow，整套都会塌。

4. opacity 作用于整棵子树，无法被后代覆盖。 「祖先把 opacity 设 0、子卡单独显示」在 CSS 里无解，只能拆规则（:has 守卫）或挪 DOM。同理 visibility 可以被后代重写、opacity 不行——别选错属性。

5. Vite dev 编译缓存会丢同轮多次写入。 症状：磁盘正确、served 残缺。处置：重启 pnpm dev；诊断：curl 模块产物对比源码。线上构建从磁盘全新编译，不受影响。

6. Playwright headless 的 evaluate 期间不泵帧。 长时间驻留在 page.evaluate 的 async 代码里做 setTimeout 采样，CSS 过渡的 currentTime 会冻结在 0、getComputedStyle 读到旧值——全部是探针自伤，不是页面 bug。本次曾因此误判 :has 守卫失效，排查了数轮。正确姿势：用 page.waitForFunction（客户端 rAF 轮询会泵帧）等过渡完成，或读数前 document.getAnimations().forEach(a => a.finish()) 强制取目标值，或穿插 page.screenshot 触发渲染。判定标准：getAnimations() 里 playState: "running" 但 currentTime 恒为 0，即冻结而非停滞。

7. floating-panel-utils 的分工（src/utils/floating-panel-utils.ts）。 data-floating-panel-trigger 只做 aria/inert/焦点同步，不绑定点击（多面板共享同一 trigger 安全）；面板 class 变化由 MutationObserver 同步 inert 并在开→关时派发 floating-panel:close（不冒泡，要在 capture 阶段或直接挂面板上监听）；setClickOutsideToClose(panel, ignores) 是无条件的 document 点击监听——不检查面板是否打开，直接加 float-panel-closed；忽略列表按 id 做 DOM 包含判断，与面板开闭状态无关。理解这三条才能推演「同事件内先开后关」类时序 bug。

8. swup 4 事件。 可靠的是 astro:before-swap / astro:page-load；swup:contentReplaced 是死事件（NavMenuPanel.astro 里有一处历史遗留监听，本次未动，改事件前先处理它）。

9. 工具纪律。 pnpm lint（Biome safe-fix）会波及无关文件，本系列全程只用只读的 npx biome check <files>；Playwright 的 element screenshot 会被动画卡 stability，交互诊断用 run_code_unsafe 里 page.setViewportSize + evaluate。

九、如何复现#

路径 A：git 一次重放（推荐）#

Terminal window
1
git clone https://github.com/jmqsOOOtatoba/FireflyPriWeb.git
2
cd FireflyPriWeb
3
git checkout 020533ee            # 系列起点（最后一批之前的基线）
4
git cherry-pick 74680341 2a00a602 f6b3d060 b7cce682 04197b82 d7d3b62c
5
# 若目标仓库没有这几个对象，先从原仓库 fetch，或直接：
6
# git diff 020533ee..d7d3b62c | git apply
7


8
pnpm install
9
pnpm dev                        # http://localhost:4321

注：b7cce682 依赖 74680341 引入的 --card-border-width 与 f6b3d060 的 --card-border-color，顺序不能乱；04197b82（搜索图标化）依赖 b7cce682 的三段结构；d7d3b62c（卡顿修复）建立在 b7cce682 的收拢动画之上，放最后。9e8a7908（18 文章补 author 字段）与本系列无关，可跳过。

路径 B：按批次手工重做#

按本文第二、三、四、五、六、七节的「改动明细」顺序执行，每节末尾的复现要点即 checklist：

  1. 边框体系（第二节）：main.css 三规则 + setting-utils.ts 四函数 + Layout.astro 内联应用 + 显示设置滑块 + i18n；
  2. 悬浮胶囊（第三节）：高度 4rem 三处联动 + 9999px 圆角 + wrapper padding/pointer-events 对 + 移动端留边；
  3. 亮黑暗白（第四节）：--card-border-color 变量 + 导航栏 !important 接管 + 删两组防闪现规则；
  4. 三段与收拢（第五节）：Navbar 结构拆分 + navbar.css/main.css retarget + scroll-utils delta 上提 + 正圆公式 + 汉堡显隐普通规则；
  5. 移动菜单配置（第六节）：mobileMenuStyle 配置 + NavMenuPanel 双分支 + click-outside 双注册；
  6. 快捷面板（第七节）：quick panel markup + 分流 + 行点击处理器（含 stopImmediatePropagation）+ :has 守卫拆规则 + 搜索输入框放开（该补丁后被第十二节取代）+ 忽略名单 + i18n 两键；
  7. 搜索图标化（第十二节）：删 PC 内嵌 #search-bar + 图标按钮去 lg:hidden! + 面板输入框去 lg:hidden + 双关键词合并 + togglePanel PC 自动聚焦 + 删收拢态补丁与死忽略项；
  8. 收拢卡顿修复（第十三节）：汉堡 display 切换改 width/visibility 连续过渡 + 控件组 max-width 30rem→14rem 去死区 + 删淡入 keyframes + 亮暗图标交叉淡化。

复现后验收清单#

Terminal window
1
npx biome check src/            # 0 错
2
pnpm type-check                 # 0 错
3
pnpm check                      # 12 个存量错误（anime.astro 11 + vndb.astro 1），无新增

浏览器人工验收（顺序即第七节 7.8 矩阵）：

  1. PC 下滚 >80px → 左右段收成正圆、中段不动、汉堡出现；
  2. 点汉堡 → 快捷卡弹开、链接菜单不开；
  3. 逐行点搜索/音乐/显示/亮暗 → 导航栏不展开、对应子卡原位弹出、搜索卡光标已就位；
  4. 点外部/Esc → 子卡关、仍收拢；再点外部 → 快捷卡关；
  5. video 行 → 快捷卡不关、背景播放切换；
  6. 回顶 → 全部恢复、汉堡消失（含第十二节时：面板内输入框全端常驻，不再有 lg:hidden 切换）；
  7. 移动端（<1024px）→ 汉堡开链接菜单、与快捷卡互斥；
  8. 显示设置调边框粗细滑块 → 卡片与导航栏边框实时变粗细，刷新后保持；切暗色 → 边框变白；
  9. 含第十二节时：PC 正常态右段为纯图标排布，点搜索图标 → 卡片弹出、光标自动就位。

十、最终验证记录（2026-10-05）#

检查项结果
npx biome check（改动文件）通过，无 fix
pnpm type-check通过
pnpm check12 errors（= 基线，无新增）
Playwright 行为断言（PC 收拢/五行/外部点击/video/回顶/移动端分流）全部通过
视觉验收由人工完成，验收通过

自动化断言里踩到的探针陷阱见第八节第 6 条——先证明探针可信，再相信断言。

十一、提交记录#

1
9e8a7908  更新18文章作者                      （与本系列无关）
2
d7d3b62c  fix: 修复PC收拢动画卡顿，汉堡改width连续过渡，控件组max-width去死区
3
04197b82  feat: PC端搜索收成图标按钮，输入统一走搜索面板
4
b7cce682  feat: PC收拢态汉堡改开控件快捷面板，行点击原位弹出子控件卡
5
f6b3d060  feat: 导航栏接入卡片边框，边框色改为亮黑暗白跟随主题
6
2a00a602  feat: 导航栏改为悬浮胶囊样式并压扁高度
7
74680341  feat: 卡片边框默认 2px 纯黑，显示设置新增边框粗细滑块
8
020533ee  更新公告动态                        （系列起点）

提交粒度说明：前三个是独立小批次、逐批验收逐批提交；b7cce682 因三段结构、收拢动画、菜单配置、快捷面板四个特性在同一批文件里交织（Navbar.astro 一个文件承载三者），拆分提交的手术成本高于收益，故合为一笔、用 commit body 分条说明。

十二、追加批次：PC 搜索收成图标按钮（04197b82，2026-10-05）#

目标#

PC 端右段的内嵌搜索输入框（#search-bar，常态宽 10rem、聚焦展开到 15rem）太占地方，改为与移动端一致：只留一个搜索图标，点击弹出搜索卡片，输入统一在卡内完成。

改动明细（4 文件 +37/−72）#

1. src/components/controls/Search.svelte（主体）：

  • 删除 PC 内嵌输入框 #search-bar（连带 #search-input-desktop、handleDesktopFocus、focus-return 钩子）；
  • #search-switch 图标按钮去掉 lg:hidden!——注意这是第八节第 1 条的正解：删掉 bang 让显示自然接管，不是写更狠的 important 去压；
  • 面板内输入框 #search-bar-inside 去掉 lg:hidden，桌面/移动共用；
  • keywordDesktop/keywordMobile 双关键词状态合并为单个 keyword（桌面输入框没了，双状态就是死代码），setPanelVisibility/search 同步去掉 isDesktop 参数；
  • data-floating-panel-trigger 从 "search-switch search-input-desktop" 收窄为 "search-switch"；
  • togglePanel 打开面板时若视口 ≥1024px，setTimeout(0) 把焦点送进卡内输入框（inert 由 MutationObserver 在微任务解除，焦点必须延到宏任务——与 7.2 同理）；移动端刻意不自动聚焦，避免一点开就弹键盘。

2. src/styles/navbar.css：删除 7.5 的收拢态补丁 #navbar.navbar-collapsed #search-bar-inside { display: flex; }——输入框全端常驻后它成了死规则。

3. src/utils/layout-init.ts：search-panel 的 click-outside 忽略名单删掉已不存在的 "search-bar"。

4. src/components/layout/Navbar.astro：只更新快捷面板搜索行的过时注释（不再有「收拢态放开 lg」这回事）。

为什么面板落位不用改#

搜索面板的定位规则（navbar.css 的 --navbar-panel-inset、<768px 贴右段右缘）本来就同时服务桌面与移动——PC 旧方案里输入框虽在导航栏内，面板弹出位置也是同一套规则。图标化后直接复用，实测 1440px 视口面板 left≈861 / right≈1341，正好挂在右胶囊下方不出屏。

验证（2026-10-05，Playwright MCP 实测）#

检查项结果
Biome / type-check / pnpm check通过 / 通过 / 12 errors（= 基线无新增）
PC：#search-bar 不复存在、图标可见、面板默认关✓
PC 点图标 → 面板开、inert 解除、光标就位、打字出 mock 结果✓
PC 点外部 → 面板关✓
下滚收拢 → 汉堡 → 快捷面板搜索行 → 保持收拢、子卡原位弹出、光标就位✓
移动端回归：图标开卡、不自动聚焦、汉堡开链接菜单✓
视觉截图：右胶囊纯图标排布、面板不出屏✓

复现：检出 b7cce682 后按上面四条改动明细重做即可，验收按表格逐行过。

十三、追加批次：PC 收拢动画卡顿修复（d7d3b62c，2026-10-05）#

现象与最初假设#

PC 端下滚触发右段收拢成圆时，肉眼可见一次「卡顿」；同一套动画在移动端却顺滑。最初的假设是：右端图标从亮暗切换变成汉堡、两图标形状不同，切换瞬间没有过渡动画，想用 anime.js 做 SVG 路径变形。

假设被逐帧数据否了——收拢过程根本不触发太阳/月亮互换（那只发生在切主题时），且 moon 与 hamburger 的 SVG path 不同构，anime.js（v3）做不了任意路径变形。真凶在布局层。

诊断：逐帧实测抓到两条根因#

探针：页面内 rAF 采样右段/控件组/汉堡三元素的 getBoundingClientRect().width（先 page.bringToFront()——窗口遮挡时 rAF 掉到 1fps，见第八节第 6 条同源教训）。

修复前曲线（收拢 class 挂上在 t=165ms）：

1
t=165   汉堡 display:none→flex 单帧出现：seg +44px     ←—— 反向弹出（PC 独有）
2
t=165+  控件组 max-width 从 480px 才开始降，内容 220px
3
        在被钳到 224px 之前宽度纹丝不动：冻结 ~60ms    ←—— 空转死区
4
t=236+  220px 全挤进剩余时长：单帧 -57、-26、-22px 猛缩 ←—— 卡顿感主体
  1. 汉堡 display 单帧切换：非收拢态 PC 汉堡 display: none 不占位，收拢 class 一挂立刻 +2.75rem，右胶囊首帧向外弹。移动端汉堡常显、宽度不变——与「移动端没问题」的观察完全吻合。
  2. .navbar-right-controls 的 max-width: 30rem 死区：实际内容只有最多 5 个 2.75rem 控件 = 220px，过渡前段（480→224px）对用宽毫无影响，动画空转后余量猛缩，速度曲线呈「冻结→暴冲→拖尾」。

改动明细（2 文件 +29/−20）#

1. src/styles/navbar.css（历史注释分「一改 important」「二改卡顿」两段保留）：

1
/* 汉堡：display:none → width/visibility 连续过渡 */
2
.navbar-seg-right #nav-menu-switch {
3
    overflow: hidden;
4
    transition:
5
        width 0.36s cubic-bezier(0.22, 1, 0.36, 1),
6
        opacity 0.25s ease,
7
        visibility 0.36s;
8
}
9
@media (min-width: 1024px) {
10
    #navbar:not(.navbar-collapsed) .navbar-seg-right #nav-menu-switch {
11
        width: 0;
12
        opacity: 0;
13
        visibility: hidden;
14
        pointer-events: none;
15
    }
16
}
展开收起

三个要点：未分层 width: 0 自然压过 utilities 层的 w-11（层序反转只对 !important 生效，这里不需要 bang）；visibility 随行过渡（宽度播完才真正隐藏），非收拢态不进 Tab 焦点与 a11y 树；正圆公式不受影响——收拢态媒体查询不生效，内容宽仍是 w-11 = 2.75rem。

  • .navbar-right-controls 的 max-width: 30rem → 14rem（13.75rem 实际内容 + 0.25rem 余量），死区归零；注释里写明了原值的空转机制。
  • 删除 navbar-collapse-fade 淡入动画与 keyframes：opacity 已由 transition 接管；该动画还会让移动端常显的汉堡每次收拢从 0 重闪一遍（历史遗留瑕疵，一并消灭）。

2. src/components/controls/LightDarkSwitch.svelte：太阳/月亮两个图标容器加 transition-opacity duration-300——这是「图标切换没过渡」假设里唯一真实存在的问题（切主题时 class:opacity-0 硬切），与收拢无关，顺手修掉。

修复后曲线（同探针复测）#

1
控件组 ctr: 220 → 171 → 107 → 63 → 36 → 20 → … → 0    单调平滑减速
2
汉堡   ham:   0 →  10 →  23 → 32 → 37 → 40 → … → 44   从零长出、同步交接
3
终态   seg = 64px 正圆；首帧无反向弹出、无冻结

验证（2026-10-05，Playwright MCP 实测）#

检查项结果
Biome / type-check / pnpm check通过 / 通过 / 12 errors（= 基线无新增）
收拢首帧无 +44px 跳变、无冻结✓（逐帧差分只剩单调递减的正常减速帧）
展开回顶：汉堡 width 0 + visibility hidden、右段回 236px✓
移动端：汉堡常显（38.5px = 14px 根 × 2.75rem）、收拢不闪、点击开菜单✓
视觉验收由人工完成，验收通过

复现：检出 04197b82 后按改动明细重做。rAF 逐帧采样 + bringToFront 这套诊断法可复用于任何「肉眼卡顿但说不清」的动画排查——先量化，再动手。

结语与未尽事项#

做完的：边框体系、悬浮胶囊、三段收拢、快捷面板与原位弹卡、PC 搜索图标化、收拢动画卡顿修复，全部合入主干并上线（推送即触发 Cloudflare 构建）。

未尽与备忘：

  • 液态玻璃原型已回滚，git 无痕，重做需从零；
  • swup:contentReplaced 死事件遗留一处（NavMenuPanel.astro），本次刻意未动；
  • 流程教训：批次验收通过前不提交推送、一次性授权不跨批次沿用——最后一笔 b7cce682 是在验收确认前推的，虽未返工，但顺序不对，下不为例。

对后来者最重要的一句话：这次所有「看起来是页面 bug」的问题里，只有两处是真 bug（同事件 click-outside 秒关、合成 click 误关快捷卡），其余怪现象全部来自探针与 dev 缓存——先怀疑测量工具，再怀疑自己的代码。

]]> https://mstzuomu.space/posts/azuma.zuomu-blog-18/ 博客性能优化全记录：Lighthouse 报告拆解到帧率根因排查（A–F 六项实战） 2026-10-04T00:00:00.000Z 2026-10-04T00:00:00.000Z 左沐 从两份 Lighthouse 对比报告出发，完整记录六项性能优化的排查方法、根因定位与修复代码：字体子集化、封面图尺寸 API、CSS 内联、强制重排归零、以及"只有 Chrome 掉帧"的浏览器设置级根因，附全部可复现命令与工具脚本

博客性能优化全记录：Lighthouse 报告拆解到帧率根因排查（A–F 六项实战）#

2026-10-03，用 Chrome / Edge 无痕模式各跑了一份本博客的 Lighthouse 报告。两份报告揭出一批共性问题，外加一个诡异现象：同一个站，Chrome 滚动掉帧、Edge 完全正常（两者同为 Chromium 154）。随后完成了 A–F 六项优化/排查，最终 Lighthouse 的强制重排审计从稳定 0 分变为多次满分，Chrome 掉帧也以「浏览器设置」定案。

本文是完整复盘：每项改了什么、为什么这么改、怎么验证的、踩了哪些坑。既是给未来维护者的存档，也希望能成为一份可照抄的性能排查教程。

〇、初始状态（两份报告的关键数字）#

指标ChromeEdge说明
性能分0.710.70两边一致
LCP4.6s5.1s最大失分项
FCP / TBT / CLS1.5s / 0ms / 0.0031.6s / 0ms / 0.007主线程本身很干净
总传输量5,349 KiB同严重超标
渲染阻塞 CSS估省 220ms估省 250ms3 个 stylesheet link
强制重排~92ms（score 0）~200ms有内联脚本热点
图片可省~1,160 KiB~1,163 KiB封面原图直出

问题清单（即本文的 A–F）：

  • A 字体：一个 3.1MB 的 TTF 在预加载
  • B 封面图：330KB 原图 JPEG 直出，尺寸超显示需求 3 倍
  • C 三个第三方源没有 preconnect
  • D 3 个渲染阻塞的 stylesheet
  • E 加载期强制重排（forced reflow）
  • F 只有 Chrome 掉帧、Edge 不掉帧

A、字体子集化：3.1MB TTF → 212KB WOFF2#

现象#

Lighthouse 列出的最大单体资源：

1
/_astro/fonts/cc84406608407d93.ttf
2
resourceSize: 3,293,520 B（3.1MB）
3
transferSize: 约 2,088,846 B（压缩后仍有 2MB）
4
且带 rel="preload" 高优先级，与首屏图片抢带宽

根因#

项目里本来就有一整套字体子集化流水线（scripts/subset-fonts.ts，pnpm build 会执行），它扫描 dist/ 全部 HTML 收集实际用到的字符，生成 woff2 子集并替换引用、删除原文件。但配置里只登记了一个装饰字体：

src/config/fontConfig.ts
1
subsetFonts: {
2
  "--font-greatvibes": { extraChars: "" },  // 只有它
3
}
4
// 而全站正文用的是（fontConfig.selected）：
5
selected: ["--font-hanyi-wenhei"],          // ← 没登记，直接漏网

子集脚本会跳过「未在 selected/区域字体中引用」的项，于是每次构建都打印 skip，原始 TTF 原样进了部署包。

修复#

src/config/fontConfig.ts 增加一行：

1
subsetFonts: {
2
  "--font-greatvibes": { extraChars: "" },
3
  // 全站正文主字体（selected 引用），不配子集化会原样输出 3.1MB TTF
4
  "--font-hanyi-wenhei": { extraChars: "" },
5
},

无需改脚本——pnpm build 链路里已有 astro build && npx tsx scripts/subset-fonts.ts。

验证与注意点#

  • 构建日志出现 Generating subset ... 211.7 KB, original: 3216.3 KB, saved 93.4%
  • dist/_astro/fonts/ 下生成 e3c41cafdc6bb33b.woff2（211.7KB），原始 TTF 被脚本删除
  • 全站 53 个页面的 @font-face 与 rel=preload 均已替换为 type="font/woff2"，HTML 中 .ttf 引用为 0
  • 浏览器实测：document.fonts 加载成功、中文渲染无豆腐块

已知取舍：子集只包含构建时 HTML 里可见的字符。密码/加密文章解密后的字符不在其中，这些页面正文会回退到 fallbacks（PingFang/雅黑）。介意可在 extraChars 手动补字。

C、preconnect：三个第三方源提前建连（顺手先做了）#

现象#

报告写明「未预连接任何源」：图床 tu.mstzuomu.space、统计 cloud.umami.is、static.cloudflareinsights.com 都是 HTML 解析到一半才发现的，连接建立偏晚。

修复#

src/layouts/Layout.astro 的 <head> 最顶部（<meta charset> 之后）：

1
<!-- 提前建立第三方连接：图床图片、umami 统计、Cloudflare beacon 都在 HTML 解析中途才被发现 -->
2
<link rel="preconnect" href="https://tu.mstzuomu.space" />
3
<link rel="preconnect" href="https://static.cloudflareinsights.com" />
4
{analyticsConfig?.umamiAnalytics?.websiteId && (
5
  <link rel="preconnect" href="https://cloud.umami.is" />
6
)}

注意：这三行会改变 HTML 的行号——后文 E 项定位 Lighthouse 坐标时会看到所有行号整体偏移，此为预期内现象。

B、封面图：接入自建图床的尺寸处理 API#

现象与根因#

封面走远程 <img> 直出：src/components/common/CoverImage.astro 对所有 http(s) 图片输出裸 <img>，不经过 Astro 的优化管道。单张封面 2169×569 JPEG 约 330KB，实际显示只有 1350×300——格式（该转 WebP）和尺寸（超 3 倍）双重浪费，Lighthouse 估算 5 张可省 1.16MB。

排查：图床支持什么转换？#

图床是自建的 CloudFlare-ImgBed（CF Workers + Telegram 存储）。探测过程：

Terminal window
1
# 1. 直接试尺寸参数 → 403
2
curl "https://tu.mstzuomu.space/file/文章/xxx.jpg?width=1656&fallback=original"
3
# → 403 "Image resizing is disabled"   # 功能存在但默认关闭！
4


5
# 2. 查官方文档（cfbed.sanyue.de/api/file.html）
6
#    支持 width/height/fit/fallback 参数；JPEG/PNG/WebP 源 Worker 部署可处理；
7
#    开启路径：dashboard → 系统设置 → 安全设置 → 访问管理 → 图片尺寸处理
8
#    允许尺寸：留空 = 任意合法值
9


10
# 3. 后台开启后复测
11
width=1656 → 141KB   （原 330KB，-57%）
12
width=828  → 48.5KB  （-85%）
13
format=webp → 被忽略（该版本只改尺寸不转格式）

博客端实现（4 个文件）#

1. 配置开关（src/config/siteConfig.ts）：

1
imageOptimization: {
2
  // ...原有配置
3
  // 支持尺寸处理的远程图床域名（后台需开启"图片尺寸处理"）
4
  resizeHosts: ["tu.mstzuomu.space"],
5
},

2. 工具函数（src/utils/image-utils.ts）：

1
export const RESIZE_WIDTHS = [828, 1656] as const;
2


3
export function canResizeRemote(src: string): boolean {
4
  if (!/^https?:\/\//.test(src)) return false;
5
  const hosts = siteConfig.imageOptimization?.resizeHosts || [];
6
  if (hosts.length === 0) return false;
7
  try { return hosts.includes(new URL(src).hostname); }
8
  catch { return false; }
9
}
10


11
export function buildResizeUrl(src: string, width: number): string {
12
  try {
13
    const u = new URL(src);
14
    u.searchParams.set("width", String(width));
15
    u.searchParams.set("fallback", "original");
16
    return u.toString();
17
  } catch { return src; }
18
}
展开收起

3. 渲染（CoverImage.astro 远程分支）：白名单域名输出 srcset 双档 + 真实显示宽度的 sizes + 回退数据属性：

1
const resizeSizes = preview
2
  ? "(max-width: 768px) 100vw, 770px"    // 列表卡桌面约 680-770px
3
  : "(max-width: 768px) 100vw, 100vw";   // 详情页封面全宽
4


5
<img
6
  src={remoteImgSrc}                          /* 1656 档 */
7
  srcset={resizeSrcset}                       /* "…828 828w, …1656 1656w" */
8
  sizes={useResize ? resizeSizes : undefined}
9
  data-resize-fallback={useResize ? remoteSrc : undefined}
10
  ...
11
/>

sizes 有个坑：本地图沿用的旧值写死了桌面 320px，单档产物无影响，但双档 srcset 下 Retina 屏会错选 828w 导致发糊——所以尺寸变体必须用真实显示宽度（770px）单独给一套。

4. 保险丝（CoverImage.astro 脚本的 onError）：尺寸版加载失败（如图床后台开关被关）时一次性回退无参数原图：

1
const resizeFallback = img.dataset.resizeFallback;
2
if (resizeFallback && !img.dataset.resizeRetried) {
3
  img.dataset.resizeRetried = 'true';
4
  img.addEventListener('load', hideLoading, { once: true });
5
  img.addEventListener('error', onError, { once: true });
6
  img.removeAttribute('srcset');
7
  img.src = resizeFallback;
8
  return;
9
}

验证#

  • 浏览器 Network：封面请求全部带 ?width=828（DPR1 选小档），加载成功
  • 保险丝实测：手动把 src 改成 404 → 自动回退原图 → 加载成功、无错误态、不循环
  • mi-fds 域名的 2 张封面不在白名单，保持原样输出（预期行为）

D、CSS 内联：3 个渲染阻塞 link 归零#

现象#

首页 head 里 3 个阻塞请求：Layout.css（原始 196KB / 传输 28.7KB）、MainGridLayout.css、全局 CSS，Lighthouse 估算拖慢首屏 220–250ms——浏览器必须等它们下载解析完才画第一笔。

修复#

astro.config.mjs 顶层（Astro 配置，不是 vite.build！）：

1
// Astro 构建行为：全部 CSS 内联进 HTML（非 vite.build）
2
build: {
3
  inlineStylesheets: "always",
4
},

踩坑记录：我第一次把这个键写进了 vite: { build: { ... } } 块里——那是 Vite 的配置，不认识 inlineStylesheets，静默无效，白构建一轮。判断依据是检查产物里 <link rel="stylesheet"> 是否归零。

前置安全检查#

内联前必须确认三个 CSS 没有 url() 引用（否则内联到嵌套路径页面会相对路径断裂）：

1
# 扫描 dist/_astro/*.css 的 url( 引用
2
# 结果：三个阻塞 CSS 均为 0 处 → 内联无风险
3
# （带 url() 的 KaTeX/fancybox 是按需加载的非阻塞样式，不在范围）

验证与取舍#

  • 首页 <link rel="stylesheet"> 数量：3 → 0
  • HTML 原始体积 370KB → 608KB（+237KB ≈ 三者之和；gzip 后约 +38KB）
  • 文章页直连、swup 切页、视觉截图均正常
  • 取舍：CSS 不再单独缓存，每多看一页 HTML 多带约 38KB——换来首屏少 3 个请求，对博客访问形态是划算的
  • 残余：文章页 body 尾部还有个 8.9KB 的 twikoo-custom.css（评论区样式，解析位置在正文后，不挡首屏）和 fancybox 两个运行时注入的 link，都不在阻塞路径上

E、强制重排归零（本文最重的一节）#

方法论：怎么抓到强制重排的真凶#

强制重排 = JS 在脚本执行中读取几何/样式，浏览器被迫当场同步全量结算。坐标解读是最大的坑，先立规矩：

1. 本地跑 Lighthouse 单审计（线上报告的行号会随每次构建漂移，必须在当前产物上重测）：

Terminal window
1
# 用 Edge 当 Lighthouse 的浏览器（本机没装独立 Chrome 时）
2
$env:CHROME_PATH = "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe"
3
npx --yes lighthouse "http://127.0.0.1:8931/" `
4
  --only-audits=forced-reflow-insight --output=json --output-path=lh.json `
5
  --chrome-flags="--headless=new"

2. 以 CDP Tracing 全栈为准（Lighthouse 只给聚合后的 line/column，且行号 0-based、列号时而脚本内相对——单独解坐标会绕死）：

1
// Playwright run_code：抓带堆栈的 Layout/UpdateLayoutTree 事件
2
const cats = 'disabled-by-default-devtools.timeline,'
3
  + 'disabled-by-default-devtools.timeline.stack,'
4
  + 'disabled-by-default-devtools.timeline.frame';
5
// Tracing.start(ReportEvents) → goto + 等待 → Tracing.end
6
// 过滤 name 为 Layout/UpdateLayoutTree 且有 stackTrace 的事件，
7
// 按 dur 排序；stack[0] 是最内层帧 = 真正读取者

3. 模拟 Lighthouse 的测量条件（否则数字对不上）：Lighthouse 默认移动视口 + 4 倍 CPU 降速——

1
await client.send('Emulation.setDeviceMetricsOverride',
2
  { width: 412, height: 823, deviceScaleFactor: 2.625, mobile: true });
3
await client.send('Emulation.setCPUThrottlingRate', { rate: 4 });

六个根因与对应修复#

E1. 解析期读 window.innerWidth（移动端最大单点）#

读视口宽度需要先确定滚动条状态，移动模拟下会触发首次全量布局。三个热点全是这一个病：

位置代价（移动+4x）修复
PostPage 立即执行脚本~84ms移动/桌面默认布局本就相同，宽度分支冗余，只按 localStorage 偏好恢复
壁纸 sync()~26mswindow.matchMedia('(min-width: 1024px)').matches
ScrollDownIndicator updatePosition~31ms同上改 matchMedia

E2. window.pageYOffset || document.documentElement.scrollTop 老式写法#

加载时 pageYOffset 为 0（假值）→ 短路求值走到 documentElement.scrollTop → 几何读取强制布局。5 处统一改 window.scrollY（滚动位置干净时读它不强制）：

  • ScrollDownIndicator.astro / Navbar.astro / BackToTop.astro
  • fullscreen-wallpaper-utils.ts（×2）
  • 另外 scroll-utils.ts 和 grid-layout-utils.ts 里还有不带 || 的直接读法，一并处理

E3. document.fonts.ready getter 本身就强制样式结算#

移动端单次可达 300ms+。注意 typeof document.fonts.ready 这个 guard 本身就访问了 getter——把判断整体挪进首绘后：

FontSetup.astro
1
if (document.fonts) {                    // 只判断对象存在（不触发）
2
  afterFirstPaint(() => {
3
    document.fonts.ready.then(...)        // getter 访问推迟到 FCP 后
4
  });
5
}

E4. PostPage 的 transition 开关体操#

原代码注释自己写着「强制重排后恢复过渡动画」——transition:none → 换类 → container.offsetHeight（故意强制）→ 恢复。

关键认知：脚本在解析期执行，元素还没有计算样式，transition 根本不可能触发——体操在初始加载场景纯属多余。改为纯类名写入；即便补上 rAF 恢复过渡的版本，Lighthouse 仍会把异步归因的帧级工作记账 ~84ms（实测两版都 ~84）。首绘后的切页注入场景由 performance.getEntriesByType('paint') 检测后跳过体操。

E5. 读写交错（改了 DOM 又立刻查询）#

  • 壁纸 sync()：拆两阶段——读阶段用 getElementsByClassName/getElementsByTagName（纯 DOM 查询，不触发样式结算）收集全部 slot+tpl，写阶段只插入；materialize 改为插入前从 frag 取占位层，删掉插入后的 slot.querySelector
  • 歌词高亮 updateLrcHighlight：先缓存 offsetTop/clientHeight 几何值，再改 class，滚动用缓存值
  • 封面动画重启的 void ui.cover.offsetWidth、PRIMARY_COLOR 顶层 getComputedStyle：都挪到首绘门闩后

E6. 新工具 src/utils/after-first-paint.ts（本轮核心基建）#

1
// 设计要点（缺一不可，都有实测依据）：
2
// 1. 轮询 performance.getEntriesByType('paint') 中的 first-contentful-paint，
3
//    而不是双 rAF——弱性能设备首帧可能被丢弃，rAF 链会在真实绘制前跑完；
4
// 2. 每帧只放行一个回调（串行队列）——所有回调挤同一帧会互相弄脏：
5
//    前一个的写入让后一个的读取再次强制结算（实测 Waves 读前序回调的脏样式 29-31ms）；
6
// 3. 超时兜底 120 帧，防 paint 条目异常时回调永不执行。
7
export function afterFirstPaint(cb: () => void): void { /* 见仓库源码 */ }

加载期读取者全部改走它：滚动初始化、分类栏、波浪、壁纸视差/模糊、侧栏几何缓存、网格列数、fonts.ready、音乐封面动画重启……（共 14 个文件，见 commit d6ceae0a）

排查过程中的三个大坑（后人必读）#

  1. MCP 浏览器窗口被遮挡 = 测量全部失真：遮挡窗口的 Chromium 会暂停绘制 + rAF 压到 2fps，表现为 paint 条目永远为空、所有门闩「不触发」、滚动功能「全坏」。page.bringToFront() 一秒复活（101fps + paint 条目齐全）。做帧率/绘制相关测量前必须先置前窗口。
  2. 先做基线 A/B 再怀疑自己：修到中途滚动类效果全灭，用 git stash 丢弃改动构建基线版同环境实测——基线一模一样，证明非本次回归（是环境问题），避免了整段回滚。
  3. PowerShell 引号吞噬：复杂内联脚本（python -c、正则带引号）会被啃得面目全非，一律落盘成临时脚本文件执行。

结果#

基线最终
Lighthouse forced-reflow每次 score 0，~121ms多次 score 1 / 0.0ms，最差 18.6ms
移动+4x CDP 实测381–481ms主要热点归零
残余—仅 Astro 水合运行时（client.js，8–16ms，库代码）

改动：14 文件修改 + 1 新文件，+280/−121，commit d6ceae0a。

F、只有 Chrome 掉帧？——浏览器设置级根因#

症状与排查设计#

同机、同站、同引擎（Chromium 154），只有真 Chrome 掉帧，Edge 正常。这个「同引擎不同表现」本身就是最强线索：嫌疑必然在两者各自的运行环境，而非站点代码。

第一轮：站点侧压力矩阵（本机 Chromium，前台窗口）

组合结果
1440×900 DPR1 滚动99.9 FPS，0 掉帧
1728×1080 DPR1.5 + 文章页99.9 FPS，0 掉帧
+ CPU 4 倍降速 + 全屏模糊渐变99.9 FPS，0 掉帧

站点在默认设置的 Chrome 系浏览器下压不出掉帧。

第二轮：真 Chrome vs 真 Edge 同机对打（决定性实验）

用 Playwright 分别以临时 profile 启动两个真实浏览器 exe，跑完全相同的滚动帧率 harness（4 秒三角波滚动，统计帧间隔）：

1
// 核心：launchPersistentContext + executablePath，各自临时 user-data-dir
2
const ctx = await chromium.launchPersistentContext(tempDir, {
3
  executablePath: "C:/Program Files/Google/Chrome/Application/chrome.exe", // 或 msedge.exe
4
  headless: false,
5
  viewport: { width: 1728, height: 1080 }, deviceScaleFactor: 1.5,
6
});
7
// 页面内 harness：rAF 记录帧间隔，每帧 scrollTo 三角波滚动 4s，
8
// 统计 fps / jank(>25ms) / jank(>50ms) / worst / p95

结果：Chrome 99.9 FPS / Edge 99.9 FPS，双双零掉帧。
这一步同时排除了「Windows 每应用 GPU 指派」（系统级设置对 exe 生效，测试用的就是你的真 Chrome）。

第三轮：读真 Chrome 的配置文件（只读排查，不用开浏览器）

1
# Chrome:  %LOCALAPPDATA%\Google\Chrome\User Data\Local State
2
# Edge:    %LOCALAPPDATA%\Microsoft\Edge\User Data\Local State
3
json.load(...)["hardware_acceleration_mode"]
hardware_acceleration_mode
你的 Chrome{"enabled": false} ← 硬件加速是关的！
你的 Edge键不存在（未动过 = 默认开），previous: true

扩展数 0、退出状态正常——唯一差异就是这个开关。

根因与修复#

Chrome 关闭了硬件加速 → 6 层 backdrop-filter 毛玻璃、全屏壁纸滚动模糊渐变（blurRamp）、波浪 canvas 的全部合成工作由 CPU 软渲染 → 滚动掉帧；Edge 默认开 → GPU 合成 → 流畅。

修复（用户操作，一分钟）：

  1. chrome://settings/system → 开启「使用硬件加速模式」→ 重启 Chrome
  2. chrome://gpu 确认 Canvas / Compositing / Rasterization / Video Decode 全部 Hardware accelerated
  3. 实测确认恢复正常 ✅

为什么我的自动化测试一直测不出问题：新开的 profile 用默认值（硬件加速开），测的是健康态的 Chrome。真凶藏在你日常 profile 的 Local State 里。

五、成果总表#

项根因修复效果
A 字体主字体没登记子集化subsetFonts +1 行3.1MB → 212KB（-93%）
C 连接三源无 preconnecthead +3 行图床/统计早建连
B 封面远程图裸出 + 图床功能未开图床开关 + srcset 双档 + 回退保险丝单张 330KB → 48.5–141KB
D CSS3 个阻塞 linkinlineStylesheets: "always"阻塞请求 3 → 0，首屏约 -250ms
E 重排innerWidth/scrollTop/fonts.ready/体操/读写交错FCP 串行门闩 + 14 文件修复forced-reflow score 0 → 多次 1 / 0ms
F 掉帧Chrome 硬件加速被关浏览器设置一键开启Chrome 恢复流畅 ✅

相关提交：3691383a(A+C) → f875aef9(D) → d6ceae0a(E)，另有若干 chore 数据刷新。

六、可复用的工具箱#

Terminal window
1
# 1. 单审计 Lighthouse（本机没独立 Chrome 时用 Edge）
2
$env:CHROME_PATH = "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe"
3
npx --yes lighthouse "http://127.0.0.1:8931/" --only-audits=forced-reflow-insight `
4
  --output=json --output-path=lh.json --chrome-flags="--headless=new"
1
// 2. CDP 带栈追踪骨架（Playwright run_code）
2
// cats 含 disabled-by-default-devtools.timeline.stack；
3
// Tracing.start(ReportEvents) → goto → end；
4
// 事件过滤 Layout/UpdateLayoutTree + stackTrace，stack[0]=最内层帧
1
// 3. 滚动帧率 harness（浏览器控制台可直接粘贴）
2
// rAF 记帧间隔 + 4s 三角波 scrollTo → fps/jank25/jank50/worst/p95
1
# 4. 浏览器硬件加速状态（只读）
2
import json
3
ls = json.load(open(r"C:\Users\<你>\AppData\Local\Google\Chrome\User Data\Local State"))
4
print(ls.get("hardware_acceleration_mode"))  # {"enabled": False} 即被关闭

七、测量经验清单#

  1. Lighthouse 默认移动视口 + 4x CPU 降速，数字比桌面裸测大数倍——跨环境对比先对齐测量条件
  2. 做绘制/帧率测量前 page.bringToFront()——被遮挡的 Chromium 窗口暂停绘制、rAF 降到 2fps、paint 条目为空
  3. Lighthouse 的 line/column 只当粗定位，真凶以 CDP Tracing 的完整栈为准
  4. 改性能代码中途若行为异常，先 git stash 建基线同环境对照，再决定是不是自己的锅
  5. 复杂内联脚本别塞 PowerShell 命令行——引号会被啃，落盘执行
  6. 同引擎双浏览器表现不一致 → 优先怀疑各自的设置与 profile，直接读 Local State / Preferences JSON

（完）

]]> https://mstzuomu.space/posts/azuma.zuomu-blog-17/ Firefly 博客实战：从零搭建任意设备可用的发布台（Vercel + GitHub API） 2026-10-03T00:00:00.000Z 2026-10-03T00:00:00.000Z 左沐 静态博客只能守在电脑前发文章？本文完整复盘如何用 Vercel 无框架函数 + GitHub API 搭一套带登录的发布后台——发文、改稿、删除、预览全部在浏览器里完成，附我们真实踩过的五个部署坑与安全边界设计，照着做可以从零复刻。

Firefly 博客实战：从零搭建任意设备可用的发布台（Vercel + GitHub API）#

静态博客的一切内容都是 Git 仓库里的 Markdown 文件，代价是：想发篇文章，你得坐在装好开发环境的电脑前。这篇讲我们怎么把”发布”这件事拆出来，做成一个任何设备打开浏览器就能用的独立系统——发文、改稿、删除、预览，全部不用碰 git。

一、需求与架构选型#

目标拆开来是三句话：

  1. 博客本体一行架构都不动（继续是纯静态站 + 自动构建）
  2. 发布系统独立部署，有登录，手机能用
  3. 发布动作最终落回 Git 仓库，触发既有的自动构建上线

这就是所谓的”前后端分离”在静态博客语境下的含义：博客 = 展示层（静态产物），发布台 = 独立的前后端（编辑界面 + API），中间靠 GitHub 仓库衔接。

口令 + 内容

Contents API

发布台前端

(浏览器/手机)

Vercel API 函数

鉴权·命名·拼 frontmatter

GitHub 仓库 master

自动构建

(Actions / Cloudflare Pages)

博客上线

口令 + 内容

Contents API

发布台前端

(浏览器/手机)

Vercel API 函数

鉴权·命名·拼 frontmatter

GitHub 仓库 master

自动构建

(Actions / Cloudflare Pages)

博客上线

为什么走 Git 而不是数据库？因为博客的内容层（content collections、文件名序号、frontmatter 约定）全部建立在文件上，搬进数据库等于推翻重建；而发布频率很低的个人博客，每次发布等 3~5 分钟构建完全可以接受。这条路只动”发布入口”，不动”内容模型”，风险最低。

二、准备工作#

开始前你需要：

  1. 一个静态博客仓库（本文以 Firefly / Astro 为例，其他静态站同理）
  2. Vercel 账号（ Hobby 免费版足够）
  3. GitHub Fine-grained PAT（精细访问令牌）：
    • 打开 GitHub → Settings（设置）→ Developer settings → Personal access tokens → Fine-grained tokens → Generate new token
    • Repository access（仓库范围）→ Only select repositories → 只勾你的博客仓库
    • Permissions（权限）→ Repository permissions → Contents 设为 Read and write，其他一律不动
    • 生成后立刻复制，只显示这一次
  4. 一个发布口令：自己想一串随机字符串（比如 firefly-xxxx-xxxx），它是发布台的登录密码，后面存进 Vercel 环境变量

PAT 只授单仓库的 Contents 写权限，就算泄露，损失也被锁死在”有人能往你博客仓库提交内容”这一件事上——这是整套设计里最关键的一条安全边界。

三、后端：五个函数就是全部#

发布台后端不用任何框架，Vercel 支持纯函数：在项目目录下建 api/ 文件夹，每个 .js 文件就是一个 HTTP 端点。最终结构：

1
publisher/
2
├── index.html          # 发布台单页（登录/发布/管理三视图）
3
├── app.js              # 前端逻辑
4
├── package.json        # {"type":"module"}，加一个空 build 脚本
5
├── vercel.json         # 锁定输出目录（防根配置串扰，见第五节）
6
├── lib/shared.js       # 端点公共工具
7
└── api/
8
    ├── auth.js         # POST   登录校验
9
    ├── publish.js      # POST   发布新内容
10
    ├── articles.js     # GET    内容列表（管理页用）
11
    └── article.js      # GET/PUT/DELETE  单篇读、存、删

3.1 鉴权：每个请求都要过口令#

口令存环境变量 PUBLISH_TOKEN，前端登录成功后把口令放在请求头 x-publish-token 里带上，服务端逐次校验。比较要用常数时间函数，避免时序侧信道：

1
import crypto from "node:crypto";
2


3
export function safeEqual(a, b) {
4
  const ab = Buffer.from(String(a ?? ""), "utf8");
5
  const bb = Buffer.from(String(b ?? ""), "utf8");
6
  if (ab.length !== bb.length) return false;
7
  return crypto.timingSafeEqual(ab, bb);
8
}
9


10
// 每个端点的第一段逻辑
11
const publishToken = process.env.PUBLISH_TOKEN;
12
if (!safeEqual(req.headers["x-publish-token"], publishToken)) {
13
  res.statusCode = 401;
14
  res.end(JSON.stringify({ ok: false, error: "口令错误" }));
15
  return;
16
}
展开收起

会话策略用 sessionStorage（存标签页内存，关浏览器即失效）而不是 localStorage，就实现了”每次打开发布台都要登录”。

3.2 发布端点：命名、frontmatter、提交三件事#

发布端点收到 { type, title, content, ...可选字段 } 后做三件事：

① 自动命名——这是”文件名序号”类博客的关键。发文章前先调 GitHub Contents API 列目录，正则抓所有 数字+文章.md 取最大值 +1：

1
const res = await fetch(
2
  `https://api.github.com/repos/${REPO}/contents/src/content/posts/txt?ref=${BRANCH}`,
3
  { headers: { Authorization: `Bearer ${token}` } },
4
);
5
const entries = await res.json();
6
let max = 0;
7
for (const e of entries) {
8
  const m = /^(\d+)文章\.md$/.exec(e.name);
9
  if (m) max = Math.max(max, Number(m[1]));
10
}
11
const path = `src/content/posts/txt/${max + 1}文章.md`;

更新公告按日期命名（更新公告20261003.md）、动态按时间戳命名（20261003-1217.md），同名冲突就追加 -2 后缀。命名规则永远现场查仓库算，不要缓存，这样本地手动加了文件它也不会撞车。

② 拼 frontmatter——两条容易翻车的经验：

  • 字符串一律用 JSON.stringify 转义：标题里的引号、冒号、特殊字符，JSON.stringify 输出的就是合法 YAML 双引号字符串，手写拼接迟早被一个带 : 的标题弄炸
  • 日期裸写、不要引号：published: 2026-10-03 会被 YAML 解析成 Date 对象（Zod schema 的 z.date() 才认）；写成 published: "2026-10-03" 就成了字符串，构建直接报 schema 错误
1
const lines = ["---", `title: ${JSON.stringify(title)}`, `published: ${now.date}`];
2
// 约定"留空不写"：可选字段没填就完全不出现在 frontmatter 里
3
if (fields.tags.length) lines.push(`tags: ${JSON.stringify(fields.tags)}`);
4
if (fields.slug) lines.push(`slug: ${JSON.stringify(fields.slug)}`);
5
lines.push("---", "", content);

③ 提交到仓库——用 Contents API 的创建接口，内容 base64 后 PUT 到目标分支：

1
await fetch(`https://api.github.com/repos/${REPO}/contents/${path}`, {
2
  method: "PUT",
3
  headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
4
  body: JSON.stringify({
5
    message: `post: ${title}`,            // 提交信息，进 git 历史一眼能看懂
6
    content: Buffer.from(markdown, "utf8").toString("base64"),
7
    branch: "master",                     // 推到构建监听的分支
8
  }),
9
});

提交成功即返回”已提交，3~5 分钟后生效”——到这一步，剩下的事全交给博客既有的自动构建，发布台不需要知道构建是否存在、是否成功。

3.3 管理端点：读、存、删#

  • 列表（articles.js）：调 Git Trees API（/git/trees/master?recursive=1）一次拿到全仓库文件树，过滤出内容目录的 .md；再并发拉各文件的 frontmatter 头部解析出标题/日期/草稿标记，拼成列表
  • 读取（article.js GET）：Contents API 返回 base64 正文和 sha（文件指纹）
  • 保存（PUT）：必须带上刚才读到的 sha，GitHub 据此判断文件有没有被别人动过——sha 对不上返回 409，提示”文件已被他人改动，请刷新重试”，两个人同时改稿就不会互相覆盖
  • 删除（DELETE）：同样要 sha，删除即一次 commit，走同样的构建上线

三条铁律写在端点入口：

1
// ① 路径白名单：只允许内容目录的 markdown，防任意文件被改/删
2
function isSafeContentPath(p) {
3
  if (p.includes("..") || p.startsWith("/")) return false;
4
  return /^src\/content\/(posts|dynamic)\/.+\.(md|mdx)$/.test(p);
5
}
6
// ② 内容不能为空
7
// ③ sha 必须提供（先读后改，不允许盲写）

四、前端：一个单页，三个视图#

前端不需要框架，一个 index.html + 一个 app.js 足够，视图切换就是显隐：

  1. 登录视图：口令输入框 → 调 POST /api/auth 校验 → 成功后口令存 sessionStorage，进主界面
  2. 发布视图：内容类型分段器（文章/公告/动态）+ 标题 + 正文 + 可选字段折叠区。可选字段照抄你博客 schema 的字段表，顺序一致、留空不写，这样发布产物和手写文件完全同构
  3. 管理视图：列表（按类型分组、显示草稿/置顶徽章）→ 点条目进编辑器（全文含 frontmatter 在一个 textarea 里改）→ 预览 / 保存 / 删除

预览用 marked 做客户端渲染，把它的 UMD 产物拷进 vendor/ 本地引用（别用 CDN，国内不稳）。渲染前先用正则剥掉 frontmatter 单独展示，正文丢给 marked.parse() 即可。要认清预览的边界：它是近似预览——自定义指令、代码高亮、排版样式最终以博客构建后的效果为准。

关键交互别忘了：

  • 删除必须二次确认（弹窗里带标题和路径，“不可撤销”写明白）
  • 401 统一处理：任何请求收到 401 都踢回登录页
  • 发布成功后清空”一对一”字段（标题、正文、slug、封面、密码……），保留可复用的（标签、分类、作者），避免下一篇带着上一篇的封面发出去

五、部署：五个步骤与五个坑#

步骤 1：导入仓库，设 Root Directory#

Vercel → Add New Project → 导入你的博客仓库 → Settings → General → Root Directory 填 publisher（根目录）。不填的话 Vercel 会去构建整个博客本体，必错。

步骤 2：环境变量#

Settings → Environment Variables 加两条：

KeyValue
GITHUB_TOKEN刚才的 fine-grained PAT
PUBLISH_TOKEN你自己定的发布口令

坑 ①：Command "build" not found#

Vercel 对 monorepo 会在仓库根装依赖（正常），但构建命令跑在 Root Directory 里——你的子目录 package.json 没有 build 脚本就报这个。修法：补一个空脚本 "build": "echo ok"（或对应包管理器的等价物）。

坑 ②：No Output Directory named "dist" found#

这个最阴险：仓库根遗留的 vercel.json（写着 buildCommand、outputDirectory: dist）会被套用到你的发布台项目上，而且 vercel.json 优先级高于界面设置，在界面上怎么改都没用。双保险修法（两头都堵死）：

  • 子目录放自己的 vercel.json：{ "outputDirectory": "." }
  • build 脚本顺便产出一份 dist/（mkdir -p dist && cp index.html dist/），满足根配置的 dist 预期

排查时先看报错信息里的配置来源指向哪，再决定动哪边的 vercel.json——别去改博客本体的根配置，那是博客自己的部署遗产。

步骤 3：部署#

点 Deploy（部署），等到 Ready（就绪）。

坑 ③：打开部署地址跳到 vercel.com/login#

新项目默认开着 Deployment Protection（部署保护）——Vercel 认证拦住了所有访客。到 Settings → Deployment Protection → Vercel Authentication（Vercel 身份验证）关掉（或只留预览环境保护）。发布台自己有口令把关，页面加 noindex 即可放心公开。

步骤 4：绑定自有子域名#

坑 ④：*.vercel.app 在国内被 DNS 污染，不绑域名基本打不开。

  1. Settings → Domains → Add Existing（添加已有域名）→ 输入你的子域名（如 pub.example.com）
  2. 到 DNS 服务商（如 Cloudflare）加一条 CNAME：名称填子域，值照 Vercel 显示的填
  3. 建议开启 CDN 代理（橙云）——解析走代理边缘，避开污染

坑 ⑤：配完 Vercel 会报 Proxy Detected（检测到代理）警告——可以无视。它只是抱怨自己的防护工具在代理后面不好使，对口令保护的个人发布页毫无影响，而代理恰恰是国内能稳定访问的关键。

步骤 5：验证#

打开你的子域名 → 登录 → 发一条测试内容 → 确认：仓库出现新 commit → 自动构建触发 → 博客页面出现这条内容。三环都绿，系统就通了。

六、安全边界清单#

边界做法
登录口令存环境变量；每请求校验；sessionStorage 关浏览器失效
GitHub 凭据fine-grained PAT，单仓库、仅 Contents 读写、定期轮换
文件操作路径白名单锁死在内容目录的 .md/.mdx，拒绝 ..
并发读写带 sha，冲突返回 409 而不是覆盖
暴露面页面 noindex；错误信息只说”口令错误”，不回显任何环境变量
仓库纪律发布台写的文件和本地手写完全同构，本地改动前先 git pull，正常 push 不会互相覆盖

七、成本与额度#

整套系统跑在免费层就够：Vercel Hobby 免费版（函数请求量对个人博客是天文数字）、GitHub API 每小时 5000 次调用（一次发布约 3~5 次请求）、marked 本地化零外部依赖。唯一的”成本”是每年记得给 PAT 续期。

八、可以继续加的东西#

  • 图片上传：API 接收文件转存到图床或仓库 images/ 目录，正文插外链
  • 构建状态：发布后轮询 Actions / Cloudflare 构建 API，把”构建中→上线”做进回执
  • 草稿箱：发布时勾 draft: true，列表里单独分组，改完一键转正
  • 移动端 PWA：加个 manifest，“添加到主屏幕”后体验接近原生 App

到这里，你就有了一套自己写、自己控、任何设备都能用的博客发布系统：写在任何地方的 Markdown，贴进发布台，剩下的交给自动化。

开源项目#

这套发布台已经整理成开箱即用的模板仓库，Fork 一键部署或下载拷进你博客的 publisher/ 目录，照着 README 走完环境变量和 Vercel 配置就能用，路径与文件命名全部可用环境变量覆盖：

jmqsOOOtatoba
/
firefly-publisher
给静态博客装一个随时随地发文的发布台：口令登录、发文/改稿/删除/预览，Vercel + GitHub API，路径命名全可配置
—
—
MIT
JavaScript
]]> https://mstzuomu.space/posts/azuma.zuomu-blog-16/ Win11 资源管理器大小列只显示 KB？开启 KB / MB / GB 自适应显示完整教程 2026-10-03T00:00:00.000Z 2026-10-03T00:00:00.000Z 左沐 Win11 详细信息视图的大小列长期以来一律用 KB 显示，4 GB 的文件写成 4,194,304 KB 根本没法看。微软其实已经原生支持自适应单位了，本文给出先更新系统、再用 ViveTool 强制开启（功能 ID 61014711）的完整教程，含回滚方法与常见问题。

Win11 资源管理器大小列只显示 KB？开启 KB / MB / GB 自适应显示完整教程#

Windows 11 的大小列动辄一长串 KB 数字，肉眼完全无法换算。好消息是微软已经原生支持自适应单位了；坏消息是灰度推送可能轮不到你。本文给出从”先试免费零风险的更新”到”ViveTool 强制开启功能 ID 61014711”的完整方案，附回滚方法。

问题#

Windows 11 的文件资源管理器切换到”详细信息”视图后，大小列长期以来一律用 KB 显示：一个 4 GB 的文件写成 4,194,304 KB，几十 GB 的文件就是一长串数字，肉眼完全无法换算，只能点开属性才能确认实际大小。

背景：微软已经原生支持了#

2026 年 7 月起，微软开始推送这个改进：

  • 7 月可选更新 KB5101684：24H2 升到 Build 26100.8973，25H2 升到 Build 26200.8973，详细信息视图的文件大小改为按实际大小自适应显示 KB / MB / GB；
  • 8 月累积更新 KB5121003：24H2 到 26100.9168，25H2 到 26200.9168，该功能随安全更新正式向所有用户推送；
  • 在更早的 25H2 Beta / Experimental 预览版（26220.8370、26300.8376）中，这个功能默认隐藏，功能 ID 为 61014711，需要手动开启。

也就是说：先检查 Windows 更新，装完再重启资源管理器，很可能什么都不用改就好了。

但我在自己的机器上实测（25H2，Build 26200.9168，已包含 8 月更新）：装了更新、重启了资源管理器，大小列依然全是 KB。原因是这类功能采用 CFR（受控功能放量）分批推送，同一个版本号的机器生效时间可能不同。这时就轮到 ViveTool 出场。

方法一：先更新系统（免费、零风险）#

  1. 设置 → Windows 更新 → 检查更新，安装 2026 年 7 月及之后的所有更新；
  2. 打开任务管理器（Ctrl+Shift+Esc）→ 找到”Windows 资源管理器” → 右键”重新启动”；
  3. 打开任意有大文件的文件夹，切到详细信息视图，看大小列是否已显示 MB / GB。

生效了就不用往下看了。

方法二：ViveTool 强制开启（更新后仍是 KB 时用）#

ViveTool 是微软隐藏功能（Feature ID）的命令行开关工具。

1. 下载 ViveTool#

任选其一：

  • winget（推荐）：终端执行

    1
    winget install --id thebookisclosed.Vive --accept-package-agreements --accept-source-agreements

  • 手动下载：GitHub 仓库已从 thebookisclosed/ViVeTool 改名为 thebookisclosed/ViVe（旧地址会 404），到其 Releases 下载 ViVeTool-v0.x.x-IntelAmd.zip，解压到任意目录。

注意：如果你的网络直连 GitHub 超时，下载需要走代理；winget 的下载进程不读系统代理，卡住不动时请换手动下载 + 代理，或用 curl.exe -x http://127.0.0.1:<代理端口> -L -o vivetool.zip <下载地址>。

2. 以管理员身份执行#

必须管理员（写注册表需要提权，否则会报”拒绝访问”）。打开一个管理员终端，执行：

1
ViVeTool.exe /enable /id:61014711

验证是否写入成功：

1
ViVeTool.exe /query /id:61014711

看到 State : Enabled 即成功。

3. 重启资源管理器#

任务管理器 → Windows 资源管理器 → 重新启动。再看大文件的大小列，此时应该显示 1.25 MB、3.72 GB 这样的自适应单位了。

如何恢复原状#

ViveTool 的修改只是加了一条功能覆盖，随时可逆：

1
ViVeTool.exe /disable /id:61014711

然后重启资源管理器即可回到 KB 显示。系统后续大版本更新也可能自动重置该覆盖。

常见问题#

  • 执行 /enable 报”拒绝访问”：终端不是管理员权限，右键”以管理员身份运行”再执行。
  • 开启了、重启了还是 KB：确认系统已装 2026 年 7 月之后的更新——ViveTool 只是把系统里已有的功能代码”翻到开”，如果系统里根本没有这段代码（更新太旧），开启也无效。
  • 对文件夹有效吗？：大小列对文件夹本身仍不显示大小（这是另一回事，需要第三方工具计算），本功能针对的是文件。
  • 只影响详细信息视图：图标、平铺等其他视图不显示大小数字，自然不受影响。

总结#

方案适用场景风险
装 2026 年 7 月后更新功能已随更新推送无
ViveTool + ID 61014711已是新版本但被灰度卡住低，可随时 disable 回滚

亲测环境：Windows 11 25H2（Build 26200.9168），更新后仍显示 KB，用 ViveTool 0.3.4 开启 61014711 并重启资源管理器后生效。

]]> https://mstzuomu.space/posts/web-update-8/ 更新公告20261003 2026-10-03T00:00:00.000Z 2026-10-03T00:00:00.000Z 左沐 网站更新公告

更新公告20261003#

1.网站版本更新到6.16.8

2.新增firefly-publisher发布后台：口令鉴权登录，支持文章列表、编辑、预览、删除，填好内容一键自动命名并提交到GitHub发布，手机等任意设备都能发文；已开源并加入项目页，搭建教程可见文章Firefly 博客实战：从零搭建任意设备可用的发布台

3.重构了MD语法下的哔哩哔哩卡片、音乐播放器、PDF阅读器三个组件，B站卡片信息改为API获取，加载更稳定

4.更新了天气API与侧边栏天气样式

5.重构了不蒜子访客统计，并修正了历史统计数据的偏移问题

6.更新了主页背景图

7.导航栏新增Umami、Cloudflare外链入口

8.修复了评论区表情被截断的问题，修复了同天发布文章顺序错乱的问题，修正了文章10的内容错误

9.发布了《Codex 重装后三大故障修复全记录》等多篇新文章，更新了文章封面

]]> https://mstzuomu.space/posts/azuma.zuomu-blog-15/ Codex 重装后三大故障修复全记录：CC Switch 报错、走官方通道、聊天记录丢失 2026-10-02T00:00:00.000Z 2026-10-02T00:00:00.000Z 左沐 一次「Codex 删了重装」引发三个环环相扣的故障：CC Switch 报 requireStack、Codex 打到 api.openai.com 401、历史聊天记录不显示。完整根因分析与修复过程。

Codex 重装后三大故障修复全记录：CC Switch 报错、走官方通道、聊天记录丢失#

环境：Windows 11 · Node v24.19.0 · npm 全局 Codex CLI 0.160.0 · Codex Desktop（ChatGPT 桌面版）26.928 · CC Switch（供应商切换工具）

一次「Codex 包名有问题，删了重装」的操作，引发了三个看似独立、实则环环相扣的故障。本文完整记录排查与修复过程，供遇到同类问题的朋友参考。

故障现象#

重装 Codex 之后，出现了三个问题：

  1. CC Switch 设置页报错：Codex 卡片显示「已安装 · 无法运行」，错误信息为 requireStack: [] } Node.js v24.19.0，底部提示「请检查运行环境」。
  2. Codex 启动走的还是官方通道：打开 Codex 桌面版直接进 ChatGPT 登录页；CLI 调用则返回 401 Unauthorized ... url: https://api.openai.com/v1/responses，完全没有走 CC Switch 配置的 MiMo 中转。
  3. 历史聊天记录消失：旧的会话记录在桌面版里一条都看不到。

三个问题各有一个根因，下面逐个拆解。

问题一：CC Switch 报「无法运行」#

根因#

CC Switch 检测 Codex 是否可用的方式，是执行 npm 全局目录下的 codex.cmd。而重装过程中，npm 全局目录里 @openai/codex 的包体被删空了，只留下了启动壳：

1
%APPDATA%\npm\node_modules\@openai\     ← 目录还在，里面 0 个文件
2
%APPDATA%\npm\codex.cmd                 ← 启动壳还在，指向不存在的包

执行 codex.cmd 时报：

1
Error: Cannot find module '...\node_modules\@openai\codex\bin\codex.js'
2
  code: 'MODULE_NOT_FOUND',
3
  requireStack: []
4
Node.js v24.19.0

requireStack: [] 就是截图里那行报错的来源——不是 Node 环境坏了，是包没了。

修复#

Terminal window
1
npm install -g @openai/codex

⚠️ 关键坑：Codex 的 npm 包采用「主包 + 平台二进制」分离结构，主包 @openai/codex 很小，真正的可执行文件在 optionalDependencies 里（如 @openai/codex-win32-x64）。国内直连官方 registry 经常在下载平台包时超时，结果是主包装上了但运行仍报错：

1
Error: Missing optional dependency @openai/codex-win32-x64.
2
Reinstall Codex: npm install -g @openai/codex@latest

解决办法是换国内镜像单独补装平台包：

Terminal window
1
npm install -g "@openai/codex-win32-x64@npm:@openai/codex@0.160.0-win32-x64" --registry=https://registry.npmmirror.com

验证：

Terminal window
1
codex --version    # codex-cli 0.160.0
2
codex doctor       # 应全部通过

问题二：Codex 走回官方通道（401）#

根因#

CC Switch 的工作原理是把供应商配置写进 ~/.codex/config.toml。正常应写入：

1
model_provider = "custom"
2


3
[model_providers.custom]
4
name = "xiaomi_mimo"
5
base_url = "https://api.xiaomimimo.com/v1"
6
wire_api = "responses"
7
requires_openai_auth = true

但实际打开 config.toml 发现：model_provider 和整个 [model_providers.custom] 表丢失了，取而代之的是一堆无效的顶层键（base_url、wire_api、experimental_bearer_token 写在了顶层——TOML 里这些键 Codex 根本不认，启动时会警告 unrecognized configuration settings）。

没有 model_provider 指示，Codex 就用默认的 OpenAI 官方 provider，于是打到 api.openai.com 返回 401；桌面版则因为没有有效凭证直接弹登录页。

为什么会被写坏？ 时间线是：

  1. 今早 Codex 桌面版启动时重写了 config.toml（9<35>）；
  2. CC Switch 把这份已经不含 provider 段的 config 回读成了自己的供应商模板（双向同步的副作用）；
  3. 之后每次切换供应商，CC Switch 用坏模板写回 config.toml——越修越坏，切换一次覆盖一次。

证据：CC Switch 数据库（~/.cc-switch/cc-switch.db 的 providers 表）里存的模板已经是坏的，而当天早些时候的数据库备份（9<29>）里配置还是完整的。

修复（三处一起改）#

改任何一处之前，先备份 CC Switch 数据库：

Terminal window
1
Copy-Item ~\.cc-switch\cc-switch.db ~\.cc-switch\backups\db_backup_manual.db
  1. 修模板（根因）：用 SQLite 打开 ~/.cc-switch/cc-switch.db，找到 providers 表中当前 Codex 供应商的 settings_config JSON 字段，删掉无效顶层键，补回 model_provider = "custom" 和 [model_providers.custom] 表。
  2. 修 ~/.codex/config.toml：同样处理。
  3. 重建 ~/.codex/auth.json（如果也丢了）：
1
{ "OPENAI_API_KEY": "你的中转 Key" }

教训：只修 config.toml 不修数据库模板是没用的，下次切换就会被覆盖回去。必须修源头。

问题三：恢复的聊天记录不显示#

背景#

Codex 的会话记录是 JSONL 文件，按日期存放在：

1
~/.codex/sessions/YYYY/MM/DD/rollout-<时间>-<uuid>.jsonl

把旧的 2026/ 文件夹整个复制回 ~/.codex/sessions/ 后，文件明明在，桌面版侧边栏却一条都不显示。

根因#

桌面版的会话列表不是实时扫描文件夹的，而是读本地索引库 ~/.codex/state_5.sqlite 的 threads 表。首次启动时有一个 backfill 扫描流程负责把 rollout 文件导入这张表，扫完后在 backfill_state 表里记：

1
(1, 'complete', NULL, <时间戳>, <时间戳>)

新装的 Codex 在 9<09> 第一次启动时扫过一次——当时 sessions 目录还是空的（聊天记录是之后才复制进去的），扫描结果标记为 complete，之后永远不会再扫。

修复#

  1. 完全退出 ChatGPT 桌面版（托盘也要退出，避免写库冲突）；
  2. 备份后清空 backfill_state 表，强制下次启动重扫：
1
import sqlite3, shutil
2
shutil.copy2(r"C:\Users\<你>\.codex\state_5.sqlite",
3
             r"C:\Users\<你>\.codex\state_5.sqlite.bak")
4
con = sqlite3.connect(r"C:\Users\<你>\.codex\state_5.sqlite")
5
con.execute("DELETE FROM backfill_state")
6
con.commit()
  1. 重新打开桌面版，启动时自动重扫，历史记录全部回来了。

修复顺序建议#

如果你同时遇到这三个问题，按这个顺序修，避免互相干扰：

1
① npm 包（codex --version 能跑）
2
        ↓
3
② CC Switch 数据库模板 + config.toml + auth.json（走通中转）
4
        ↓
5
③ 退出桌面版 → 重置 backfill_state → 重启（恢复列表）

验证清单#

  • codex --version 输出版本号
  • codex doctor 无致命错误
  • CC Switch 设置页 Codex 卡片无警告
  • codex exec "你好" 走中转正常回复（不应出现 api.openai.com 的 401）
  • 桌面版侧边栏能看到历史会话

经验教训#

  1. requireStack: [] ≠ 环境坏了：十有八九是包文件缺失，先 ls 看包目录是不是空的。
  2. npm 装 Codex 国内务必配镜像：平台二进制包体积大，官方 registry 容易半途超时，留下「装了一半」的残局。
  3. 双向同步类工具有「污染源头」风险：CC Switch 会把 app 重写过的 config 回读成模板，坏一次就循环放大。修的时候一定要连它的数据库模板一起修。
  4. 文件在 ≠ 能显示：现代客户端基本都有本地索引库，恢复数据文件后要找到对应的「重扫/重建索引」开关。
  5. 改数据库前先备份：本文所有数据库操作都留了备份，出问题可随时回滚。

本文基于一次真实排障记录整理，涉及的具体厂商（CC Switch / MiMo 中转）仅为实例，同类「供应商切换工具 + Codex」组合的排查思路通用。

]]> https://mstzuomu.space/posts/azuma.zuomu-blog-14/ 评论区回复时表情面板被截断：一次 overflow 裁剪排查实录 2026-10-01T00:00:00.000Z 2026-10-01T00:00:00.000Z 左沐 主评论框的表情菜单好好的，一到回复就少了半截？不是 z-index 的锅，是祖先容器的 overflow 在裁。完整复现步骤、根因分析与修复代码。

评论区回复时表情面板被截断：一次 overflow 裁剪排查实录#

主评论框点开表情菜单一切正常，回复别人的评论时表情按钮本来就靠下，点开后面板下半截连同底部的分类 tab 全被容器”吃”掉了。第一反应是层级（z-index）不够，实际查下来跟层级半点关系没有——是祖先容器的 overflow 在裁。本文记录完整复现步骤、排查过程和修复方案，无论你用的是不是我这套主题/评论系统，都能照着修。

现象与复现#

复现条件很稳定，按下面步骤一定能碰到：

  1. 打开任意一篇文章，滚到评论区；
  2. 在顶部主评论框点表情按钮：表情面板完整弹出，颜文字 / Emoji / Bilibili 分类 tab 都在——一切正常；
  3. 找到一条已有评论，点它的回复，回复框出现在评论列表靠下的位置（贴近评论卡片底部）；
  4. 再点回复框的表情按钮：面板弹是弹出来了，但下半截被整齐地切掉，底部分类 tab 直接消失，切分类无从下手。

主评论框正常、回复框遭殃，很容易让人怀疑”回复框的 z-index 低了”。但无论你把表情面板的 z-index 调到多大都没用——z-index 管的是叠放顺序，管不了裁剪。一个绝对定位浮层能不能完整显示，取决于它全部祖先的 overflow 设置，任何一层 overflow: hidden 都会在那层的边界上把它齐刷刷切掉。

排查：顺着 DOM 向上找 overflow#

打开 DevTools，用元素选择器选中被截断的表情面板，沿着祖先链逐层看计算样式里的 overflow：

1
表情面板（position: absolute，本身没问题）
2
  └─ 评论卡片 #post-comments          ← overflow: hidden  ❌ 第一层裁剪
3
       └─ 主内容列 wrapper             ← overflow: hidden  ❌ 第二层裁剪
4
            └─ #content-wrapper / main ← 无 overflow        ✅

本站（Firefly 衍生主题 + Twikoo）具体是这两处：

第一层：评论卡片。 src/components/comment/index.astro 里的 #post-comments，类名里带着 overflow-hidden，而且它继承的 .card-base 基类本身也带 overflow: hidden（为了圆角裁剪）。主评论框没事，是因为它在卡片顶部，面板向下展开 200 多 px 依然在卡片内部；回复框贴近卡片底部，面板需要溢出卡片才能显示完整——正好撞在裁剪边界上。

第二层：主内容列。 src/utils/responsive-utils.ts 的 generateMainContentClasses() 给内容列 push 了 overflow-hidden。就算修掉卡片那一层，面板接着会被这一层继续裁，所以两层要一起改。

同样的问题临渊羡鱼也踩过并写过一篇很详细的分析（评论区表情面板被裁、切换还抖，原因在 overflow，他修的是 Waline + Firefly，还给上游提了 PR）。评论系统不同，根因完全一致：主题为了圆角在祖先链上套的 overflow: hidden，把评论系统绝对定位的浮层关在了里面。

关键陷阱：为什么不能直接 overflow-y: visible#

第一反应可能是把裁剪层改成”横向还裁、纵向放开”。但这里有个规范级的坑：

只要一个轴是 visible，另一个轴是 hidden / auto / scroll / clip 里任何非 visible 值，浏览器就会强制把 visible 那一轴降级成 auto。

1
/* ❌ 看起来对，实际 overflow-y 被计算成 auto：
2
   元素变成滚动容器，浮层照样被关在里面裁掉 */
3
overflow-x: hidden;
4
overflow-y: visible;

正确的组合是 overflow-x: clip 配 overflow-y: visible——clip 不触发上面那条降级规则（规范里 visible 和 clip 是允许共存的一对），只裁切、不生成滚动容器，也不影响列内 sticky 吸顶：

1
/* ✅ 横向只裁不滚，纵向完全放开 */
2
overflow-x: clip;
3
overflow-y: visible;

修复#

一共改两个文件：

1. src/components/comment/index.astro — 评论卡片

1
<div id="post-comments" class="card-base p-8 mb-6 relative overflow-hidden">
2
<div id="post-comments" class="card-base p-8 mb-6 relative overflow-x-clip overflow-y-visible">

注意 .card-base 基类里还有 overflow: hidden，光删类名上的 overflow-hidden 没用，必须用 overflow-x-clip / overflow-y-visible 两个工具类去覆盖长轴属性（本主题用 Tailwind v4，utilities 层优先级高于 @layer components 里的 .card-base，能覆盖住）。

2. src/utils/responsive-utils.ts — 主内容列

1
classes.push("min-w-0");
2
classes.push("overflow-hidden");
3
classes.push("overflow-x-clip");
4
classes.push("overflow-y-visible");
5
classes.push("z-10");

横向的 clip 要保留：卡片的圆角和装饰性 SVG 靠它裁剪，横向不能放。

3. 为什么要加 z-10

浮层纵向放开后会溢出内容列、盖到页脚区域。本主题的页脚带着 onload-animation，动画结束后 transform: translateY(0) 会残留（animation-fill-mode: forwards），只要有 transform 就会生成层叠上下文——页脚在 DOM 里靠后，绘制顺序压在内容列上面。结果是：浮层显示出来了，但底部 tab 被页脚盖住，看得见点不着。

页脚和内容列都是 #main-grid 的 grid 子项，grid 子项直接写 z-index 就能生效（不需要额外加 position），给内容列加 z-10 把它整体抬到页脚之上即可。这一幕和羡鱼文章里描述的”旧架构”问题一模一样——他后来赶上上游重构、页脚那层 transform 没了才不用加；本站页脚还有这个 transform 残留，所以这个 z-10 得带上。

换成你自己的主题/评论系统怎么修#

不管用 Twikoo、Waline 还是 Artalk，凡是”绝对定位浮层被容器切掉”，排查套路通用：

  1. DevTools 选中浮层，沿祖先链找 overflow 不是 visible 的那一层（通常不止一层，逐个记下来）；
  2. 每一层改成 overflow-x: clip; overflow-y: visible——不要用 overflow-x: hidden 配 overflow-y: visible，会被降级成 auto 白改；
  3. 横向想继续裁（保圆角、防横向滚动条）就靠 clip，别用 visible；
  4. 改完如果浮层能出来但被下方元素盖住或点不动，用元素选择器看盖住它的东西：若那个元素（或它的某个祖先）带 transform、opacity < 1、position + z-index 之类生成层叠上下文的属性，给你的内容容器加个 z-index（grid/flex 子项可直接写，普通元素配合 position: relative）压回去；
  5. 验证三件事：回复框贴底时面板完整显示、分类 tab 能点、评论卡片的圆角和装饰没有溢出。

验证结果#

  • 主评论框表情面板：正常；
  • 回复框（贴近卡片底部）表情面板：完整浮出卡片，分类 tab 可见可点；
  • 卡片圆角、装饰 SVG：横向仍被裁剪，无溢出；
  • astro check / type-check / Biome lint：无新增问题。

参考#

]]> https://mstzuomu.space/posts/azuma.zuomu-blog-13/ Firefly 博客实战：给文章页加阅读进度条与圆环百分比 2026-09-28T00:00:00.000Z 2026-09-28T00:00:00.000Z 陌殊途左沐 从设计思路到逐文件代码，手把手为 Firefly/Astro 博客实现纯客户端阅读进度功能：顶部细条、右下角与悬浮按钮同款的圆环百分比，零网络请求，兼容 Swup 切页

Firefly 博客实战：给文章页加阅读进度条与圆环百分比#

本文记录一次完整的功能实现：为基于 Astro + Swup 的 Firefly 博客添加阅读进度——文章页顶部一条随滚动生长的细条，右下角悬浮按钮栈最上方一个与现有按钮同规格的方框，内部 SVG 圆环实时填充百分比。

功能特点：

  • 纯客户端计算：零网络请求、零第三方依赖，不拖慢加载
  • 精准语义：只统计正文（横幅、评论区、推荐文章不计入）
  • UI 与现有按钮一致：3rem 方框、圆角、--card-bg 背景、毛玻璃、细边框，尺寸断点跟随 FloatingButton
  • Swup 兼容：切页不残留旧值、软导航后自动重新绑定
  • 可配置开关：siteConfig.post.readingProgress 一键启停

改动规模：7 个文件修改 + 1 个新文件，净增约 100 行。本文给出每一处改动的精确位置和完整代码，可对照逐条复现。

一、设计思路（先读懂再动手）#

1. 进度怎么算#

进度语义定义为：正文进入视口底边记 0%，正文底边到达视口底边记 100%：

1
p = clamp((viewportHeight - rect.top) / rect.height, 0, 1)

其中 rect 是正文容器 #post-container 的 getBoundingClientRect()。这个公式的好处：

  • 横幅高度、评论区长度、推荐文章数量都不影响进度
  • 短文章（高度小于视口）也能自然收敛到 0~1

顶部细条用 transform: scaleX(p) 驱动；圆环用 SVG stroke-dashoffset = 周长 × (1 - p) 驱动——两者都不触发布局。

2. 性能三板斧#

这个博客的滚动管线是 scrollFunction（scroll 事件 rAF 节流），阅读进度不是自己注册监听器，而是挂进现有管线，这是全部性能设计的前提：

  1. 调用点卡在布局新鲜期：scrollFunction 先读 scrollTop（布局脏时浏览器在此强制计算一次），紧接着读 rect 命中同一次新鲜布局——增量回流成本为 0
  2. 文字只在整数变化时写：百分比从整数维度最多写 100 次/全程；徽章 CSS 带 contain: content，文字变更的布局失效被隔离在徽章子树内，不污染正文布局。圆环的 dashoffset 是 SVG 属性，只标记绘制不触发布局，可以逐帧写
  3. 非文章页近乎零成本：靠 isConnected + null === null 短路，首页每帧只多一次 getElementById 哈希查找（与 scrollFunction 里已有的 navbar 查询同量级）

3. Swup 适配（这个博客的特殊点）#

本站用 Swup 做软导航，DOM 会局部替换，处理不好会出现”换页后进度条卡在旧值”：

元素位置跨页行为
#reading-progress-barLayout.astro不在 Swup 容器内，元素持久，引用不失效
#reading-progress-badgeFloatingControls.astro同上，持久
#post-container#swup-container 内每次换页被替换，靠 isConnected 自愈重查

再加两条 CSS：切页期间（html.is-page-transitioning）同时隐藏细条和徽章，避免旧页百分比残值闪现；scrollFunction 在过渡期本来就提前 return，visit:end 后恢复调用并刷新。

4. 三个补测时机#

有些场景没有滚动事件，需要主动补算：

  • 图片加载 / 代码块展开 / 加密文章解密 → 正文高度变了但用户没滚 → ResizeObserver 盯正文容器
  • 移动端地址栏收起 → 视口高度变了但正文没变 → 单独听 resize
  • 沉浸阅读切换 → 正文位置变了但可能停在同一滚动位置 → 监听 immersiveReadingChange 事件，立即算一次 + 400ms 过渡结束后再算一次

二、改动总览#

#文件改动
1src/types/siteConfig.ts类型：加 readingProgress: boolean
2src/config/siteConfig.ts配置：加 readingProgress: true
3src/utils/reading-progress.ts新文件，核心逻辑
4src/utils/scroll-utils.ts滚动管线接入（2 处）
5src/utils/layout-init.ts初始化调用（2 处）
6src/layouts/Layout.astro顶部条 DOM（1 行）
7src/styles/transition.css顶部条样式（文件末尾追加）
8src/components/controls/FloatingControls.astro圆环徽章 DOM + 样式

三、分步实现#

Step 1：配置开关（2 个文件）#

src/types/siteConfig.ts —— 在 post 类型区块中，generateOgImages: boolean; 之后添加：

1
    // 是否显示阅读进度（顶部进度条 + 百分比 + 预计剩余时间）
2
    readingProgress: boolean;

src/config/siteConfig.ts —— 在 post 配置区块中，generateOgImages: true, 之后添加：

1
    // 阅读进度：文章页顶部细条 + 悬浮百分比与预计剩余时间（纯客户端计算，无网络请求）
2
    readingProgress: true,

SiteConfig 是严格类型，只改 config 不改类型会直接 type-check 报错，两处必须成对加。

Step 2：核心模块（新文件）#

新建 src/utils/reading-progress.ts，完整内容如下（可整段复制）：

1
/**
2
 * 阅读进度（顶部细条 + 右下角圆环百分比）。
3
 *
4
 * 进度语义：正文进入视口底边为 0%，正文底边到达视口底边为 100%，
5
 * 即 p = clamp((viewportHeight - rect.top) / rect.height, 0, 1)——
6
 * 横幅、评论区、推荐文章不计入。
7
 *
8
 * 每帧成本：一次 getBoundingClientRect + 算术。scrollFunction 先读 scrollTop
9
 *（布局脏时已在此强制计算），随后本函数的 rect 读取命中同一次新鲜布局，不触发额外回流。
10
 * 百分比文字仅在整数变化时写入，且 badge 带 contain:content，文字变更的布局失效
11
 * 被限制在 badge 子树内，不污染正文布局；圆环 dashoffset 走 SVG 属性（不触发布局）。
12
 * 正文元素被 Swup 替换后靠 isConnected 自愈重新查询，非文章页每帧仅一次
13
 * getElementById 哈希查找（与 scrollFunction 中已有的 navbar 查询同量级）。
14
 */
15


16
let initialized = false;
17
let enabled = false;
18


19
let bar: HTMLElement | null = null;
20
let badge: HTMLElement | null = null;
21
let pctEl: HTMLElement | null = null;
22
let ringEl: SVGCircleElement | null = null;
23


24
let article: HTMLElement | null = null;
25
let observer: ResizeObserver | null = null;
26
let active = false;
27
let lastP = -1;
28
let lastPct = -1;
29


30
/** 圆环周长 2πr（r=15，与 SVG viewBox 一致） */
31
const RING_C = 2 * Math.PI * 15;
32


33
/** Swup 换页/解密后旧引用断开 → 重查并重绑 ResizeObserver；非文章页 null===null 直接短路 */
34
function resolveArticle(): void {
35
  if (article?.isConnected) return;
36
  const next = document.getElementById("post-container");
37
  if (next === article) return;
38
  article = next;
39
  lastPct = -1;
40
  if (observer) {
41
    observer.disconnect();
42
    if (article) observer.observe(article);
43
  }
44
}
45


46
function setActive(next: boolean): void {
47
  if (active === next) return;
48
  active = next;
49
  lastPct = -1;
50
  bar?.classList.toggle("visible", next);
51
  badge?.classList.toggle("show", next);
52
}
53


54
export function initReadingProgress(): void {
55
  if (initialized) return;
56
  initialized = true;
57


58
  // 配置关闭时 DOM 不渲染；查询不到即永久空转
59
  bar = document.getElementById("reading-progress-bar");
60
  badge = document.getElementById("reading-progress-badge");
61
  pctEl = document.getElementById("reading-progress-pct");
62
  ringEl = document.getElementById(
63
    "reading-progress-ring",
64
  ) as SVGCircleElement | null;
65
  if (!bar || !badge || !pctEl || !ringEl) return;
66


67
  enabled = true;
68


69
  if (typeof ResizeObserver !== "undefined") {
70
    // 正文高度变化（图片加载、代码块展开、解密）后无滚动也能重算
71
    observer = new ResizeObserver(() => updateReadingProgress());
72
  }
73


74
  // 移动端地址栏收起只改视口高度、不改正文尺寸 → 单独听 resize
75
  window.addEventListener("resize", updateReadingProgress, { passive: true });
76
  // 沉浸阅读切换改变正文位置且可能落在同一滚动位置（无 scroll 事件）→ 立即 + 过渡结束后各算一次
77
  document.addEventListener("immersiveReadingChange", () => {
78
    updateReadingProgress();
79
    window.setTimeout(updateReadingProgress, 400);
80
  });
81


82
  updateReadingProgress();
83
}
84


85
/** 由 scrollFunction 每帧调用；页面过渡期间 scrollFunction 提前返回，不会执行到这里 */
86
export function updateReadingProgress(): void {
87
  // enabled 为 true 时下列元素必然存在，显式判空仅为满足 TS 收窄
88
  if (!enabled || !bar || !badge || !pctEl || !ringEl) return;
89


90
  resolveArticle();
91
  if (!article) {
92
    setActive(false);
93
    return;
94
  }
95


96
  const rect = article.getBoundingClientRect();
97
  if (rect.height <= 0) return;
98


99
  const p = Math.min(
100
    1,
101
    Math.max(0, (window.innerHeight - rect.top) / rect.height),
102
  );
103
  setActive(true);
104


105
  // transform/dashoffset 只影响合成与绘制，不触发布局，逐帧写入开销可忽略
106
  if (p !== lastP) {
107
    lastP = p;
108
    bar.style.transform = `scaleX(${p})`;
109
    ringEl.style.strokeDashoffset = String(RING_C * (1 - p));
110
  }
111


112
  // 百分比文字仅整数变化时写，配合 contain:content 把回流限制在徽章内
113
  const pct = Math.round(p * 100);
114
  if (pct !== lastPct) {
115
    lastPct = pct;
116
    pctEl.textContent = `${pct}%`;
117
  }
118
}
展开收起

模块导出两个函数：initReadingProgress（一次性初始化）和 updateReadingProgress（每帧调用）。模块级缓存了 DOM 引用、正文引用、ResizeObserver 实例和两个”上次写入值”（lastP / lastPct），全部写入都先比对再落 DOM。

两个细节：

  • getElementById 返回类型是 HTMLElement，赋给 SVGCircleElement 需要显式断言（as SVGCircleElement | null），否则 type-check 报 TS2322
  • 圆环周长常量 RING_C = 2π×15 ≈ 94.2478 必须与 Step 6 中 SVG 的 r="15" 保持一致，改半径要同步改这里和 CSS 里的 stroke-dasharray

Step 3：接入滚动管线（src/utils/scroll-utils.ts）#

两处改动。

第一处，文件顶部 import 区，加入：

1
import { updateReadingProgress } from "@/utils/reading-progress";

第二处，scrollFunction 函数内，找到这段：

1
  const scrollTop = document.documentElement.scrollTop;
2
  const bannerHeight = window.innerHeight * (BANNER_HEIGHT / 100);
3
  const navbarElement = document.getElementById("navbar");
4


5
  // 根据滚动位置动态更新侧边栏 sticky 间距
6
  updateSidebarStickySpacing();

在 navbarElement 之后、updateSidebarStickySpacing() 之前插入调用：

1
  const scrollTop = document.documentElement.scrollTop;
2
  const bannerHeight = window.innerHeight * (BANNER_HEIGHT / 100);
3
  const navbarElement = document.getElementById("navbar");
4


5
  // 阅读进度：紧跟 scrollTop 读取（布局已新鲜），后续 DOM 写入前完成 rect 测量
6
  updateReadingProgress();
7


8
  // 根据滚动位置动态更新侧边栏 sticky 间距
9
  updateSidebarStickySpacing();

位置很关键：必须在所有 DOM 写入之前完成 rect 测量。scrollTop 读取已经把布局算干净了，此时 getBoundingClientRect 不会触发新的回流；如果挪到函数末尾（一堆 class 写入之后），每帧会多付一次强制布局。

Step 4：初始化（src/utils/layout-init.ts）#

两处改动。

import 区加：

1
import { initReadingProgress } from "@/utils/reading-progress";

initLayout() 函数内，initScroll() 之后紧跟调用：

1
  initScroll();
2
  initReadingProgress();

initLayout 有 window.__fireflyLayoutInit 守卫只会执行一次，initReadingProgress 内部也有 initialized 双保险。注意顺序：initScroll() 注册监听后会立即调一次 scrollFunction，此时阅读进度尚未初始化、enabled 为 false 会静默跳过——紧接着的 initReadingProgress() 自己会补一次首帧计算，所以顺序必须是 initScroll 在前。

Step 5：顶部细条 DOM + 样式（2 个文件）#

src/layouts/Layout.astro —— 找到 Swup 导航进度条，在其后面加一行：

1
    <div id="progress-bar"></div>
2
    {siteConfig.post.readingProgress && <div id="reading-progress-bar" aria-hidden="true" />}

（siteConfig 该文件本来就有 import，无需新增。）

src/styles/transition.css —— 文件末尾追加：

1
/* --------------------------------------------------------------------------
2
   4b. Reading Progress Bar (post pages)
3
   -------------------------------------------------------------------------- */
4


5
#reading-progress-bar {
6
    --reading-progress-height: 3px;
7


8
    position: fixed;
9
    top: 0;
10
    left: 0;
11
    width: 100%;
12
    height: var(--reading-progress-height);
13
    /* 低于 #progress-bar(9999)：切页时由导航进度条覆盖，同色无缝衔接 */
14
    z-index: 9998;
15
    pointer-events: none;
16
    background: var(--primary);
17
    transform-origin: left center;
18
    transform: scaleX(0);
19
    opacity: 0;
20
    transition: opacity 0.3s ease;
21
    will-change: transform;
22
}
23


24
#reading-progress-bar.visible {
25
    opacity: 1;
26
}
27


28
/* 切页期间隐藏阅读进度条，避免旧页残值与导航进度条混显；visit:end 移除类后淡入 */
29
html.is-page-transitioning #reading-progress-bar {
30
    opacity: 0;
31
}
展开收起

样式要点：

  • z-index 9998 vs Swup 条的 9999：切页时导航进度条永远压在阅读条上面，两者同为 var(--primary) 颜色，视觉无缝
  • transition 只写了 opacity：transform 不能加过渡，否则进度条会”追不上”滚动
  • html.is-page-transitioning 规则优先级 (1,1,1) 高于 .visible 的 (1,1,0)：切页时无需 JS 介入即可强制隐藏

Step 6：圆环徽章（src/components/controls/FloatingControls.astro）#

徽章放在右下角悬浮按钮栈的第一项（最顶部），样式与 FloatingButton（.floating-btn）同规格：3rem 方框、1rem 圆角、--card-bg 背景、12px 毛玻璃、细边框——远看就是第五个按钮，只是内部是圆环而非图标。

import 区无需改动（徽章不依赖 i18n），frontmatter 里 immersiveReadingEnabled 之后加一行：

1
const readingProgressEnabled = siteConfig.post.readingProgress;

模板里，.floating-controls-container 内第一项插入：

1
<div class="floating-controls-container">
2
  {readingProgressEnabled && (
3
    <div id="reading-progress-badge" class="reading-progress-badge card-base" aria-hidden="true">
4
      <!-- 类名用 rp- 前缀：.ring 会撞 Tailwind 的 .ring 焦点环工具类（box-shadow 1px currentColor） -->
5
      <svg class="rp-ring" viewBox="0 0 36 36">
6
        <circle class="rp-ring-track" cx="18" cy="18" r="15" />
7
        <circle id="reading-progress-ring" class="rp-ring-value" cx="18" cy="18" r="15" />
8
      </svg>
9
      <span id="reading-progress-pct">0%</span>
10
    </div>
11
  )}
12
  <FloatingTOC headings={headings ?? []} encrypted={encrypted} />
13
  <!-- ……其余原有内容不动…… -->

<style> 块开头（.floating-controls-container 规则之前）插入徽章样式：

1
  /*
2
   * 阅读进度圆环：与 .floating-btn 同规格的方框。背景/圆角/overflow 交给 card-base——
3
   * 卡片透明度、卡片边框等全局设置都通过 .card-base 类挂钩，必须带上才能跟随这些设置。
4
   * 本组件只补尺寸、毛玻璃、边框与内容布局。不可交互（pointer-events: none），无 hover。
5
   */
6
  #reading-progress-badge {
7
    display: none;
8
    place-items: center;
9
    position: relative;
10
    width: 3rem;
11
    height: 3rem;
12
    flex-shrink: 0;
13
    border: 1px solid rgba(0, 0, 0, 0.1);
14
    backdrop-filter: blur(12px);
15
    -webkit-backdrop-filter: blur(12px);
16
    color: var(--primary);
17
    pointer-events: none;
18
    user-select: none;
19
    /* 环与文字的布局失效限制在徽章子树内，不污染正文布局 */
20
    contain: content;
21
  }
22


23
  #reading-progress-badge.show {
24
    display: grid;
25
  }
26


27
  /* 切页期间隐藏，visit:end 移除类并刷新后重新显示，避免旧页百分比残值闪现 */
28
  :global(html.is-page-transitioning) #reading-progress-badge {
29
    display: none;
30
  }
31


32
  /* SVG 与数字叠放（同 FloatingButton 双图标的手法：grid 同格） */
33
  #reading-progress-badge .rp-ring,
34
  #reading-progress-badge #reading-progress-pct {
35
    grid-area: 1 / 1;
36
  }
37


38
  .rp-ring {
39
    width: 83%;
40
    height: 83%;
41
    /* 从 12 点方向起笔 */
42
    transform: rotate(-90deg);
43
  }
44


45
  .rp-ring-track,
46
  .rp-ring-value {
47
    fill: none;
48
    stroke-width: 3;
49
  }
50


51
  .rp-ring-track {
52
    stroke: rgba(0, 0, 0, 0.1);
53
  }
54


55
  .rp-ring-value {
56
    stroke: var(--primary);
57
    stroke-linecap: round;
58
    /* 周长 2πr（r=15）≈ 94.2478；初始 dashoffset = 周长 = 0% */
59
    stroke-dasharray: 94.2478;
60
    stroke-dashoffset: 94.2478;
61
  }
62


63
  #reading-progress-pct {
64
    font-size: 0.6875rem;
65
    font-weight: 600;
66
    line-height: 1;
67
    font-variant-numeric: tabular-nums;
68
  }
69


70
  :global(.dark) #reading-progress-badge {
71
    border-color: rgba(255, 255, 255, 0.15);
72
  }
73


74
  :global(.dark) .rp-ring-track {
75
    stroke: rgba(255, 255, 255, 0.15);
76
  }
77


78
  /* 尺寸断点跟随 FloatingButton（480 → 2.5rem，360 → 2rem，320 → 1.75rem） */
79
  @media (max-width: 480px) {
80
    #reading-progress-badge {
81
      width: 2.5rem;
82
      height: 2.5rem;
83
    }
84


85
    #reading-progress-pct {
86
      font-size: 0.625rem;
87
    }
88
  }
89


90
  @media (max-width: 360px) {
91
    #reading-progress-badge {
92
      width: 2rem;
93
      height: 2rem;
94
    }
95


96
    #reading-progress-pct {
97
      font-size: 0.5625rem;
98
    }
99
  }
100


101
  @media (max-width: 320px) {
102
    #reading-progress-badge {
103
      width: 1.75rem;
104
      height: 1.75rem;
105
    }
106


107
    #reading-progress-pct {
108
      font-size: 0.5rem;
109
    }
110
  }
展开收起

设计要点：

  • 必须带 card-base 类：本站”卡片透明度”滑块的生效链是 --card-transparent-opacity → --card-bg-transparent → main.css 中的 .wallpaper-transparent .card-base { background-color: var(--card-bg-transparent) !important }——透明背景、卡片边框等全局设置全部通过 .card-base 类挂钩。徽章的背景/圆角/overflow 因此直接交给 card-base 提供（--radius-large 也等于 1rem），组件自身只写尺寸、毛玻璃、边框和内容布局；漏掉这个类，徽章就会游离在透明度体系之外，和其余按钮表现不一致
  • 与 .floating-btn 同规格：3rem / 1rem 圆角 / --card-bg / blur(12px) / 1px 细边框 / 尺寸断点（480→2.5rem、360→2rem、320→1.75rem）全部对齐，放进按钮栈毫无违和
  • SVG 双圆环：rp-ring-track 是底环（淡色轨道），rp-ring-value 是进度环（--primary 色、圆头线帽）。整只 SVG rotate(-90deg) 让进度从 12 点方向起笔
  • 类名必须避开 Tailwind 工具类：最初用的 .ring 正好撞上 Tailwind 的 .ring（box-shadow: 0 0 0 1px currentColor），导致 SVG 外围出现一圈橙色直角描边——详见坑 6
  • stroke-dasharray + dashoffset：dasharray = 周长 把圆环变成一条整长虚线，dashoffset 从周长（完全看不见 = 0%）收到 0（完整闭合 = 100%）
  • 数字与环同格叠放：grid-area: 1 / 1——与 FloatingButton 双图标（default/toggled 两个 SVG 同格切换）同一手法
  • font-variant-numeric: tabular-nums：等宽数字防止 9%→10% 时文字宽度抖动
  • aria-hidden="true"：纯视觉进度，避免读屏被频繁变化的数字打扰
  • 默认 display: none，.show 才 grid：非文章页徽章完全不占位，悬浮按钮栈不留空隙
  • Astro 作用域样式：.dark 和 html.is-page-transitioning 是全局祖先选择器，必须用 :global() 包裹，否则匹配不到

至此全部改动完成。

四、验证#

1. 静态检查#

Terminal window
1
pnpm type-check

预期：与本功能相关的文件 0 错误。注意本仓库存在一批存量错误（与本功能无关，改动前就存在），复现时不要误判：

  • en/ja/ko/ru/zh_TW.ts：缺 siteStatsTotalViews / siteStatsTotalVisitors 两个旧键（只有 zh_CN 有）
  • anime.astro / vndb.astro：引用了不存在的 I18nKey.anime*、siteConfig.anime、vndb.nsfw

如果在核心模块遇到 TS2322: Type 'HTMLElement | null' is not assignable to type 'SVGCircleElement'，说明漏了 Step 2 里的 as SVGCircleElement | null 断言。

2. 手动功能验证#

Terminal window
1
pnpm dev

打开任意文章页（如 /posts/markdown-extended/），逐项核对：

#操作预期
1页面加载顶部无进度条、右下角无圆环徽章
2向下滚动顶部 3px 细条从左往右生长；徽章圆环从 12 点方向顺时针填充，中心数字 N% 实时跳动
3滚到正文结束（评论区上方）细条满宽、圆环闭合成整圆、数字停在 100%
4滚回顶部细条缩回、圆环清空、数字回 0%
5导航到首页徽章和细条消失
6从首页点回文章（Swup 软导航）徽章重新出现且数值正确，无旧值闪现
7两篇文章之间切换数值立即反映新文章，不残留上一篇的百分比
8切换暗色模式方框边框与底环切换为暗色配色（rgba(255,255,255,0.15)）
9开启沉浸阅读再退出进度立即重算（监听了 immersiveReadingChange）
10窗口缩放 / 手机模拟器改视口进度立即重算；480px 以下徽章缩为 2.5rem、360px 缩为 2rem
11对比右下角其余按钮同尺寸、同圆角、同背景毛玻璃、同边框，视觉上是”第五个按钮”

3. 关闭功能验证#

把 src/config/siteConfig.ts 中 readingProgress 改为 false 后：细条和徽章的 DOM 都不再渲染，控制台无报错（initReadingProgress 查不到元素后静默空转）。

五、避坑记录#

坑 1：pnpm lint 会顺手改你的无关文件#

本仓库的 lint 脚本是 biome check --write ./src ./scripts——带 --write 的全局自动修复。实际执行时它顺带格式化了 21 个与本功能无关的文件（music-player、各种 config 等），不得不逐一 git checkout 回滚。

复现时建议只对自己的文件做只读校验：

Terminal window
1
npx biome check src/utils/reading-progress.ts src/utils/scroll-utils.ts

或者先 git stash 记下基线，跑完 lint 后用 git diff --stat 检查波及范围。

坑 2：i18n 加键必须六个语言文件同步#

本功能最终没有引入任何 i18n 文案（圆环只显示数字），但仓库里 pnpm type-check 会报一批 TS2739 存量错误——成因是 src/i18n/translation.ts 的 Translation 类型是全键映射：

1
export type Translation = {
2
  [K in I18nKey]: string;
3
};

每加一个枚举键，六个语言文件必须同时补全，漏一个就报错（存量 siteStats* 错误正是只加了枚举和 zh_CN）。复现本文时不需要动 i18n，但以后加文案要记住这条。

坑 3：进度条的调用位置不能挪#

updateReadingProgress() 必须放在 scrollFunction 中所有 class 写入之前。本站滚动管线的约定是”先批量读、再批量写”（写操作 deferred 到嵌套 rAF），如果把 rect 测量挪到写操作之后，每帧都会强制重排一次——正是 swup-transitions.ts 注释里警告过的”大型文章 DOM 同步重排”问题。

坑 4：transition 属性别写成 all#

顶部条 CSS 若写 transition: all .3s，transform 也会被过渡——进度条会滞后于滚动约 300ms。必须显式只写 transition: opacity .3s。

坑 5：SVG 半径三处联动#

圆环半径 r=15 出现在三个地方，改一个必须同步改全部：

  1. 模板 viewBox="0 0 36 36" 与 r="15"
  2. 核心模块 const RING_C = 2 * Math.PI * 15
  3. 样式 .rp-ring-value { stroke-dasharray: 94.2478 }（= 2π×15）

任何一处不一致，圆环都会填不满或超过 100%。

坑 6：类名撞了 Tailwind 工具类（真实踩坑）#

初版给 SVG 用的类名是 .ring，结果徽章外围出现一圈橙色直角描边，与预期的圆角按钮完全不像。排查过程值得记录：

  1. 先怀疑自己的 border/border-radius 没生效——抓取页面编译后的 scoped CSS，规则完整输出，排除
  2. 再全局搜索 .ring 的定义——实锤：页面 CSS（Tailwind v4）里有工具类
1
.ring {
2
  --tw-ring-shadow: ... 0 0 0 calc(1px + var(--tw-ring-offset-width)) var(--tw-ring-color, currentcolor);
3
  box-shadow: var(--tw-ring-shadow);
4
}

Tailwind 的 .ring 是焦点环工具类：box-shadow 0 0 0 1px currentColor。三个要素全部命中截图症状：

  • currentColor = 元素的 color = var(--primary) = 橙色
  • box-shadow 扩散出的轮廓是矩形（SVG 元素没有圆角）→ 直角
  • 扩散只 1px 且紧贴 SVG 边界 → 比按钮小一圈的”奇怪方框”

而且我 scoped 里的 .ring 规则只设了 width/height/transform，没设 box-shadow——两条规则各管各的属性，scoped 样式”生效了”也压不掉它。

修复：类名换 rp- 前缀（rp-ring / rp-ring-track / rp-ring-value），彻底避开 Tailwind 命名空间。JS 用的是 id="reading-progress-ring"（id 不与类名冲突），核心模块无需改动。

教训：这个项目全局启用 Tailwind，起 class 名前先搜一遍目标名字是否是 Tailwind utility（ring、grid、container、hidden、group……都是雷区）；组件内自定义类统一加项目前缀最稳。

六、文件清单速查#

复现顺序建议：配置类型 → 核心模块 → 滚动管线 → 初始化 → 顶部条 → 圆环徽章 → 验证。

1
src/types/siteConfig.ts                        +2    类型开关
2
src/config/siteConfig.ts                       +2    配置开关
3
src/utils/reading-progress.ts                  新增   核心逻辑
4
src/utils/scroll-utils.ts                      +4    每帧调用点
5
src/utils/layout-init.ts                       +2    初始化
6
src/layouts/Layout.astro                       +1    顶部条 DOM
7
src/styles/transition.css                      +31   顶部条样式
8
src/components/controls/FloatingControls.astro +107  圆环徽章 DOM + 样式

（本文即为该功能的完整实现记录，欢迎对照复现。）

]]> https://mstzuomu.space/posts/web-update-7/ 更新公告20260928 2026-09-28T00:00:00.000Z 2026-09-28T00:00:00.000Z 左沐 网站更新公告

更新公告20260928#

1.网站版本更新到6.16.7

2.新增友圈功能，聚合各位友链的最新文章，数据来自友链们的RSS订阅，数据站部署在fc.mstzuomu.space

3.新增文章阅读进度功能：页面顶部显示细进度条，悬浮按钮实时显示已读百分比与预计剩余阅读时间，只统计正文内容，横幅、评论区和推荐文章不计入

4.新增沉浸阅读模式，阅读时可一键隐藏侧边栏等干扰元素，专注正文，配合独立的沉浸目录栏使用

5.新增文章系列功能，同一系列的文章可以通过系列导航连续阅读

6.导航栏支持static、fixed、dynamic三种模式，重构了移动端导航菜单，菜单抽屉加入毛玻璃效果

7.全屏壁纸支持classic、hero两种布局，可自由切换

8.更新了网站logo和默认字体

9.修复了移动端访客数据显示异常、友链评论区Markdown渲染、音乐播放器失效、亮暗色切换面板闪烁、MDX中mermaid图表报错等问题

10.完善了SEO与结构化数据，整理了文章分类，更新了友链

11.重构了三个Markdown嵌入组件（PDF阅读器、文章内音乐播放器、哔哩哔哩卡片）：样式统一收进框架的Markdown扩展样式体系，按页面按需加载；颜色全部改用主题变量，暗色模式与主题色现在能正确跟随；文件去重，清理了散落在public目录的手写样式和脚本引入；修复文章音乐播放器在站内切页时初始化失效、歌曲信息不加载、切页后音乐不停止的问题

]]> https://mstzuomu.space/posts/azuma.zuomu-blog-12/ Firefly 博客接入友链朋友圈：从零开始的完整部署教程 2026-09-26T00:00:00.000Z 2026-09-26T00:00:00.000Z 陌殊途左沐 手把手教你为博客搭建自动更新的友链朋友圈，含全部代码改动与实战踩坑排查

Firefly 博客接入「友链朋友圈」完整部署教程#

适用对象：基于 Firefly（Astro） 主题的静态博客 + Friend-Circle-Lite（下称 FCL）友圈数据服务。 本文是实战复盘：每一步、每一处代码改动都来自真实部署过程，照做即可从零跑通。 预计耗时：1～2 小时。难度：会复制粘贴、会用命令行敲几条命令即可（文中有兜底的网页操作替代方案）。

0. 先搞懂原理：三个部分怎么协作#

友链朋友圈不是”装进博客的插件”，而是一条独立的数据流水线：

1
┌────────────────────────────┐
2
│ ① 你的博客仓库              │  展示层
3
│ Firefly (Astro)            │  /fcircle/ 页面
4
│ 每次构建生成 friend.json ───┼──┐  （你的友链名单）
5
└────────────────────────────┘  │
6
                                ▼
7
┌────────────────────────────┐  每 4 小时爬一次
8
│ ② 你的 FCL fork 仓库        │◄─┘ 读取 friend.json
9
│ GitHub Actions 定时爬虫      │──► 抓取每个友链的 RSS
10
│ 产出 all.json / link.json   │──► 推送到 page 分支
11
└──────────────┬─────────────┘
12
               │ git push (自动)
13
               ▼
14
┌────────────────────────────┐
15
│ ③ Vercel 数据站             │  托管层
16
│ 托管 page 分支的静态文件      │  https://fc.你的域名/
17
│ 提供 all.json (带 CORS 头)  │
18
└──────────────┬─────────────┘
19
               │ fetch 跨域读取
20
               ▼
21
        /fcircle/ 页面渲染友圈文章流
展开收起

职责划分：

部分负责什么技术栈
① 博客仓库新增 /fcircle/ 页面；构建时生成友链名单 friend.jsonAstro + Firefly 主题
② FCL fork 仓库每 4 小时定时爬取友链 RSS，生成数据文件Python + GitHub Actions（免费）
③ Vercel把数据文件托管成 HTTPS 静态站（带 CORS 头）Vercel 免费版

最终效果：博客上出现「友圈」菜单和 /fcircle/ 页面，自动聚合所有友链的最新文章，每 4 小时更新一次，全程无需人工干预。

1. 准备工作#

开始前确认你有：

  1. GitHub 账号 —— 托管博客仓库和 FCL fork
  2. Vercel 账号 —— 免费版即可（vercel.com 注册，可用 GitHub 登录）
  3. Cloudflare 账号 + 你自己的域名 —— 博客已解析在 Cloudflare 上（本文以 mstzuomu.space 为例，换成你自己的）

    国内访问者无法解析 *.vercel.app（被 DNS 污染），必须绑自定义域名，否则访客拉不到数据。

  4. 本机环境：
    • Node.js ≥ 22、pnpm ≥ 11（你跑得动 pnpm dev 就说明够了）
    • Git 基本操作（add / commit / push）
    • 浏览器

命令行注意（Windows）：教程里的 curl 命令请写成 curl.exe。PowerShell 里裸写 curl 会别名到 Invoke-WebRequest，参数不兼容会报错。

2. 第一部分：博客侧代码改造#

改动清单（共 10 处，先看全貌再逐个做）：

#文件操作作用
2.1scripts/generate-friend-json.ts新增从友链配置生成 FCL 需要的 friend.json
2.2package.json修改把生成脚本挂进 pnpm build
2.3public/friend.json生成执行脚本产出（会被发布到站点根目录）
2.4src/config/fcircleConfig.ts新增友圈页面配置（数据站地址等）
2.5src/config/index.ts修改导出新配置
2.6src/pages/fcircle.astro新增友圈页面本体
2.7src/types/siteConfig.ts + src/config/siteConfig.ts修改页面开关 pages.fcircle
2.8src/config/navBarConfig.ts修改导航栏「社交 → 友圈」菜单
2.9public/fclite/fclite.js、fclite.css新增FCL 前端渲染脚本（自托管 + 按 2.9 做主题化改造）
2.10—验证本地跑通 → 提交推送 → 线上验证

2.1 新增 scripts/generate-friend-json.ts#

FCL 的爬虫只认一种友链格式：{"friends": [["站点名", "网址", "头像"], ...]}。Firefly 的友链写在 src/config/friendsConfig.ts 里，所以需要一个脚本做转换。

新建文件，完整内容：

1
import fs from "node:fs/promises";
2
import path from "node:path";
3
import { getEnabledFriends } from "../src/config/friendsConfig";
4


5
// 生成 Friend-Circle-Lite 所需的友链数据文件
6
// 格式: { "friends": [["站点名", "站点地址", "头像地址"], ...] }
7
// 产物发布到站点根目录 (public/friend.json)，供 FCL 的 Action 定时拉取
8


9
const OUTPUT_FILE = path.join("public", "friend.json");
10


11
async function main() {
12
  const friends = getEnabledFriends();
13


14
  const data = {
15
    friends: friends.map((item) => [item.title, item.siteurl, item.imgurl]),
16
  };
17


18
  await fs.mkdir(path.dirname(OUTPUT_FILE), { recursive: true });
19
  await fs.writeFile(OUTPUT_FILE, `${JSON.stringify(data, null, 2)}\n`, "utf-8");
20


21
  console.log(`friend.json 已生成: ${OUTPUT_FILE} (${friends.length} 个友链)`);
22
}
23


24
main().catch((error) => {
25
  console.error("生成 friend.json 失败:", error);
26
  process.exit(1);
27
});
展开收起

它只导出 enabled: true 的友链，与 /friends/ 页面看到的列表保持一致。以后你增删友链，只要正常改 friendsConfig.ts，其余全自动。

2.2 修改 package.json#

打开 package.json 的 scripts，做两处修改：

改动 1：build 命令最前面插入生成步骤：

1
"build": "npx tsx scripts/generate-github-card-data.ts && ..."
2
"build": "npx tsx scripts/generate-friend-json.ts && npx tsx scripts/generate-github-card-data.ts && ..."

改动 2：新增一个手动执行的命令（放在 lqips 旁边）：

1
"lqips": "npx tsx scripts/generate-lqips.ts",
2
"friend-json": "npx tsx scripts/generate-friend-json.ts",

2.3 执行脚本生成 public/friend.json#

Terminal window
1
pnpm friend-json

预期输出：

1
friend.json 已生成: public\friend.json (N 个友链)   ← N 为你的友链数量

打开 public/friend.json 确认内容长这样：

1
{
2
  "friends": [
3
    [
4
      "MIFENG BLOG",
5
      "https://blog.imbee.top/",
6
      "https://blog.imbee.top/images/logo/logo.webp"
7
    ]
8
  ]
9
}

2.4 新增 src/config/fcircleConfig.ts#

1
// 友链朋友圈 (Friend-Circle-Lite) 页面配置
2
export const fcircleConfig = {
3
  // 页面标题
4
  title: "友链朋友圈",
5


6
  // 页面描述
7
  description: "聚合朋友们的最新文章，数据来自各位友链的 RSS 订阅",
8


9
  // FCL 数据站地址（fork 仓库 page 分支部署后的站点根地址，末尾必须带 /）
10
  // 部署完成后把这里改成你自己的地址，例如 https://xxx.vercel.app/
11
  apiUrl: "https://YOUR-FCL-DOMAIN.vercel.app/",
12


13
  // 每次加载文章数量
14
  pageSize: 24,
15


16
  // 头像加载失败时的默认图片
17
  errorImg: "/favicon/sakura2.png",
18
};
展开收起

⚠️ 先保持占位符不动，apiUrl 在第 6 章拿到数据站地址后再回填（本文示例最终填的是 https://fc.mstzuomu.space/）。

2.5 修改 src/config/index.ts#

加一行导出（保持字母序，放在 dynamicConfig 之后）：

1
export { dynamicConfig } from "./dynamicConfig"; // 动态页面配置
2
export { fcircleConfig } from "./fcircleConfig"; // 友链朋友圈页面配置

2.6 新增 src/pages/fcircle.astro（页面本体）#

完整内容：

1
---
2
import { Icon } from "astro-icon/components";
3
import { fcircleConfig, siteConfig } from "@/config";
4
import MainGridLayout from "@/layouts/MainGridLayout.astro";
5


6
// 检查页面是否启用
7
if (!siteConfig.pages.fcircle) {
8
  return Astro.redirect("/404/");
9
}
10


11
const title = fcircleConfig.title;
12
const description = fcircleConfig.description;
13
---
14


15
<MainGridLayout title={title} description={description}>
16
  <div
17
    class="flex w-full rounded-(--radius-large) overflow-hidden relative min-h-32"
18
  >
19
    <div class="card-base z-10 px-9 py-6 relative w-full">
20
      <!-- 页面标题和描述 -->
21
      <div class="mb-4">
22
        <div class="flex items-center gap-3 mb-3">
23
          <div
24
            class="h-8 w-8 rounded-lg bg-(--primary) flex items-center justify-center text-white dark:text-black/70"
25
          >
26
            <Icon name="material-symbols:public" class="text-[1.5rem]" />
27
          </div>
28
          <div
29
            class="text-3xl font-bold text-neutral-900 dark:text-neutral-100"
30
          >
31
            {title}
32
          </div>
33
        </div>
34
        {
35
          description && (
36
            <p class="text-base text-neutral-600 dark:text-neutral-400 leading-relaxed mb-4">
37
              {description}
38
            </p>
39
          )
40
        }
41
      </div>
42


43
      <!-- Friend-Circle-Lite 友圈文章流 -->
44
      <link rel="stylesheet" href="/fclite/fclite.css" />
45
      <div id="friend-circle-lite-root"></div>
46
      <script
47
        is:inline
48
        define:vars={{
49
          apiUrl: fcircleConfig.apiUrl,
50
          pageSize: fcircleConfig.pageSize,
51
          errorImg: fcircleConfig.errorImg,
52
        }}
53
      >
54
        window.UserConfig = {
55
          private_api_url: apiUrl,
56
          page_turning_number: pageSize,
57
          error_img: errorImg,
58
        };
59
      </script>
60
      <script is:inline src="/fclite/fclite.js"></script>
61
    </div>
62
  </div>
63


64
  <!--
65
    fclite.css 依赖 [data-theme=light]/[data-theme=dark] 切换亮暗色，
66
    而本站的 data-theme 是代码高亮主题名（one-light/one-dark-pro），
67
    亮暗切换实际由 html.dark 控制，这里做一层变量桥接。
68
  -->
69
  <style is:global>
70
    #friend-circle-lite-root {
71
      --text-color: var(--text-color-light);
72
      --background-color: var(--background-color-light);
73
      --tag-bg-color: #bfbfbf;
74
      --container-bg-color: var(--container-bg-color-light);
75
      /* 副文本（日期、统计标签、页脚）统一到主题元信息色 */
76
      --author-color: var(--content-meta);
77
      --shadow-color: var(--shadow-color-light);
78
      --border-color: var(--border-color-light);
79
      --modal-bg-color: rgba(255, 255, 255, 0.5);
80
      --modal-content-bg-color: rgba(239, 250, 255, 0.5);
81
      --load-more-btn-bg-color: var(--container-bg-color);
82
      /* 跟随站点主题色 */
83
      --hover-color: var(--primary);
84
    }
85


86
    :root.dark #friend-circle-lite-root {
87
      --text-color: var(--text-color-dark);
88
      --background-color: var(--background-color-dark);
89
      --tag-bg-color: #474747;
90
      --container-bg-color: var(--container-bg-color-dark);
91
      --author-color: var(--content-meta);
92
      --shadow-color: var(--shadow-color-dark);
93
      --border-color: var(--border-color-dark);
94
      --modal-bg-color: rgba(0, 0, 0, 0.3);
95
      --modal-content-bg-color: rgba(20, 20, 20, 0.5);
96
      --load-more-btn-bg-color: var(--container-bg-color);
97
    }
98
  </style>
99
</MainGridLayout>
展开收起

几个关键点解释（看懂可以更好 DIY）：

  • define:vars 会把 fcircleConfig 里的值序列化进内联脚本，所以改配置文件就能改页面行为，不用动这个文件。
  • 顺序很重要：window.UserConfig 的 <script> 必须写在 fclite.js 之前——fclite.js 加载时会立即读取 UserConfig，读不到会直接报错。Firefly 的 Swup 页面切换会在每次进入页面时重新执行容器内脚本，所以从别的页面切过来也能正常渲染。
  • 底部 <style is:global> 是亮暗色桥接：FCL 原版样式用 [data-theme=light/dark] 切色，而 Firefly 的 data-theme 装的是代码高亮主题名（one-light/one-dark-pro），真正控制暗色的是 html.dark 类。不加这段，暗色模式下友圈样式会错乱。

2.7 页面开关：pages.fcircle#

文件 1 src/types/siteConfig.ts，在 pages 类型里加一行：

1
pages: {
2
  booknav: boolean; // 书签导航页面开关
3
  friends: boolean; // 友链页面开关
4
  fcircle: boolean; // 友链朋友圈页面开关

文件 2 src/config/siteConfig.ts，在 resolvePageToggles 里加开关：

1
// 友链页面开关
2
friends: true,
3
// 友链朋友圈页面开关（Friend-Circle-Lite）
4
fcircle: true,

开关为 false 时：页面自动 404、导航菜单自动隐藏（前提是 2.8 的菜单项配了 pageKey）。还支持环境变量覆盖 PUBLIC_PAGES_FCIRCLE=false。

2.8 导航栏菜单：src/config/navBarConfig.ts#

改动 1，在「社交」子菜单里、友链之后插入：

1
// 友链
2
LinkPresets.Friends,
3


4
// 友链朋友圈
5
LinkPresets.Fcircle,
6


7
// 留言
8
LinkPresets.Guestbook,

改动 2，在 LinkPresets 表里、Friends 之后新增条目：

1
Friends: {
2
  name: "友链",
3
  url: "/friends/",
4
  icon: "material-symbols:link-2-rounded",
5
  pageKey: "friends",
6
},
7
Fcircle: {
8
  name: "友圈",
9
  url: "/fcircle/",
10
  icon: "material-symbols:public",
11
  pageKey: "fcircle",
12
},

2.9 自托管 FCL 前端文件 public/fclite/（含主题化改造）#

FCL 官方文档让你用 jsdelivr CDN 引脚本——国内不稳定，不要用。改为自托管：

  1. 打开你 fork 的仓库（第 3 章会讲怎么 fork），进入 main/ 目录
  2. 下载其中的 fclite.js 和 fclite.css 两个文件
  3. 在博客仓库新建目录 public/fclite/，把两个文件放进去

（也可以从上游仓库拿：https://github.com/willow-god/Friend-Circle-Lite 的 main/ 目录。）

拿到的原版文件是 FCL 自带画风（8px 圆角、灰底卡片、方角按钮），和 Firefly 主题不搭，而且不接入主题的卡片设置——拖透明度滑块、开关卡片边框对它完全无效。所以还要做两轮本地化改造（本文实战时改的，改处都留了「本地修改」注释方便日后比对）：

改造 ①：卡片接入主题卡片系统（card-base）#

原理：Firefly 的卡片透明度、卡片边框开关、主题色相底色全部通过 .card-base 类挂钩（规则在 src/styles/main.css：.wallpaper-transparent .card-base 用 !important 吃掉一切自写背景）。FCL 原版自己写死了背景/圆角/边框，把主题系统的值全压掉了。改法 = 给卡片加上 card-base 类 + 删掉它自写的那三样属性。

fclite.js 两处：

1
const randomArticleContainer = document.createElement('div');
2
randomArticleContainer.id = 'random-article';
3
randomArticleContainer.classList.add('card-base');
1
card.className = 'card';
2
card.className = 'card card-base';

fclite.css 两处（只删下面标 - 的属性行，其余保留）：

1
#random-article {
2
    display: flex;
3
    ...
4
    background-color: var(--container-bg-color);
5
    border-radius: 8px;
6
    border: 1px solid var(--border-color);
7
    padding: 20px;
1
.card {
2
    background-color: var(--container-bg-color);
3
    border-radius: 8px;
4
    padding: 12px;
5
    border: 1px solid var(--border-color);
6
    position: relative;

改完后的效果：底色 = var(--card-bg)（透明壁纸模式下自动改用滑块控制的 --card-bg-transparent）、圆角 = --radius-large（1rem，与全站卡片一致）、边框跟随「卡片边框」开关，开启时 hover 仍会变主题色高亮（原 fclite 的 hover 规则保留）。

改造 ②：内层元素统一到主题设计语言#

以下都在 fclite.css 里改。颜色一律用主题变量（用之前先在 src/styles/variables.styl 里核对存在，防止幽灵变量），对照表：

选择器对应页面元素关键改动
.stat-item订阅/活跃/文章/失败 四个统计块底色 → var(--btn-regular-bg)；边框 → 1px solid var(--line-divider)；圆角 → var(--radius-xl)；hover 边框 → color-mix(in srgb, var(--primary) 30%, transparent)
.card-author、.random-author、.random-date名字/日期胶囊改成 category-pill 同款：底 color-mix(in srgb, var(--btn-content) 6%, transparent)、边框 color-mix(in srgb, var(--btn-content) 12%, transparent)、border-radius: var(--radius-full)、文字 var(--btn-content)；hover 边框/文字 → var(--primary)
.random-button-container a「换一篇」按钮底 var(--btn-regular-bg)、边框 var(--line-divider)、圆角 var(--radius-full)、文字 var(--btn-content)；hover 底 var(--btn-regular-bg-hover)
.random-link-button「阅读文章」按钮border-radius: var(--radius-full)（底色本来就是 var(--primary)，不动）
#load-more-btn「再来亿点」加载按钮套「换一篇」同款 btn-regular 胶囊方案

最后回到 2.6 的 fcircle.astro：桥接块里 --author-color 两条映射改成 var(--content-meta)（代码已同步），日期文字、统计标签、页脚这些副文本就统一到主题元信息色，明暗自动适配。

⚠️ 这些改造都在你博客仓库的 public/fclite/ 里，不影响数据站。若日后从上游重新下载这两个文件，改造需要重新做一遍。

2.10 本地验证 → 推送上线#

本地验证（3 条命令）：

Terminal window
1
pnpm check          # Astro 诊断（既有的 i18n/anime 报错与本改动无关，可忽略）
2
pnpm lint           # Biome 检查
3
pnpm dev            # 启动后访问 http://localhost:4321/fcircle/

浏览器打开 http://localhost:4321/fcircle/，应看到：标题「友链朋友圈」、友圈数据加载中（此时 apiUrl 还是占位符，报加载失败属正常，第 6 章回填后就好）。 同时检查导航栏「社交」下多了「友圈」菜单。

提交推送：

Terminal window
1
git add .
2
git commit -m "feat: 新增友链朋友圈页面"
3
git push

推送后等 CI 构建完成（几分钟），然后用 curl.exe 线上验证两个关键地址：

Terminal window
1
# 应返回 200，且内容是你的友链名单
2
curl.exe -sL https://你的域名/friend.json
3


4
# 应返回 200
5
curl.exe -o NUL -w "%{http_code}" https://你的域名/fcircle/

friend.json 是 FCL 爬虫的输入，必须先上线，第 3 章的爬虫才能读到你的友链。顺序不能反。

3. 第二部分：Fork Friend-Circle-Lite 并配置（4 处改动）#

3.1 Fork 仓库#

  1. 打开上游仓库：https://github.com/willow-god/Friend-Circle-Lite
  2. 点右上角 Fork → Create fork（只 fork main 分支即可）
  3. 克隆到本地（换成你的用户名）：
Terminal window
1
git clone https://github.com/你的用户名/Friend-Circle-Lite.git
2
cd Friend-Circle-Lite

3.2 改动 1：conf.yaml（4 处，最重要）#

这个文件是爬虫的总配置。只改值，不动结构：

配置项原值（上游）改成说明
spider_settings.json_url"https://blog.liushen.fun/friend.json""https://你的域名/friend.json"你的友链名单地址
link_check.author_url"blog.liushen.fun""你的域名"反链检测用（只填域名不带 https）
rss_subscribe.enabletruefalse邮件订阅功能，用不到就关
rss_subscribe.github_usernamewillow-god你的GitHub用户名顺手改掉
rss_subscribe.your_blog_urlhttps://blog.liushen.fun/https://你的域名/顺手改掉
rss_subscribe.website_info.title"清羽飞扬""你的博客标题"顺手改掉

对照 diff：

1
spider_settings:
2
  enable: true
3
  json_url: "https://blog.liushen.fun/friend.json"
4
  json_url: "https://你的域名/friend.json"
5
  article_count: 5
6


7
link_check:
8
  ...
9
  enable_backlink_check: true
10
  author_url: "blog.liushen.fun"
11
  author_url: "你的域名"
12


13
rss_subscribe:
14
  enable: true
15
  github_username: willow-god
16
  enable: false
17
  github_username: 你的GitHub用户名
18
  github_repo: Friend-Circle-Lite
19
  your_blog_url: https://blog.liushen.fun/
20
  your_blog_url: https://你的域名/
21
  ...
22
  website_info:
23
    title: "清羽飞扬"
24
    title: "你的博客标题"
展开收起

这是整个部署里最容易漏、漏了后果最严重的一步。 如果忘了改 json_url，爬虫会去爬上游作者的 200 多个友链，你的友圈页面会显示一堆陌生人（本文实战就踩过这个坑，第 9 章有排查方法）。

3.3 改动 2：新增 static/vercel.json（CORS 跨域头）#

浏览器从你的博客域名跨域请求 Vercel 数据站，对方必须返回 Access-Control-Allow-Origin: *，否则数据拉不下来。

新建文件 static/vercel.json，完整内容：

1
{
2
  "headers": [
3
    {
4
      "source": "/(.*)",
5
      "headers": [
6
        {
7
          "key": "Access-Control-Allow-Origin",
8
          "value": "*"
9
        },
10
        {
11
          "key": "Access-Control-Allow-Methods",
12
          "value": "GET, POST, OPTIONS, PUT, DELETE"
13
        },
14
        {
15
          "key": "Access-Control-Allow-Headers",
16
          "value": "*"
17
        }
18
      ]
19
    }
20
  ]
21
}
展开收起

为什么放 static/ 而不是仓库根目录？因为 Actions 工作流会把 static/ 里的指定文件拷贝进 page 分支，而 Vercel 部署 page 分支时只认分支根目录的 vercel.json。下一步就是把这个文件加进拷贝清单。

3.4 改动 3：.github/workflows/friend_circle_lite.yml#

找到 Build static publish directory 步骤里的 cp 命令，在清单里加上 ./static/vercel.json：

1
- name: Build static publish directory
2
  run: |
3
    mkdir pages
4
    cp -r main ./static/edgeone.json ./static/_headers ./static/index.html ./static/readme.md ./static/favicon.ico ./static/bg-light.webp ./static/bg-dark.webp all.json link.json errors.json pages/
5
    cp -r main ./static/edgeone.json ./static/_headers ./static/vercel.json ./static/index.html ./static/readme.md ./static/favicon.ico ./static/bg-light.webp ./static/bg-dark.webp all.json link.json errors.json pages/

3.5 改动 4：.gitignore#

仓库的 .gitignore 忽略了所有 *.json（防止数据文件进主分支），需要给 vercel.json 开例外，否则它永远推不上去：

1
# 忽略数据文件
2
*.json
3
!edgeone.json
4
!vercel.json

3.6 提交并推送#

Terminal window
1
git add conf.yaml .gitignore .github/workflows/friend_circle_lite.yml static/vercel.json
2
git commit -m "fix: 友链数据源指向本站并为 page 分支添加 Vercel CORS 配置"
3
git push

⚠️ 核对清单：git status 确认这 4 个文件都进了提交。实战中曾出现”以为推了实际没推”的情况，导致爬虫用了上游的友链列表。推完可以去 GitHub 网页上点开 conf.yaml 确认 json_url 已经是你的域名。

4. 第三部分：启用 GitHub Actions，生成 page 分支#

FCL 的数据完全由 GitHub Actions 定时生成，部署在免费额度内（公开仓库无限，私有仓库每月 2000 分钟，这个爬虫每次不到 2 分钟，绰绰有余）。

4.1 启用工作流（fork 有两道开关，都要点！）#

开关 ①：打开 https://github.com/你的用户名/Friend-Circle-Lite/actions 顶部会有条黄色提示 “Workflows aren’t being run on this forked repository…” → 点 “I understand my workflows, go ahead and enable them”。

开关 ②（很多人卡在这）：左侧工作流列表里，Friend Circle Lite 可能仍显示 「已禁用」（fork 特有的 disabled_fork 状态）—— → 点击左侧的 Friend Circle Lite → 工作流页面点绿色 “Enable workflow” 按钮。

只启用开关 ① 不启用开关 ②，手动触发会报 422 Cannot trigger a 'workflow_dispatch' on a disabled workflow。

4.2 手动运行一次#

  1. 左侧点 Friend Circle Lite
  2. 右上角 Run workflow → 下拉选 main → 点绿色 Run workflow
  3. 等 1～2 分钟刷新，看到绿色 ✅ success 即可（首次运行要下载依赖，慢一点正常）

这次运行会：

  • 读取你博客上线的 friend.json（你的友链名单）
  • 检测每个友链可达性 + 抓取 RSS 文章
  • 生成 all.json / link.json / errors.json
  • 强制推送 page 分支（首次创建）

4.3 验证 page 分支#

打开 https://github.com/你的用户名/Friend-Circle-Lite/tree/page，确认存在：

  • all.json（点开能看到 "friends_num": 你的友链数）
  • link.json
  • vercel.json（重点：没有它 CORS 会挂）
  • main/、index.html 等静态文件

5. 第四部分：Vercel 部署数据站#

5.1 导入仓库#

  1. 登录 vercel.com → Add New… → Project
  2. 在仓库列表里找到 Friend-Circle-Lite 点 Import（首次会让你安装/授权 Vercel 的 GitHub App，按提示授权）
  3. 构建配置全部保持默认即可（main 分支没有构建步骤，仓库根目录的 vercel.json 里 deploymentEnabled.main: false 会让它跳过 main 分支的部署——这是上游作者设计好的）
  4. 等导入完成

5.2 把生产分支改成 page（关键步骤）#

进入项目 → Settings → Environments → Production，找到 Branch Tracking：

  • 把分支从 main 改成 page → 点 Save

两个坑：

  1. 报错 Branch "page" not found in the connected Git repository —— 说明第 4 章还没跑成功、page 分支不存在。回去先完成第 4 章再来。
  2. 新版 Vercel 界面里没有单独的 “Production Branch” 选项（旧教程会误导你去 Git 页找）——它就在上面说的 Environments → Production → Branch Tracking 里。找不到就用 Settings 页左侧顶部的 Find 搜索框搜 production。

5.3 首次生产部署#

保存成功后 Vercel 通常会弹出 Redeploy 对话框：

  • 环境选 Production
  • 源部署选带 page 分支标记的那条（列表里最新的）
  • 点 Redeploy

如果没弹窗，去 Deployments 页找到 page 分支的那条部署 → 右侧 … → Promote to Production。

完成后，项目的生产地址（形如 friend-circle-lite-xxx.vercel.app）就由 page 分支驱动了——以后 Actions 每次推送，Vercel 自动部署，无需任何手动操作。

5.4 绑定自定义子域名（国内必做）#

为什么必须：*.vercel.app 域名在国内被 DNS 污染（解析出假 IP），你的访客会全部加载失败。实测必须绑自有域名。

第 1 步 — Vercel 侧添加域名：

项目 → Settings → Domains → 输入你想用的子域名（例：fc.你的域名）→ Add。 添加后 Vercel 会提示需要一条 CNAME 记录（目标是 cname.vercel-dns.com）。

第 2 步 — Cloudflare 侧加 DNS 记录：

Cloudflare 控制台 → 你的域名 → DNS → Records → Add record：

字段填写
TypeCNAME
Namefc（对应 fc.你的域名 的前缀）
Targetcname.vercel-dns.com
ProxyDNS only（一定选灰云，不要开橙色云代理）
TTLAuto

第 3 步 — 回 Vercel 等证书签发：

DNS 生效通常 1～5 分钟。如果域名状态显示证书错误，点 Refresh / 重新保存一次域名即可触发重新签发。

验证：

Terminal window
1
# 应返回 200，并且能看到 Access-Control-Allow-Origin: *
2
curl.exe -sI https://fc.你的域名/all.json

响应头里必须有这一行，缺了就回头检查 page 分支上有没有 vercel.json（第 3.3/3.4 步）。

6. 第五部分：回填数据站地址，全线贯通#

打开 src/config/fcircleConfig.ts，把占位符换成你的真实数据站地址（末尾的 / 不能少）：

1
// FCL 数据站地址（fork 仓库 page 分支部署后的站点根地址，末尾必须带 /）
2
apiUrl: "https://YOUR-FCL-DOMAIN.vercel.app/",
3
apiUrl: "https://fc.你的域名/",

提交推送：

Terminal window
1
git add src/config/fcircleConfig.ts
2
git commit -m "feat: 回填友圈数据站地址"
3
git push

等博客 CI 部署完成（几分钟），最终验证：

Terminal window
1
# 1. 页面 HTML 里已包含新地址
2
curl.exe -sL https://你的域名/fcircle/ | findstr "fc.你的域名"
3


4
# 2. 数据接口 200 + CORS + 你的友链数
5
curl.exe -sI https://fc.你的域名/all.json

浏览器打开 https://你的域名/fcircle/ —— 看到自己朋友们的最新文章，部署完成 🎉

页面如果还显示旧数据/加载失败：FCL 前端有 10 分钟 localStorage 缓存，等 10 分钟再刷新，或开无痕窗口立即查看。

7. 成品验收清单#

逐项打勾，全过即部署成功：

#检查项验证方法预期
1友链名单已上线curl.exe -sL https://你的域名/friend.json200，friends 数量 = 你的友链数
2页面已上线浏览器打开 /fcircle/200，标题「友链朋友圈」
3导航菜单导航栏「社交」下拉有「友链」和「友圈」两项
4Actions 正常fork 的 Actions 页最近一次运行是绿色 success
5page 分支github.com/你/Friend-Circle-Lite/tree/page有 all.json / link.json / vercel.json
6数据站可达curl.exe -sI https://fc.你的域名/all.json200 + Access-Control-Allow-Origin: *
7数据是你的友链浏览器打开 https://fc.你的域名/all.jsonfriends_num = 你的友链数，作者都是你朋友
8文章渲染无痕窗口打开 /fcircle/文章卡片正常显示，点「换一篇」「阅读文章」可用
9自动更新等一个 cron 周期（≤4 小时）后看 last_updated_time时间刷新
10亮暗色切换博客暗色模式友圈样式跟随切换、无错乱
11卡片跟随主题设置拖「卡片透明度」滑块、开关「卡片边框」统计面板与文章卡片底色/边框同步变化（未做 2.9 改造则此项不过）

8. 自动化之后：日常运行说明#

部署完成后你什么都不用做，全自动链路：

1
每 4 小时 (cron: 22 */4 * * * UTC，即北京时间 00:22 / 04:22 / 08:22 / 12:22 / 16:22 / 20:22)
2
   └─ GitHub Actions 爬虫运行
3
        ├─ 检测友链可达性（结果缓存 24 小时，不会频繁骚扰友链站点）
4
        ├─ 抓取各站 RSS 最新文章
5
        ├─ 生成 all.json / link.json
6
        └─ 推送 page 分支
7
             └─ Vercel 自动生产部署 → fc.你的域名 更新
8
                  └─ 博客 /fcircle/ 下次访问即是新数据

常见日常操作：

  • 改了友链配置：改 friendsConfig.ts → 推送博客（friend.json 自动更新）→ 下一个爬虫周期生效。想立即生效就去 fork 的 Actions 手动 Run workflow 一次。
  • 想手动立刻刷新数据：fork → Actions → Friend Circle Lite → Run workflow，约 90 秒完成并自动上线。
  • 看哪些友链挂了：打开 https://fc.你的域名/（FCL 自带的展示首页有可达性列表），或看博客友圈统计里的「失败」数。

数据字段含义（友圈顶部统计条）：

字段含义
订阅友链总数
活跃可达且能抓到 RSS 的站点数
文章聚合的文章总数
失败不可达 / 没有 RSS / 抓取失败的站点数（有几台挂了属正常现象，不是你的部署问题）

9. 踩坑排查表（本文实战遇到的全部问题）#

现象原因解决
Actions 页显示「无工作流程运行」，列表里工作流带「已禁用」fork 仓库有两道开关：仓库级启用 + 单个工作流启用第 4.1 章：先点 “I understand my workflows…”，再进工作流页点 “Enable workflow”
手动触发报 422 Cannot trigger a 'workflow_dispatch' on a disabled workflow同上，第二道开关没开同上
Vercel 报 Branch "page" not foundpage 分支还不存在先成功运行一次 Actions（第 4 章），再回来保存
找不到 “Production Branch” 设置Vercel 新版 UI 已移动位置Settings → Environments → Production → Branch Tracking；或左侧 Find 搜 production
友圈显示的全是陌生人（200+ 订阅，作者都不认识）conf.yaml 的 json_url 还指向上游作者的友链列表（改动没推送成功）改 conf.yaml → git add 确认 → 推送 → 手动 Run workflow → 核对 page 分支 all.json 的 friends_num
友圈页面一直加载中/加载失败apiUrl 占位符没回填、末尾漏 /、或数据站 CORS 头缺失第 6 章回填；curl.exe -sI 检查 Access-Control-Allow-Origin: *；确认 page 分支有 vercel.json
数据站地址国内打不开*.vercel.app 被 DNS 污染第 5.4 章绑定自定义子域名（CNAME 到 cname.vercel-dns.com，灰云）
页面数据是旧的fclite.js 有 10 分钟 localStorage 缓存 + 浏览器缓存等 10 分钟或无痕窗口刷新
友圈数据突然变回旧数据（或又出现陌生人文章）Vercel 的 Redeploy 弹窗里选中了历史旧部署并发布，生产被回滚Deployments 列表核对最新一条 page 部署的时间 → 对最新的那条执行 … → Promote to Production；别选日期是几天前的部署
证书签发失败 / 域名一直 PendingDNS 还没生效等 1～5 分钟，在 Vercel Domains 页 Refresh 重试；确认 Cloudflare 里是灰云
PowerShell 里 curl -sI 报”参数无效”PS5.1 把 curl 别名成 Invoke-WebRequest一律写 curl.exe
pnpm check / type-check 一堆报错项目既有问题（i18n 缺键、anime/vndb 页）与本教程无关，只看你新增文件有没有报错
pnpm lint 把一堆无关文件改了格式biome check --write 会顺手格式化git checkout -- <无关文件> 还原，只保留自己的改动
本机构建报 unable to verify the first certificate（OG 图片生成）本机网络环境的 TLS 证书链问题set NODE_OPTIONS=--use-system-ca 后重跑，或忽略（CI 上不会出现）
本地跑 FCL 爬虫报 ZoneInfoNotFoundError: Asia/ShanghaiWindows 的 Python 缺 tzdata 包pip install tzdata（见附录 B）

10. 安全收尾（推荐）#

如果你在部署过程中用过 API Token（比如为了用 CLI 部署临时生成的 Vercel Token）：

  1. vercel.com → Settings → Tokens → 删除用完的 token
  2. 清理本机临时凭据文件（如果有）
  3. 检查 fork 仓库：Settings → Actions → General → Workflow permissions 确认是 Read repository contents and permissions（本教程的工作流文件里已显式声明 contents: write，够用，无需给默认权限开写）

附录 A：文件改动总清单#

博客仓库（FireflyPriWeb）：

文件操作
scripts/generate-friend-json.ts新增
package.json修改（build 链 + friend-json 命令）
public/friend.json脚本生成（勿手改）
src/config/fcircleConfig.ts新增
src/config/index.ts修改（+1 行导出）
src/pages/fcircle.astro新增
src/types/siteConfig.ts修改（pages.fcircle 类型）
src/config/siteConfig.ts修改（pages.fcircle 开关）
src/config/navBarConfig.ts修改（Fcircle 菜单项 ×2 处）
public/fclite/fclite.js、fclite.css新增（从 fork 的 main/ 目录复制，并按 2.9 完成两轮主题化改造）

FCL fork 仓库：

文件操作
conf.yaml修改（json_url / author_url / rss_subscribe 共 6 处值）
static/vercel.json新增
.github/workflows/friend_circle_lite.yml修改（cp 清单 +1 文件）
.gitignore修改（!vercel.json）

平台侧配置（非代码）：

位置操作
GitHub fork → Actions启用仓库 workflows + 启用 Friend Circle Lite 工作流
Vercel 项目 → EnvironmentsProduction 分支 = page
Vercel 项目 → Domains添加 fc.你的域名
Cloudflare DNSCNAME fc → cname.vercel-dns.com（灰云）
博客 fcircleConfig.apiUrl回填数据站地址

附录 B（可选方案）：不用 GitHub Actions，本地 Python 爬虫手动部署#

适用于：想本地先跑通看看效果，或不想用 Actions 的场景。

Terminal window
1
cd Friend-Circle-Lite
2
python -m venv .venv
3
.venv\Scripts\python.exe -m pip install -i https://pypi.tuna.tsinghua.edu.cn/simple requests feedparser PyYAML jinja2 python-dateutil tzdata
4
.venv\Scripts\python.exe run.py        # 生成 all.json / link.json / errors.json

注意两点：

  • 国内直连 PyPI 会超时，务必加清华镜像 -i https://pypi.tuna.tsinghua.edu.cn/simple；Windows 必须装 tzdata。
  • 生成后把 main/、static/ 下的指定文件、vercel.json 和三个 json 拷到一个目录，用 Vercel CLI 部署：
Terminal window
1
npm install vercel --registry=https://registry.npmmirror.com   # npmjs 被墙时用 npmmirror
2
vercel deploy --prod --token=你的token

但此方式数据不会自动更新（每次都要手动跑），正式使用推荐本文正文的 GitHub Actions 方案。

附录 C：把本文发布到你的博客#

想把这篇教程作为博客文章发布：

Terminal window
1
pnpm new-post

把本文内容粘进生成的 md 文件，补上 frontmatter（标题、日期、分类、标签），放 src/content/posts/ 下推送即可。若你的博客启用了友圈失败站点的评论系统接入，按 Firefly 惯例在 frontmatter 加 comment: true。

教程基于实战部署整理：Firefly 6.16.7 + Friend-Circle-Lite（v2.x）+ Vercel Hobby + Cloudflare DNS。文中示例域名 mstzuomu.space / fc.mstzuomu.space 请替换为你自己的。

]]> https://mstzuomu.space/posts/azuma.zuomu-blog-11/ MiMo-V2.6：扩展强化学习规模，迈向自我提升 2026-09-22T00:00:00.000Z 2026-09-22T00:00:00.000Z 陌殊途左沐 全新MIMO模型发布

MiMo-V2.6：扩展强化学习规模，迈向自我提升#

来源：Xiaomi MiMo 文档中心 ｜ 更新时间：2026 年 09 月 22 日

今天，我们正式发布并开源 Xiaomi MiMo-V2.6 系列。这是我们探索 RSI（递归自我改进）路径的关键一步：以可验证的复杂任务为基础，规模化扩展强化学习（RL）算力，让模型在持续的探索与反馈中不断拓展智能边界。

夫夷以近，则游者众；险以远，则至者少。在一个智能容易被复制的时代，我们选择把算力投进真实环境，让模型在反馈中一次次试错、自己学会。这条路更慢，也更少被看见。MiMo-V2.6 这 6 天的 Live RL 训练，是我们在这条路上的一次公开跋涉；而这 6 天的背后，是长达半年的基础研究积累和工程试错。

MiMo-V2.6 系列包含 Pro 和 Flash 两个原生全模态模型。得益于 RL 算力的扩展，MiMo-V2.6-Pro 在 Artificial Analysis Intelligence Index（AA 综合智能指数）中取得 46 分，超过 Kimi K3 和 Qwen3.8 Max，成为当前最强的开源模型；但与最强的闭源模型 Claude Fable 5.1 和 GPT-6 Astra 相比，仍有差距。

综合智能指数对比
综合智能指数对比

MiMo-V2.6 系列沿用 V2.5 系列的 API 定价。智能提升，价格不变，“智能-成本”的帕累托前沿由此再度向外推进。MiMo-V2.6-Pro 刷新了国产模型的性价比纪录：在同等智能水平下，价格仅为海外模型的 1/20 至 1/60。

智能与成本对比
智能与成本对比

大规模扩展 RL 并全面开源#

在 RL 训练阶段，MiMo-V2.6 可能是目前国产开源模型中投入算力最多的模型之一。经过大规模、多任务强化学习训练，MiMo-V2.6-Pro 在多数 Agent Benchmark 上取得了比肩 Claude Opus5 和 GPT-5.6 Sol 的效果，MiMo-V2.6-Flash 则全面超越 MiMo-V2.5-Pro。

Agent Benchmark 对比
Agent Benchmark 对比

整个过程中，我们攻克了 RL 训练中的基础研究与工程挑战，并通过 Live 分享正式实验历程。历时不到 6 天，MiMo-V2.6-Flash 与 MiMo-V2.6-Pro 训练成本分别约 85 万与 262 万美元，各完成 30 步，累计约 75 万条轨迹；训练任务平均通过率分别相对提升 25% 和 12%，样本外的长程软件工程评测基准 DeepSWE v1.1 分别提升约 17 分（48.8 → 65.7）和约 14 分（58.4 → 72.6），体现出 RL 较高的样本效率、持续改进能力和样本外的泛化能力。

DeepSWE v1.1 提升
DeepSWE v1.1 提升

本次训练主要从三个维度扩展 RL 算力：

  • 更大的 Batch 与更高吞吐：结合大 Batch 和全异步架构，单次更新使用 1,568 个样本，支持 1M 上下文长度训练，单步训练 Token 达 3.5～3.7B。
  • 更多任务与复杂环境：构建覆盖 Code、General、Visual、Cyber 等方向的多任务训练体系，并混合多个 Harness，促进不同能力维度协同提升。
  • 更大的 Grader 算力：通过 Group 内相对比较，为 Long-Horizon RL 任务提供更精准、多样的奖励信号，形成模型自我改进闭环，并引导模型以更短路径、更少 Token 完成任务。

随着训练规模扩大，我们冻结 MoE Router 以抑制专家负载漂移，并建立覆盖奖励设计、对抗性评测、异常检测和验证器交叉校验的 Reward Hacking 防线，提升训练稳定性与奖励可靠性。

为支撑大规模混合任务的智能体强化学习，我们设计统一的轨迹表示与惩罚机制来细化学习信号，支撑多种智能体框架的高并发交互，解耦控制面与数据面以支持海量轨迹的迁移，在混合批次中稳定各任务的样本配比，并优化训练与推理引擎的效率及它们的一致性。

我们已开源上述技术成果及配套资源，包括完整技术报告、训练环境与 RL 代码，帮助更多研究者复现和验证相关结果，共同探索规模化 RL 与模型自我改进的更多可能。

从 Vibe Coding 到 Vibe World#

MiMo-V2.6 融合了 3D 空间推理、多模态感知与计算机操作（CUA）能力，进一步拓展了编程所能触及的边界，它可以将自然语言驱动的编程任务拓展为面向交互世界构建的”Vibe World”。

3D 开放世界游戏#

在游戏开发中，用户输入图片、视频或文字后，MiMo-V2.6 会将需求拆解为多个任务，由多智能体协作完成游戏 3D 场景搭建、交互逻辑编写与视觉验证，并根据渲染结果不断修正，最终生成符合用户意图的可运行交互世界。

Blender 3D 建模#

MiMo-V2.6 能够根据用户的文字描述或参考图片，在 Blender 中完成物体与场景的三维建模，生成可用于动画制作、3D 打印与游戏开发的 3D 资产。

具身智能#

在具身仿真环境中，MiMo-V2.6 可以直接以多视角相机画面为输入，持续进行推理与决策，并通过视觉反馈闭环控制 Franka Panda 机械臂，完成物体抓取、颜色匹配与精准放置。

Computer Use Agent#

MiMo-V2.6 进一步拓展了 Computer Use 能力，将多模态感知与原生训练的行动能力相结合。它可以理解复杂的图形界面，使用常见办公与生产力工具，完成信息检索、编辑和数据处理等任务，并根据视觉反馈检查结果、排查问题、调整后续行动。

推动前沿科学研究#

未经针对科研任务的专项强化学习训练，MiMo-V2.6 已在多个研究领域展现出应用潜力。从材料设计到数学形式化，以下案例展示了模型如何将推理、编程与工具使用能力应用于具体科研任务。

材料科研的 Co-Scientist#

MiMo-V2.6-Pro 协助研究人员完成材料设计与计算筛选。在小米前沿材料研究团队的多轮提示与交互下，它提出了数种金属有机框架（MOF）材料的设计方案，目标是吸附被称为”永久性污染物”的全氟和多氟烷基物质（PFAS）。在这一过程中，模型检索并梳理相关文献与专利，提出研究假设，并评估设计方案的新颖性。

随后，它进一步开展了”干实验”：即调用开源计算工具，自动搭建模拟环境，计算设计出的 MOF 材料与 PFAS 之间的结合强度，从中筛选出最有潜力的候选材料，以供后续”湿实验”验证。

MOF 材料设计干实验演示
MOF 材料设计干实验演示

形式化数学证明#

MiMo-V2.6-Pro 协助研究员，在 Lean 4 中完成了 Li–Yorke 经典论文《周期三蕴含混沌》原始主定理的完整形式化。该定理揭示：对于连续的区间自映射，一个三周期轨道的存在，就足以推出所有正整数周期的轨道，以及一个不可数的混沌集。

在研究员设计的探索策略引导下，MiMo-V2.6-Pro 通过 Sub-Agent 协作推进了定理叙述与证明的形式化。经后续修订与整合，项目最终形成了 6000 余行 Lean 源码，完整证明通过 Lean 内核核验，无未完成证明占位。模型未接受过针对 Lean 的专项后训练，这一案例展示了其参与复杂形式化证明任务的能力。

Lean 4 形式化证明过程
Lean 4 形式化证明过程

代码驱动的内容创作与审美表现#

MiMo-V2.6 系列大幅提升了模型创建精美数字产品的能力，涵盖包括前端网页、Figma 设计稿、幻灯片、SVG、视频、音乐等在内的方方面面。在设计评测榜单 Design Arena 上，MiMo-V2.6-Pro 取得了与 Claude Opus 5、GPT-5.6 Sol 相近的水平。

Design Arena 设计评测
Design Arena 设计评测

前端 & PPT 的审美表现#

MiMo-V2.6 可以将简单的指令转化为完整的前端界面和 PPT，生成结构化的布局并精心设计美观的组件、交互元素和丰富的动画效果。还熟练运用 Figma 和图像/视频生成工具，制作符合整体风格的视觉素材，在字体、配色和图文编排上保持协调，兼顾审美表现与阅读、交互体验。

视频创作#

MiMo-V2.6 能够端到端完成高质量视频创作。在创意与产品宣传视频中，MiMo-V2.6 可根据用户需求完成视觉设计、镜头与动效编排、配乐合成及节奏卡点；在科普视频中，它能将傅里叶分解（Fourier Decomposition）、凸包（Convex Hull）等抽象概念转化为通俗解说与连贯动画，并调用 MiMo-V2.5-TTS 合成旁白，与画面精准对齐，从而将复杂知识转化为观众可轻松理解的生动内容，实现从概念拆解到成片输出的全流程自动化。

音乐创作#

在 MiMo-V2.6 中，我们进一步强化了模型的音乐理解、审美判断与知识运用能力，探索模型在音乐创作中的应用。它已展现出创作 Demo 级音乐作品的能力，以及辅助专业作曲与编曲人员开展创作的潜力。

在这一案例中，MiMo-V2.6-Pro 根据要求创作了一首包含约十种乐器的管弦乐作品，完成乐谱生成后，自主将其转换为 MIDI。作品体现了模型对不同乐器分工与配器关系的理解，也展示了它将音乐知识用于旋律创作和整体编排的能力。

开始使用#

使用 Xiaomi MiMo Desktop 桌面客户端#

随着新模型发布，MiMo Desktop 桌面客户端及会员订阅方案同步上线，欢迎通过下方链接下载体验。订阅会员即可使用 MiMo-V2.6-Pro 和 Flash 模型，也可配置自己的 API Key 使用客户端。

🔗: https://mimo.xiaomimimo.com/desktop/

MiMo Desktop 同步上线 MiMo-V2.6-Pro 的 UltraSpeed 超高速模式，提供最高 20 倍的推理速度，满足强实时交互与对响应速度敏感的场景。

原邀测活动将在 1 周后结束，已获得邀测资格的用户切换模型名称后方可继续使用。

接入 Xiaomi MiMo API#

同时，MiMo-V2.6 系列已上线 Xiaomi MiMo 开放平台，API 价格维持不变。

MiMo-V2.6-Pro 同样于开放平台提供 UltraSpeed 超高速模式，提供最高 20 倍的推理速度。

模型定价如下：

模型定价
模型定价

全面开源#

我们全面开源 MiMo-V2.6-Pro、Flash 模型权重与技术报告，同步开放 MiMo-V2.6-Distill-Qwen-9B 及配套 RL 研究资源，分享经过验证的训练实践，以下是详细开源内容：

  • 7k+ 高质量 RL 任务环境：覆盖软件工程、漏洞复现、知识型工作、网页设计开发四类智能体任务。以 MiMo-V2.6-Distill-Qwen-9B 为起点展开 RL 训练，在 11 项评测中均较 SFT 基线取得提升：SWE-bench Verified 从 61.1 提升至 66.2，MiMo Cyber Bench 从 31.3 提升至 47.0，Terminal Bench 2.1 从 37.1 提升至 52.8，MiMo Visual Coding 从 64.0 提升至 72.4；
  • 端到端 RL 训练框架：基于 verl、uni-agent 和 mini-swe-agent，覆盖环境交互、轨迹采集、奖励评估与策略优化的完整训练流程。结合开放的模型与任务环境，支持社区围绕训练算法、奖励机制和 agent harness 开展研究与迭代；
  • 轻量可组合的 Harness：开源极简 mini-harnesses，将系统提示、工具与上下文管理解耦，构建多样且可控的训练配置。通过 Multi-Harness Training，能够将多样性和整洁性纳入 RL 训练，提升模型在不同框架、包括未见框架上的泛化能力，支持社区自由组合框架组件、拓展训练配置，持续探索新的研究方向。

开源内容概览
开源内容概览

希望这次分享能为社区持续探索强化学习算法与智能体机制提供共同基础，推动 Agentic RL 研究不断向前。

开源链接：https://huggingface.co/collections/XiaomiMiMo/mimo-v26

注意：调用 API 时请使用全小写模型名 mimo-v2.6-pro、mimo-v2.6-flash、mimo-v2.6-pro-ultraspeed。

]]> https://mstzuomu.space/posts/azuma.zuomu-blog-10/ 零基础部署Codex接入第三方大模型API 2026-09-13T00:00:00.000Z 2026-09-13T00:00:00.000Z 陌殊途左沐 让你的Codex更换大脑

OpenAI Codex 作为强大的代码生成、解释、调试智能工具，默认依赖官方接口，存在访问限制、调用成本高、国内适配差等问题。通过接入第三方大模型API（DeepSeek、MiniMax、通义千问、聚合API等），可完美替代官方接口，实现无限制调用、低成本落地、适配国内网络环境，同时完整保留 Codex 的代码补全、项目分析、智能问答、工程优化等核心功能。

本文为零基础保姆级教程，主要方便零基础小白进行部署，实际在国内网络能主动访问到本博客的人也不需要本教程 哈哈！

前置准备#

点击相应文本可跳转下载

python : 编写脚本、处理数据、自动化任务、开发后端、运行测试，也能生成 Excel、PDF、图表等文件。

Git : 查看代码改动和历史、对比版本、创建提交、处理分支，帮助安全地管理项目。

node.js : 开发和运行网页、前端及 JavaScript/TypeScript 项目；安装依赖、执行构建、测试和代码检查。

vscode : 方便查看和继续编辑codex修改的代码、运行程序、调试问题。

python部署教程#

  1. 访问python，点击downloads，出现新界面后点击python 3.14.6(默认下载推荐版本即可，注意不要点击Python install manager)

  2. 下载完成后双击安装包

推荐通过Customize installation进行安装，可以自定义安装位置。Install Now是默认安装到C盘。 同时勾选下方的两个选项

  • Use admin privileges when installing py.exe
  • Add python.exe to PATH
  1. 直接点击Next

  1. 自定义安装路径

5. 安装完成后关闭窗口即可

Git部署教程#

  1. 访问Git 点击install，选择对应的系统下载，点击Click here to download

如果你在国内的网络下载Git过慢，并且没有加速器，可以选择清华大学开源软件镜像站 | Tsinghua Open Source Mirror找到Git for windows下载安装即可。

  1. Git安装相对简单，下载完成安装包后一直点击Next即可，无需修改设置

node.js部署教程#

  1. 访问Node.js — 在任何地方运行 JavaScript,点击获取Node.js

  1. 点击Windows安装程序即可获取下载。

  2. 下载完成安装包后选择安装路径，无需修改设置直接默认安装即可。

VS Code部署教程#

  1. 访问Visual Studio Code - 开源的 AI 代码编辑器 |你多智能体开发的家园，点击Windows版下载
  2. 下载完成后打开安装包，选择安装路径后安装即可。
  3. VScode默认为英文，切换中文可以按如下操作
  • 点击左侧工具栏的扩展，在弹出的搜索界面搜索chinese
  • 点击安装，安装完成后右下角会弹出引导提示，跟随提示重启VScode即可

Codex部署#

  1. 访问ChatGPT 中的 Codex | 专为软件工程打造的 AI 编程智能体点击下载Windows版。注意！国内网络不支持访问Codex官网，请自行解决该问题。

  2. 如果您无法解决网络问题，可以通过微软商店下载。本文提供微软镜像下载方法，您可以通过本站“我的—书签导航—工具”找到Microsoft商店 - 世代项目（v1.2.3）[由@rgadguard提供]在该网站内键入

1
https://apps.microsoft.com/detail/9plm9xgg6vks?hl=zh-CN&gl=CN

选择适合你的安装包

如无特殊设备，选择x64版本的msix文件下载即可

警告：如果选择此方式安装，请勿将系统的默认安装位置C盘修改成其他盘，微软商店不支持修改安装位置，否则会无法安装或无法正常使用

第三方大模型 API Key获取#

目前市面上有许多主流大模型，如豆包太蠢了哈哈！千问、文心一言、智谱GLM、DeepSeek、Kimi。本文以小米MiMo模型为例演示如何让获取API KEY，推荐读者使用智谱，GPT等模型，不考虑价格因素，目前是市面上相对较强的模型。

  1. 访问Xiaomi MiMo Home，点击API接入
  2. 点击API KEYS—新建API KEY—输入KEY的名称，随后即可生成API KEY
警告：API KEY只会出现一次，请及时复制之后保存。
  1. 将API KEY填入CC Switch，如果您不想使用CC S作为API中转，可以根据不同Agent的官方文档教程来进行部署，本文不作介绍。

CC Switch部署#

访问CC Switch 官方网站 - AI 编程工具统一管理平台，下载安装即可

CC Switch快速上手#

第一步：添加供应商#

  1. 点击主界面右上角的 + 按钮
  2. 在「预设」下拉框中选择你的供应商 • 常用预设：智谱 GLM、MiniMax、DeepSeek、Kimi、PackyCode • 或选择「自定义」手动配置
  3. 填写 API Key
  4. 点击「添加」

第二步：切换供应商#

添加完成后，供应商会出现在列表中。

方式一：主界面切换

  • 点击供应商卡片的「启用」按钮

方式二：托盘快速切换

  • 右键系统托盘图标
  • 直接点击供应商名称

完成以上步骤后，您可以自由的使用Codex接入的第三方API，请注意每次启动Codex之前都需要开启CC Switch

]]> https://mstzuomu.space/posts/azuma.zuomu-blog-9/ MIMO CODE客户端发布 2026-09-09T00:00:00.000Z 2026-09-09T00:00:00.000Z 陌殊途左沐 属于MIMO的客户端即将发布

前言#

就在今天下午，小米官方通过邮件发文：面向个人开发者的桌面客户端 Xiaomi MiMo Desktop 正式开放邀测。

MiMo Desktop 是一款面向真实工作场景的桌面 AI 应用：接收多格式素材输入，理解目标，拆解任务，调用工具，交付高可用度成果，并支持实时预览与修改。我们希望通过真实任务，验证它在长链路执行、工具调用、交付质量和使用体验上的边界，并据此持续迭代。

核心能力#

  • 从回答问题到交付成果：表格、图片、视频、PDF、录音甚至压缩包都可直接作为输入；MiMo Desktop 理解素材、拆解任务、调用工具，交付可继续编辑的文档、表格、幻灯片、网页、图片、音频、视频、3D 模型、App 或软件工程项目。
  • 可直接交互的预览界面：成果预览不是静态截图，而是可点击、操作和继续修改的完整页面，支持在会话中实时运行和迭代。
  • 在成果上继续工作：选中任意元素即可用自然语言提出修改要求，系统只处理选中部分并保留版本记录，可随时回退到此前版本。
  • Smart 调度：自动评估任务类型、复杂度与成本，在标准与旗舰模型之间动态路由，并按需匹配 Harness、Agent 与 Skill；复杂任务可拆解给多个 Agent 并行推进。
  • 浏览器操控：自主控制浏览器检索信息、提取素材、填写表单，信息直接进入当前任务；生成网页类成果后可自动检查关键交互。
  • 让长任务成本可控：模型路由、局部编辑与上下文缓存减少不必要消耗，同会话缓存命中率最高可达 99%，跨会话最高可达 95%。

新模型抢先体验#

邀测期间，通过申请的用户可限时、限量、免费体验两款 Xiaomi MiMo 新一代模型（代号：MiMo-X-Pro-Preview、MiMo-X-Flash-Preview）。MiMo-X 系列面向真实专业工作场景优化，重点覆盖复杂任务推理、多 Agent 协作、大型编程项目、Office、网页设计、前端与交互设计、视频剪辑、3D 生成、音乐生成、电脑操控等。目前仍处于预览测试阶段，能力表现可能随版本迭代变化。

如何加入邀测#

访问申请链接并提交申请。审核通过后，即可下载和使用 MiMo Desktop。本次邀测将优先面向 Xiaomi MiMo 开放平台已有用户开放。

Xiaomi MiMo Desktop 暂不在欧盟、英国及韩国提供服务，来自相关区域的用户登录时会收到“该地区暂不支持”的提示。

我们相信，AGI 的意义不止于理解世界，更在于帮助每个人创造世界。MiMo Desktop 是我们迈入真实工作流、帮助用户将想法转化为高质量成果的第一步。欢迎申请参与邀测，并用真实任务告诉我们：它已经能够完成什么，还有哪些地方需要改进。

]]> https://mstzuomu.space/posts/azuma.zuomu-blog-8/ 龙之剑自由相机模组 2026-08-28T00:00:00.000Z 2026-08-28T00:00:00.000Z 陌殊途左沐 在龙之剑中调整相机

🗡龙之剑自由相机模组#

N网上有个模组我挺喜欢用，可以调整相机镜头，并且反虚化，但是没有汉化并且窗口特别小，在大屏上看眼睛都要花了，于是我简单进行了汉化，并且增添了调整窗口大小的功能。

原版模组下载地址

我的修改版下载地址

原版模组描述：移除放大角色时的透明效果，这样你可以欣赏素材或其他内容。还允许配置一些摄像机设置（距离、角色偏移等），默认还能解锁摄像机的俯仰角，这样你就能看天空，嗯嗯。

📕使用教程#

  1. 需要安装发行版 ·UE4SS-RE/RE-UE4SS，并且一定要安装最新的版本，如果你已经安装可以忽略此步骤。
  2. 下载后解压到DragonSword Awakening\DS\Binaries\Win64\路径下。
  3. 下载模组，并解压到DragonSword Awakening\DS\Binaries\Win64\ue4ss\Mods目录下
  4. 启动游戏，当完全进入游戏后按F5即可唤出模组界面。

龙之剑.png
龙之剑.png

📷 CameraTweaker 设置面板功能详解#

🔘 开关类设置#

设置说明
启用相机调整总开关。关闭后所有相机参数恢复游戏默认值。
禁用近距离透明开启后，角色靠近镜头时不会变透明（原版游戏会变透明）。需要切换角色后生效。
应用到载具开启后，相机参数也会应用到载具上。默认关闭。

📐 实时更新选项（拖动滑块立即生效）#

设置默认值说明
最小俯仰角-90°视角能往下看的最低角度。原版是 -45°，改成 -90° 可以直接看地面。
最大俯仰角90°视角能往上看的最高角度。原版是 45°，改成 90° 可以直接看天空。
相机跟随速度10相机跟随角色移动的速度。值越大，相机跟得越紧，不容易”飘”。设为 0 则禁用跟随延迟。
相机相对位置 X/Y/Z0相机相对于角色的直接偏移量。X=前后，Y=左右，Z=上下。

⏳ 非实时更新选项（切换角色后生效）#

设置默认值说明
相机最近距离0拉近镜头的最小距离。值越小，镜头能离角色越近。
相机最远距离600拉远镜头的最大距离。值越大，镜头能离角色越远。
近景插槽偏移 X-100镜头拉近时，相机的前后位置。负值=在角色前方（防止镜头穿进身体）。
近景插槽偏移 Y30镜头拉近时，相机的左右位置。正值=偏右，负值=偏左。
近景插槽偏移 Z75镜头拉近时，相机的高度。75 大约是头部高度。
远景插槽偏移 X0镜头拉远时，相机的前后位置。
远景插槽偏移 Y60镜头拉远时，相机的左右位置。
远景插槽偏移 Z125镜头拉远时，相机的高度。

🖥️ 面板设置#

设置说明
面板宽度调整设置面板的宽度（300-1200）。
面板高度调整设置面板的高度（400-1000）。
应用面板大小点击后保存并重建面板，使尺寸更改生效。

🔘 底部按钮#

按钮说明
应用并保存应用所有相机参数并保存到配置文件。
重置恢复所有设置为默认值。

💡 使用建议#

  1. 想要自由视角：把俯仰角范围调到 -90° ~ 90°
  2. 想要更近的特写镜头：把相机最近距离调小
  3. 想要更稳定的镜头：把相机跟随速度调高
  4. 想要肩越视角：调整近景插槽偏移 Y（左右）和 Z（高度）

按 F5 打开面板，试试调整这些参数！ 🎮

]]> https://mstzuomu.space/posts/azuma.zuomu-blog-7/ 从零开始搭建个人图床 2026-08-24T00:00:00.000Z 2026-08-24T00:00:00.000Z 陌殊途左沐 简单搭建属于你的个人图床

利用CF和TG搭建个人图床#

本文介绍方法基于Cloudflare Workers和Telegram，开始部署前请先确保有CF和TG账号，如果您想自行选取方法，请参考官方文档。 项目地址：CloudFlare-ImgBed 官方文档：CloudFlare-ImgBed

前期准备#

  1. 在 Telegram 中搜索 @BotFather并添加到列表
  2. 发送 /newbot 命令
  3. 按提示输入 Bot 名称和用户名等信息
  4. 成功创建后将会获得 Bot Token（格式：123456789:ABCdefGHIjklMNOpqrsTUVwxyz）
  5. 创建一个全新的频道，选择频道管理，将刚才创建的Bot设为管理员。
  6. 设备Bot权限，除邀请新成员外其他权限全部开启
  7. 在频道中发送一条测试消息
  8. 向 @VersaToolsBot 转发这条消息
  9. 获得频道 ID（示例：-1001234567890）

Cloudflare Workers部署#

第一步：Fork 项目#

  1. 访问 CloudFlare ImgBed
  2. 点击右上角的 “Fork” 按钮，如果您喜欢该项目，欢迎加入Star以支持
  3. 选择您的 GitHub 账户
  4. 确认 Fork 完成

第二步：准备 Cloudflare 资源#

2.1 获取 API 令牌 和 Account ID#

  1. 登录 Cloudflare Dashboard
  2. 点击右上角头像 → “配置文件” → “API 令牌”
  3. 点击 “创建令牌”
  4. 选择 “编辑 Cloudflare Workers” 模板
  5. 账户资源选择自己的账户，区域资源选择所有区域
  6. 确认权限并创建，记录生成的API令牌
  7. 返回账户主页，右侧三个点展开复制账户ID，如果找不到可以直接搜索”复制账户”，记录复制的账户ID

2.2 创建数据库#

数据库用于存储文件元数据，本文选择KV

特点KV 数据库
读写性能高
免费额度少

KV 数据库#

  1. 在 Dashboard 中选择 “存储和数据库” → “Workers KV”
  2. 点击 “创建实例”，名称填 img_url，请勿修改此名称
  3. 创建完成后返回，记录img_url ID

⚙️ 第三步：配置 GitHub Secrets#

在 Fork 的仓库中，进入 Settings → Secrets and variables → Actions → Secrets，添加以下 Secrets：

Secret 名称说明是否必填
CLOUDFLARE_API_TOKENCloudflare API Token✅ 必填
CLOUDFLARE_ACCOUNT_IDCloudflare Account ID✅ 必填
KV_NAMESPACE_IDKV 命名空间 ID

创建完成后进入 Actions → I understand… →Deploy to Cloudflare Workers →Run workflow →Run workflow（注意此处默认的work name不要修改）

运行之后等待一段时间部署deploy

存储渠道配置#

部署完成后访问您的域名，进入管理后台配置存储渠道。

访问管理后台#

访问 https://你的域名/dashboard

管理后台默认无需密码，登录后请及时设置管理员用户名和密码。

配置 Telegram 渠道#

  1. 左上角菜单栏进入 “系统设置” → “上传设置”
  2. 找到 “Telegram 渠道配置”
  3. 点击 “添加渠道”
  4. 填入准备好的 Token 和 Chat ID：
    • 渠道名称：自定义名称（如：主渠道）
    • Bot Token：从 @BotFather 获得的 Token
    • Chat ID：频道 ID（有-号时需要保留）
    • 代理 URL：（可选）自定义代理地址，用于代理 Telegram API 请求
    • 启用状态：开启
  5. 点击 “保存设置”
]]> https://mstzuomu.space/posts/web-update-6/ 更新公告20260823 2026-08-23T00:00:00.000Z 2026-08-23T00:00:00.000Z 左沐 网站更新公告

更新公告20260823#

1.网站版本更新到6.16.2

2.修复了文章中添加音乐播放器功能失效的问题，修复了音频丢失的问题

3.增添全新的首页样式

4.网站默认字体更换为汉仪文黑65w,修改路径src\config\fontConfig.ts

]]> https://mstzuomu.space/posts/azuma.zuomu-blog-6/ 文章中添加音乐播放器 2026-08-18T00:00:00.000Z 2026-08-18T00:00:00.000Z 陌殊途左沐 简单实现文章嵌入播放器

利用现有组件添加音乐播放器#

依旧可以直接利用 MD 语法在文章中嵌入组件，并且实现默认自动播放。

效果展示（音频源网易云示例）#

未知歌曲
未知艺术家
网易云音乐 · 单曲
0:000:00

使用说明#

直接URL方式#

1
::music{url="https://example.com/song.mp3" title="歌曲标题" artist="艺术家" cover="封面URL"}

网易云音乐方式#

1
::music{server="netease" type="song" id="1901371647" title="歌曲标题" artist="艺术家"}

参数说明（基本和主页播放器组件相同）#

参数说明示例
url音乐文件URLurl="/assets/music/song.mp3"
server音乐平台server="netease"
id歌曲IDid="1901371647"
typeID类型(默认song)type="song"
title歌曲标题title="我的歌曲"
artist艺术家artist="艺术家"
cover封面图片URLcover="https://example.com/cover.jpg"
autoplay自动播放(默认true)autoplay="true"
loop循环播放(默认false)loop="true"
volume音量0-1(默认0.7)volume="0.5"

代码实现#

  1. rehype-component-music-player.mjs（组件，src/plugins/） 解析 ::music{…} 语法 支持参数：url、server、id、type、title、artist、cover、autoplay、loop、volume

  2. music-player-script.js（脚本，src/plugins/） 音频播放控制（播放/暂停/进度/音量） Meting API 集成（网易云、QQ音乐等，三级回退） 多播放器互斥暂停、自动播放处理 切页时自动暂停并重新初始化（见下方事件说明）

切页事件的坑：站点用的是 Swup 4 + @swup/astro，它有个兼容层会把 Swup 钩子转成 astro 风格事件派发——content:replace 前触发 astro:before-swap，page:view 触发 astro:page-load。这两个才是实际会触发的事件；Swup v3 时代的 swup:contentReplaced / swup:willReplaceContent 在 4.x 里根本不派发， 写了也白写（会表现为：swup 切进文章时播放器不初始化、切页后音乐不停）。 脚本里监听 astro:before-swap 暂停、astro:page-load 清理并重新初始化。

  1. music-player.css（样式，src/styles/） 跟随主题色的扁平卡片风，全部用 Tailwind @apply + 主题变量 暗色模式自动适配（不再手写 .dark 覆盖） 加载中/错误/播放中三个状态类

  2. astro.config.mjs（配置）

1
import { MusicPlayerComponent } from "./src/plugins/rehype-component-music-player.mjs";
2
// ...
3
components: {
4
    music: MusicPlayerComponent,
5
}
  1. MusicPlayerManager.astro（脚本接入，src/components/features/）

对齐框架里 GithubCardManager 的模式，一行副作用导入脚本，由 Layout 统一渲染：

1
---
2
// 文章内嵌音乐播放器客户端管理器（::music 指令）
3
---
4
<script>
5
  import "@/plugins/music-player-script.js";
6
</script>

Layout.astro 里引入并渲染这个组件即可，不再需要手写 <link> 和 <script src>：

1
import MusicPlayerManager from "@components/features/MusicPlayerManager.astro";
2
// ...
3
<MusicPlayerManager />
  1. 样式加载（Markdown.astro / DynamicItemTemplate.astro）
1
import "@/styles/music-player.css";

和 markdown.css、markdown-extend.styl 放在一起，只在有正文的页面（文章、动态）加载，首页等页面不背这份 CSS。

]]> https://mstzuomu.space/posts/azuma.zuomu-blog-5/ 2026新版Kindle解密｜告别旧版PC客户端，一键导出EPUB电子书 2026-08-17T00:00:00.000Z 2026-08-17T00:00:00.000Z 左沐 一键去除Kindle的D加密？已经这么方便啦！

解除Kindle电子书DRM加密并转换为EPUB格式教程#

本教程适用于微软商店版Kindle应用。原exe安装包版本（Kindle for PC）已于2026‑06‑30终止服务，2.8版本已停止维护，2.9版本虽暂时可用，但后续也将不再提供支持。

所需工具#

  1. 微软商店版 Kindle（如果下载过慢可从离线站下载）
  2. Calibre：开源电子书管理软件，支持各类电子书格式转换与插件扩展
  3. DeDRM‑Tools 解密工具包：版本需要与Kindle版本匹配，版本号建议大于等于对应Kindle版本

操作步骤#

1. 在Kindle客户端下载电子书#

打开微软商店版Kindle，将需要解密的电子书完整下载到本地。

新版Kindle界面
新版Kindle界面

2. 使用DeDRM‑Tools提取解密后的KFX‑ZIP文件#

  1. 在DeDRM工具包目录中，双击运行 MSIXKFXArchiverMobi1_18632.exe；
  2. 程序运行成功后，工具包文件夹内会生成 archived_kfx 文件夹；
  3. 该文件夹内的 kfx‑zip 文件即为去除DRM加密后的电子书源文件；
  4. 提示：工具会自动在C盘根目录生成 Date 文件夹，任务完成后可直接删除该文件夹。

3. Calibre安装KFX Input插件#

Calibre需要安装KFX Input插件才能识别kfx‑zip格式文件

  1. 打开Calibre，点击顶部菜单栏「首选项」；
  2. 在窗口下方选择「插件」；
  3. 在弹窗底部点击「获取新的插件」；
  4. 搜索 KFX Input，选中后点击安装，安装过程可能短暂卡顿；
  5. 按照提示重启Calibre使插件生效。

4. 导入文件并转换为EPUB格式#

  1. 将解密得到的 kfx‑zip 文件直接拖拽到Calibre书库中；
  2. 文件导入成功后，右键选中该书，选择「批量转换」；
  3. 在转换设置右上角，输出格式选择 EPUB，按需调整其他参数；
  4. 确认执行转换，完成后即可得到无DRM加密的EPUB电子书。

补充说明#

相比旧版Kindle for PC的解密流程，当前DeDRM‑Tools更新后的版本操作流程更加简洁。本教程流程基于该工具作者更新的新版工具实现。

⚠️ 法律提示：本教程仅用于个人已购买电子书的备份，请勿将解密后的文件用于传播、分享或商用，遵守著作权相关法律法规。

]]> https://mstzuomu.space/posts/web-update-5/ 更新公告20260817 2026-08-17T00:00:00.000Z 2026-08-17T00:00:00.000Z 左沐 网站更新公告

更新公告20260817#

1.修复了网站异常跳转后崩溃的问题

2.添加了文章中音乐播放器功能，详情可见文章中添加音乐播放器

]]> https://mstzuomu.space/posts/azuma.zuomu-blog-4/ 基于Firefly主题的列表封面位置改造 2026-08-16T00:00:00.000Z 2026-08-16T00:00:00.000Z 左沐 不想让封面挤在侧边？Firefly封面置顶记录

Firefly 主题自定义文章封面位置：实现列表模式封面在上方#

Firefly 主题默认的列表模式只支持封面在左侧或右侧，但我想让封面显示在标题上方。于是开始了一番折腾，记录一下完整的修改过程。

最终效果#

修改前（封面在右侧）：

1
┌─────────────────────────────────┐
2
│ 标题                    [封面图] │
3
│ 标签                            │
4
└─────────────────────────────────┘

修改后（封面在上方）：

1
┌─────────────────────────────────┐
2
│ [封面图]                        │
3
│ 标题                            │
4
│ 标签                            │
5
└─────────────────────────────────┘

需要修改的文件#

一共涉及 4 个文件：

  1. src/types/siteConfig.ts — 类型定义
  2. src/config/siteConfig.ts — 配置文件
  3. src/components/layout/PostCard.astro — 文章卡片组件
  4. src/components/layout/PostPage.astro — 文章列表页面

第一步：修改类型定义#

文件： src/types/siteConfig.ts

找到 coverPosition 的类型定义：

1
coverPosition?: "left" | "right" | undefined;

添加 "top" 选项，修改为：

1
coverPosition?: "left" | "right" | "top" | undefined;

第二步：修改配置文件#

文件： src/config/siteConfig.ts

找到 postListLayout 配置中的 coverPosition：

1
postListLayout: {
2
    // 列表模式下封面图显示在哪一侧："right" 右侧，"left" 左侧
3
    coverPosition: "right",
4
    // ...
5
},

修改为：

1
postListLayout: {
2
    // 列表模式下封面图显示在哪一侧："right" 右侧，"left" 左侧，"top" 上方
3
    coverPosition: "top",
4
    // ...
5
},

第三步：修改文章卡片组件#

文件： src/components/layout/PostCard.astro

3.1 添加变量判断#

找到这行代码（约第 53 行）：

1
const coverWidth = "30%";

在它下面添加：

1
const isCoverTop = style.includes("cover-top");

3.2 修改容器 class#

找到容器 div 的 class 定义（约第 107-114 行）：

1
class:list={[
2
    "post-card-wrapper",
3
    hasCover ? "has-cover" : "no-cover",
4
    pinned ? "pinned" : "",
5
    gridCoverFullWidth ? "" : "grid-cover-inset",
6
    "card-base flex flex-col-reverse w-full rounded-(--radius-large) overflow-hidden relative",
7
    className,
8
]}

添加 cover-top 类，修改为：

1
class:list={[
2
    "post-card-wrapper",
3
    hasCover ? "has-cover" : "no-cover",
4
    pinned ? "pinned" : "",
5
    gridCoverFullWidth ? "" : "grid-cover-inset",
6
    isCoverTop ? "cover-top" : "",
7
    "card-base flex flex-col-reverse w-full rounded-(--radius-large) overflow-hidden relative",
8
    className,
9
]}

3.3 添加 CSS 样式#

在文件末尾的 <style> 标签内添加以下 CSS：

1
/* 列表模式封面在上方 - 移动端 */
2
:global(.list-mode.cover-top) .post-card-wrapper {
3
    flex-direction: column-reverse !important;
4
}
5


6
:global(.list-mode.cover-top) .has-cover .post-card-image {
7
    position: relative !important;
8
    top: auto !important;
9
    bottom: auto !important;
10
    right: auto !important;
11
    left: auto !important;
12
    width: 100% !important;
13
    height: 200px !important;
14
    margin: 0 !important;
15
    border-radius: var(--radius-large) var(--radius-large) 0 0 !important;
16
}
17


18
:global(.list-mode.cover-top) .has-cover .post-card-content {
19
    width: 100% !important;
20
}
21


22
/* 列表模式封面在上方 - 桌面端 */
23
@media (min-width: 768px) {
24
    :global(.list-mode.cover-top) .post-card-wrapper {
25
        flex-direction: column-reverse !important;
26
    }
27


28
    :global(.list-mode.cover-top) .has-cover .post-card-image {
29
        position: relative !important;
30
        top: auto !important;
31
        bottom: auto !important;
32
        right: auto !important;
33
        left: auto !important;
34
        width: 100% !important;
35
        height: 300px !important;
36
        margin: 0 !important;
37
        border-radius: var(--radius-large) var(--radius-large) 0 0 !important;
38
    }
39


40
    :global(.list-mode.cover-top) .has-cover .post-card-content {
41
        width: 100% !important;
42
        padding: 1.75rem 2.25rem !important;
43
    }
44


45
    :global(.list-mode.cover-top) .has-cover .post-card-title::before {
46
        display: none !important;
47
    }
48
}
展开收起

第四步：修改文章列表页面#

文件： src/components/layout/PostPage.astro

找到 coverPositionClass 的定义（约第 28-29 行）：

1
const coverPositionClass =
2
  siteConfig.postListLayout.coverPosition === "left" ? " cover-left" : "";

添加对 "top" 的支持，修改为：

1
const coverPositionClass =
2
  siteConfig.postListLayout.coverPosition === "left" ? " cover-left" :
3
  siteConfig.postListLayout.coverPosition === "top" ? " cover-top" : "";

完整配置参考#

修改完成后，siteConfig.ts 中的 postListLayout 配置示例：

1
postListLayout: {
2
    // 默认布局模式："list" 列表模式，"grid" 网格模式
3
    defaultMode: "list",
4
    // 移动端默认布局模式
5
    mobileDefaultMode: "grid",
6
    // 列表模式下封面图位置："right" 右侧，"left" 左侧，"top" 上方
7
    coverPosition: "top",
8
    // 文章简介显示行数
9
    descriptionLines: 2,
10
    // 其他配置...
11
},

踩坑记录#

问题 1：TypeScript 类型错误#

一开始直接在配置里写 coverPosition: "top"，结果报错：

不能将类型”top”分配给类型”left” | “right” | undefined”

原因： 类型定义文件中没有 "top" 选项。

解决： 先修改 types/siteConfig.ts，添加 "top" 类型。

问题 2：修改后没有效果#

改了配置和样式，但页面没有任何变化。

原因： PostPage.astro 中的 coverPositionClass 只处理了 "left"，没有处理 "top"，导致 cover-top 这个 class 根本没被加到容器上。

解决： 修改 PostPage.astro，添加对 "top" 的判断逻辑。

小结#

整体修改涉及 4 个文件，核心逻辑就是四步：

  1. 在类型定义中添加新选项
  2. 在配置中启用新选项
  3. 在组件中添加对应的 CSS 样式
  4. 在页面中添加对应的 class 处理

Firefly 主题的组件化设计很清晰，修改起来逻辑明确，唯一需要注意的就是别漏了 PostPage.astro 里的 class 映射——我一开始就栽在这了，样式写了半天不生效，最后发现是 class 根本没挂上去。

]]> https://mstzuomu.space/posts/web-update-4/ 更新公告20260816 2026-08-16T00:00:00.000Z 2026-08-16T00:00:00.000Z 左沐 网站更新公告

更新公告20260816#

1.为网站添加了MD语法下的PDF控件，现在可以直接在文章里阅读PDF

2.修复了外链PDF无法正常读取的问题

3.更换网站图床，感谢开源项目CloudFlare ImgBed

4.将文章封面显示位置新增top选项

PDF控件示例：

我的PDF文档
下载PDF
]]> https://mstzuomu.space/posts/azuma.zuomu-blog-3/ 基于rehype的博客PDF嵌入组件实现 2026-08-16T00:00:00.000Z 2026-08-16T00:00:00.000Z 左沐 基于现有组件体系的博客 PDF 预览扩展实践

博客里已经有了 GitHub 卡片、B站卡片这类 Markdown 扩展组件，一直想着能不能把 PDF 也直接嵌进文章里，不用再丢个链接让读者跳出去看。今天折腾了一下，用 AI 辅助搞定了，由于制作B站卡片时忘记记录了，于是决定记录一下制作PDF组件全过程。

思路#

项目里已经有一套基于 rehype 的自定义指令组件体系，比如 ::github{...} 和 ::bilibili{...}。我要做的就是照着这个模式，新增一个 ::pdf{...} 指令，让它在 Markdown 里渲染成一个带标题栏和下载按钮的 PDF 查看器。

整个过程分三步：写插件 → 注册插件 → 写样式。样式直接写在框架统一存放 Markdown 扩展样式的 markdown-extend.styl 里，它由 Markdown.astro 自动加载，不需要额外引入。

第一步：创建 PDF 查看器插件#

在 src/plugins/ 路径下新建 rehype-component-pdf-viewer.mjs，核心逻辑是接收 url、title、height 三个参数，用 hastscript 拼出一个带 header 和 iframe 的 DOM 结构。

代码里做了两个校验：如果指令不是叶子类型（带了子内容），或者没传 url，就返回一个隐藏的错误提示 div，避免页面崩掉。

1
/// <reference types="mdast" />
2
import { h } from "hastscript";
3


4
/**
5
 * Creates a PDF Viewer component.
6
 *
7
 * @param {Object} properties - The properties of the component.
8
 * @param {string} properties.url - The URL of the PDF file.
9
 * @param {string} [properties.title] - Optional title for the PDF viewer.
10
 * @param {number} [properties.height] - Optional height in pixels (default: 600).
11
 * @param {import('mdast').RootContent[]} children - The children elements.
12
 * @returns {import('mdast').Parent} The created PDF Viewer component.
13
 */
14
export function PdfViewerComponent(properties, children) {
15
  if (Array.isArray(children) && children.length !== 0)
16
    return h("div", { class: "hidden" }, [
17
      'Invalid directive. ("pdf" directive must be leaf type "::pdf{url="https://example.com/file.pdf"}")',
18
    ]);
19


20
  if (!properties.url)
21
    return h(
22
      "div",
23
      { class: "hidden" },
24
      'Invalid URL. ("url" attribute is required)',
25
    );
26


27
  const url = properties.url;
28
  const title = properties.title || "PDF Viewer";
29
  const height = properties.height || 600;
30


31
  // 浏览器原生 PDF 预览（iframe 直接加载），不引入 pdf.js 重依赖
32
  return h("div", { class: "pdf-container" }, [
33
    h("div", { class: "pdf-header" }, [
34
      h("div", { class: "pdf-title" }, title),
35
      h(
36
        "a",
37
        {
38
          class: "pdf-download",
39
          href: url,
40
          target: "_blank",
41
          download: "",
42
        },
43
        "下载PDF",
44
      ),
45
    ]),
46
    h("div", { class: "pdf-viewer-wrapper" }, [
47
      h("iframe", {
48
        class: "pdf-viewer",
49
        src: url,
50
        style: `height: ${height}px;`,
51
        title: title,
52
      }),
53
    ]),
54
  ]);
55
}
展开收起

第二步：在 astro.config.mjs 中注册插件#

插件写好了还得注册才能用。打开 astro.config.mjs，分两处修改。

第一处：顶部 import（和其他组件插件放一起，约 41–44 行附近）

1
import { BilibiliCardComponent } from "./src/plugins/rehype-component-bilibili-card.mjs";
2
import { GithubCardComponent } from "./src/plugins/rehype-component-github-card.mjs";
3
import { MusicPlayerComponent } from "./src/plugins/rehype-component-music-player.mjs";
4
import { PdfViewerComponent } from "./src/plugins/rehype-component-pdf-viewer.mjs";

第二处：components 中注册（约第 329 行附近）

找到 components 配置，在里面加一行 pdf 字段：

1
components: {
2
    github: GithubCardComponent,
3
    bilibili: BilibiliCardComponent,
4
    pdf: PdfViewerComponent,
5
},

第三步：添加 CSS 样式#

光有 DOM 还不够，得给它穿件衣服。打开框架统一的 Markdown 扩展样式文件 src/styles/markdown-extend.styl（GitHub 卡片、图表控件的样式也都在这里），按 Stylus 语法追加一段。

有两点值得注意：颜色全部用主题变量而不是写死的色值——var(--license-block-bg)、var(--line-divider) 这类变量在暗色主题下会自动切换，不用再手写一套 .dark 覆盖；另外要显式覆盖 .custom-md iframe 的全局 margin 和圆角，否则 iframe 会被文章里通用的 iframe 规则影响。

1
// ─── PDF 查看器（::pdf 指令，rehype-component-pdf-viewer） ──────────────────
2


3
.pdf-container
4
  margin: 1.5rem 0
5
  border-radius: 0.75rem
6
  overflow: hidden
7
  background: var(--license-block-bg)
8
  border: 1px solid var(--line-divider)
9


10
.pdf-header
11
  display: flex
12
  align-items: center
13
  justify-content: space-between
14
  padding: 0.75rem 1rem
15
  border-bottom: 1px solid var(--line-divider)
16


17
.pdf-title
18
  font-weight: 600
19
  font-size: 0.95rem
20
  color: var(--tw-prose-headings)
21


22
.pdf-download
23
  font-size: 0.85rem
24
  color: var(--primary)
25
  text-decoration: none
26
  padding: 0.25rem 0.75rem
27
  border-radius: 0.375rem
28
  background: var(--btn-regular-bg)
29
  transition: background-color 0.2s ease
30


31
  &:hover
32
    background: var(--btn-regular-bg-hover)
33


34
.pdf-viewer-wrapper
35
  position: relative
36
  width: 100%
37


38
.pdf-viewer
39
  display: block
40
  width: 100%
41
  border: none
42


43
// 覆盖上方 .custom-md iframe 的全局 margin/border-radius，由容器自己控制留白
44
.custom-md .pdf-viewer
45
  margin: 0
46
  border-radius: 0
展开收起

由于 PDF 阅读器并未进行本地配置而是选择了 iframe 直接嵌入，因此实际阅读控件和读者的浏览器有关。

样式写完就完事了——markdown-extend.styl 已经由 Markdown.astro 引入，不需要在 Layout.astro 里再手动 import 一份。

使用方法#

全部搞定之后，在任何 Markdown 文章里直接写一行指令就行：

1
::pdf{url="https://example.com/your-file.pdf" title="我的PDF文档" height="600"}

三个参数说明：

参数说明是否必填默认值
urlPDF 文件的 URL 地址必填—
title查看器顶部显示的标题可选"PDF Viewer"
height查看器高度（像素）可选600

PDF控件示例：

我的PDF文档
下载PDF

小结#

整体下来没什么坑，核心就是复用项目已有的 rehype 组件模式，新增一个指令处理器而已。iframe 直接加载 PDF URL，浏览器原生支持预览，省得引入 pdf.js 那种重依赖。header 上放个下载按钮，读者想保存也方便。

以后写技术文章放论文、说明书之类的 PDF 就舒服多了，不用再让读者跳出博客去看。

]]> https://mstzuomu.space/posts/web-update-3/ 更新公告20260815 2026-08-15T00:00:00.000Z 2026-08-15T00:00:00.000Z 左沐 网站更新公告

更新公告20260815#

1.新增MD语法下的哔哩哔哩控件

2.修复了哔哩哔哩控件无法正常显示的问题

3.修复了移动端哔哩哔哩控件文字溢出的问题

4.为网站添加Live2D控件

]]> https://mstzuomu.space/posts/azuma.zuomu-blog-2/ Twikoo评论系统部署踩坑记录：Vercel域名无法访问的解决之路 2026-08-14T00:00:00.000Z 2026-08-14T00:00:00.000Z 左沐 解决评论系统无法部署的经历

Twikoo 评论系统部署踩坑记录：Vercel 域名无法访问的解决之路#

给自己留个备忘，也给遇到同样问题的朋友指条路。

起因#

博客的主要内容基本完成更换，于是决定完善评论系统。

在本网站项目里其实已经内置好配置文件了，只需修改个人的 envId 即可，最后定了 Twikoo，（最大的原因是免费🤣）并且支持 Vercel 一键部署。

部署过程遇到一些问题，首先浏览器插件建议关闭，或直接更换浏览器，否则在部署的时候相关控件被隐藏导致部署失败。（建议使用 Chrome ）另外官方文档相关内容略微落后实际网页版本，请以实际网页内容为主，并且在保存自己的 envId 信息的时候，建议下载 .env 文件保存，后续可以一键导入。部署操作完成后 Vercel 控制台显示 Ready，以为已经部署成功了。

然后问题来了。

问题一：Vercel 默认域名无法访问#

点了 Visit 按钮，浏览器转了半天，给我甩了一句：

1
无法访问此网站
2
xxxxxxxxx-xxxx-xxxx（你部署后的域名） 的响应时间过长。
3
ERR_CONNECTION_TIMED_OUT

连接超时。

第一反应是我哪里配错了。回去检查：

  • 部署状态：Ready ✅
  • 环境变量（MONGODB_URI / USERNAME / PASSWORD）：都配了 ✅
  • 域名配置：Valid Configuration ✅

啥都没问题，但就是打不开。

后来才反应过来——*.vercel.app 这个默认子域名在大陆本身就属于超时状态，而官方文档和相关教程并没有提到这点，最新的教程也只停留在23年。

解决方案：绑定自定义域名#

既然默认域名用不了，那就绑定本网站的子域名。

第一步：Verc 添加域名#

在 Vercel 项目的 Settings → Domains 里点 Add Existing，输入 twikoo.xxxx（你的域名）。

添加完之后，Vercel 会显示 Invalid Configuration，并告诉你需要配什么 DNS 记录。它自动识别出我的 DNS 是 Cloudflare 管理的，给出了精确的配置：

字段值
类型CNAME
名称twikoo
目标xxxxxx
代理状态Disabled

注意类型一定要填写正确

第二步：Cloudflare 配置 DNS（重点！）#

去 Cloudflare 的 DNS 记录页面，点 添加记录：

  • 类型选 CNAME
  • 名称填 twikoo
  • 目标填 Vercel 给的那串 xxxxx.com 地址
  • TTL 保持自动
  • 代理状态必须选「仅 DNS」（灰色云朵）

这里是最容易踩坑的地方。我博客的主域名和其他子域名都是开着 Cloudflare 代理的（橙色云朵），但 Twikoo 这条必须关代理。

原因是：Vercel 需要通过 DNS 验证域名所有权并签发 SSL 证书，如果开着 Cloudflare 代理，请求会先走到 Cloudflare，Vercel 验证不过去，证书也签不下来。

第三步：等待验证和证书签发#

保存 DNS 记录后，回到 Vercel 点 Refresh。

先是 DNS 验证通过（蓝色对勾），然后状态变成 Generating SSL Certificate。等了大概一两分钟，再访问 https://xxxxx.xxxxx.xxxxx，返回：

1
{"code":100,"message":"Twikoo 云函数运行正常，请参考 https://twikoo.js.org/frontend.html 完成前端的配置","version":"1.7.19"}

到这一步就算是成了。

第四步：博客前端配置#

最后在博客的 Twikoo 配置里，把 envId 改成自定义域名：

1
https://xxxxxxx.xxxxx.xxxx

原来的 *.vercel.app 地址就可以换掉了。

评论系统首次上线一定要点设置，保存密码，并在配置文件里隐藏设置控件。

总结#

如果你也在部署 Twikoo 或者类似的 Vercel 项目，并遇到相关问题，希望这篇能帮你少走点弯路。

]]> https://mstzuomu.space/posts/web-update-2/ 更新公告20260814 2026-08-14T00:00:00.000Z 2026-08-14T00:00:00.000Z 左沐 网站更新公告

更新公告20260814#

1.留言功能正式上线

2.更换公告图片

3.修复了网站文章丢失的问题

4.为网站添加Umami后台控件，网站数据后台可视化

5.添加不蒜子访客量统计

6.修复访客量不显示的问题

7.删除了Markdown语法中的哔哩哔哩控件，项目手动回档

8.修复了站点统计异常显示的BUG

]]> https://mstzuomu.space/posts/azuma.zuomu-blog-1/ 这是我的第一篇BLOG 2026-08-13T00:00:00.000Z 2026-08-13T00:00:00.000Z 左沐 首次个人博客搭建记录

来自我的第一条博客#

🎉 从零开始，翻阅众多教程，在 MIMO 的帮助和自己不懈的调试摸索下，我终于搭建完成了属于自己的个人博客！

接下来我会继续摸索，持续更新与完善本站。

END

]]> https://mstzuomu.space/posts/web-update-1/ 更新公告20260813 2026-08-13T00:00:00.000Z 2026-08-13T00:00:00.000Z 左沐 网站更新公告

更新公告20260813#

1.移除了站点信息组件

2.新增访客信息组件，并添加地址显示以及天气显示

3.更换天气API地址

4.新增移动端访客信息组件显示

5.修复了移动端访客信息无法成功加载的问题

6.新增留言控件(留言功能暂未开放)

]]>