年华

Vercel 部署后全站 404 排查记

Fri, 07 Aug 2026 00:00:00 GMT

引言#

本博客同时部署在 Vercel、Cloudflare Workers、EdgeOne Pages 等多个平台。某天发现：

本地开发、Cloudflare、EdgeOne 访问全部正常；
唯独 Vercel 上的域名（blog.amamo.top）所有 HTML 页面都返回 404，而非 HTML 资源（_astro/*、图片、pagefind、rss.xml 等）全部正常。

CI 构建日志显示构建、部署、Alias 全部成功。这是一个”部署成功但内容缺失”的诡异问题，折腾了很久，记录下完整的排查思路和根因。

观察现象#

对线上逐路径探测，得到如下行为矩阵：

路径	状态码
`/`、`/about/`、`/posts/xxx/`	404（响应体是站点自定义 404 页）
`/_astro/.css`、`.js`、图片	200
`robots.txt`、`rss.xml`、`pagefind/*`	200
`/index.html`、`/about.html`	308 重定向到去扩展名路径

关键信息：

非 HTML 静态资源 200，说明部署确实上传了文件；
所有 HTML 页面 404，说明 HTML 部分出了问题；
*.html 请求被 308 重定向，说明存在 cleanUrls 风格的路由规则。

排查过程#

第一步：确认是部署产物问题而非缓存#

本地 pnpm dev 正常，dist/ 里 37 个 index.html 都在。为了排除中间层 CDN 缓存，带随机 query 重新请求，仍然是 404。查看响应头：

1
server: Vercel
2
x-vercel-cache: HIT

404 是源站（Vercel 边缘）自己返回的，不是 CDN 缓存了旧响应。

第二步：对比「部署文件列表」与「本地产物」#

通过 Vercel API 拉取最新部署的文件列表：

Terminal window

1
curl -H "Authorization: Bearer $TOKEN" \
2
  "https://api.vercel.com/v13/deployments/<id>/files"

结果出乎意料：37 个 HTML 文件全部在部署里，路径也都正确（posts/astbot/index.html、about/index.html 等）。文件在、路径对，线上却 404 —— 说明文件内容在服务端无效。

第三步：找到 cleanUrls 冲突#

本地执行 vercel build --prod 后检查生成的 .vercel/output/config.json，发现 CLI 生成了大量 overrides 和 308 重定向规则：

1
{
2
  "overrides": {
3
    "index.html": { "path": "index" },
4
    "about/index.html": { "path": "about/index" }
5
  },
6
  "routes": [
7
    { "src": "^/(?:(.+)/)?index(?:\\.html)?/?$", "headers": { "Location": "/$1" }, "status": 308 }
8
  ]
9
}

这就是问题一：vercel.json 里的 "cleanUrls": true 会让 CLI 把所有 HTML 文件”改名为无扩展名”（about/index.html → about/index）。于是：

请求 /about/ 走目录解析，找 about/index.html —— 不存在（已被改名）；
请求 /about/index —— 被 308 重定向规则切到 /about；
/about 又找不到文件 —— 404。

而 /404 之所以能 200，是因为它不在重定向规则里、能直接命中改名后的 404 文件。

修复后，404 页面本身回归正确 404，/、/about/ 等一级页面全部 200。但 /posts/、/gallery/、/dynamic/ 依旧 404 —— 还有第二个问题。

第四步：定位真正的元凶 —— l2s 上传 bug#

继续对比，发现一个奇怪规律：有一级子目录的「父目录」全部 404，纯叶子目录全部 200：

1
/about 200    /archive 200    /search 200
2
/posts 404    /gallery 404    /dynamic 404     （这三个目录里还有子目录）

此时检查本地 .vercel/output/static/ 里的文件类型，真相大白：

1
output/static/about/index.html      # 普通文件 529060 字节（正常）
2
output/static/posts/astbot/index.html -> /home/qwc/Firefly/dist/posts/astbot/.l2s..l2s.index.html0001.00010001   （符号链接！）

Vercel CLI 58.7.1 的 l2s 上传优化在处理大文件时，把 index.html 替换成了指向失效路径的符号链接（symlink），真实数据被写进了 .l2s.index.html0001.0002 分片文件。上传时 Vercel 把这些符号链接原样记录（目标路径在服务器上不存在），于是:

HTML 在文件列表里”存在”，但服务端读取时解析不到 → 404；
about/index.html 是硬链接（保留真实文件）→ 正常；
wrangler（Cloudflare）上传时会跟随符号链接读到真实内容 → CF 完全正常。

这也解释了为什么 CI 部署时上传只有 19.8MB（大量符号链接被跳过/去重），而实际产物有 52MB。

为什么新版本 CLI 有问题，旧版本没问题#

这次问题的核心在 Vercel CLI 58.x 引入的 l2s（large-file storage）上传优化。它的本意是把大文件切分成约 1MB 的小块（.l2s.<文件名>0001、0002…），以便内容寻址去重、并发上传、断点续传，服务器端再重组。57 和 58 都用了分片，但实现方式截然不同：

	分片后的原文件	上传结果
vercel@57	保留为真实文件（与分片文件互为硬链接，link count = 2），`readFile` 随时能读到完整内容	正常
vercel@58.7.1	被替换成符号链接，指向本地绝对路径（`/home/qwc/.../.l2s...`），且出现嵌套分片（`.l2s..l2s.` 双层前缀）	服务端解析不到 → 404

58.7.1 的具体问题有两个：

symlink 目标写死成本机绝对路径：posts/astbot/index.html -> /home/qwc/Firefly/dist/posts/astbot/.l2s..l2s.index.html0001.00010001。这个路径只在本机存在，上传到 Vercel 后无法解析，文件”在列表里、读不出内容”。
对已分片的文件再次分片：正常的 l2s 分片命名是 .l2s.index.html0001.0001，而 58.7.1 在部分文件上生成了嵌套前缀 .l2s..l2s.index.html0001.00010001，说明分片逻辑对”分片产物”又跑了一遍，symlink 指向了错误的目标。

而 57 的处理方式是硬链接：index.html 和 .l2s.index.html0001.0002 是同一个 inode 的两个目录项，index.html 始终是真实文件、内容完整。上传时 CLI 读到的就是完整数据，服务器端重组无需依赖符号链接。

为什么”以前正常、某一天突然全站 404”：CI 里用的是 npx vercel（不带版本号），npx 每次拉取的都是最新版。以前最新版还是 57.x（实现正确），某次升级到 58.7.1（实现有 bug）后，CI 的每一次部署都带着坏掉的符号链接上传——所以在 GitHub Actions 部署日志全部成功的情况下，线上依旧全站 404。

为什么 Cloudflare / EdgeOne 不受影响#

同一份 dist，三家平台的部署工具走的是完全不同的上传模型：

部署工具	上传模型	遇到 symlink	结果
`wrangler`（Cloudflare）	逐文件 `readFile` 读取内容上传	自动跟随链接，读到真实字节	正常
`edgeone pages deploy`	逐文件读取内容上传	自动跟随链接	正常
`vercel deploy`（CLI 58）	本地预处理 + 内容寻址分片上传	把 symlink 当路径记录，不上传内容	404

wrangler / edgeone 是朴素的”文件内容上传”模型，没有本地预处理这一层，符号链接在读文件时就被解析掉了，自然不受影响。Vercel CLI 因为多了 l2s 预处理层，才把 bug 带进了部署产物。多平台部署（CF / EdgeOne / Vercel）在这种场景下相当于交叉验证：同一份 dist，别人正常、只有 Vercel 异常，问题几乎可以锁定在 Vercel 的部署链路上。

根因总结#

两个问题叠加：

cleanUrls: true 与 Astro 的 trailingSlash: "always" 冲突 —— HTML 被改名导致带尾斜杠的路由全部 404；
Vercel CLI 58.x 的 l2s 上传 bug —— 更大的问题，大文件被替换成失效符号链接，导致部分目录的 HTML 无法读取。

两个问题都只在 Vercel 这边出现，Cloudflare / EdgeOne 的部署链路不受影响。

解决方案#

直接修复#

从 vercel.json 删除 cleanUrls: true，HTML 文件保持原名，目录路由恢复正常；
固定 Vercel CLI 版本到 57：
Terminal window
```
1
npx -y vercel@57 build --prod
2
npx -y vercel@57 deploy --prebuilt --prod
```
vercel@57 同样会生成 l2s 分片，但采用硬链接（index.html 保持真实文件），上传到 Vercel 后数据完整。58.7.1 则会被坏符号链接“阉割”掉大文件。
CI workflow 中同步把 npx vercel 改为 npx vercel@57，防止自动升级到带 bug 的版本。

经验总结#

部署”成功”不等于内容完整，排查时对比线上返回值与本地产物而不是只看状态码；
对于知名 PaaS 的 CLI，锁定版本是避免”莫名其妙” bug 的最有效手段（npx vercel → npx vercel@57）；
多平台部署（CF / EdgeOne / Vercel）有交叉验证的作用：同一份 dist，wrangler 正常、vercel CLI 异常，直接指向 CLI 本身的问题。

怎么用Netlify反代

Wed, 05 Aug 2026 00:00:00 GMT

怎么反代#

首先去Netlify官网注册账号。再去你的github新建一个仓库，只要写一个netlify.toml（在根目录下），内容如下

1
[[redirects]]
2
  from = "/*"
3
  to = "http://反代域名:反代端口/:splat"
4
  status = 200
5
  force = true

你只要替换http://反代域名:反代端口/:splat 如果你实际要反代的url没有端口就不填，但一定要有端口后的 / 最后回netlify创建一个新项目，选择你刚创建的Github项目，部署即可最后绑定一下你的域名。

留言页的群聊风格改造

Mon, 27 Jul 2026 00:00:00 GMT

博客的留言板应该是什么样子的？传统的评论区一层一层嵌套回复，看起来有点像论坛。但如果把它做成聊天软件那种气泡风格，会不会更有意思一点？

这篇文章就聊聊这个改造过程。

整体思路#

改造的核心是用一个自定义的 Svelte 组件替换掉原来的 Twikoo 评论挂件。组件直接与 Twikoo 的 API 通信，获取留言数据，然后以聊天气泡的形式渲染出来。

这样做的几个好处：

视觉上更统一，可以完全控制样式
交互更灵活，可以加一些原版挂件没有的功能
不需要额外引入第三方 UI，自己写更容易控制体积

API 通信#

组件通过 fetch 直接调用 Twikoo 的 API 接口，主要就两个操作：

COMMENT_GET：获取指定路径（这里是 /guestbook/）下的所有留言
COMMENT_SUBMIT：提交新的留言

Twikoo 返回的数据是嵌套结构的——每条留言下可能有若干条回复。但聊天界面不适合树形展示，所以组件把整个回复树拍平成一个按时间排序的列表，回复内容前面加上 @昵称 的前缀，这样上下文就很清晰了。

聊天气泡#

整个界面是最像聊天软件的部分。每条消息是一行，包含头像、昵称、时间和气泡内容。

头像 36 像素的圆形，优先显示 Gravatar 头像，没有的话显示昵称首字。自己的消息靠右对齐，其他人的靠左。

气泡的样式靠 border-radius 的不对称处理来实现——别人的气泡是左下角直角、其他角圆角；自己的气泡反过来，右下角直角。这种不对称感就是聊天气泡的视觉特征。

自己的气泡使用主题色作为背景，白色文字，在视觉上突出区分。管理员的消息也使用相同的样式。

区分自己与他人#

组件通过 localStorage 存储用户的留言档案（昵称、邮箱、网址），提交时会记录这条留言的 ID。再次加载时，如果某条留言的邮箱或 ID 匹配，就把它标记为”自己的消息”，显示在右侧。

自动刷新#

留言板每隔 30 秒会自动请求一次新数据，新留言会即时出现，不需要手动刷新页面。但如果用户已经向上滚动浏览历史消息，自动滚动会暂停，只有停留在底部时才会自动滚到最新消息。

个人资料弹窗#

首次留言时会弹出一个资料填写框，输入昵称和邮箱后才会显示发送栏。这些信息存在 localStorage 里，下次访问就不用再填了。

回复功能#

每条消息悬浮时会出现”回复”按钮，点击后会在输入框上方显示”回复 @某某”的提示条，发送时会将这条回复关联到原消息上。点击提示条上的叉号可以取消回复。

一些样式细节#

所有样式都写在 Svelte 组件的 <style> 标签里，使用 gb__ 前缀来避免污染全局样式。

发送按钮是圆形的，不可用时有降低透明度。消息列表限制了最大高度（520px），超出可以滚动。每条新消息出现时有一个轻微的淡入动画，让感觉更自然。

深色模式的支持没有额外处理，因为组件直接使用了 CSS 变量 var(--primary)、var(--card-bg) 这些主题变量，切换主题时颜色会自动适配。

最后#

这个改造其实不复杂，核心就是”把树形评论拍平成聊天记录”。但效果还是挺明显的——留言板不再是冷冰冰的评论区，更像一个可以聊天的空间。如果你也用的 Twikoo，不妨试试类似的改造，让访客感觉更轻松一些。

这个博客的朋友圈是怎么做的

Mon, 27 Jul 2026 00:00:00 GMT

前几天有朋友问我，博客里的”朋友圈”页面是怎么做的。仔细一想，这个功能确实挺有意思的，它把友链和内容聚合结合在了一起。今天就来聊聊它的实现思路。

什么是朋友圈#

这里的”朋友圈”不是微信那个朋友圈，而是博客圈里的一种内容聚合页。它会抓取友链列表中各位博友的最新文章，汇总展示在一个页面里。效果类似于一个迷你 RSS 阅读器，但更轻量，也更有人情味。

你可以在导航栏找到”钓鱼”入口（之所以叫钓鱼，是因为逛朋友们的博客就像钓鱼一样，你永远不知道下一秒会钓上来什么有趣的内容）。

核心思路#

实现思路其实不复杂：每个友链条目都可以配置一个 RSS 地址，系统定期去抓取这些 RSS 源，把文章信息整理后展示出来。

整个流程可以分为三步：

配置友链时附带 RSS 地址
服务端抓取并解析所有 RSS 源
前端展示为卡片列表

数据源：friendsConfig#

所有的友链信息集中管理在 friendsConfig.ts 里。每个友链除了常规的站点名、头像、网址外，还可以配置一个 rss 字段：

1
{
2
  title: "友人A",
3
  siteurl: "https://example.com",
4
  imgurl: "https://example.com/avatar.png",
5
  rss: "https://example.com/feed.xml",
6
  enabled: true
7
}

没有配置 RSS 的友链不会出现在朋友圈里，但会正常显示在友情链接页面。这样设计的好处是，每个人可以自由选择是否参与内容聚合。

数据抓取：rss-utils#

抓取逻辑集中在 rss-utils.ts 里。它同时支持 RSS 2.0 和 Atom 两种格式，通过 Promise.allSettled 并行抓取所有友链的 Feed，单个源失败不会影响其他源。

每个 Feed 最多取 5 篇文章，超时时间设为 8 秒。抓取到的文章会解析标题、链接、发布时间、摘要等信息，摘要会被截断到 200 字以内。

API 端点#

/api/circle.json 这个接口负责整合数据。它在请求时调用抓取逻辑，然后将所有文章按发布时间排序，同时返回一些统计数据：

好友总数
活跃好友数（成功抓取到文章的数量）
文章总数
最后更新时间

接口会设置一小时的缓存，避免频繁请求给朋友们的服务器造成压力。

前端展示：CircleFeed.svelte#

前端是一个完全客户端渲染的 Svelte 组件。页面加载时会请求上述接口，拿到数据后以卡片网格的形式展示。

每张卡片包含：

文章标题（最多两行，超出省略）
作者头像和名称
发布时间
文章摘要

卡片排列采用自适应网格，auto-fill 配合 minmax(260px, 1fr)，在不同屏幕宽度下都能合理展示。鼠标悬停时作者头像会高亮，增加一点交互的趣味。

分页逻辑也在客户端完成，默认每页 20 条，点击”加载更多”逐步展示。排序支持按发布时间和最近更新两种方式，切换后即时生效，不需要重新请求接口。

一些细节#

页面顶部会随机展示一条最新的文章通知（取最近 6 篇中的随机一篇），算是一个小彩蛋。统计栏可以显示好友总数、活跃数和文章数，也可以选择关闭。

评论区在朋友圈页面是可选的，如果配置了评论系统且没有禁用，文章列表下方会显示评论区，方便朋友们留言互动。

最后想说的是，这个功能的初衷很简单——希望博客之间能有更多的连接。友链不只是单向的跳转，它也可以变成一种内容的流动。如果你也有自己的博客，不妨试试在你的站点上搭建类似的功能，感受一下博客圈的温度。

今天是伟大的0721日

Tue, 21 Jul 2026 00:00:00 GMT

今天居然是0721日

Cloudflare VS Vercel？！

Fri, 03 Jul 2026 00:00:00 GMT

引言#

Vercel 和 Cloudflare 是目前较为常见的两个 Web 部署平台。Vercel 偏向前端生态和开发体验，Cloudflare 则依托其全球边缘网络提供底层计算和存储能力。两者都在往”全栈应用交付平台”的方向发展，但实现路径和适用场景有所不同。

本文将介绍双方的服务和异同点，希望能帮读者理清其中的差别，从而根据自身需求做出合适的选择。

Cloudflare#

Cloudflare 依托其全球边缘网络，将计算和存储部署在离用户较近的节点上。以下是其四个核心服务。

Workers#

Workers 是一个在 Cloudflare 全球网络上运行的无服务器计算平台，基于 Service Workers API，运行在 V8 隔离环境中，启动速度快。

能跑什么后端代码： Workers 运行在 V8 引擎上，不兼容完整的 Node.js API（没有 fs、net 等模块），但提供了 fetch、Request、Response 等 Web 标准 API。支持的编程语言包括 JavaScript、TypeScript、Rust（编译为 WASM）和 Python（通过 Pyodide）。

能运行什么框架：

Web 框架：Hono、Itty Router
全栈框架：Astro（SSR）、SvelteKit、Remix、SolidStart
静态站点：Hugo、Jekyll、Zola、Astro（静态模式）

免费计划每天 10 万次请求，128 MB 内存。

D1#

D1 是 Cloudflare 的无服务器关系型数据库，基于 SQLite，可通过 Workers 直接访问或通过 HTTP API 操作，无需管理连接池。免费计划 5 GB 存储。

KV#

Workers KV 是一个全局键值存储，数据被复制到 Cloudflare 的边缘节点，适合存储配置、缓存数据等。免费计划 10 万个键。

R2#

R2 是 Cloudflare 的对象存储服务，兼容 S3 API，特点是不收取出口流量费。阿里云 OSS 属于同一类。它主要用于存储非结构化数据，所以可以存很多东西，甚于像本站一样的博客。免费计划 10 GB 存储。

Vercel#

Vercel 与前端的框架整合较好，提供了从开发到部署的一体化体验。

Node.js 运行时#

Vercel 的核心无服务器函数基于 Node.js 运行时，也支持 Python、Go、Ruby、Bun。函数在 AWS Lambda 上执行，可以使用完整的 Node.js API。

能跑什么后端代码： 函数运行在标准的 Node.js 环境中，可以访问 fs、net、http、child_process 等所有 Node.js 内置模块，也可以安装任何 npm 包。因此能跑大多数 Node.js 后端代码，包括 Express、Fastify、Apollo Server 等。注意函数有超时限制（Hobby 计划 60 秒），不适合长时间运行的后台任务。

能运行什么框架：

React 框架：Next.js（原生支持最好）、Remix
Vue 框架：Nuxt
Svelte 框架：SvelteKit
通用框架：Astro、VitePress、Docusaurus、Hexo
几乎所有前端框架都能自动检测并选择最佳构建配置

免费计划每月 100 小时函数执行时间，单函数最大 50 MB。

数据库（PostgreSQL）#

Vercel 与 Neon 合作提供了 Vercel Postgres（现为 Vercel Storage 的一部分），是标准的 PostgreSQL 数据库。也可以用 pg 或 @vercel/postgres 连接外部 PG 实例，如 Supabase、AWS RDS 等。

构建系统#

Vercel 的构建系统会为每次 git push 自动触发构建和部署，自动检测框架并生成预览环境。免费计划每月 6,000 分钟构建时长。

D1（SQLite）与 PG 的差异#

D1 基于 SQLite，PostgreSQL（Neon）是一个独立的关系型数据库，两者差异不小：

什么项目适合什么：

D1 适合个人博客、小型 API、配置管理、原型项目、边缘地理位置需要低延迟的场景。不需要复杂查询和高并发，追求简单和免运维。

PostgreSQL 适合需要事务完整性、复杂查询、高并发的项目：如电商系统、论坛、内容管理系统、数据分析后台等。如果已经有现成的 PG 应用迁移过来也更合适。

给博客写了个后台管理

Sat, 27 Jun 2026 00:00:00 GMT

一边写博客一边觉得，要是能有个顺手的管理界面就好了。于是趁周末动手写了一个，前后端都搭在自己能掌控的基础设施上。

前端是 Firefly 主题的一部分，嵌在博客项目里，用 Svelte 5 的 runes 语法写的几个组件；后端单独部署在 Cloudflare Workers 上，框架是 Hono。

文章存在 GitHub 仓库里，通过 Contents API 读写，所以每次保存都会自动产生一次 Git 提交，版本历史天然就跟着走了。站点配置存在 Cloudflare D1 里，查询和保存都很快。图片走的是自建的 CloudFlare-ImgBed，上传时通过后端代理转发到图床，返回的 URL 直接插入 Markdown 正文。

后台主要分三块：文章编辑器带 Markdown 工具栏和实时预览，站点配置页管理社交链接和友链，还有一个图片管理器可以浏览和删除已上传的图片。编辑器支持拖拽和剪贴板上传图片，前端用 XHR 做了进度条。

后台示例

前后端都已开源：

qwc-ch

Firefly

Waiting for api.github.com...

00K

Waiting...

qwc-ch

firefly-admin-cfworkers

Waiting for api.github.com...

00K

Waiting...

待办

Sun, 21 Jun 2026 00:00:00 GMT

功能#

[√] 后台
[√] AI摘要
[√] AI聊天页面
[√] 说说/朋友圈

想法#

这几个功能里，后头没想法用伪后，还是做真后端。AI聊天页面我打算用Cloudflare Workers 不存任何记录，所以并不依赖任何数据库。其他的想到了在加……

GitHub Actions 自动构建并部署 Cloudflare Workers 实现思路

Thu, 04 Jun 2026 00:00:00 GMT

Warning

这个项目在 Cloudflare Workers 上构建时可能会翻车。Astro 构建过程依赖 sharp（图片处理）和一些 Node.js 原生模块，Cloudflare Workers 的构建环境对这些支持有限。如果你在 Workers 上构建失败，别慌，这是正常操作。解决方案是：在 GitHub Actions 里构建好，只把产物丢过去，让 Workers 只管托管静态文件，别让它干重活。

为什么要搞这个#

每次手动构建、再部署，累不累啊？反正我累了。目标是：推送代码到 main 分支后，GitHub Actions 自动帮你搞定三件事：

构建 Astro 项目（让它在 CI 里卷）
把构建产物推送到 build 分支（留个备份）
部署到 Cloudflare Workers（上线，收工）

一条龙服务，你只需要 git push，剩下的交给机器人。

整体流程#

1
push main → checkout → 安装依赖 → pnpm build → 推送 dist 到 build 分支 → wrangler deploy

实现思路#

1. 触发条件#

监听 main 分支的 push 事件，同时支持手动触发（workflow_dispatch）。手动触发的好处是：万一自动部署翻车了，你可以点一下重试，不用再 push 一个空提交。

1
on:
2
  push:
3
    branches: [main]
4
  workflow_dispatch:

2. 环境准备#

GitHub Actions 的 Ubuntu 镜像里没有 pnpm，得自己装。顺序有讲究：先装 pnpm，再装 Node.js，这样 Node.js 的缓存机制才能识别 pnpm。搞反了缓存就废了。

1
- name: Setup pnpm
2
  uses: pnpm/action-setup@v4
3
  with:
4
    version: 9.14.4
5

6
- name: Setup Node.js
7
  uses: actions/setup-node@v4
8
  with:
9
    node-version: '24'
10
    cache: 'pnpm'  # 必须在 pnpm 安装之后

3. 构建项目#

pnpm run build 其实是个三连：先生成图标，再用 Astro 构建，最后用 Pagefind 做全文搜索索引。这三步缺一不可，少了哪个搜索功能都会出问题。

1
- name: Install Dependencies
2
  run: pnpm install --frozen-lockfile
3

4
- name: Build
5
  run: pnpm run build

4. 推送到 build 分支#

用 peaceiris/actions-gh-pages 这个 action，把 dist/ 目录的内容推到 build 分支。它每次都会暴力覆盖，不会保留历史。不过也没关系，反正构建产物每次都一样。

1
- name: Push to build branch
2
  uses: peaceiris/actions-gh-pages@v4
3
  with:
4
    github_token: ${{ secrets.GITHUB_TOKEN }}
5
    publish_dir: ./dist
6
    publish_branch: build

5. 部署到 Cloudflare Workers#

最后一步，用 wrangler deploy 把构建好的静态文件丢到 Workers 上。这一步需要两个 secrets：API Token 和 Account ID，没这俩东西.wrangler 连不上 Cloudflare。

1
- name: Deploy to Cloudflare Workers
2
  run: npx wrangler deploy
3
  env:
4
    CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
5
    CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

完整源码#

1
# 构建项目并将产物推送到 build 分支，然后部署到 Cloudflare Workers
2
name: Build to Branch
3

4
# 当推送到 main 分支时触发，也支持手动触发
5
on:
6
  push:
7
    branches: [main]
8
  workflow_dispatch:
9

10
# 需要写入权限来推送 build 分支
11
permissions:
12
  contents: write
13

14
# 同一时间只运行一个构建任务，取消正在运行的旧任务
15
concurrency:
16
  group: build
17
  cancel-in-progress: true
18

19
jobs:
20
  build:
21
    runs-on: ubuntu-latest
22
    steps:
23
      # 检出代码
24
      - name: Checkout
25
        uses: actions/checkout@v4
26

27
      # 安装 pnpm 包管理器
28
      - name: Setup pnpm
29
        uses: pnpm/action-setup@v4
30
        with:
31
          version: 9.14.4
32

33
      # 安装 Node.js 并配置 pnpm 缓存
34
      - name: Setup Node.js
35
        uses: actions/setup-node@v4
36
        with:
37
          node-version: '24'
38
          cache: 'pnpm'
39

40
      # 安装项目依赖
41
      - name: Install Dependencies
42
        run: pnpm install --frozen-lockfile
43

44
      # 构建项目：生成图标 → Astro 构建 → Pagefind 索引
45
      - name: Build
46
        run: pnpm run build
47

48
      # 推送 dist 目录到 build 分支
49
      - name: Push to build branch
50
        uses: peaceiris/actions-gh-pages@v4
51
        with:
52
          github_token: ${{ secrets.GITHUB_TOKEN }}
53
          publish_dir: ./dist
54
          publish_branch: build
55

56
      # 使用 wrangler CLI 部署到 Cloudflare Workers
57
      - name: Deploy to Cloudflare Workers
58
        run: npx wrangler deploy
59
        env:
60
          # Cloudflare API Token，需要 Edit Cloudflare Workers 权限
61
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
62
          # Cloudflare 账户 ID，在 Dashboard 右侧栏可见
63
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

展开收起

需要配置的 Secrets#

在 GitHub 仓库 Settings → Secrets and variables → Actions 里加两个 secret，不加的话 workflow 会直接报错退出。

Secret	说明	获取方式
`CLOUDFLARE_API_TOKEN`	API 令牌	Cloudflare Dashboard → My Profile → API Tokens → Create Token
`CLOUDFLARE_ACCOUNT_ID`	账户 ID	Cloudflare Dashboard 右侧栏

API Token 要选 “Edit Cloudflare Workers” 模板，这个模板包含 Workers 脚本编辑权限，部署够用了。

注意事项#

--frozen-lockfile 是个好东西，确保 CI 里不会偷偷给你更新依赖版本，避免”我本地能跑线上挂了”的经典剧情
concurrency 配置能避免同时跑多个构建任务，省点 CI 分钟数
wrangler deploy 会老老实实读取仓库根目录的 wrangler.toml，所以记得把这个文件提交上去
build 分支只包含 dist/ 的内容，源码不会泄露，放心用

Firefly 主题添加WelcomeToast 组件

Sun, 31 May 2026 00:00:00 GMT

Firefly 主题 WelcomeToast 组件分析#

Firefly是一个基于 Astro的博客主题。

CuteLeaf

Firefly

Waiting for api.github.com...

00K

Waiting...

WelcomeToast 是我自己加的一个小组件，效果就是访客第一次打开页面时，右下角会弹出一个欢迎卡片，还带了 IP 地理位置的个性化问候，5 秒后自动消失。

WelcomeToast 效果演示

涉及的文件#

整个组件涉及两个文件：

文件	路径
组件本身	`src/components/widget/WelcomeToast.astro`
在布局中引用	`src/layouts/MainGridLayout.astro`

组件是怎么实现的#

这个组件的 frontmatter 是空的，没有任何服务端逻辑。所有事情都在浏览器端的 <script> 和 <style> 里完成。

页面上长什么样#

组件本身不输出任何 HTML，所有 DOM 都是 JS 动态生成的。结构大概是这样：

1
#welcome-toast（固定在右下角，z-50）
2
└── 一个卡片 div（白色背景、圆角、阴影）
3
    ├── 👋 表情
4
    ├── 文字区
5
    │   ├── 问候语（一开始显示"正在加载..."，后面会变成具体地址）
6
    │   └── 副标题"欢迎来到我的博客"
7
    └── 关闭按钮（一个 ×）

几个关键函数#

整个逻辑不复杂，就是 5 个函数各管各的事：

1
// 用 sessionStorage 做会话标识，防止重复弹出
2
const VISIT_SESSION_KEY = 'blog_visit_flag';
3
let hasShownToast = false;
4

5
// 创建 Toast 的 DOM 结构，插入到页面上
6
function createWelcomeToast()
7

8
// 关掉 Toast：先滑出去，500ms 后把节点从 DOM 里移掉
9
function closeWelcomeToast()
10

11
// 请求一个免费的 IP API，拿到访客的位置信息
12
async function fetchLocation()
13

14
// 整个弹出流程的"导演"：创建 → 滑入 → 拿位置 → 5秒后自动关闭
15
async function showWelcomeToast()
16

17
// 入口函数：判断是不是第一次访问，是的话才弹
18
function initWelcome()

展开收起

执行顺序#

说白了就是这么个流程：

怎么适配 SPA 导航的#

这里有个坑：Firefly 用了 Swup 做客户端路由，页面切换的时候不会走完整的 DOMContentLoaded。所以组件同时绑了两个事件：

1
if (document.readyState === 'loading') {
2
    document.addEventListener('DOMContentLoaded', initWelcome);
3
    document.addEventListener('astro:page-load', initWelcome);  // Swup 专用
4
} else {
5
    initWelcome();
6
}

另外关闭按钮用的是内联 onclick，所以函数得挂到 window 上才能调用：

1
(window as any).closeWelcomeToast = closeWelcomeToast;

样式部分#

桌面端：固定在右下角（fixed bottom-4 right-4 z-50），用 CSS transition 做滑入滑出动画，500ms ease-out。
移动端（640px 以下）：改到屏幕底部居中，宽度 90%，不会遮挡太多内容。
深色模式：用 Tailwind 的 dark: 变体自动切换背景色、边框色和文字色。

在 MainGridLayout 里怎么放的#

MainGridLayout 是 Firefly 的主布局，导航栏、壁纸、侧边栏、Footer 都在这里面。WelcomeToast 在第 7 行被 import，然后放在了第 858 行：

1
import WelcomeToast from "@components/widget/WelcomeToast.astro";

具体位置是在 #swup-container 里面、<slot /> 后面：

1
<main id="swup-container" class="transition-main">
2
    <div id="content-wrapper">
3
        <slot></slot>
4
    </div>
5
    <WelcomeToast />
6
</main>

整个布局大概是这么个层级关系：

1
Layout.astro
2
└── MainGridLayout.astro
3
    ├── Navbar（导航栏）
4
    ├── Wallpaper（背景壁纸）
5
    ├── <main id="swup-container">      ← Swup 的容器，导航时会替换这里面的内容
6
    │   ├── <slot>                       ← 每个页面的具体内容
7
    │   └── <WelcomeToast />             ← 放在内容后面
8
    ├── Footer（页脚）
9
    └── FloatingControls（浮动控制按钮）

几个值得注意的点#

没传任何 props：组件完全是自包含的，不需要从外面传参数。
靠 sessionStorage 去重：每次 Swup 导航都会重建组件，但因为有 blog_visit_flag 标记，所以不会重复弹出。
兼容 Swup 的 astro 事件：客户端路由切换后也能正常触发。
构建时没有 HTML 输出：组件只有 <script> 和 <style>，不产生静态 HTML，全靠 JS 在浏览器里创建。

总结#

WelcomeToast 说白了就是一个浏览器端的欢迎弹窗，用 sessionStorage 保证每个会话只弹一次，用 IP API 拿位置做个性化问候，5 秒自动消失。放在 Firefly 主题的 MainGridLayout 里，和 Swup 的 SPA 导航机制配合得很好。

为 Firefly 添加 Umami 访问统计卡片

Fri, 29 May 2026 00:00:00 GMT

Note

这篇文章是基于 THW’s Blog 的教程改造的，感谢大佬的分享。

为什么要加统计#

搞个博客总想知道有没有人看吧。Umami 是个轻量级的统计工具，部署简单，也不会像 Google Analytics 那样隐私问题一堆。

但问题来了：Umami 自带的分享链接打开就是一个独立页面，跟博客风格完全不搭。所以我把它做成了一个侧边栏组件，嵌进博客里，打开就能看到访问数据，顺眼多了。

准备工作#

前提是你已经部署好了 Umami，然后拿到一个分享链接。后面填进代码里就行。

添加组件#

在 src/components/widget/ 目录下新建一个 UmamiStats.astro 文件，把下面的代码贴进去：

1
---
2
import WidgetLayout from "../common/WidgetLayout.astro";
3

4
interface Props {
5
  class?: string;
6
  style?: string;
7
}
8
const { class: className, style } = Astro.props;
9
---
10

11
<WidgetLayout name="统计" class:list={["umami-stats-container", className, "cursor-pointer transition-opacity active:scale-95"]} {style}>
12
    <a target="_blank" rel="noopener noreferrer" class="block umami-link">
13
        <div class="text-center py-2">
14
            <div class="text-3xl font-bold text-neutral-900 dark:text-neutral-100 umami-total-pageviews">-</div>
15
            <div class="text-sm text-neutral-500 dark:text-neutral-400">总浏览量</div>
16
        </div>
17
        <div class="grid grid-cols-2 divide-x divide-neutral-200 dark:divide-neutral-700 text-center pt-2">
18
            <div class="px-2">
19
                <div class="text-xl font-bold text-neutral-900 dark:text-neutral-100 umami-total-visits">-</div>
20
                <div class="text-sm text-neutral-500 dark:text-neutral-400">访问数</div>
21
            </div>
22
            <div class="px-2">
23
                <div class="text-xl font-bold text-neutral-900 dark:text-neutral-100 umami-total-visitors">-</div>
24
                <div class="text-sm text-neutral-500 dark:text-neutral-400">游客数</div>
25
            </div>
26
        </div>
27
    </a>
28
</WidgetLayout>
29

30
<script>
31
const UMAMI_CONFIG = {
32
    shareUrl: '你的分享链接',
33
};
34

35
let __UMAMI_INTERNAL = {
36
    baseUrl: '',
37
    websiteId: '',
38
    shareToken: '',
39
    shareId: '',
40
    isReady: false
41
};
42

43
const FALLBACK_STATS = {
44
    pageviews: 1000,
45
    visits: 1000,
46
    visitors: 1000,
47
};
48

49
async function initUmamiConfig() {
50
    try {
51
        const sharePath = UMAMI_CONFIG.shareUrl.split('/share/')[1];
52
        if (!sharePath) throw new Error('Invalid Umami Share URL');
53

54
        let apiBase = '';
55
        if (UMAMI_CONFIG.shareUrl.includes('cloud.umami.is') || UMAMI_CONFIG.shareUrl.includes('analytics.umami.is')) {
56
            const region = UMAMI_CONFIG.shareUrl.includes('/analytics/eu/') ? 'eu' : 'us';
57
            apiBase = `https://cloud.umami.is/analytics/${region}/api`;
58
        } else {
59
            const urlObj = new URL(UMAMI_CONFIG.shareUrl);
60
            apiBase = `${urlObj.origin}/api`;
61
        }
62

63
        const res = await fetch(`${apiBase}/share/${sharePath}`);
64
        if (!res.ok) throw new Error(`Failed to fetch share config: ${res.status}`);
65
        const data = await res.json();
66

67
        __UMAMI_INTERNAL = {
68
            baseUrl: apiBase,
69
            websiteId: data.websiteId,
70
            shareToken: data.token,
71
            shareId: data.shareId,
72
            isReady: true
73
        };
74

75
        const links = document.querySelectorAll('.umami-link');
76
        links.forEach(link => link.setAttribute('href', UMAMI_CONFIG.shareUrl));
77

78
    } catch (e) {
79
        console.error('Umami Config Init Failed:', e);
80
    }
81
}
82

83
function formatNumber(num: number): string {
84
    if (num >= 1000000) {
85
        return (num / 1000000).toFixed(1) + 'M';
86
    } else if (num >= 1000) {
87
        return (num / 1000).toFixed(1) + 'K';
88
    }
89
    return Math.round(num).toString();
90
}
91

92
function setStats(values: { pageviews: number; visits: number; visitors: number }) {
93
    const pageviewsElements = document.querySelectorAll('.umami-total-pageviews');
94
    const visitsElements = document.querySelectorAll('.umami-total-visits');
95
    const visitorsElements = document.querySelectorAll('.umami-total-visitors');
96

97
    const easeOutCubic = (t: number) => 1 - Math.pow(1 - t, 3);
98
    const animHandles = new Map<HTMLElement, number>();
99

100
    const animateStat = (el: HTMLElement | null, to: number, duration = 2000) => {
101
        if (!el) return;
102

103
        const prev = animHandles.get(el);
104
        if (prev) cancelAnimationFrame(prev);
105

106
        const from = 0;
107
        const startTime = performance.now();
108

109
        const tick = (now: number) => {
110
            const elapsed = now - startTime;
111
            const progress = Math.min(1, elapsed / duration);
112
            const easedProgress = easeOutCubic(progress);
113

114
            const current = from + (to - from) * easedProgress;
115
            el.textContent = formatNumber(current);
116

117
            if (progress < 1) {
118
                animHandles.set(el, requestAnimationFrame(tick));
119
            }
120
        };
121
        animHandles.set(el, requestAnimationFrame(tick));
122
    };
123

124
    pageviewsElements.forEach(el => animateStat(el as HTMLElement, values.pageviews));
125
    visitsElements.forEach(el => animateStat(el as HTMLElement, values.visits));
126
    visitorsElements.forEach(el => animateStat(el as HTMLElement, values.visitors));
127
}
128

129
async function fetchUmamiStats() {
130
    if (!__UMAMI_INTERNAL.isReady) {
131
        await initUmamiConfig();
132
    }
133

134
    if (!__UMAMI_INTERNAL.isReady) {
135
        setStats(FALLBACK_STATS);
136
        return;
137
    }
138

139
    try {
140
        const endAt = Date.now();
141
        const startAt = 0;
142
        const url = `${__UMAMI_INTERNAL.baseUrl}/websites/${__UMAMI_INTERNAL.websiteId}/stats?startAt=${startAt}&endAt=${endAt}&unit=hour&timezone=Asia%2FShanghai`;
143

144
        const response = await fetch(url, {
145
            headers: {
146
                'x-umami-share-context': '1',
147
                'x-umami-share-token': __UMAMI_INTERNAL.shareToken
148
            }
149
        });
150

151
        if (!response.ok) throw new Error(`HTTP ${response.status}`);
152
        const data = await response.json();
153
        const getValue = (field: any) => (typeof field === 'object' ? field?.value : field) || 0;
154

155
        setStats({
156
            pageviews: getValue(data.pageviews),
157
            visits: getValue(data.visits),
158
            visitors: getValue(data.visitors),
159
        });
160

161
    } catch (error) {
162
        console.error('Umami Fetch Failed:', error);
163
        setStats(FALLBACK_STATS);
164
    }
165
}
166

167
let __umamiStatsStarted = false;
168
function startUmamiStats() {
169
    if (__umamiStatsStarted) return;
170
    __umamiStatsStarted = true;
171
    fetchUmamiStats();
172
}
173

174
function initUmamiStatsVisibility() {
175
    const containers = document.querySelectorAll('.umami-stats-container');
176
    const io = new IntersectionObserver((entries) => {
177
        let isAnyVisible = false;
178
        entries.forEach(entry => {
179
            if (entry.isIntersecting) isAnyVisible = true;
180
        });
181

182
        if (isAnyVisible) {
183
            startUmamiStats();
184
            io.disconnect();
185
        }
186
    }, { threshold: 0.1 });
187

188
    containers.forEach(container => io.observe(container));
189
}
190

191
initUmamiStatsVisibility();
192

193
if (window.swup) {
194
    window.swup.hooks.on('page:view', () => {
195
        __umamiStatsStarted = false;
196
        initUmamiStatsVisibility();
197
    });
198
}
199
</script>

展开收起

配置#

代码里有个 UMAMI_CONFIG，把你的分享链接填进去就行：

1
<script>
2
const UMAMI_CONFIG = {
3
    shareUrl: '你的分享链接',  // ← 这里改成你自己的
4
};

挂到侧边栏上#

组件写好了，接下来得让它出现在页面上。打开 src/components/layout/SideBar.astro，把 UmamiStats import 进来，然后在合适的位置放上 <UmamiStats />。

下面是改完之后的完整代码，可以对照着改：

1
---
2
import type { MarkdownHeading } from "astro";
3
import Advertisement from "@/components/widget/Advertisement.astro";
4
import Announcement from "@/components/widget/Announcement.astro";
5
import Calendar from "@/components/widget/Calendar.astro";
6
import Categories from "@/components/widget/Categories.astro";
7
import Music from "@/components/widget/Music.astro";
8
import Profile from "@/components/widget/Profile.astro";
9
import SidebarTOC from "@/components/widget/SidebarTOC.astro";
10
import SiteStats from "@/components/widget/SiteStats.astro";
11
import Tags from "@/components/widget/Tags.astro";
12
import { sidebarLayoutConfig } from "@/config";
13
import type {
14
  MobileBottomComponentConfig,
15
  WidgetComponentConfig,
16
  WidgetComponentType,
17
} from "@/types/config";
18
import UmamiStats from "../widget/UmamiStats.astro";
19

20
interface Props {
21
  class?: string;
22
  headings?: MarkdownHeading[];
23
  side?: "left" | "right" | "bottom";
24
}
25

26
const SIDEBAR_SIDE = {
27
  LEFT: "left",
28
  RIGHT: "right",
29
  BOTTOM: "bottom",
30
} as const;
31

32
const COMPONENT_POSITION = {
33
  TOP: "top",
34
  STICKY: "sticky",
35
} as const;
36

37
const ANIMATION_DELAY_UNIT = 50;
38

39
const componentMap = {
40
  profile: Profile,
41
  announcement: Announcement,
42
  categories: Categories,
43
  tags: Tags,
44
  sidebarToc: SidebarTOC,
45
  advertisement: Advertisement,
46
  stats: SiteStats,
47
  calendar: Calendar,
48
  music: Music,
49
} satisfies Record<WidgetComponentType, typeof Profile>;
50

51
const side = (Astro.props.side ||
52
  SIDEBAR_SIDE.LEFT) as (typeof SIDEBAR_SIDE)[keyof typeof SIDEBAR_SIDE];
53
const className = Astro.props.class;
54

55
const getComponents = (): (
56
  | WidgetComponentConfig
57
  | MobileBottomComponentConfig
58
)[] => {
59
  if (side === SIDEBAR_SIDE.LEFT) {
60
    return sidebarLayoutConfig.leftComponents;
61
  }
62
  if (side === SIDEBAR_SIDE.RIGHT) {
63
    return sidebarLayoutConfig.rightComponents;
64
  }
65
  if (side === SIDEBAR_SIDE.BOTTOM) {
66
    return sidebarLayoutConfig.mobileBottomComponents;
67
  }
68
  return [];
69
};
70

71
const filterAndSortComponents = (
72
  components: (WidgetComponentConfig | MobileBottomComponentConfig)[],
73
) => {
74
  return components.filter((comp) => comp.enable);
75
};
76

77
const getComponentsByPosition = (
78
  components: (WidgetComponentConfig | MobileBottomComponentConfig)[],
79
) => {
80
  const topComponents = components.filter(
81
    (c) => "position" in c && c.position === COMPONENT_POSITION.TOP,
82
  ) as WidgetComponentConfig[];
83
  const stickyComponents = components.filter(
84
    (c) => "position" in c && c.position === COMPONENT_POSITION.STICKY,
85
  ) as WidgetComponentConfig[];
86
  return { topComponents, stickyComponents };
87
};
88

89
const getAnimationDelay = (index: number): string => {
90
  return `${index * ANIMATION_DELAY_UNIT}ms`;
91
};
92

93
const isPostPage = Astro.url.pathname.includes("/posts/");
94

95
const isComponentInitiallyVisible = (
96
  config: WidgetComponentConfig | MobileBottomComponentConfig,
97
): boolean => {
98
  if (
99
    "showOnPostPage" in config &&
100
    config.showOnPostPage === false &&
101
    isPostPage
102
  ) {
103
    return false;
104
  }
105
  if (
106
    "showOnNonPostPage" in config &&
107
    config.showOnNonPostPage === false &&
108
    !isPostPage
109
  ) {
110
    return false;
111
  }
112
  return true;
113
};
114

115
const getComponentProps = (
116
  config: WidgetComponentConfig | MobileBottomComponentConfig,
117
  index: number,
118
): Record<string, unknown> => {
119
  const baseProps: Record<string, unknown> = {
120
    class: "onload-animation",
121
    style: `animation-delay: ${getAnimationDelay(index)}`,
122
  };
123

124
  if ("showOnPostPage" in config && config.showOnPostPage === false) {
125
    baseProps.class = `${baseProps.class} widget-hide-on-post`;
126
    if (isPostPage) {
127
      baseProps.class = `${baseProps.class} hidden`;
128
    }
129
  }
130
  if ("showOnNonPostPage" in config && config.showOnNonPostPage === false) {
131
    baseProps.class = `${baseProps.class} widget-hide-on-non-post`;
132
    if (!isPostPage) {
133
      baseProps.class = `${baseProps.class} hidden`;
134
    }
135
  }
136

137
  if (config.type === "sidebarToc") {
138
    return { ...baseProps, headings: Astro.props.headings || [] };
139
  }
140

141
  if (
142
    config.type === "advertisement" &&
143
    "configId" in config &&
144
    config.configId
145
  ) {
146
    return { ...baseProps, configId: config.configId };
147
  }
148

149
  return baseProps;
150
};
151

152
const allComponents = getComponents();
153
const filteredComponents = filterAndSortComponents(allComponents);
154

155
const isMobileBottom = side === SIDEBAR_SIDE.BOTTOM;
156
const { topComponents, stickyComponents } = !isMobileBottom
157
  ? getComponentsByPosition(filteredComponents)
158
  : { topComponents: [], stickyComponents: [] };
159
const bottomComponents = isMobileBottom ? filteredComponents : [];
160
const hasInitiallyVisibleTopComponents = topComponents.some(
161
  isComponentInitiallyVisible,
162
);
163

164
let mobileProfileComp: MobileBottomComponentConfig | undefined;
165
let mobileOtherComponents: MobileBottomComponentConfig[] = [];
166

167
if (isMobileBottom) {
168
  mobileProfileComp = bottomComponents.find((comp) => comp.type === "profile");
169
  mobileOtherComponents = bottomComponents.filter(
170
    (comp) => comp.type !== "profile",
171
  );
172
}
173

174
const hasStickyContent =
175
  stickyComponents.length > 0 || side === SIDEBAR_SIDE.LEFT;
176
---
177

178
{
179
  (topComponents.length > 0 || stickyComponents.length > 0 || bottomComponents.length > 0 || hasStickyContent) && (
180
    <div id={`${side}-sidebar`} class:list={[className, "flex flex-col w-full pt-0"]}>
181
      {isMobileBottom ? (
182
        <div class="flex flex-col w-full gap-4">
183
          {mobileProfileComp && (() => {
184
            const Component = componentMap[mobileProfileComp.type];
185
            if (!Component) return null;
186
            const props = getComponentProps(mobileProfileComp, 0) as any;
187
            return <Component {...props} />;
188
          })()}
189

190
          <UmamiStats class="onload-animation" style="animation-delay: 50ms" />
191

192
          {mobileOtherComponents.map((comp, index) => {
193
            const Component = componentMap[comp.type];
194
            if (!Component) return null;
195
            const props = getComponentProps(comp, index + 2) as any;
196
            return <Component {...props} />;
197
          })}
198
        </div>
199
      ) : (
200
        <>
201
          {topComponents.length > 0 && (
202
            <div
203
              class:list={[
204
                "flex flex-col w-full gap-4",
205
                hasInitiallyVisibleTopComponents && "mb-4",
206
              ]}
207
            >
208
              {topComponents.map((comp, index) => {
209
                const Component = componentMap[comp.type];
210
                if (!Component) return null;
211
                const props = getComponentProps(comp, index) as any;
212
                return <Component {...props} />;
213
              })}
214
            </div>
215
          )}
216

217
          {hasStickyContent && !isMobileBottom && (
218
            <div
219
              id={`${side}-sidebar-sticky`}
220
              class:list={[
221
                "flex flex-col w-full mt-0 gap-4",
222
                "sticky",
223
                hasInitiallyVisibleTopComponents ? "top-4" : "top-0",
224
              ]}
225
            >
226
              {side === SIDEBAR_SIDE.LEFT && (
227
                <UmamiStats class="onload-animation" style="animation-delay: 200ms" />
228
              )}
229

230
              {stickyComponents.map((comp, index) => {
231
                const Component = componentMap[comp.type];
232
                if (!Component) return null;
233
                const props = getComponentProps(
234
                  comp,
235
                  topComponents.length + index
236
                ) as any;
237
                return <Component {...props} />;
238
              })}
239
            </div>
240
          )}
241
        </>
242
      )}
243
    </div>
244
  )
245
}

展开收起

结尾#

搞定了。现在每次打开博客，侧边栏就会自动加载 Umami 的访问数据，还有个数字滚动的动画效果，看着还挺舒服的。如果数据拉不到（比如 API 挂了），会自动显示 fallback 的数字，不至于空空的。

NVIDIA Build：免费 AI API

Fri, 29 May 2026 00:00:00 GMT

免费 API#

NVIDIA Build 的免费额度挺大方的，每分钟 40 次请求，日常开发完全够用。

模型也挺丰富，DeepSeek V4 Pro、DeepSeek V4 Flash 这些都有，还有云端 GPU 实例可以免费试用。

如果你想体验一下最新的 AI 模型又不想花钱，这个平台目前是最值得薅的。

一个非常NB的IP优选

Sun, 24 May 2026 00:00:00 GMT

在 MIFENG の主页上发现了一个 IP 优选项目，用起来挺顺手的。

开源免费，不需要折腾太多配置，直接上手就能用。

网址：NB优选

论二模试卷上的错误

Sat, 23 May 2026 00:00:00 GMT

众所周知我是一名初二学生，在5月21日这么浪漫的一天，我考玩了地理和生物的二模。发现试卷上有些低级错误。

地理#

赤道周长写错了成了赤道昼长。

地理

生物#

肺泡写成了胚泡。

生物

所以，试卷是不需要审核的吗。错别字都能出现。果然世界就是一个巨大的草台班子。

转载止战之殇

Wed, 13 May 2026 00:00:00 GMT

止战之殇#

雷德王还有3个小时降临地球，世界各大媒体平台将这条消息传唤的沸沸扬扬，他的到来，是救赎还是毁灭，我无从得知，众说纷纭，我只想先吃个汉堡吧。

宇宙无穷，人生微渺，我从一无所有中来，自当归于虚无。唯独让我牵挂难以放下执念的，便是学校的汉堡了，汉堡不大，面包很干，初相识于三年前，我年少，它缥纱，浅尝一口：“哇”很好吃。可惜后来吃饭时间越来越晚，与曾经的挚爱想重逢却要隔着人山人海，我等了一次又一次。

可惜不悔梦归处，只恨太匆匆，不知什么时候起，汉堡的肉饼变成了自制小牛肉，陈然多了一份人情味，少了一份预制感，但干燥的触感与同样燥干的面饼相结合，让我失去了对其往日的热爱，或者它也不能称之为那个它了。

学校门口的餐车最近上了汉堡，用的和学校同样的佐料，不过是曾经的面饼一样的干，早上考试我又饿又渴，买了个汉堡，更渴了。

可字宙苍茫，谁又能主宰学校的汉堡呢?其实世间一切自有定数，我不信奉佛陀，自我信仰上帝，也许那全知全能的主会将仁爱的汉堡撒下大地，在我活着，或在我死后。

雷德王降临了，在维多利亚港。

没有谈判，硝烟中，炮火轰鸣中，世界想去了色彩。

我到了，因为我必须来，作为新时代新青年，肩负历史使命与伟大复兴重担，拯救世界，舍我其谁?

可站在雷德王脚下那一刻，我才意识到自己有多弱小，他比自由女神像还要大，尽管我没去过美国，但我刷过视频。

雷德王停下进攻的脚步，低头看我，示意我把手给他，我不敢拒绝却也止不住的颤抖，原来他是要我手中的汉堡啊，看来无论何等高级的生命都无法抵御汉堡的诱惑。

一颗子弹贯穿我的胸膛，临死前耳畔传来的话语，在说我通敌。

哈哈哈，这就是人性吗?雷德王，我开始理解你了，不过，突然……好想吃个汉堡····

原文图,请以倒观方式观看

Linux（Debian 系）上搭建 C++ 开发环境

Sat, 02 May 2026 00:00:00 GMT

介绍#

Linux 做 C++ 开发确实舒服，工具链齐全，编译速度也快。这篇文章手把手教你在 Debian 系的 Linux 上，用 VS Code + Clang + CMake + Ninja + vcpkg 搭一套现代化的开发环境，最后还会用 C++20 模块跑一个示例项目。

需要装的东西#

编译器：Clang
项目构建器：CMake
本地构建器：Ninja
依赖包管理：vcpkg

安装和配置#

1. 安装 Clang 编译器#

Clang 的错误提示比 GCC 友好很多，而且对新标准的支持一直很积极。截至 2026 年 4 月，最新稳定版是 Clang 22.1.3。Clang 23 已经有预发布版了，但建议还是用稳定的。

用 LLVM 官方脚本装最省事：

Terminal window

1
wget https://apt.llvm.org/llvm.sh
2
chmod +x llvm.sh
3
sudo ./llvm.sh 22

脚本跑完会自动添加 LLVM 的 APT 仓库，然后装好 clang-22 和相关工具。

装完之后设一下默认版本，这样终端里直接输 clang 就能用：

Terminal window

1
sudo update-alternatives --install /usr/bin/clang clang /usr/bin/clang-22 100
2
sudo update-alternatives --install /usr/bin/clang++ clang++ /usr/bin/clang++-22 100
3
sudo update-alternatives --install /usr/bin/clangd clangd /usr/bin/clangd-22 100
4
sudo update-alternatives --install /usr/bin/lldb lldb /usr/bin/lldb-22 100
5
sudo update-alternatives --install /usr/bin/lld lld /usr/bin/lld-22 100
6
sudo update-alternatives --install /usr/bin/clang-tidy clang-tidy /usr/bin/clang-tidy-22 100
7
sudo update-alternatives --install /usr/bin/clang-format clang-format /usr/bin/clang-format-22 100

跑完 clang --version 看一下，输出里有 “clang version 22.1.3” 就说明装好了。

2. 安装 CMake 构建系统#

CMake 是 C++ 项目构建的标配，能生成各种构建系统需要的文件。当前最新稳定版是 CMake 4.3.1。

从官方下载安装脚本：

Terminal window

1
wget https://github.com/Kitware/CMake/releases/download/v4.3.1/cmake-4.3.1-linux-x86_64.sh

Terminal window

1
chmod +x cmake-4.3.1-linux-x86_64.sh
2
sudo ./cmake-4.3.1-linux-x86_64.sh --prefix=/opt/cmake-4.3.1 --skip-license

然后配一下默认版本：

Terminal window

1
sudo update-alternatives --install /usr/bin/cmake cmake /opt/cmake-4.3.1/bin/cmake 100
2
sudo update-alternatives --install /usr/bin/ctest ctest /opt/cmake-4.3.1/bin/ctest 100
3
sudo update-alternatives --install /usr/bin/cpack cpack /opt/cmake-4.3.1/bin/cpack 100

cmake --version 能看到 4.3.1 就 OK 了。

3. 安装 Ninja 构建工具#

Ninja 专注速度，配合 CMake 用编译特别快。目前最新稳定版是 1.13.2。

从 GitHub 下载预编译的二进制文件，解压放到系统路径里就行：

Terminal window

1
wget https://github.com/ninja-build/ninja/releases/download/v1.13.2/ninja-linux.zip
2
unzip ninja-linux.zip
3
sudo mv ninja /usr/bin/ninja
4
sudo chmod +x /usr/bin/ninja
5
ninja --version

4. 安装 vcpkg 包管理器#

vcpkg 是微软出的 C++ 库管理器，装第三方库特别方便，不用手动折腾依赖。最新稳定版是 2026.04.08。

Terminal window

1
cd ~
2
git clone https://github.com/microsoft/vcpkg.git
3
cd vcpkg
4
# Linux 下用 .sh 结尾的引导脚本
5
./bootstrap-vcpkg.sh

装好后把路径加到环境变量里，编辑 ~/.bashrc 或 ~/.zshrc：

Terminal window

1
export PATH=/opt/cmake-4.3.1/bin:$PATH
2
export VCPKG_ROOT=~/vcpkg
3
export PATH=$VCPKG_ROOT:$PATH

改完重启终端或者 source ~/.bashrc，然后 vcpkg --version 看看版本就对了。

5. Visual Studio Code#

VS Code 做 C++ 开发挺好用的（当然你也可以用 CLion 之类的）。装好之后去扩展市场搜这几个插件：

Clangd（作者: LLVM）：代码补全、跳转、实时诊断，比微软的 C/C++ 插件好用。
CodeLLDB（作者: Vadim Chugunov）：本地调试器，跟 VS Code 集成得很好。
CMake Tools（作者: Microsoft）：直接在 VS Code 里配置、构建、运行 CMake 项目。
CMake（作者: Microsoft）：给 CMakeLists.txt 提供语法高亮。

构建和运行你的第一个程序#

用 C++20 的模块特性来写第一个项目。

项目结构#

建一个项目文件夹，结构长这样：

1
CppProject/
2
├── .vscode/
3
│   └── launch.json      # 调试配置（后面会创建）
4
├── CMakeLists.txt       # CMake 项目配置
5
├── CMakePresets.json    # CMake 预设
6
├── main.cpp             # 主程序
7
├── utilities.ixx        # 一个简单的 C++20 模块
8
└── vcpkg.json           # vcpkg 依赖描述

不知道这些文件里写什么的话，把这篇文章丢给 AI 让它帮你生成。

配置代码和调试器#

utilities.ixx 模块文件：

1
module;
2
#include <string>
3
export module utilities;
4
export auto get_greeting() {
5
    return "Hello from a C++20 Module!";
6
}

主程序 main.cpp：

1
import utilities;
2
#include <fmt/core.h>
3
int main() {
4
    fmt::print("{}\n", get_greeting());
5
    return 0;
6
}

调试配置文件 .vscode/launch.json，注意 program 的路径要跟你的构建输出目录对上：

1
{
2
    "version": "0.2.0",
3
    "configurations": [
4
        {
5
            "type": "lldb",
6
            "request": "launch",
7
            "name": "Debug (LLDB)",
8
            "program": "${workspaceFolder}/build/linux_clang/Debug/Rocket",
9
            "args": [],
10
            "cwd": "${workspaceFolder}"
11
        }
12
    ]
13
}

配置、构建与运行#

1. 选择预设#

在 VS Code 里打开项目文件夹，Ctrl+Shift+P 打开命令面板，输入 CMake: Select Configure Preset，根据你的系统和编译器选一个合适的预设。

2. 开始构建#

再打开命令面板，输入 CMake: Build，或者直接按 F7。CMake 会调用 Clang 和 Ninja 来编译和链接。

3. 运行与调试#

构建成功后，点 VS Code 底部的 ▶️ 按钮就能运行。设好断点按 F5 启动调试，F10 单步执行，变量值也能实时看到。

总结#

搞定了，你现在有了一套完整的现代化 C++ 开发环境。不管是自己学习还是团队协作都能用。

有两个要注意的地方：

装完所有工具后，记得用 --version 一个个验证版本，确保环境变量没配错。
launch.json 是项目的调试启动配置，新建项目的时候记得把这个文件复制过去，然后把 program 字段改成新项目的可执行文件路径。
CMakeLists.txt 和 CMakePresets.json 不知道怎么写的话，直接问 AI 就行。

Linux 上安装和使用 AstrBot

Sat, 25 Apr 2026 00:00:00 GMT

AstrBot 是什么#

AstrBot 是一个开源的聊天机器人框架，轻量好用，能对接 QQ、微信、飞书这些平台。自带插件系统和可视化面板，社区里已经有上千款插件了，做自动回复、群管理、定时任务什么的都挺方便的。

安装#

在 Linux 终端里跑这个脚本就行：

Terminal window

1
bash <(curl -sSL https://raw.githubusercontent.com/zhende1113/Antlia/refs/heads/main/Script/AstrBot/Antlia.sh)

如果你的系统没装 curl，用 wget 也行：

Terminal window

1
wget -qO- https://raw.githubusercontent.com/zhende1113/Antlia/refs/heads/main/Script/AstrBot/Antlia.sh | bash

Tip

如果 uv sync 报错，可以试试设置环境变量：

Terminal window

1
echo 'export UV_LINK_MODE=copy' >> ~/.bashrc
2
source ~/.bashrc

然后正常启动：

Terminal window

1
cd AstrBot
2
uv run main.py

如果下载依赖时遇到网络问题，可以换成国内镜像源：

Terminal window

1
echo 'export UV_DEFAULT_INDEX="https://pypi.tuna.tsinghua.edu.cn/simple"' >> ~/.bashrc
2
source ~/.bashrc

AstrBot 仓库

AstrBot 官方文档

脚本仓库

Cloudflare Worker 优选

Sat, 25 Apr 2026 00:00:00 GMT

什么是优选#

说白了就是挑一个国内访问更快的 Cloudflare 节点。

Cloudflare 默认分配给你的 IP，国内访问延迟可能很高，甚至直接打不开。通过优选，我们可以手动把域名解析到那些国内访问快的 Cloudflare IP 上，速度会明显提升。

要实现优选，核心就两件事：自己控制路由规则 + 自己控制 DNS 解析。

寻找优选域名#

可以用社区大佬做的这个网站来获取优选域名。

Worker 优选方法#

打开你的 Worker 项目，添加一条路由，路由格式填 你的域名/*：

路由示例

然后去域名 DNS 设置里加一条记录，类型选 CNAME。名称根据你路由里填的内容来定：比如你路由填的是 blog.example.com，这里名称就填 blog（前提是域名 example.com 托管在 Cloudflare 上）。如果路由填的域名跟你托管的域名一样，直接填 @。最后目标填从社区网站复制下来的优选域名就行。

DNS记录示例

Tip

优选的前提是你有一个域名托管在 Cloudflare 上。路由里记得在域名后面加 /*，不然优选只对根域名生效。

年华

Vercel 部署后全站 404 排查记

引言#

观察现象#

排查过程#

第一步：确认是部署产物问题而非缓存#

第二步：对比「部署文件列表」与「本地产物」#

第三步：找到 cleanUrls 冲突#

第四步：定位真正的元凶 —— l2s 上传 bug#

为什么新版本 CLI 有问题，旧版本没问题#

为什么 Cloudflare / EdgeOne 不受影响#

根因总结#

解决方案#

直接修复#

经验总结#

怎么用Netlify反代

怎么反代#

留言页的群聊风格改造

整体思路#

API 通信#

聊天气泡#

区分自己与他人#

自动刷新#

个人资料弹窗#

回复功能#

一些样式细节#

最后#

这个博客的朋友圈是怎么做的

什么是朋友圈#

核心思路#

数据源：friendsConfig#

数据抓取：rss-utils#

API 端点#

前端展示：CircleFeed.svelte#

一些细节#

今天是伟大的0721日

Cloudflare VS Vercel？！

引言#

Cloudflare#

Workers#

D1#

KV#

R2#

Vercel#

Node.js 运行时#

数据库（PostgreSQL）#

构建系统#

D1（SQLite）与 PG 的差异#

给博客写了个后台管理

待办

功能#

想法#

GitHub Actions 自动构建并部署 Cloudflare Workers 实现思路

为什么要搞这个#

整体流程#

实现思路#

1. 触发条件#

2. 环境准备#

3. 构建项目#

4. 推送到 build 分支#

5. 部署到 Cloudflare Workers#

完整源码#

需要配置的 Secrets#

注意事项#

Firefly 主题 添加WelcomeToast 组件

Firefly 主题 WelcomeToast 组件分析#

涉及的文件#

组件是怎么实现的#

页面上长什么样#

几个关键函数#

执行顺序#

怎么适配 SPA 导航的#

样式部分#

在 MainGridLayout 里怎么放的#

几个值得注意的点#

总结#

为 Firefly 添加 Umami 访问统计卡片

为什么要加统计#

准备工作#

添加组件#

Firefly 主题添加WelcomeToast 组件