文章之间切页是连着的，因为 Firefly 用的是 Swup 软导航，只换内容区、不重载文档，挂在 Layout 上的 <audio> 一直活着。唯独音乐页不行 —— 当初为了让全屏可视化不跟 Swup 打架，给它设了整页加载。而整页加载会把整个 JS 上下文连同那个常驻播放器一起销毁。
为了续播我做过一版跨整页的方案：pagehide 时把曲目索引、进度、是否在播写进 localStorage，重载后读出来 seek 回去再 play()。进度是能继承的，播放状态不行 —— 整页导航会重置浏览器的用户手势，这时候再调 play() 会被 autoplay 政策直接拒。我又加了静音兜底（先 muted 播再恢复），还是拒；再加”首次点击或按键时续播”的一次性监听，那就不叫无缝了，跟”点一下才能听”没区别。
绕到这儿结论很清楚：只要音乐页走整页加载，就不可能无缝。得回到软导航。
回到软导航，先得解释上次为什么放弃了它。
上次的现象是”进音乐页界面乱、内链还失效”，当时的判断是可视化器那个 position: fixed 全屏层被 Swup 过渡期加在容器上的 transform 弄坏了。这次我去翻了 git，那层从来没改过，这个假设站不住。
真正的根子，校验一下 Swup 的容器配置就浮出来了。astro.config.mjs 里 containers 配了六个：
#swup-container#banner-overlay-container#banner-dim-container#left-sidebar-dynamic#right-sidebar-dynamic#floating-toc-wrapper把这六个 id 拿去搜谁渲染，答案只有一个：MainGridLayout。而 music.astro 用的是 <Layout> 直出 —— 也就是说音乐页的 HTML 里，这六个容器一个都不存在。
Swup 换内容的方式是”拿目标页的同名容器来替换”。目标页没有容器，这次导航就只能半途失败：地址变了、内容没换，过渡用的 is-page-transitioning 类也摘不掉，表现出来就是界面乱、内链点不动。
之所以一直没暴露，是因为音乐链接上挂着 fullPage: true，从来没真正软导航过。上次我把这个标志去掉，等于第一次真的走软导航，问题立刻现形。
还有条佐证。swup-transitions.ts 的 page:view 里会跑 updateMainGridCols()、updateSidebarComponentsVisibility()、syncFullscreenOverlays() 这些，全都依赖 MainGridLayout 的 DOM。用 Layout 直出，它们不是空转就是报错。
所以修法很直接：music.astro 改用 MainGridLayout，内容塞一个空占位。引申一下，凡是要参与软导航的路由，都不能用 Layout 直出。
容器补齐，音乐页能正常软导航了。但可视化器本身还渲染在内容区里，软导航会把它跟内容一起换掉，three 场景和 AudioContext 都得重建。虽然播放不断了，但可视化的状态每次都要重来，不干净。
做法是把 MusicVisualizer 从页面里提出来，挂进 Layout，做成常驻覆盖层。它和 MusicManager 一样待在 #swup-container 外面，软导航碰不到。进出音乐页只切 body 上的 music-active 类来显隐，three 场景和播放器都不销毁。
1<body>2 #top-row 导航栏（常驻）3 <audio> MusicManager 的播放器（常驻）4 #music-overlay 可视化器覆盖层（常驻，软导航不销毁）5 .content-panel6 └─ #swup-container Swup 只换这里面的东西页面那边只剩一个路由占位，内容是个空的 <main>，回退按钮走 window.swup.navigate("/")。
常驻是有代价的：组件的脚本和样式从此在每个页面都会加载。所以 three 改成懒加载，第一次进音乐页才 await import("three")，不然那六百多 KB 会摊到每一页的首屏。同理，覆盖层的 DOM 现在每页都在，里面就不能留会自动发请求的东西 —— 之前有个 src="" 的空封面 <img>，顺手去掉了。
覆盖层如果只靠 astro:page-load 切类，Swup 的过渡动画期间会先露出音乐页的外壳，闪一下。所以在 visit:start 里按目标地址提前把类切好，visit:end 和 astro:page-load 再按真实地址校准一次。
覆盖层本身给了不透明的底色，three 首帧就绪之前不会透出下面的页面。
音乐页场景是深色的，导航栏得透明加白字。我写的是 body.music-active #navbar > div { background: transparent !important }，结果导航栏还是浅色毛玻璃，白字叠上去就是发白。
原因是 navbar.css 里导航栏底色和阴影用的都是 !important，选择器还是 html[data-has-wallpaper] #navbar[data-transparent-mode="…"] > div 这种。两条都带 !important 时，比的不是谁写在后面，是特异性。
改法是选择器也带上 [data-transparent-mode]，把特异性抬上去。顺手把 --navbar-surface-blur 清零，不然 ::before 那层毛玻璃还在糊背景。
还有个连带的地方。下拉面板跟搜索、主题、音乐、显示设置面板共用 .float-panel，而且都挂在 #navbar 里。一开始只敢改 .dropdown-content，怕整片刷会把那几块面板的文字也刷白。结果留着的那几块成了”亮色面板配浅色文字”，比不改还难看，只能回头再收拾一遍。
这个问题只在返回的时候露出来：点回首页，导航栏肉眼可见地往左移了一下。
用浏览器一量就清楚了。音乐页的 body.music-active 上有 overflow: hidden，把页面滚动条去掉了。滚动条一没，视口可用宽度就多出整整一条 —— 本机是 15px，1249 变成 1264。导航栏外壳 #top-row 是 fixed 加 mx-auto，还挂着 transition-all duration-700，宽度一变，靠右和居中的导航项整体位移，再被那 700ms 过渡一放，就是一个明显的”往左挪”。
这里有个很容易量错的点：#navbar 自己的 left 两次都是 16，根本没变，变的是宽度。只盯着左边缘看，永远看不出问题，得量 #top-row 的宽度或者右边元素的 right。
改法是给根元素锁住滚动条槽位：html { scrollbar-gutter: stable }。这样布局宽度恒等于”视口宽减滚动条宽”，滚动条出现或消失都不再引起位移。首页本来就有滚动条、槽位被它占着，位置一点没变。
两个细节。scrollbar-gutter 必须挂 html，我试过挂 body，计算值确实生效了，但视口槽位不保留 —— gutter 不跟着 overflow 一起传播。另外不能只在音乐页加，离开音乐页时 music-active 是在内容替换之前就被摘掉的，那一瞬页面还没滚动条，宽度会先弹回去，反而抖一下。
锁完槽位还有个副作用：空出来的那一条露的是根元素背景，亮色主题下是浅色，在深色场景右边留一条亮边。音乐页把根背景刷成近黑就看不见了。
在首页放着歌切进音乐页，歌词区一直停在”加载歌词”；但在音乐页刷新一下就一直正常。
歌词是事件驱动的（fm:lyrics），可视化器在初始化的时候才绑监听。问题就出在这条路径上：
1首页 取歌词 → 发 fm:lyrics （监听器这时还没绑）2进音乐页 才绑监听 → 收不到 → 歌词区空着3刷新 绑监听 → 取歌词 → 发事件 → 正常改法是初始化时主动从管理器状态里补一次，getState() 里本来就带着歌词数组和当前行号。
顺带修了个同类的：覆盖层隐藏时是 display: none，量出来的歌词高度全是 0；而换行事件只在行真正切换时才发，不会立刻把位置纠正回来，所以恢复显示的时候要重算一次滚动位置。
导航栏一 hover 或者按下就亮一块，在那个深色场景上很刺眼。
那块底色不是元素自己的背景，是主题的 expand-animation 画在 ::before 上的，亮色主题里用的颜色是 oklch(0.95 0.025 …)，基本就是白的。
排查的时候也绕了一下。读 getComputedStyle(el).backgroundColor 拿到的是透明，因为背景压根不在元素上。得读伪元素，getComputedStyle(el, "::before").backgroundColor，才看得到那块底色。
改法就是把音乐页的 ::before 在 hover、聚焦、按下这几种状态下的底色换成半透明白。
导航栏里不只有下拉菜单，搜索面板、主题面板、音乐面板、显示设置面板都挂在 #navbar 里，共用 .float-panel。只改 .dropdown-content 的话，那几块还是亮色毛玻璃，在深色场景上非常突兀。
更麻烦的是它们内部的文字走 Tailwind 的 dark: 变体。主题自定义了 @custom-variant dark (&:where(.dark, .dark *))，意思是只要在面板自身或祖先挂上 dark 类，内部 dark:text-* 就会生效。所以修法分两步：给这几个面板统一加 dark 类，同时用 CSS 把 .float-panel 的背景、边框、阴影强制改成深色毛玻璃。
搜索框是另一个特例。它用的是亮色主题配色 bg-black/4 text-black/30，在音乐页的深色背景上等于完全隐形，但点击区域还在，于是出现”点得到却看不见”的怪现象。要单独覆盖成半透明白底白字。
显示设置面板又更隐蔽一层。它的分区标题 .section-title 在 display-settings.css 里默认是深色，dark 类按道理能让它变浅，但实际因为规则优先级或加载顺序，“主色色相""页面布局""卡片样式”这些标题还是几乎读不出来。最后是在 music-visualizer.css 里直接对 body.music-active #display-setting .section-title 强制浅色，并把面板里的 --btn-content 也翻成浅色，才把所有文字统一压住。
桌面软导航后播放一直连着，手机却从首页进音乐页时会闪一下、然后播放暂停。反向（音乐页回首页）没事。
根子在 Web Audio 的接管时机。可视化器要拿音频数据，必须用 createMediaElementSource(audio) 把 <audio> 的输出改道进 AudioContext。如果 AudioContext 处于 suspended 状态（移动端没有用户手势就新建上下文，默认就是 suspended），这一接管会把正在播的声音直接闷掉。
桌面通常能直接 running，所以无感；移动端从首页点进音乐页时还没手势，于是播放被掐。
修法是把 AudioAnalyzer 拆成三步：ensureContext() 只建上下文和各节点、ensureRunning() 等用户交互把状态顶到 running、connect() 只在 running 时执行接管。如果当前跑不起来，先把 <audio> 记下来，挂一个一次性 pointerdown/keydown 监听，首个手势时再做接管。离开音乐页时不 disconnect，反向导航自然不受影响。
到这里整个修复流程基本就结束了，现在整个网站的音乐都能一首歌不中断播放，而不是像之前的播放器和音乐页各放各的。
我博客一直想要一个友链聚合页——把朋友们最近的 RSS 文章、友链可达性、主页截图汇到一页里。
之前用的 check-flink 撑不起这些了，后面看到原作者 willow-god 又搞了个新项目 Friend-Circle-Lite，于是 fork 下来做了二开。
上游已经把核心跑通了，但有几个点跟我自己的用法对不上：友链真源只想放在 FCL 仓库、对外发布的 friends.json 字段名要对齐我的主题、Astro 这类客户端渲染的站反链抓不到、截图和告警没人管。
于是按自己的用法加了一些小功能。
线上效果：fc.yufish.cn，本站的朋友圈、友链数据和截图延迟都来自这个项目。
spider_settings.source：local / remote 切换开关friends_input.rename 读写共用一份桥接eo_ping_url 国内延迟探针 + verified 人工核验postprocess.siteshot + refresh_dayspostprocess.geo_diagnose.cnb.yml）原版把友链真源远程读取 json_url。我加了个 spider_settings.source 开关：
local：真源在 FCL 仓库的 friends.json，Issue 申请通过后自动写回这里；remote：真源在外部博客的 /friends.json 端点，FCL 只巡检展示、不维护，对应 Issue 自助申请整套关闭。同一份字段映射既管读取又管发布：我博客用 title/siteurl/imgurl，FCL 内部用 name/link/avatar，两边都不用迁就对方。配起来就是 conf.yaml 里这几行：
1spider_settings:2 source: local3 list_key: "friends"4 friends_input:5 rename:6 name: "title"7 link: "siteurl"8 avatar: "imgurl"9 linkpage: ""10 verified: ""值留空 "" 表示直接用 FCL 原生字段名，不做映射；填了就按外部端点字段名取/重命名。这样不同的端点字段名不一也能零改动适配。
原版只在静态 HTML 里找你的域名。可部分网站的友链是客户端渲染的，静态 HTML 里根本没有友链列表，反链永远判「无」。我加了 Playwright 无头渲染兜底（backlink_headless），没装 playwright 时自动回退静态匹配、不阻断主流程，装了就用无头浏览器渲染后再判定。
由于GitHub Actions服务器在美国，访问国内网站延迟会失真，于是我加了 eo_ping_url 国内延迟探针，额外测一个国内视角并自动取优显示；另加了 verified 人工核验标记（默认关），用于给个别网站添加白名单，避免反链误报反复打扰。
1link_check:2 enable_backlink_check: true3 author_url: "x1anyu.cn"4 eo_ping_url: "" # 留空则走仓库环境变量 EO_PING_URL5 backlink_headless: true # 未装 playwright 自动跳过postprocess.siteshot.refresh_days 控制截图有效期，图龄超过天数自动重新截：
1postprocess:2 siteshot:3 enable: true4 upload_folder: "friends"5 max_workers: 26 refresh_days: 7 # 7 天前的截图自动重拍；0 = 永久有效apply-friend.yml 支持 Issue 形式的友链自助申请：访客提交 [友链申请] Issue → 工作流解析 → Playwright 验证可访问性 + 反链 → 通过即写回 friends.json，失败打 待更新 标签。
主流程里再用 github-script 做巡检回评：不可达或反链丢失就自动给对应申请 Issue 回评、打标签，恢复了再撤。verified 站点不会因反链误报被反复打扰。
postprocess 拆成三段，开关集中在 conf.yaml，CI 只注入敏感信息与路径：
geo_diagnose：不可达站点地域屏蔽二次诊断（含国内视角二次探测）；siteshot：截图回填 + 图床上传；alert：状态翻转告警，QQ 机器人经 blog-bot 转发消息加了一份 .cnb.yml（cnb.cool 的流水线），和 GitHub Actions 二选一，跑的是同一组命令。
仅人工手推
pull/push
needs
tree比对变了才force
普通push
该验
pass
不pass
访客回复评论
写回真源
dispatch
友链方回复
friends.json · main 分支
唯一真源
cache 分支
cache.sqlite3 orphan 单文件
Friend Circle Lite 工作流
schedule 每4h · dispatch · push
Job1 检测
pull cache→抓RSS/可达性/反链
→postprocess: 告警diff
→Issue巡检回评→push cache
→强推 page
Job2 截图 needs Job1
Selenium 增量截友链主页
普通 push page
Job3 保活 always
page 分支产物
index/link/all/friends.json
Vercel · fc.yufish.cn
博客 friends.astro
useRemote 渲染
Issue opened/reopened
或 comment ·「友链申请」
解析·去重·闸门「待更新」
Playwright 核验
可达性+反链含 AUTHOR_URL
pass→写回 friends.json
关 Issue
不pass→打「待更新」开放
gh workflow run 主流程
仅 shouldVerify
alert 检出状态翻转
不可达/反链丢失/恢复
持续离线档位/反链缺失
POST /api/alert
blog-bot Worker
QQ 主动消息→我
失败兜底企微
巡检异常→评论Issue
打待更新；恢复移除
仅人工手推
pull/push
needs
tree比对变了才force
普通push
该验
pass
不pass
访客回复评论
写回真源
dispatch
友链方回复
friends.json · main 分支
唯一真源
cache 分支
cache.sqlite3 orphan 单文件
Friend Circle Lite 工作流
schedule 每4h · dispatch · push
Job1 检测
pull cache→抓RSS/可达性/反链
→postprocess: 告警diff
→Issue巡检回评→push cache
→强推 page
Job2 截图 needs Job1
Selenium 增量截友链主页
普通 push page
Job3 保活 always
page 分支产物
index/link/all/friends.json
Vercel · fc.yufish.cn
博客 friends.astro
useRemote 渲染
Issue opened/reopened
或 comment ·「友链申请」
解析·去重·闸门「待更新」
Playwright 核验
可达性+反链含 AUTHOR_URL
pass→写回 friends.json
关 Issue
不pass→打「待更新」开放
gh workflow run 主流程
仅 shouldVerify
alert 检出状态翻转
不可达/反链丢失/恢复
持续离线档位/反链缺失
POST /api/alert
blog-bot Worker
QQ 主动消息→我
失败兜底企微
巡检异常→评论Issue
打待更新；恢复移除
我博客是 Firefly 主题。友链页面修改数据在线获取自 FCL，本地 friendsConfig.ts 作为兜底数据，同时写一份同步脚本每日同步，每天12点自动检测远程，有改动就自动添加，无改动则静默。
src/config/friendsConfig.ts 里只开一个开关：
1export const friendsPageConfig: FriendsPageConfig = {2 useRemote: true, // true = 拉 fc.yufish.cn 实时数据；false = 仅用本地兜底3 remoteBaseUrl: "https://fc.yufish.cn", // 页面从此取 friends.json / link.json4 imgProxy: { // 封面图同域反代，走博客 CDN 避免访客直连图床5 enabled: true,6 fromHost: "imgbed.yufish.cn",7 toHost: "x1anyu.cn",8 },9};src/pages/friends.astro 的拉取逻辑分两步、各自有回退：
link.json 拿封面截图和延迟状态；friends.json 拿友链清单，远程优先、失败回退到本地 friendsConfig.ts；fetch(..., { cache: "no-store" }) 的实时刷新，页面打开即重渲染。博客机器人是一套跑在 Cloudflare Workers 上的服务。它给 FCL 提供了告警端点：
| 端点 | 方法 | 作用 |
|---|---|---|
/api/alert | POST | FCL 后处理告警推送，QQ 单聊主动消息 |
这部分是踩坑后最该写清楚的地方——上游文档对 Secrets 语焉不详，我按真实工作流把变量列全。
流水线 .github/workflows/friend_circle_lite.yml 三个触发入口：每 4 小时定时（00 */4 * * *）、推 friends.json 到 main 自动巡检、workflow_dispatch 手动。步骤是：恢复 cache 分支缓存 → run.py 抓取检测 → postprocess all 后处理 → Issue 回评 → 组装静态产物强推 page 分支。并发做了串行化，避免定时 / 手动 / 截图 job 互相覆盖。
Vercel 这边 vercel.json 只一句，只从 page 分支部署：
1{2 "git": { "branch": "page", "deploymentEnabled": { "main": false } }3}缓存由根目录 _headers 控制（注意：Vercel 只读根 _headers，不读 static/edgeone.json，后者是死配置），给 index.html / all.json / link.json / errors.json / friends.json 设 no-cache，图片字体等长缓存。
需要在 FCL 仓库 Settings → Secrets and variables → Actions 里配的 Secrets：
| Secret | 用途 | 必填 |
|---|---|---|
GITHUB_TOKEN | 推 page 分支、触发 workflow、清理运行记录 | 内置自动提供，不用手动建 |
QQ_BOT_ALERT_URL | blog-bot 的 /api/alert 地址 | 想收告警则填 |
QQ_BOT_ALERT_TOKEN | 与 blog-bot 的 ALERT_TOKEN 一致 | 同上 |
WECOM_WEBHOOK_URL | 企业微信 webhook 兜底渠道 | 可选 |
IMG_UPLOAD_URL | 图床上传端点（siteshot 用） | 想用截图则填 |
IMG_AUTH_CODE | 图床鉴权码 | 同上 |
PROXY_URL | 代理地址（国内抓 RSS / 检测） | 可选 |
EO_PING_URL | 国内延迟探针端点（对应 eo_ping_url） | 可选 |
AUTHOR_URL | 反链检测的本站域名（apply-friend.yml 用，默认 x1anyu.cn） | 可选 |
SMTP_PWD | 邮件功能密码 | 基本不用（email_push / rss_subscribe 均关） |
conf.yaml 里凡标注「推荐走环境变量、配置留空」的项，就对应上面这些 Secrets；填了 Secrets 后 conf.yaml 里保持空串即可。
非敏感变量写在 wrangler.toml 的 [vars] 里（随代码提交），敏感信息用 wrangler secret put 注入（不进仓库）：
1wrangler secret put WX_TOKEN # 企微回调 Token（只用企微才需要）2wrangler secret put WX_AESKEY # 企微 EncodingAESKey3wrangler secret put WX_CORPID # 企业 ID4wrangler secret put WX_SECRET # 应用 Secret5wrangler secret put ALERT_TOKEN # /api/alert 鉴权 token，须与 FCL 的 QQ_BOT_ALERT_TOKEN 一致6wrangler secret put GH_TOKEN # GitHub PAT（repo 权限），写文章/动态/开友链 Issue 用7wrangler secret put QQ_PRIVATE_KEY # QQ 机器人 Ed25519 私钥（只用 QQ 才需要）wrangler.toml 里已固化的关键 [vars]：
| 变量 | 含义 |
|---|---|
GH_OWNER / GH_REPO / GH_BRANCH / GH_PATH | 博客仓库定位（写文章 / 动态） |
FL_OWNER / FL_REPO / FL_BRANCH / FL_PATH | 友链真源仓库定位（FCL 的 friends.json） |
QQ_APPID / QQ_CALLBACK_PATH | QQ 机器人 AppID 与回调路径 |
SITE_URL / R2_PUBLIC_URL | 站点域名与图床公开域名 |
DEPLOY_MODE | cf = 纯 Cloudflare 自解密；hybrid = 作 EdgeOne 的 /internal 后端 |
KV（草稿 / access_token 缓存）和 R2（图床）在 wrangler.toml 以 binding 形式声明，不是 Secret。
| 时间 | 内容 |
|---|---|
每 4 小时（00 */4 * * *） | 抓取 + 检测 + 后处理全套 |
推 friends.json 到 main | 真源变更后立即重跑一轮 |
开 [友链申请] Issue | 申请通过后自动写回并触发主检测 |
进仓库 Actions → Friend Circle Lite → Run workflow，只有一个参数：
target_link：填友链名称或 URL 关键词（多个用 | 或逗号分隔），只处理匹配的那几个；留空 = 按增量规则处理全部。改这个就能「只截某几个友链的图 / 只重测某几个」，不会把其他友链的数据冲掉。在我博客友链页填表单 → 开 [友链申请] Issue → apply-friend.yml 解析并 Playwright 验证 → 通过写回 friends.json。失败会打 待更新 标签，修复后在 Issue 下回任意内容即可重验。
| 我想… | 怎么做 |
|---|---|
| 日常看看谁挂了 | 等每 4h 自动跑，或 Actions → Run workflow（target_link 留空） |
| 新加了个友链，只测它 | Run workflow，target_link 填名字或 URL 关键词 |
| 给别人加友链 | 在 friends.json 添加友链 → 自动触发验证 |
| 某友链失效被标「待更新」 | 修复后在对应 Issue 下回任意内容 → 自动重验 → 通过撤标签 |
| 截图太旧了 | Run workflow 填 target_link 触发增量截图，或等 refresh_days 自动重拍 |
截图会过期，且有兜底链。 refresh_days 控制图龄，超期自动重拍；截图上传走图床，图床挂了也有在线兜底服务，不会白屏。Selenium 那套在 CI 装 Chrome 要两三分钟，所以截图拆成独立 job，不和每 4h 的轻量检测抢时间。
反链用 verified 挡误报。 客户端渲染的站靠 Playwright 兜底能认，但仍有个别反爬站抓不到。与其天天被误报吵，不如手动标 verified 让巡检跳过它的反链检查——这是给站长自己留的「我确认过」开关。
状态翻转才告警，不是每轮都推。 notify.run 先比对本轮和上轮 link.json，没变化就静默；有变化且 alert.enable 开着才推。QQ 通道失败会自动降级到企业微信，两条都没配就跳过，绝不阻断主流程。
真源只维护一份。 友链清单只在 FCL 仓库的 friends.json 维护（local 模式），博客自动拉取、连本地兜底都是脚本同步出来的。加友链只需要在这边添加，不用两边改。
fork 一个别人维护得挺好的项目，最舒服的地方就是能在它结实的地基上，按自己的用法挑几处改。截图、地域诊断、Playwright 反链兜底、Issue 自助申请、QQ 告警、CNB——这些都不是多高深的东西，但拼起来正好适合我的使用场景。
演示地址: music.x1anyu.cn
动手前项目里有三块桌面专属的东西：desktop/（Electron 主进程、窗口、菜单）、server/（本地后端，干网易云/QQ 反代和 Cookie 转发的活）、local-server.mjs（开发态本地服务）。连 package.json 里的 electron 依赖和打包脚本一块删掉，项目立马轻了一截。
vite.config.ts 里原来挂了个 neteaseApiPlugin，开发态把网易云接口代理到本地后端。删掉它，vite 的 plugins 就剩 react() 和 tailwindcss()，成了一次纯粹的前端构建，开发态不再有后端。
第一个是 base: './'。桌面端资源都在本地，无所谓；但纯网页常常被丢到子目录或对象存储的某个路径下，构建产物要是写死 /assets/xxx 这种绝对路径，一放非根目录就整页 404。把 vite 的 base 设成 './'，产物全走相对路径，dist/ 扔哪都能跑——子目录、对象存储、EO Pages 都行。
第二个是状态。后端没了，歌单和设置没地方放，最顺手的去处就是浏览器 localStorage（musicApi.ts + uiStorage.ts，歌单 key 是 sonic-topography-playlists-v1）。好处是零后端、打开即用，代价是状态全绑在这台浏览器上——换设备、清缓存，歌单就没了。
第三个是音源，换成 Meting。网页端其实只走两路：Meting 接口（默认 tencent，就是 QQ 音乐）+ 本地文件上传。启动时默认加载一个 Meting 歌单（DEFAULT_METING_PLAYLIST_ID = '7991874132'）并放第一首，免得进来是张空白页。
实际对接的是初叶 Meting（metowolf 的衍生版），不是 metowolf 原版，接口细节有点差别，下面写的都是实测过的。它响应统一带 Access-Control-Allow-Origin: *，配合 AudioEngine 的 crossOrigin="anonymous"，音频能播也能拿去做频谱可视化，正好补上「没登录态也能播」这个缺口。
基址是 /api，不是根路径。初叶的 base 长 https://meting.yufish.cn/api 这样，解析路径是 /?server=&type=&id=。漏掉 /api 直接 404。前端 metingApi.ts 里的 METING_BASE 一定得带这个后缀。
返回字段是 title / author / url / pic / lrc。注意 url / pic / lrc 这三个不是真实资源的直链，而是接口端点，各自再 302 跳到真实资源。
type=lrc 返回的是纯文本歌词（不是 JSON）。type=url 返回的是音频端点，302 跳到真实音频 CDN，同样带 Access-Control-Allow-Origin: *，所以音频可视化没问题。地址解析有优先级。运行时可覆盖的 Meting 地址按这个顺序取：localStorage sonic-topography:meting-api → window.__SONIC_METING_API__ → public/meting-config.json 的 base → 环境变量 VITE_METING_API。部署时填个自建地址就能切走公共实例。默认搜索源设成 'meting'。
状态、构建、音源都顺了，下一个坑出在 3D 背景封面上。它时好时坏，特别容易误判。
pic 返回的是接口端点，真实图片要 302 跳到腾讯图片 CDN（y.gtimg.cn / y.qq.com，偶尔 qpic.cn）。这些 CDN 不返回 Access-Control-Allow-Origin。后果分两种：
<img>。浏览器加载 <img> 不读像素，跨域限制不拦它，所以播放条封面一直正常显示，这也是我一开始没察觉的原因。THREE.TextureLoader，WebGL 贴图要读像素。CDN 没 CORS 头，纹理被标成跨域污染，加载失败，背景封面就不显示。同一张图，一个地方好使一个地方坏。根子就在 CORS 污染：<img> 能看不能读，WebGL 既要看又要读。
修法是在交给 TextureLoader 之前，把已知缺 CORS 的图床主机先包一层图片代理：
1function resolveCoverUrl(pic?: string): string | undefined {2 if (!pic) return undefined;3 // 腾讯图床不返 CORS，WebGL 读像素会被污染 → 走图片代理补 CORS4 const noCorsHosts = ['y.gtimg.cn', 'y.qq.com', 'qpic.cn'];5 if (noCorsHosts.some(h => pic.includes(h))) {6 const proxy = localStorage.getItem('sonic-topography:meting-pic-proxy')7 || 'https://proxy-api.x1anyu.cn/pic/?url=';8 return proxy + encodeURIComponent(pic);9 }10 return pic;11}自建的 edgeone /pic 图片代理（相当于 weserv 的角色，但跑在广州节点、同源可控）会返回 Access-Control-Allow-Origin: *，污染就解了。代理默认就是它，也能经 localStorage sonic-topography:meting-pic-proxy 改回 weserv 或任何自建端点。
上游只有一条 CSS 断点 @media (max-width: 600px)，压根没有 JS 侧的 isMobile。第一件事就是加一个 JS 媒体查询，在组件里分流布局：
1const MOBILE_MQ = '(max-width: 768px), (pointer: coarse)';2const isMobile = typeof window !== 'undefined'3 ? window.matchMedia(MOBILE_MQ).matches4 : false;pointer: coarse 是关键——它盯的是「主输入设备是不是粗指针（手指）」，不是屏幕宽度。触屏笔记本、平板会命中，普通桌面显示器不会。这样切出来的 isMobile 在真机上才准，不会误伤那些逻辑分辨率卡在 768 附近、实际是鼠标 + 触屏混用的设备。
顺带把 CSS 断点从 600px 提到 768px，跟这条 JS 断点对齐。不然 JS 判 isMobile 和 CSS 改样式会在同一台设备上各判各的，出现「JS 当手机、CSS 当桌面」的错位。
确定哪些地方是手机布局、哪些是桌面布局之后，有两种做法：
@media 把桌面样式改写成手机样式。isMobile ? <手机布局> : <桌面布局> 直接分流。我一开始想走 A，少写重复结构。撞到的第一个坎是 Tailwind v4 下，某些 transform 类用 CSS 覆盖不掉。具体说，桌面端播放条某个元素用了 translate-x-* / -translate-x-full 这类工具类，我在 @media (max-width: 768px) 里写 transform: none !important 想压平，结果没生效。不是 !important 没写，是 Tailwind v4 的生成规则在那个具体类上赢了层叠和内联优先级。
于是下决心走 B：凡是手机和桌面布局差到「要改 transform / 要换元素结构」的地方，直接 isMobile ? ... : ... 在 JSX 层分成两套。桌面那套的 transform 类根本不参与手机渲染，从根上避开覆盖之争。CSS 只留「同一个 DOM、只是间距字号不同」的微调，比如按钮 min-height: 46px、font-size: 14px 这种纯数值覆盖。
说白了就是：结构或 transform 差异大就 JSX 分支，纯数值微调就 CSS 覆盖。两种混着用最稳，非要只用一种反而麻烦。
桌面端那个左侧菜单的触发，最早是挂在一个「hover 就展开」的整高触发条上（side-nav-trigger / side-nav-trigger-right，absolute left-0 top-0 h-full + pointer-events-auto），靠 onMouseEnter 展开、onMouseLeave 收起。桌面鼠标 hover 没问题。
到了手机上，这条触发条是一整条 pointer-events-auto 覆盖层，把左缘的 touch 全吞了——点歌单按钮、滑菜单，全没反应，事件根本传不到下面真实的按钮上。
⚠️ 大坑：任何「悬停才出现/才触发」的交互，在手机上必须落地成一次明确的 tap，否则整片覆盖层会吞掉下面所有 touch 事件。
修法：移动端把触发条的 pointer-events 设成 none、给 onMouseEnter 加个 if (isMobile) return，hover 展开在手机上直接失效；真正打开菜单交给左上角齿轮按钮的 onClick 切换 isMobileSideNavOpen。
左侧菜单超长可滚动。菜单项一多，手机竖屏塞不下。原来 justify-center 居中，超长底部就被裁。改成 justify-start gap-6 overflow-y-auto，菜单比屏长就自己滚，不再丢项。
播放条按钮均分。手机播放条独立一行，8 个按钮（菜单 / 循环 / 上一首 / 播放 / 下一首 / 歌词 / 主题 / 音量）用 flex 均分，触摸目标够大。音量不是常驻滑块，是点一下弹个竖向滑块：showMobileVolume 状态 + 一个 writing-mode: vertical-lr; direction: rtl 的竖向 range（.vol-vertical），松开再收起来。手机横屏本来就窄，常驻横向音量条太占地方，弹窗更顺手。
Sonic Topography 有三种歌词样式：songyancai（默认，2D 时间线）、dynamic-bounce（弹跳）、spatial-wall（3D 环绕，渲染在 Three.js 画布里）。
手机上其实更想要 3D 环绕那种沉浸感。我在 App.tsx 初始化 lyricsSettings 时做了个判断：
1import { STORAGE_KEY as LYRICS_SETTINGS_STORAGE_KEY } from './lib/lyricsSettings';2// ...3const stored = readLyricsSettingsStorage();4const isMobileInit =5 typeof window !== 'undefined' &&6 window.matchMedia('(max-width: 768px), (pointer: coarse)').matches;7const initial =8 isMobileInit && !localStorage.getItem(LYRICS_SETTINGS_STORAGE_KEY)9 ? { ...stored, style: 'spatial-wall' }10 : stored;要点：
spatial-wall。桌面端沿用改后的全局默认 songyancai。有个容易忽略的点：上游全局默认其实是 spatial-wall，这轮我们把它翻成了 songyancai，再用这条 override 给手机端恢复 3D 环绕。所以「手机端 3D 环绕」严格说是「恢复」不是「新加」。spatial-wall 是在 3D 画布里渲染的，2D 的 LyricsDisplay 在 style === 'spatial-wall' 时直接 return null。所以手机端默认开启后，2D 歌词浮层让位给 3D 环绕歌词。顺带提一个之前留的坑：.lyrics-main-container 那条移动端 CSS 写着「关闭 3D 倾斜避免溢出与变形」。它只作用于 2D 歌词容器的内联 transform，对 spatial-wall（走 3D 画布）完全没影响，所以这次默认开 3D 环绕不用动它。当初写它是为了防止 2D 歌词在窄屏被 transform 撑变形，跟 3D 环绕是两码事。
重排过程中，几个一直没改好的细节也一起收掉了：
歌名别拼歌手。原来桌面歌名显示成 周杰伦 - 红尘客栈 这种「歌手 - 歌名」合并串。根子是 trackName 状态在加载歌曲时拼成了 ${artist} - ${name}，桌面 meta 直接用了它。改法是桌面歌名改用 currentSong?.name（手机端早这么用了），歌手单独走下面那行 currentSong?.artist。trackName 这个组合串我没删，它还给 3D 标题和「无歌时的禁用判断」用，属于无害残留，没必要为了干净把依赖它的地方也改崩。
关掉歌名滚动。原来歌名是跑马灯（MarqueeTitle 组件，两份重复 span + CSS 动画）。桌面空间够，根本不用滚，反而晃眼。直接换成静态 <div className="truncate ...">，超长就省略号，不再动。
左上角齿轮贴边 + 移动端常显。上游品牌齿轮（brand-mark）定位在 top-[88px] left-[56px]，而且没有那圈半透明圆——初稿里「原来套了一圈光晕」是我写错了，那圈 rounded-full border border-white/15 bg-black/30 其实是我们加在右菜单按钮的移动端分支上的，不是上游基线。真正改的是齿轮位置：移动端从 top-[88px] left-[56px] 移到 top-[10px] left-[10px] 贴左上角，可见条件从「仅 showLeftIcon」放宽成「移动端永远显示」（(displaySettings.showLeftIcon || isMobile) && !(isMobile && isRightSidebarOpen)）。要是你觉得右菜单按钮那圈圆角边框碍眼，它现在确实还在，可以一并去掉。
菜单点开关不了。播放条上的菜单按钮，原来 onClick 只干一件事：setIsRightSidebarOpen(true)，只能开不能关，再点一次当然没反应。改成 toggle：开着就关，关着就开并切到歌单视图：
1onClick={() => {2 if (isRightSidebarOpen) setIsRightSidebarOpen(false);3 else { setIsRightSidebarOpen(true); setMobileRightView('list'); }4}}改完再点菜单按钮，开合就正常了。到这里，从桌面到手机，网页版总算能当个正经播放器用了。
MusicManager 是挂在 Layout 上的全局单例，负责拉歌单、管 <audio> 元素、做 Web Audio 频谱分析，是真正的”大脑”。MusicVisualizer 只管可视化：Three.js 那块 InstancedMesh 方块、着色器、OrbitControls，音频数据从 Manager 拿，驱动地形起伏。music.astro 就是个页面壳，把可视化挂上去。
为什么要做成全局单例、而不是只放在 /music/ 页里？因为 Firefly 的页面切换走的是 Swup 软导航——切页面不整页重载、不重跑脚本。播放器想跨页面连续播，就必须活在被保留的那一层（Layout）里。
数据源用 Meting API，配置只有一行 meting.api，歌单 id 写死在配置里。接口自己掌控的好处是灵活，代价是 cookie 和可用性得自己维护。
链路本身不长：
1const source = audioCtx.createMediaElementSource(audioEl); // 把 <audio> 接进 Web Audio2source.connect(analyser);3analyser.connect(audioCtx.destination); // 这根不能省4// 每帧5analyser.getByteFrequencyData(freqData); // 0–255 的实时频点能量freqData 是一串 0–255 的频点能量，地形就是拿它去驱动 InstancedMesh 里每个方块的高度——方块数量固定，每帧只改矩阵、不重建几何体，所以铺几万个也不卡。
两个通用但容易忽略的点：
analyser.connect(destination) 这根线必须接。分析器不是”旁路监听”，它是串联在链路上的——接了分析器却没接输出，声音直接没了。createMediaElementSource 对同一个 <audio> 元素只能调一次，重复调用会抛 InvalidStateError。所以初始化那里要有锁，否则 Swup 反复进出页面就会炸。meting.api 一定要写全 https://。 漏了协议头，浏览器把请求当成相对路径拼到当前页域名上，变成 x1anyu.cn/music/meting.yufish.cn/...，直接 404，歌单就拉不到。
<audio> 必须设 crossOrigin="anonymous"。 否则跨域音频会被浏览器判定为”污染”，Web Audio 的 analyser 读到的永远是 0，地形一动不动。这个属性要在元素创建时就设上，等 src 赋值之后再补是无效的。
地形不动。 MusicVisualizer 要靠 mgr.getAudio() 拿 audio 元素去做 createMediaElementSource，但 MusicManager 的公开 API 里压根没有 getAudio——拿到的是 null，代码就走进了”等一会儿再试”的 setTimeout 死循环，分析器从头到尾没连上。补上 getAudio: function () { return audio; } 之后地形立刻活了。
这个 bug 的表现很有迷惑性：歌照放、进度条照走、UI 一切正常，只有地形是死的。因为播放本身根本不经过 Web Audio，只有可视化依赖它。所以排查时很容易往”着色器写错了""数据没传到”那边想，实际是源头就没接上。
主题 Meting 默认指向的公共 API 用不了了，找了一圈也没几个能长期用的公共实例。于是干脆把 Meting-UI-API 这个 fork 自己部署了一份，跑在 Vercel 上。
本以为克隆个仓库、设两个环境变量就完事，上线后才发现两个绕不开的问题：国内访问慢，以及 QQ 音乐的歌词拿不到。这篇记录怎么填这两个坑，以及哪几步才是真正起作用的。
Vercel 函数默认部署在美国东部（IAD1），这才是国内访问慢的原因。
点一首歌，播放器实际会向 API 发 4 次请求：song → url → pic → lrc。我在中国，Vercel 在美国。每一次请求都是一次跨境往返，叠加起来就是 4 倍 RTT。
把函数区域从美东改到**香港（hkg1）**后，体感是立竿见影的——链路短了一大截，那 4 次往返的叠加延迟直接砍掉。这一步比任何代码层面的优化都直接。
最好的做法是直接写死在 vercel.json，免得哪天换机器、重新部署后忘了在控制台设：
1{2 "env": { "RUNTIME": "vercel" },3 "functions": {4 "api/index.js": { "regions": ["hkg1"] }5 },6 "rewrites": [7 { "source": "/(.*)", "destination": "/api" }8 ]9}控制台也能改（Settings → Functions → Region → Hong Kong），但写进配置文件才不会因为忘记设置又回到美东。改完记得 Redeploy。
现象：在 Vercel 上，type=lrc&server=tencent 返回 {"error":"no data"}，但 search/url/pic 都正常，netease 的歌词也正常。
原因：QQ 音乐的歌词接口 c.y.qq.com/lyric/fcgi-bin/fcg_query_lyric_new.fcg 对境外 IP 有限制，其余接口不校验。所以只需要在请求 tencent 歌词时，把域名换成国内的中转服务即可。
我在 api.js 里留了一个开关：
1const LYRIC_PROXY = process.env.LYRIC_PROXY || '';2// ...3if (type === 'lrc' && server === 'tencent' && LYRIC_PROXY) {4 const proxyBase = LYRIC_PROXY.replace(/\/$/, '');5 const origCurl = meting._curl.bind(meting);6 meting._curl = (url, body) =>7 origCurl(String(url).replace(/^https:\/\/c\.y\.qq\.com/, proxyBase), body);8}只有 tencent 歌词会走代理，其他请求完全不受影响。留空则走直连（国内/无限制环境正常工作）。
我一开始用的是 EdgeOne 的边缘函数，结果在 Vercel 上依然拿不到歌词。排查了半天才突然想到：
⚠️ 边缘函数是就近执行——谁调用它，它就跑在谁附近的边缘节点上。
Vercel 在美国 → 代理函数跑在美国边缘 → 从美国 IP 去抓 c.y.qq.com → 还是被 QQ 墙。等于白忙活。
正解是用 EdgeOne Makers（Cloud Functions），它是「固定区域」执行，能在 edgeone.json 里把地域钉死：
1{2 "mainlandRegions": ["ap-guangzhou"],3 "overseasRegions": ["ap-guangzhou"],4 "cloudFunctions": { "maxDuration": 30 }5}广州节点（ap-guangzhou）永远是国内 IP，从国内抓 QQ 歌词 → 放行。代理函数本身极简，就是个带白名单的 fetch 转发：
1const UPSTREAM = 'https://c.y.qq.com';2
3export async function onRequest(context) {4 const u = new URL(context.request.url);5 if (!u.pathname.startsWith('/lyric/')) {6 return new Response('forbidden', { status: 403 });7 }8 const target = UPSTREAM + u.pathname + u.search;9 const headers = new Headers();10 headers.set('host', 'c.y.qq.com');11 headers.set('referer', 'https://y.qq.com/');12 headers.set('user-agent', 'Mozilla/5.0 ... Chrome/120 Safari/537.36');13
14 const upstream = await fetch(target, { method: context.request.method, headers });15 const text = await upstream.text();16 return new Response(text, { status: upstream.status });17}部署命令（注意 -n 指定名称，避免和已存在的同名项目撞车）：
1cd makers-proxy2edgeone makers deploy -n meting-qq-proxy拿到 Makers 默认域名后，把它填进 Vercel 的 LYRIC_PROXY 环境变量，重新 Deploy 即可。
同理，腾讯云 SCF、阿里云 FC、你自己的国内 VPS，只要「执行位置固定在国内」都能干这活，思路完全一致。
区域改香港之后，单次请求已经很快了。这两项优化是进一步把体验做稳，属于「有了更好」。
边缘缓存：之前所有响应都没设缓存头，Vercel 不会边缘缓存，重复请求每次都回源。加上 s-maxage 后，重复请求由 Vercel 边缘就近返回：
1const setEdgeCache = (c, type) => {2 const ttl = (type === 'url' || type === 'pic') ? 600 : 3600;3 c.header('Cache-Control', `public, s-maxage=${ttl}, max-age=60`);4};错误响应不缓存，避免把「无数据」也顶到边缘上。
内联播放直链（&fill=1）：默认情况下，单曲接口返回的 url 是一个「再去拉一次」的 API 地址，播放器拿到后还要再发一次 type=url 请求才拿到真正的 mp3。等于白送一次往返。加上 fill=1 后，服务端并行把直链解析好直接塞进 url 字段：
1const audioUrl = urlId2 ? (fillSong ? await resolveAudioUrl(server, urlId, cookie)3 : `${get_url(c)}?server=${server}&type=url&id=${urlId}`)4 : '';这里有个取舍：只对 type=song（单曲）做内联，playlist/search/artist 这些返回数组的不内联——否则一张歌单几十首，服务端要并发去打几十次接口，反而把自己打挂。所以内联保持「按需开启」（默认关），播放器调 type=song 时拼上 &fill=1 就能少一次往返。
合并到一半想回退，手比脑子快，直接 git merge --abort——本以为会回到合并前。结果工作树两百多个文件全没了，git status 一片 D，但索引还在。后来才摸清，git checkout <分支>、git rm <file> 这几个在这环境里都会触发同样的”物理删除”，我三个全中。
恢复倒不难，一条底层管道把索引里的 blob 重新写回磁盘就行：
1git checkout-index -a -f # 把索引里所有 blob 重新写回磁盘跑完 git status -s 归零、git diff HEAD --stat 为空，文件一个没少。
这关最费脑子。上游把横幅/壁纸/侧栏整套重写了，引入 WallpaperSection、SidebarColumn 和 getBannerVisibilityState()，还把我依赖的那几个 isBannerMode/isFullscreenMode 布尔变量删了。
我那一言横幅正好挂在这几个旧变量上，于是冲突变得很别扭：两边各自引用了对方才有的变量——上游代码引用我这边已经删的，我的代码引用它那边刚删的。哪一段单独取都不对，干脆谁都别取，整段重写。
最后手动把一言重挂到新的 banner 模型上：渲染走 BannerHomeTextOverlay，逻辑塞进 MainGridLayout 的新薄壳。也就是换个挂点。
这事给我提了个醒：私有功能尽量挂在配置入口，别依赖主题内部的实现细节（布尔变量、DOM 结构这些）。不然上游每重构一次，我就得手动重挂一次。
这个最隐蔽。src/types/siteConfig.ts 根本不在冲突清单里，git 自动合并时直接拿上游版本覆盖了我私改的部分——我加的 anime? 类型块没了，构建报 ts(2353)。
所以现在合完我第一件事就是跑 astro check，把被吞的私有类型补回来。这坑藏得深，不跑检查根本发现不了。
一言副标题在新布局里连着出了三个问题，一个比一个隐蔽。
第一个，一言被顶到标题上方。 旧布局给 .banner-subtitle 加了 position: absolute; top: 0，新上游是 flex 列布局，这一下直接把它粘到 overlay 顶部，跑到标题上面去了。修法是把绝对定位收窄到 .banner-subtitle-wrap 容器内，普通 .banner-subtitle 回归文档流。
第二个，副标题消失后主标题上下跳。 打字机删空、加载中、回退无数据时，副标题高度塌成 0，上方主标题跟着跳。给一言槽恒定预留一行高度就稳了：
1#banner-subtitle[data-hitokoto="1"],2#banner-subtitle-fallback {3 min-height: 1.4em;4}这选择器只作用一言模式（data-hitokoto），不碰上游默认副标题——我一直守着一条线：私有功能不能影响上游默认行为。
第三个，链接图标被挤来挤去。 回退槽初始带 Tailwind 的 hidden（display:none），回退逻辑里用 display="" 去还原，结果被 .hidden 吃掉，回退槽永远不出现。改成内联 display="block" 才生效。
这三个坑的共同教训：改布局前先看清楚当前 DOM 结构——是不是 flex、背后有没有 Tailwind class 在干扰，比闷头写 CSS 重要得多。
中途手滑了一次。想放弃一部分改动，git reset --hard HEAD 一敲，一整天没提交的私有改动全没了。还好 git add 过的东西其实还在对象库里没真消失：
1git fsck --unreachable --no-reflogs # 列出悬空 blob2git cat-file -p <hash> | grep "特征串" # 按文件特征定位是哪个文件靠这两条把 git add 过的文件一个个认领了回来。没 add 过的部分是真没了，只能认栽重写——也算买个教训，改动再不满意，先 add 一把再说。
但当时写回调那会儿真磨人——AES 加 SHA1、全链路加密，还得自己手写 PKCS#7 分块。好在调通之后就不用再碰了。
后来我才发现 QQ 的机器人平台更好用，Webhook 也开放了好久。签名模型用 Ed25519，比企微那套清爽得多，所以想直接迁过去。
迁移下来最大的收获不是多接了个 QQ，而是把接入层和业务逻辑拆开了：想用 QQ 就用 QQ，想留企微就留企微，以后想接 Telegram 也只是多写个适配器，核心的「发博文/动态/友链」一行都不用动。
QQ 机器人走 Webhook，核心是 Ed25519（而不是企微的 SHA1 + 自定义 AES）。两件事：
plain_token 和 event_ts，你用私钥对 "plain_token" + plain_token + event_ts 签名返回，平台确认你持有私钥就算验证通过。X-Signature 头，值是 Ed25519(私钥, "https://bots.qq.com" + 请求路径 + 时间戳 + body) 的 base64。你本地按同样规则算一遍比对即可。没全链路加密、没自定义块长的 AES、没 XML 套娃。验签就是验签，发消息走官方 API。
1import * as ed from "@noble/ed25519";2import { sha512 } from "@noble/hashes/sha2.js";3ed.hashes.sha512 = sha512; // ⚠️ Workers 里必须手动注入，否则 ed.signAsync 会找不到哈希函数4
5// 握手6const sd = "plain_token" + plain_token + event_ts;7const sig = await ed.signAsync(new TextEncoder().encode(sd), privKey);8return Response.json({ plain_token, signature: b64(sig) });9
10// 消息验签11const concat = "https://bots.qq.com" + url.pathname + timestamp + body;12const sigBytes = base64ToBytes(signatureHeader); // X-Signature 头取出的 base64 解码13const ok = await ed.verifyAsync(sigBytes, new TextEncoder().encode(concat), pubKey);一个差点栽的坑：@noble/ed25519 在 Cloudflare Workers 里必须手动把 sha512 挂上去（ed.hashes.sha512 = sha512）。不挂的话签名走的是它内部默认实现，在 Workers 运行时下会报「hash 未定义」——这个报错信息非常误导性，查了半天才反应过来是注入没做。
我一开始的想法是「再加个 Worker 专门跑 QQ」。一想不对——企微和 QQ 干的是同一件事：解析用户意图 → 发博文 / 动态 / 友链。平台差异只在「收消息、验身份、回消息」这三步。
于是我把结构改成了这样：
AES解密+SHA1验签
Ed25519验签
dispatch/publish/githubPut
handleFriendLink
企业微信回调
wxbot/wx.js 适配器
QQ Webhook
worker.js 内联 QQ 适配器
共享业务层 src/shared.js
GitHub 仓库 构建发布
check-flink 真源
AES解密+SHA1验签
Ed25519验签
dispatch/publish/githubPut
handleFriendLink
企业微信回调
wxbot/wx.js 适配器
QQ Webhook
worker.js 内联 QQ 适配器
共享业务层 src/shared.js
GitHub 仓库 构建发布
check-flink 真源
共享业务层 src/shared.js 只认一条统一结构 {msgType, content, fromUser}，根本不关心消息来自企微还是 QQ。两个平台各自把自家协议翻译成这条结构，丢给 dispatch 就完事。
1// worker.js 入口（节选）2export default {3 async fetch(request, env, ctx) {4 const url = new URL(request.url);5 if (url.pathname === env.QQ_CALLBACK_PATH) return handleQQCallback(request, env, ctx);6 if (url.pathname === "/__qqmenu") return qqSetMenu(env); // QQ 自定义菜单7 if (url.pathname === "/__qqpanel") return qqSetPanel(env); // QQ 指令面板8 if (url.pathname === "/api/apply-friend") return handleApplyFriend(request, env);9 if (url.pathname === "/friends.json") return r2Friends(env);10 // 其余交给企微适配器；它内部对「非企微请求」返回 null，由这里兜底 40411 const wxRes = await handleWechat(request, env, url, ctx);12 if (wxRes) return wxRes;13 return new Response("not found", { status: 404 });14 }15};这里有个我挺满意的小设计：企微适配器不负责「路由归属」。它 export 一个 handleWechat，把企微相关的 GET 验签、POST 解密、各调试端点全收进去；对于「这请求根本不是企微的」情况返回 null，交给 root 兜底 404。这样 root 的 fetch 永远是「先 QQ、再各业务端点、再丢给企微、最后 404」，顺序清晰，互不越界。
我原本把企微逻辑整个抽成了独立部署的 wxbot/worker.js，后来觉得没必要——独立部署意味着企微回调地址要改、要管两份绑定、出问题时查两个地方。
最后方案是只分代码目录，不分架构：把企微那一坨挪进 wxbot/wx.js，root 用 import { handleWechat } 调它。线上还是同一个 Worker，企微回调地址一个字都不用动，QQ 和企微在同一进程里共存。对外部（企微后台、QQ 开放平台）来说，什么都没变。
1import { dispatch } from "../src/shared.js";2export async function handleWechat(request, env, url, ctx) {3 // 企微全套：验签 / 解密 / 被动回包 / cf+hybrid 双模式 / 调试端点4 // 非企微请求 → return null5}哪天真不想留企微了，删掉这一行 import 和这个文件夹就行，QQ 半边一行都不用碰。反过来想留企微、砍 QQ 也一样。平台成了可插拔的模块。
ed.hashes.sha512 = sha512 会莫名其妙报错，记住就好。"https://bots.qq.com" + path + timestamp + body 原样拼，少一段、顺序错、把 query 也算进去，验签全失败。建议直接拿官方示例的拼接方式对齐，别自己发挥。media/get 受「可信 IP 名单」限制，Worker 出口 IP 不在名单里，下载素材会报 60020。所以图片一律改成链接写（封面：外链、），适配器里根本不存图，只引导。这点 QQ 反而省心，能直接发图。/^\/(友链|friend|fl)(\s.*)?$/ 匹配，结果 . 不匹配换行，一发多行信息块就被当成普通博文吞了。改成「前缀式」/^\/(友链|friend|fl)(?:\s|$)/ 才行。我后来实在烦了，干脆重做了一套：真源只留一份，申请走 GitHub Issue 模板让机器人核验反链，每天定时巡检谁挂了自动提醒。博客侧只管展示，检测逻辑全在另一个仓库里跑。
检测系统这套（check-flink）是我基于 fqzlr/check-flink 改造的——在原版友链巡检基础上，加了自助申请核验、SSRF 防护和自动同步。
友链清单两边各存一份：真源放在 check-flink，本地这份只作兜底。
static/friends.json 真源
博客构建期 fetch
定时巡检回写状态
apply-friend.yml 解析+验证
push main 触发
check-flink 仓库
部署到 friends.yufish.cn
my-blog 友链页
GitHub Issue 申请
check_links.yml 重新部署
static/friends.json 真源
博客构建期 fetch
定时巡检回写状态
apply-friend.yml 解析+验证
push main 触发
check-flink 仓库
部署到 friends.yufish.cn
my-blog 友链页
GitHub Issue 申请
check_links.yml 重新部署
check-flink：友链的「数据库」加检测系统。真源是 static/friends.json，部署到 friends.yufish.cn；两个 workflow 管「申请核验」和「定时巡检」。my-blog：博客本身（Firefly 主题，Astro）。友链页构建期 fetch 远程清单，本地 friendsConfig.ts 只是断网兜底。为啥拆两个仓库？因为检测系统要读写 Issue、强推 page 分支，权限和操作都跟博客构建没关系。拆开后我博客仓库保持干净，检测系统那边怎么折腾都不影响线上站点。
友链清单我只留一份真源，在 check-flink 的 static/friends.json。博客本地的 friendsConfig.ts 从一开始就是「断网 / 404 时的保底」，平时根本不参与显示——因为 friends.astro 的 loadFriends() 和客户端 refreshFriends() 都只读远程 friends.yufish.cn/friends.json，那个端点就是 check-flink 部署出来的。
加 / 改 / 删友链，只动 check-flink/static/friends.json 一处，博客侧全自动跟随。
博客这边 loadFriends() 就是「远程优先、本地兜底」：
1async function loadFriends(): Promise<RemoteFriend[]> {2 if (!useRemoteFriends) {3 console.log("[friends] 已配置 useRemote=false，仅使用本地 friendsConfig.ts");4 return getEnabledFriends();5 }6 try {7 const res = await fetch("https://friends.yufish.cn/friends.json", {8 signal: AbortSignal.timeout(15000),9 });10 if (res.ok) {11 const data = (await res.json()) as { friends?: RemoteFriend[] };12 const remote = (data.friends || [])13 .filter((f) => f.enabled !== false)14 .sort((a, b) => (b.weight ?? 0) - (a.weight ?? 0));15 if (remote.length > 0) return remote;16 console.warn("[friends] friends.json 为空，回退本地配置");17 } else {18 console.warn(`[friends] friends.json HTTP ${res.status}，回退本地配置`);19 }20 } catch (e) {21 console.warn("[friends] 读取远程 friends.json 失败，回退本地配置:", e);22 }23 return getEnabledFriends();24}这个开关的值来自 friendsPageConfig.useRemote，在组件里叫 useRemoteFriends。
申请入口做成 GitHub Issue 模板（friend-link.yml）。申请人填网站名称 / 链接 / 描述 / 头像 / 友链页 URL，提交后 apply-friend.yml 自动跑三步：
https:// 前缀），跟现有清单去重。verify-friend.mjs，用 Playwright 打开对方友链页，等 JS 渲染完 + 滚到底触发懒加载，再看页面里有没有指向我站的真实超链接（href / data-url）。顺带查可访问性。static/friends.json（带 issue_id），评论并关 Issue；不通过（不可达 / 没反链）就打 待更新 标签、保持开放，对方修完在 Issue 下回一句就能重验。友链页上的「自助申请」按钮直接跳这个模板：
1<a2 href="https://github.com/ImYufish/check-flink/issues/new?template=friend-link.yml"3 target="_blank"4 rel="noopener noreferrer"5 class="shrink-0 inline-flex items-center gap-1 rounded-lg bg-(--primary) px-3 py-1.5 text-xs font-medium text-white no-underline opacity-100 hover:opacity-80 transition-opacity"6>7 <svg class="w-3.5 h-3.5" fill="currentColor" viewBox="0 0 24 24" aria-hidden="true"><path d="M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12"/></svg>8 自助申请9</a>check_links.yml 里状态检测设了每天两次（cron 0 1 * * * / 0 13 * * *）；另外有个单独 job 每 6 天截一次友链主页。检测完把结果写回 result.json 强推 page 分支，博客友链页读这个状态来标「异常 / 已失效」。
巡检发现异常（不可达 / 没反链），会去 static/friends.json 查这条友链的 issue_id，在对应 Issue 下评论并打 待更新；等对方修好、下次巡检正常了，自动摘标签并评论「已恢复」。当然友链是自助申请的才有issue_id，自己添加的没有。
另外，截图和检测是两个 job，都会强推 page 分支，所以加了 concurrency 串行，免得并发覆盖把数据搞丢：
1concurrency:2 group: check-links3 cancel-in-progress: false另外我让 push: [main] 也触发检测——手动在 static/friends.json 加一条，push 后 CI 立刻核验 + 部署，不用干等下一个定时点。
检测系统跑在公开仓库，谁都能在公开 Issue 里提交任意 URL。如果验证器直接 fetch 这些地址，等于给人开了个内网探测跳板、内网服务随便打。所以 verify-friend.mjs 在做任何网络访问之前，先过一道闸门：scheme 白名单 + 私有 / 保留地址拦截。
1function isPrivateHost(ip) {2 if (!ip) return true;3 if (ip.includes(":")) {4 const v = ip.toLowerCase();5 if (v === "::1" || v === "::" || v === "0:0:0:0:0:0:0:0") return true;6 if (v.startsWith("fe80")) return true; // 链路本地7 if (v.startsWith("fc") || v.startsWith("fd")) return true; // 唯一本地8 return false;9 }10 const p = ip.split(".").map(Number);11 if (p.length !== 4 || p.some(Number.isNaN)) return true;12 if (p[0] === 0) return true;13 if (p[0] === 10) return true; // 10.x14 if (p[0] === 127) return true; // 回环15 if (p[0] === 169 && p[1] === 254) return true; // 链路本地 / 云元数据16 if (p[0] === 172 && p[1] >= 16 && p[1] <= 31) return true; // 172.16-31.x17 if (p[0] === 192 && p[1] === 168) return true; // 192.168.x18 return false;19}20
21// 任何网络访问前先校验22if (!isHttpUrl(target) || (await isPrivateHost(getHostname(target)))) {23 out.reason = "友链地址不合法或指向内网/保留地址，已拒绝访问（安全策略）";24 fs.writeFileSync(outputPath, JSON.stringify(out, null, 2));25 process.exit(0);26}重点：不只拦 IP 字面量，还要 dns.lookup 把域名解析出来再判私有——攻击者可以拿一个公网域名指向内网 IP 绕过纯字符串判断。isPrivateHost 解析失败也保守拒绝。Playwright 启动失败降级到纯 fetch 检测，那也是在 SSRF 校验通过之后才发生的。
远程是真源，但本地 friendsConfig.ts 也得留一份兜底（断网 / 远程 404 时友链页不至于空白）。问题是这份兜底怎么跟真源保持一致——总不能每次手动改两处。
我在 my-blog 里加了 scripts/sync-friends.mjs，构建 / 构建前从 friends.yufish.cn/friends.json 拉取，只重写 friendsConfig 数组，其它（friendsPageConfig / getEnabledFriends）原样不动。任何失败都只告警跳过、不阻塞构建：
1// 用锚点精确定位 friendsConfig 数组，而非脆弱正则：2// 起点 = "export const friendsConfig: FriendLink[] = ["3// 终点 = "export const getEnabledFriends"4const startMarker = "export const friendsConfig: FriendLink[] = [";5const endMarker = "export const getEnabledFriends";6const si = file.indexOf(startMarker);7const ei = file.indexOf(endMarker);8if (si === -1 || ei === -1 || ei < si) { /* 跳过 */ }9const before = file.slice(0, si);10const after = file.slice(ei);11await writeFile(SRC, before + replacement + "\n" + after, "utf8");这里还做了字段兜底：远程某条缺 weight / enabled 时补 0 / true，否则会写出不合法的 TS，让 astro build 类型检查挂掉、整站部署失败。
同步脚本我也挂进了 GitHub Actions（sync-friends.yml），每天跑一次，有变才 commit 回仓库，无变就不动。从此本地兜底自动跟随真源，我只用改 check-flink 一处。
有时候我想临时冻结友链（调试、或远程不可达时不想依赖它），加了个开关，放在 friendsPageConfig.useRemote：
1export const friendsPageConfig: FriendsPageConfig = {2 // ...3 // true（默认）= 使用远程 friends.yufish.cn/friends.json4 // false = 仅用本地 friendsConfig.ts5 useRemote: true,6};这开关有个坑我记一下：必须两处都拦。构建期 loadFriends() 要拦，客户端 refreshFriends() 也得拦。客户端脚本读不到 TS 常量，所以用 Astro 的 define:vars 把值注进去：
1<script is:inline define:vars={{ USE_REMOTE: useRemoteFriends }}>2 async function refreshFriends() {3 if (!USE_REMOTE) {4 console.log("[friends] 已配置仅用本地友链，跳过远程刷新");5 return;6 }7 // ...拉远程重渲染8 }9</script>只拦构建期不够——会出现「构建期读本地、页面加载完客户端又偷偷拉远程盖掉」的假象。开关放在 friendsPageConfig 里，而 sync 脚本的锚点是 friendsConfig 数组到 getEnabledFriends，开关在区间之外，自动同步永远碰不到它。
static/friends.json。博客本地 friendsConfig.ts 只是兜底，改它页面不会显示、检测系统也扫不到。[\s\S]*?\]; 切 friendsConfig 数组，结果数组里某条数据自带 ]; 导致切片错位、整脚本跳过。改成按 export const friendsConfig: FriendLink[] = [ 和 export const getEnabledFriends 两个锚点 indexOf 切片，再没错位过。useRemote 只拦构建期不够，客户端 refreshFriends() 也得拦，否则出现「本地构建、远程覆盖」的假象。只有一步：在 check-flink 的 static/friends.json 加一条，或者走 Issue 自助申请模板填表提交。剩下的——核验反链、定时巡检、状态提醒、博客侧同步、断网兜底——全自动。
整套跑在 GitHub Actions 上，公共仓库免费，零成本。
上面这些实现都在我的两个仓库 check-flink 和 my-blog 里，感兴趣可以自己翻。
先看整条链路。从你发消息到文章上线，中间一共四跳：
1企业微信（收消息 + 被动回复）2 │ 解密后的 XML3 ▼4EdgeOne 边缘函数（解密 / 验签 / 加密回包）5 │ /internal 转发（hybrid 模式）6 ▼7Cloudflare Worker（攒草稿 → 拼 markdown → 写 GitHub）8 │ commit 一个 .md 文件9 ▼10GitHub（Actions 自动构建部署博客）最绕的是「被动回复」。企业微信要求你在收到回调后 5 秒内把回复写进响应体，而且必须是加密的 XML。真实的写博客动作（调 GitHub API、等部署）绝对不能在 5 秒里同步做完，否则超时企微就当你没回。
我的做法是：边缘函数收到消息，先解密、立刻拼一句「已记录」加密回包返回（满足 5 秒），再在后台把内容丢给 Worker 去写 GitHub。回不回消息和写不写文章是两条线，互不阻塞。
EdgeOne 边缘函数，http 响应返回之后，普通 fetch 会被运行时强制终止。 向后端 Cloudflare Worker 转发任务，必须使用 event.waitUntil(fetch(…)) 包裹转发逻辑。 如果不包，企微能收到 “已记录” 回复，但后续写 GitHub 逻辑直接不执行，很难排查。
最早我全放在 Cloudflare 上，企业微信回调死活访问不通。当时直觉是「CF 源站在国内被掐了」，于是把入口迁到 EdgeOne（国内 CDN，理论上更稳）。
结果迁过来还是不通。最后一行行查，发现是我自己写的 AES 加解密有 bug——企微回调用的是 AES-256-CBC + PKCS7，密文前面还要拼 16 字节随机串和 4 字节消息长度，回包还要按它的格式再加密一遍。只要哪一步字节对不上，企微就直接当你非法请求，表现就是「回调不通」。
修好之后我才确认：Cloudflare 源站本来是通的，当初根本不用换入口。为了不依赖任何第三方库（CF / EO 的运行时都不一定让你装包），我直接用了纯 JS 实现，核心是拿 Web Crypto 的 AES-ECB 当 AES-256-CBC 的轮函数，自己拼 CBC 链和 PKCS7 填充：
1// // Web Crypto 不直接提供 AES‑256‑CBC，基于原生 AES‑ECB 手动实现 CBC 模式，无第三方依赖2async function aes256cbc(key32, iv16, data, decrypt) {3 const wkey = await crypto.subtle.importKey("raw", key32, "AES-ECB", false, ["encrypt", "decrypt"]);4 const pad = (b) => { const n = 32 - (b.length % 32); const p = new Uint8Array(n).fill(n); const o = new Uint8Array(b.length + n); o.set(b); o.set(p, b.length); return o; };5 const unpad = (b) => b.subarray(0, b.length - b[b.length - 1]);6 let prev = iv16, out = new Uint8Array(decrypt ? data : pad(data));7 const step = decrypt ? data.length / 16 : out.length / 16;8 for (let i = 0; i < step; i++) {9 const blk = out.subarray(i * 16, i * 16 + 16);10 const d = new Uint8Array(await crypto.subtle[decrypt ? "decrypt" : "encrypt"]({ name: "AES-ECB" }, wkey, blk));11 for (let j = 0; j < 16; j++) d[j] ^= prev[j];12 if (decrypt) prev = blk.slice(); else { prev = d.slice(); out.set(d, i * 16); }13 }14 return decrypt ? unpad(out) : out;15}这段在 Cloudflare Worker 和 EdgeOne 边缘函数里各放了一份，逻辑完全一样，企微都能正确解开。也是因为它没有 npm 依赖，后面做纯 CF / 纯 EO 才能直接复制过去用。
这个坑最麻烦，因为它不报错。
被动回复的 XML 结构企微是有标准 schema 的，里面没有 AgentID 这个字段。我当时顺手把 agentid 也塞进了回包（想着反正带上呗），结果企微收下后什么都不回、什么都不报错，表现就是「收不到任何回复」。我对着日志看了半天，加密对了、验签对了、回包也返回 200 了，就是没动静。
最后发现是那个多余的 AgentID 字段让企微判定回包非法，整条静默丢掉。把回包 XML 里的 AgentID 删掉、重部署，机器人就能收到消息了。
1// 回包内层 XML：千万别带 AgentID2const xml = `<xml>3 <Encrypt><![CDATA[${encrypt}]]></Encrypt>4 <MsgSignature>${sig}</MsgSignature>5 <TimeStamp>${ts}</TimeStamp>6 <Nonce>${nonce}</Nonce>7</xml>`;指令集现在是这样的，发文字给它就会攒成一个草稿，指令控制行为：
| 指令 | 作用 |
|---|---|
/done 或 /发布 | 把当前草稿发布成文章或动态 |
/取消 /清空 /cancel | 丢弃草稿，下次从头写 |
/动态 | 切到动态模式（短内容，文件名用时间戳） |
/文章 | 切到文章模式（文件名用标题） |
/tags | 设置文章标签，如 /tags: 折腾, 教程 |
/状态 | 看看当前草稿攒了多少、什么模式 |
/预览 | 返回将要发布的 markdown 原文，不发 |
/修改 | 把草稿全文甩回给你，下次回复整体替换重算 |
/帮助 | 打印上面这一张表 |
文字里以「键: 值」开头的行会自动识别成文章属性，中英文键名都认（标题： / tags: 都行），剩下的当正文。几个常用的点：
2026-08-14-020613.md；文章用 FILENAME_FORMAT 开关——title（默认）就是纯标题 标题.md，date 就是 2026-08-14-标题.md。slug: 05，发布后返回 https://你的域名/posts/05；不设 slug 就退回文件名链接。location: 广西 和 pinned: true，直接进 frontmatter。[文字](url) 就行，链接行不会被误吞。封面：https://... 才用；不写就 image: api（随机封面），发的图只进正文不抢封面。标记（@提及 / #话题标签）目前不可用，正文直接写文字即可。
用环境变量 DEPLOY_MODE 切换角色。现在三种模式随时换：
hybrid（默认）
EdgeOne 当入口解密回包，真正的写博客交给 Cloudflare Worker 的 /internal。国内延迟最低，两套东西各司其职。
eo（纯 EdgeOne）
EdgeOne 自己解密、自己 dispatch、自己写 GitHub，草稿存 EdgeOne 的 KV（绑定名 DRAFTS），Worker 彻底退休。入口本来就在 EO、解密回包也已跑通，只补「写 GitHub + KV 存草稿」两步，是改动最小的一个。
EdgeOne 的 KV 存储仅规则引擎形态边缘函数支持，普通 JS 边缘函数无法绑定 KV；切换为 eo 模式部署前先确认你的边缘函数类型。
代码已存档在仓库 edge-functions/wxbot.js（与图床反代 index.js 分立），部署时作为企微入口边缘函数发布即可。
cf（纯 Cloudflare）
反过来，回调直接打 Cloudflare Worker，Worker 自己解密 + 回包 + 写 GitHub。需要把 EO 那份纯 JS AES 加密回包逻辑搬进 Worker（已经搬了，且跑了加解密往返测试，企微能正确解开）。
切换就是改环境变量，业务逻辑同源、指令集完全一致：
1# EdgeOne 侧（index.js 的环境变量）2DEPLOY_MODE = "hybrid" # hybrid / eo3
4# Cloudflare 侧（wrangler.toml 的 [vars]）5DEPLOY_MODE = "hybrid" # hybrid / cf切到 cf 时，企业微信回调的入口域名得从 EdgeOne 换成 Cloudflare 的 Worker 域名——所以「换模式」不只是改个 env，还牵动域名指向，部署时要一起改。
纯 EO 那个 KV 绑定我在 EdgeOne 规则引擎形态里实测过能跑；万一你控制台那边 KV 绑定名不是 DRAFTS，回去补一下绑定就行，代码不用动。
昨天逛别人友链，看到有人写了篇「用微信发博文」的文章，点进去扫了一眼，觉得挺有意思。今天自己研究了一下，发现原作者的方案需要一台服务器——而我没有，这条路直接走不通。
那就换个思路。企业微信的机器人不用服务器也能收消息；再借 EdgeOne 的边缘函数把消息转到 Cloudflare Worker，Worker 负责把内容拼成 markdown 丢进 GitHub，GitHub Actions 一跑，博客就自动发出来了。
整条链路全白嫖，零成本把整个项目跑起来了 ♫꒰･◡･๑꒱
如果你有服务器，原作者的方案更简单，可以参考：把博客后台搬进微信：随手一条消息就能发动态、笔记、足迹
一开始我其实打算全丢在 Cloudflare 上部署的。结果卡在企业微信机器人的 API 回调，怎么配都访问不通。当时以为是 Cloudflare 源站被墙了，就把入口换成了 EdgeOne。
后来排查才发现，根本不是源站的问题，是我自己加密算法没写好。也就是说，当初可能压根不用换入口。这个坑后面专门写一篇，顺便研究下能不能弄出「纯 CF」和「纯 EO」两个更干净的版本。
发动态是真方便：切到动态模式随手一句就发，出门在外不用再登后台。
]]>1. 语句从哪来：local 打包 vs remote 拉取
sentences-bundle 按 a~l 共 12 类分文件存。组件里两种模式靠 bundleSource 切换：
local：构建时打包进 public/hitokoto/hitokoto.json，零外部依赖，加载最快；remote：运行时直接拉 jsDelivr 远程包，不想跑构建就选它，但多一个 fallbackToLocal 开关。2. 四类展示位统一
侧边栏 widget、首页横幅、页脚、文章内 ::hitokoto 指令，共用同一个配置中心 hitokotoConfig 和同一个 fetcher src/utils/hitokoto.ts。区别只在”展示参数”和”装数据的容器”。横幅额外有个独立 banner 块（独立开关 + 分类白名单 + 打字机），其它三个读全局开关再用各自 data-* 覆盖。
一句话概括：一个配置中心 + 一个 fetcher + N 个展示位各自接线。把开关收拢到 hitokotoConfig 之后，想调展示、换来源、加展示位都是局部改动，不会牵一发动全身。
local
remote
失败
开
关
bundleSource
本地包
拉远程包
fallbackToLocal
侧边栏/页脚/文章内隐藏
展示一条
侧边栏
横幅打字机
页脚
文章内指令
local
remote
失败
开
关
bundleSource
本地包
拉远程包
fallbackToLocal
侧边栏/页脚/文章内隐藏
展示一条
侧边栏
横幅打字机
页脚
文章内指令
1. 缓存没 TTL → 换不了句子
早期直接裸数组缓存，部署更新了 hitokoto.json 对已缓存老访客无效，表现就是”换不了句子”。加 6 小时 TTL 后，老访客最多 6 小时内自动拿到新库；旧格式裸数组兼容成 ts=0，自然失效重拉。缓存 key 要含 bundleSource + 启用分类 + remoteUrl——你关了某分类 key 就变，缓存立刻失效，不会显示关掉的类别。
2. fallbackToLocal 的两种行为别混
开关开 → 退本地包，组件照常显示；开关关且远程挂 → 侧边栏/页脚/文章内直接隐藏，但首页横幅副标题要切到主题 TypewriterText 预设节点（无预设才隐藏）。这两类行为不一样，写回退逻辑时得分开处理。
3. 页脚在 Swup 容器外
其它展示位在 Swup 容器里，页面切换 DOM 重渲染会重新触发绑定；页脚不在，跨页面不换 DOM。所以每次导航要把它的 dataset.filled 重置成 "0" 强制重拉，否则翻页后那句不更新。
4. 打字机按码点切分
Array.from(full) 而不是 String[i]，否则中文/emoji 会截一半乱码。
5. remoteUrl 必须 @master
sentences-bundle 没 release tag，@latest 在 jsDelivr 直接 404。另外六个语言文件的 i18nKey 漏一个，astro check 就报翻译缺 key，部署前过一遍 check。
组件基于 Firefly 主题开发，主要用到它的侧边栏 widget 注册体系。
博客是纯静态站，天气数据只能在浏览器里 fetch，没法构建时拿。这决定了两件事：接口得允许跨域，国内那些要登录、要 Key、还常限频的基本可以排除。
最后定了四个源，原则是能免 Key 就免 Key、国内优先：
| 数据源 | Key | 角色 |
|---|---|---|
| uapis.cn | 不需要 | 国内主力，单接口返回全部，反射 Origin 放行跨域 |
| 和风天气 | 需要 | 兜底，实时更准 |
| Open-Meteo | 不需要 | 坐标出中国包围盒就用，免费不限频 |
| wttr.in | 不需要 | 全球兜底，不带空气质量 |
整个组件最关键的设计是四源归一化：不管哪个源，全部 map 成同一套 {cur, daily, aqi, city}，渲染层完全不关心数据从哪来。后面换源、加源都不用动 UI。配置中心（weatherConfig）+ fetcher（拉 + 归一化 + 缓存）+ 渲染三层分离，widget 只管画。
uapis
归一化
和风
Open-Meteo
wttr
统一结构 {cur,daily,aqi,city}
渲染层
uapis
归一化
和风
Open-Meteo
wttr
统一结构 {cur,daily,aqi,city}
渲染层
1. scoped 样式对动态 DOM 不生效
组件运行时往 DOM 塞内容，Astro 的 scoped <style> 只对编译期存在的节点打 hash，运行时注入的吃不到。表现就是样式明明写对了，刷新出来没效果。解法要么用 :global()，要么把样式丢进 <style is:global> 或干脆 inline。这个坑不在逻辑，而在「为什么样式不生效」这个排查方向上。
2. Swup 重入
Firefly 用 Swup 做 SPA 跳转，脚本不重载但 DOM 会换。所有客户端脚本要 document.addEventListener("astro:page-load", fn) 重新绑定，首屏再直接 fn() 跑一次（防错过首次事件），并用 dataset.bound 之类的标志位防重复绑。不这么干，翻几页事件就绑了好几遍，打字机动画还会两段打架——用递增 token 作废上一段动画：
1let _token = 0;2function loop() {3 const my = ++_token;4 // 循环里每步先判断 if (my !== _token) return;5}6document.addEventListener("astro:page-load", loop);7loop();3. 缓存别裸存数组
localStorage 里直接 setItem(JSON.stringify(arr)) 看着省事，结构一变老访客解包就丢数据或报错。我存 {ts, data}，带 6 小时 TTL，结构变了老缓存自动失效重拉：
1const ok = Array.isArray(obj?.data) && Date.now() - (obj?.ts || 0) < TTL;wind_speed_unit=kmh 直接是 km/h；wttr 的 windspeedKmph 已是 km/h。别混。Math.round(((deg + 22.5) % 360) / 45) % 8。/airquality，Open-Meteo 没有 AQI 得另算，兜底层级要想清楚。纯前端、零外部依赖、离线可用。把文件放在同一目录，双击 index.html 就能用，不需要 Node、不需要构建，也不依赖网络。反正就是写篇随笔，不想先起一套构建流程，打开就能写，关掉就收工。
/ 斜杠命令、查找替换、富文本粘贴、文档库多文章管理、自动保存。克隆或下载后双击 index.html 就能开始用。遇到问题或者想加点什么，欢迎去仓库提 Issue。
默认是纯前端：在设置里粘贴一个 GitHub PAT（Personal Access Token，需要 repo 权限），就能把文章直接推到你博客仓库的 src/content/posts，保存即发布。
不想在浏览器里暴露 PAT 的话，可以启用服务器模式：
firefly-markdown-worker），负责 OAuth 登录并代理 GitHub Contents API；用 PAT 直连不需要任何后端，只有想走 OAuth 登录时才用得上它。
欢迎使用 Astro ，这是您的第一篇文章。编辑或删除它，然后尽情Ciallo~
]]>