暖阳的个人博客

NodeWarden 走了第三条路——把整个 Bitwarden 兼容服务端直接跑在 Cloudflare Workers 上。不用买服务器，不用管 SSL，不用做进程守护，Cloudflare 免费额度就够用。项目 2026 年 2 月开源，使用 LGPL-3.0 协议，技术栈为 TypeScript + Preact。

1.2 技术架构#

NodeWarden 完全构建在 Cloudflare 的免费基础设施之上：

组成	使用的 Cloudflare 服务	作用
计算	Cloudflare Workers	无服务器函数，承载全部 API
数据库	Cloudflare D1	Cloudflare 版 SQLite，存放账号、密码库元数据等
附件存储	R2 或 KV（二选一）	存放附件、Send 文件
前端	Preact 构建的原版 Web Vault	与官方一致的网页密码库界面，支持 PWA 离线安装

最重要的一点：它延续了 Bitwarden 的零知识（Zero-Knowledge）架构，加解密全部在你的客户端本地完成，服务端（以及 Cloudflare）拿到的只是密文。即使服务端数据泄露，攻击者没有你的主密码也无法解密。

1.3 核心功能#

根据官方 README，目前支持的能力包括：

✅ 原版 Web Vault 界面，并支持 PWA 安装、离线使用
✅ 官方 Bitwarden 客户端全兼容：Windows / Linux 桌面端、手机 App、浏览器扩展（macOS 桌面端尚未完全验证）
✅ 密码同步、自动填充、实时推送同步（多设备）
✅ TOTP 两步验证，甚至支持 steam:// 格式的 Steam 令牌
✅ Passkey 无密码登录、YubiKey、2FA 恢复码
✅ 附件与 Bitwarden Send（R2 模式单文件最大 100 MB，KV 模式 25 MiB）
✅ 导入 / 导出（Bitwarden JSON、CSV、ZIP）
✅ 云端备份中心：定时 WebDAV / S3 增量备份（官方免费版都没有的功能）
✅ 设备管理、跨设备登录请求审批
✅ API Key、域名规则（等效域名、全局排除）、fill-assist
✅ 多用户：通过邀请码注册
❌ 不支持组织 / 集合 / 成员角色、SSO / SCIM / 企业目录

1.4 主要特点#

真正零成本：Workers、D1、KV/R2 都在 Cloudflare 免费额度内，个人使用完全够。
免运维：没有服务器要维护，HTTPS 证书由 Cloudflare 自动处理，全球边缘节点加速。
部署门槛低：点点鼠标（Workers Builds）或一行 npm run deploy 都能完成，D1 数据表在首次访问时自动初始化，不需要手动导入 SQL。
升级省心：Fork 仓库后在 GitHub 点一下 Sync fork 即可；也可以开启仓库自带的 Actions，每天自动同步上游。
数据自持：所有数据都在你自己的 Cloudflare 账号里。

1.5 适用 / 不适用场景#

适合：

想自托管密码库、但不想买 VPS / 折腾 Docker 的个人用户
已经在用 Cloudflare、希望一切服务都收敛到一个面板里的人
需要手机、电脑、浏览器扩展多端同步，并且看重 TOTP、附件、Send 的用户
预算为零的学生党、白嫖党

不适合：

团队共享密码库（需要组织 / 集合 / 权限角色）——这类需求请用官方 Bitwarden 组织版或 Vaultwarden
网络环境无法稳定访问 Cloudflare / workers.dev 域名，且没有可接入 Cloudflare 的自定义域名的用户
对 macOS 桌面端有强依赖的用户（目前尚未完全验证，可用浏览器扩展替代）

1.6 与同类方案对比#

对比项	Bitwarden 官方服务端	Vaultwarden	NodeWarden
语言	C#	Rust	TypeScript
运行方式	Docker / VPS	Docker / VPS	Cloudflare Workers（无服务器）
数据库	SQL Server	SQLite / MySQL / PostgreSQL	Cloudflare D1
附件	本地/对象存储	本地文件系统	R2 或 KV
HTTPS	自行配置	自行配置	Cloudflare 自动签发
日常维护	更新、备份、监控	更新、备份、监控	Fork 同步，全自动
成本	服务器费用	服务器费用	免费额度内 ¥0
TOTP	免费版受限	支持	支持（含 steam://）
组织 / 集合	✅	✅	❌

一句话总结：个人用选 NodeWarden，团队用选 Vaultwarden / 官方版。

二、部署前的准备#

NodeWarden 提供两种部署方式，二选一即可：

方式一：Cloudflare 面板可视化部署（推荐新手）——全程网页点选，电脑上不用装任何东西；
方式二：本地 CLI 部署——适合熟悉命令行、想本地调试或自定义配置的玩家。

2.1 必备账号#

账号	注册地址	用途	是否需要信用卡
GitHub 账号	github.com	Fork 源码、后续一键更新	否
Cloudflare 账号	dash.cloudflare.com	运行 Worker、D1、KV/R2	看存储模式（见下表）

2.2 先选好存储模式：R2 还是 KV？#

部署前唯一需要做的决策，是附件存储用 R2 还是 KV：

存储模式	是否需要绑信用卡	单个附件 / Send 文件上限	免费额度	部署命令
R2（默认，推荐）	需要（只是验证，免费额度内不扣款）	100 MB（软限制，可调）	10 GB	`npm run deploy`
KV（免信用卡）	不需要	25 MiB（Cloudflare 硬限制）	1 GB	`npm run deploy:kv`

选择建议：

只是存密码、偶尔传小附件 → KV 模式足矣，免去绑卡；
需要传大附件、截图、证件扫描件 → 选 R2 模式。

💡 密码库本身的文本数据存在 D1，与附件存储互不影响，以后想换模式重新部署即可。

2.3 本地 CLI 部署才需要的环境（方式一可跳过本节）#

如果你选择面板部署，可以直接跳到第三章。CLI 部署需要本机准备：

软件	版本要求	说明
Node.js	18.12+，推荐 20 LTS 或更新	带 npm；可在 nodejs.org 下载安装包
Git	任意较新版本	用于拉取源码
Cloudflare 账号	——	`wrangler login` 走浏览器授权
代码编辑器（可选）	VS Code 等	想改配置时用

验证安装：

Terminal window

1
node -v
2
# 期望输出 v20.x.x（或 >= v18.12）
3

4
npm -v
5
git --version

Windows 用户推荐用 PowerShell 或 Windows Terminal；macOS / Linux 直接用终端即可。

三、方式一：面板可视化部署（新手推荐）#

整个流程不需要在本地敲一行命令，只需在两个网页之间操作。

第 1 步：Fork 仓库#

浏览器打开项目主页：https://github.com/shuaiplus/NodeWarden
点击页面右上角的 Fork 按钮；
跳转到创建页面后，仓库名保持默认 NodeWarden 即可，Copy the main branch only 保持默认勾选，直接点击 Create fork；
稍等几秒，你会得到一个属于自己的仓库，地址形如 https://github.com/你的用户名/NodeWarden。

🔑 为什么必须先 Fork？因为 Cloudflare 要连接你自己的仓库来构建；以后更新也全靠这个 Fork（见第七章）。

第 2 步：在 Cloudflare 创建 Worker 并连接 GitHub#

打开 Cloudflare 创建入口：Workers & Pages → Create
在创建页面找到 Import a repository（导入仓库）/ Connect to Git 一类入口，点击 Continue with GitHub；
第一次连接时按提示授权 Cloudflare 访问你的 GitHub，可以只勾选 NodeWarden 这一个仓库；
回到选择列表，选中你刚刚 Fork 的 NodeWarden 仓库，点击 Begin setup / 开始设置。

第 3 步：填写构建配置#

在构建配置页面，按下表填写：

配置项	R2 模式（默认）	KV 模式（免信用卡）
Project name（项目名）	`nodewarden`（随意，会成为三级域名的一部分）	同左
Branch（分支）	`main`	`main`
Build command（构建命令）	`npm run build`	`npm run build`
Deploy command（部署命令）	`npm run deploy`	`npm run deploy:kv`

填好后点击 Deploy（部署）。

第 4 步：等待首次构建完成#

保存后会自动跳转到部署日志页，滚动能看到 npm install → build → deploy 的过程；
第一次大约需要 1～3 分钟，看到 Deployment complete / 绿色对勾即为成功；
部署过程中会自动创建所需的资源绑定（D1 数据库、R2 存储桶或 KV 命名空间），名字由仓库根目录的 wrangler.toml（R2 模式）或 wrangler.kv.toml（KV 模式）定义，无需手动新建。

⚠️ R2 模式下，如果账号从未开通 R2，日志可能提示你先启用 R2（需要绑定信用卡验证）。按日志里的链接到面板开通后，重新部署一次即可。完全不想绑卡就改用 KV 模式：把部署命令换成 npm run deploy:kv 后重新触发部署。

第 5 步：设置 JWT_SECRET（必做，最重要的一步）#

部署完成后，打开 Worker 的访问地址（如 https://dash.cloudflare.com/a9d21f407514e204238da710be47c992/workers/services/view/nodewarden/production/settings）；
页面会提示 缺少 JWT_SECRET——这是服务端签发登录令牌用的密钥，必须配置一个强随机值，且不要使用任何示例值；
生成一个至少 32 位的随机字符串，任选一种方式或者使用NodeWarden页面生成的随机串：

macOS / Linux 终端：

Terminal window

1
openssl rand -base64 24

Windows PowerShell（本机装了 Node.js 时最省事，跨平台通用）：

Terminal window

1
node -e "console.log(require('crypto').randomBytes(24).toString('base64url'))"

回到 Cloudflare 面板：进入 Workers & Pages → 你的 nodewarden 服务 → Settings（设置）→ Variables and Secrets（变量和机密）；
点击 添加变量，密钥：JWT_SECRET，值值粘贴刚才生成的随机串，然后点击小三角保存，而不是部署，接着点击编辑类型选择 Secret（密钥），部署即可；
保存后 Worker 会自动重新部署，等待几十秒后刷新你的站点页面。

🔒 JWT_SECRET 一定要用 Secret 类型而不是普通文本变量；一旦设置不要随意更换，否则所有已登录设备需要重新登录。请把它和主密码一样妥善保管。

第 6 步：按需添加可选变量#

同在 Variables and Secrets 页面，还可以配置：

变量名	类型	值	作用
`HIDE_WEB_VAULT`	Text（文本）	`1`	隐藏服务器上的网页版密码库（前端页面与静态资源返回 404），客户端 API 照常可用；适合只用桌面/手机 App 的人
`TOTP_SECRET`	Secret	Base32 种子	给登录本身开启 TOTP 二次验证（见 5.4 节，向导也会给出生成器）

不需要就全部留空。删除变量或把 HIDE_WEB_VAULT 改成非 1 的值即可恢复网页版。

第 7 步：跟随初始化向导创建账号#

再次打开站点，NodeWarden 自带一个初始化向导（Setup），按提示一路 Next：

JWT_SECRET 检查：通过则继续；
同步策略（可选）：讲解如何 Fork 同步更新，可先跳过；
创建账号：填写邮箱、主密码、姓名，注册你的第一个（也是管理员）账号；
登录 TOTP（可选）：向导会生成一个 Base32 种子和二维码，需要的话先去设置 TOTP_SECRET，再用验证器扫码；
完成：页面显示你的服务器 URL，后续所有 Bitwarden 客户端都填这个地址。

👤 主密码是整个密码库的唯一加密密钥，零知识架构下遗忘无法找回。建议同时把主密码离线记录在安全的地方。

四、方式二：本地 CLI 部署#

喜欢命令行，或者想在本地先跑起来看看，可以用这种方式。

第 1 步：拉取源码并安装依赖#

Terminal window

1
git clone https://github.com/shuaiplus/NodeWarden.git
2
cd NodeWarden
3
npm install

第 2 步：登录 Cloudflare#

Terminal window

1
npx wrangler login

执行后会自动打开浏览器，登录你的 Cloudflare 账号并点击 Allow 授权。回到终端看到 Successfully logged in 即成功。

第 3 步：部署#

Terminal window

1
# 默认：R2 模式（单附件最大 100 MB，免费 10 GB，账号需绑卡验证 R2）
2
npm run deploy
3

4
# 或者：KV 模式（免信用卡，单文件 25 MiB，免费 1 GB）
5
npm run deploy:kv

部署脚本会自动完成 Worker 发布以及 D1、R2/KV 绑定的创建，日志末尾会输出 Worker 的访问 URL。

第 4 步：设置 JWT_SECRET#

Terminal window

1
# 生成随机密钥
2
node -e "console.log(require('crypto').randomBytes(48).toString('base64url'))"
3

4
# 写入 Secret（执行后粘贴上一步生成的值，回车确认）
5
npx wrangler secret put JWT_SECRET

可选的登录 TOTP 种子同理：

Terminal window

1
npx wrangler secret put TOTP_SECRET

第 5 步：本地开发调试（可选）#

Terminal window

1
npm run dev       # R2 模式本地开发
2
npm run dev:kv    # KV 模式本地开发

本地调试完成后，再执行 npm run deploy 发布即可。

4.1 关于权限与配置文件#

绑定名称统一写在仓库根目录的 wrangler.toml（R2）/ wrangler.kv.toml（KV）中，不要随意改动资源名，否则代码里的绑定会找不到；
D1 数据表在第一次请求站点时自动迁移创建，无需手动上传 SQL；
CLI 部署默认使用你 wrangler 当前登录的账号（npx wrangler whoami 可查看），注意别部署错账号。

五、客户端接入（部署后必做）#

服务跑起来之后，真正日常使用的是 Bitwarden 官方客户端。NodeWarden 兼容官方客户端，去 bitwarden.com/download 下载你需要的平台即可，已测试通过：Windows 桌面端、Linux 桌面端、手机 App、浏览器扩展。

5.1 通用原则：把服务器地址改成你自己的#

所有客户端的登录/注册页，都要找到自托管（Self-hosted）服务器设置入口，填入：

1
https://nodewarden.你的子域.workers.dev

注意：

必须带 https://，结尾不要加斜杠；
填的是你自己的 Worker 域名，不是 nodewarden.app，也不是官方地址。

5.2 浏览器扩展#

打开 Bitwarden 扩展，点击登录页左下角的 齿轮图标（Settings）；
在 Self-hosted environment / 自托管环境 区域，勾选自定义服务器；
Server URL 填入你的 Worker 地址，保存；
回到登录页，点击 Create account（注册账号）——如果你还没在网页向导注册，也可以直接在这里注册；
用主密码登录，先手动点一次同步，看到密码库出现即为成功。

5.3 桌面端 / 手机 App#

桌面端（Windows / Linux）：登录窗口左下角同样有齿轮图标，入口与扩展一致；
手机 App：登录页点击右上角/左下角的 设置（齿轮），找到「自托管服务器」，填入地址后保存，再登录。

5.4（可选）给登录开启 TOTP 两步验证#

先在 Worker 的 Variables and Secrets 中添加 TOTP_SECRET（初始化向导会提供一个 Base32 种子与二维码）；
用 Google Authenticator、Authy、2FAS 等验证器扫描二维码；
以后在新设备登录时，除主密码外还需输入 6 位动态码。

这与密码库条目的 TOTP 是两回事：前者保护账号登录，后者用来自动填充其他网站的验证码。

5.5 绑定自定义域名（可选，但国内网络建议配置）#

workers.dev 默认域名在部分网络环境下可能无法直连。如果你的域名已接入 Cloudflare：

进入 Workers & Pages → nodewarden → Settings → Domains & Routes；
添加一个你自己的子域名，例如 vault.example.com；
证书自动签发，等一两分钟生效；
把客户端里的服务器地址换成新域名。

六、部署后的验证清单#

按下面清单逐项确认，全部通过说明部署完整可用：

浏览器打开 Worker 域名，能正常显示 Web Vault 登录页，而不是 缺少 JWT_SECRET 报错；
初始化向导中 JWT_SECRET check passed；
成功注册账号并登录网页版，能新建一条密码条目；
Cloudflare 面板中确认 D1 数据库已自动建好表（D1 → 选择数据库 → Console，可见若干数据表）；
至少一个官方客户端（扩展或手机 App）配置自托管地址后登录成功；
在一端新增/修改一条密码，另一端点「同步」后能实时看到变更；
上传一个附件（R2 模式可传较大文件，KV 模式控制在 25 MiB 内）并能下载；
（可选）开启 TOTP 的账号重新登录一次，验证动态码流程；
退出登录后，确认未登录状态无法查看任何密码库数据。

也可以用「导出加密备份 → 新建测试条目 → 删除 → 重新导入」的方式，熟悉一遍导入导出流程，确保以后迁移心里有底。

七、如何升级到新版本#

NodeWarden 更新很活跃，升级有两种方式。

7.1 手动更新（推荐先看 changelog）#

打开你 Fork 的 GitHub 仓库主页；
文件列表上方若出现 This branch is behind ... 提示条，点击 Sync fork；
点击 Update branch，等待几秒；
因为你的 Worker 连接了这个 Fork，同步提交会自动触发 Cloudflare 重新构建部署，去 Cloudflare 部署日志页确认成功即可。

7.2 自动更新#

仓库自带了每日同步上游的 GitHub Actions 工作流：

进入你的 Fork → Actions 标签页；
点击绿色按钮 I understand my workflows, go ahead and enable them；
默认每天 03<00> 自动检查并同步；也可以随时点击对应工作流 → Run workflow 立即执行。

建议大版本更新前先去 Releases 页面看一眼 changelog，确认是否有需要手动处理的变更。

7.3 从一键部署示例仓库换成自己的 Fork#

如果你最初是通过别人给的一键部署按钮创建的服务，需要先解绑示例仓库：Cloudflare 面板 → 你的服务 → Settings → Builds and deployments → Source code，解除当前绑定后，重新绑定你自己的 Fork，之后才能正常收到更新。

八、常见问题（FAQ）#

Q1：打开站点一直提示缺少 JWT_SECRET？ 确认变量名拼写完全一致（全大写、下划线），类型是 Secret；保存后等 Worker 自动重新部署完成（约几十秒），再强制刷新页面（Ctrl/Cmd + Shift + R）。

Q2：客户端无法登录 / 一直转圈 / 同步失败？ 依次排查：① 服务器地址是否带 https:// 且结尾无多余斜杠；② 浏览器能否正常打开该地址；③ 当前网络能否访问 workers.dev，不行就绑自定义域名；④ 客户端是否为官方 Bitwarden 客户端（第三方兼容客户端未测试）。

Q3：KV 模式下附件上传失败？ KV 单值有 25 MiB 硬限制，超过必然失败。请改传小文件，或重新部署为 R2 模式（附件上限 100 MB）。

Q4：需要手动建数据库表吗？ 不需要。D1 的表结构在首次访问站点时自动迁移创建。只要 D1 绑定正确即可，不要手动执行来历不明的 SQL。

Q5：主密码忘了怎么办？ 没有办法。零知识加密意味着服务端不保存、也无法验证你的主密码内容，官方与作者都无法帮你找回。只能凭记忆恢复，或清空数据重新开始（所以从其他密码管理器迁移前，务必保留旧库一段时间）。

Q6：可以多人一起用吗？ 支持通过邀请码注册多个普通用户，但没有组织、集合、角色权限体系，适合家人各自独立使用，不适合团队共享密码库。

Q7：部署时 R2 开通失败 / 不想绑信用卡？ 直接改用 KV 模式：面板部署把部署命令改成 npm run deploy:kv；CLI 则执行 npm run deploy:kv。

Q8：隐藏 Web Vault 后客户端还能用吗？ 可以。设置 HIDE_WEB_VAULT=1 后，服务器上的前端页面和静态资源返回 404，但登录、同步、附件、图标、通知等客户端 API 全部正常；已安装的 PWA 也能继续使用本地缓存的前端。

Q9：数据怎么做备份？ NodeWarden 内置「云端备份中心」，支持定时向 WebDAV / S3 目标做增量备份，在 Web Vault 设置中配置即可。此外也建议定期用官方客户端导出一份加密 JSON/ZIP 存档，异地保存。

Q10：日志里出现语言高亮、构建警告怎么办？ 构建日志中的 npm warning、代码块语言 fallback 提示一般不影响运行；只有出现红色 Error 且部署状态为 Failed 时才需要处理，重点检查构建/部署命令是否按第三章的表格填写。

九、小结#

NodeWarden 把「自托管 Bitwarden」的最后一点门槛也抹掉了：一台服务器都不用买，免费额度就能拥有完整的多端密码同步体验。整个部署过程可以概括为：

1
Fork 仓库 → Cloudflare 连接 GitHub → 填 build/deploy 命令
2
→ 设置 JWT_SECRET → 打开域名注册账号 → 官方客户端填入地址

数据在自己的 Cloudflare 账号里、加解密在自己的设备上完成，再加上 WebDAV/S3 增量备份，个人密码资产的自主性和安全性都拉满了。唯一需要你牢记的，就是那个无法找回的主密码——设好之后，先备份，再使用。

祝大家用得安心，永不脱库 🔐

参考资料：NodeWarden GitHub 仓库 · 官方 Wiki · Cloudflare Workers 文档 · Bitwarden 客户端下载

PNPM 11 适配 CNB 构建安全兼容方案

Sun, 02 Aug 2026 00:00:00 GMT

问题根因#

PNPM 11 进行了重大安全策略升级，默认开启两大防护机制，与无交互的 CNB 构建环境冲突，导致安装依赖失败

构建脚本严格校验（核心报错）#

PNPM 11 默认开启 strictDepBuilds: true，禁止所有第三方依赖自动执行 postinstall/preinstall 构建脚本。本地开发可通过交互式命令 pnpm approve-builds 手动授权白名单，但 CNB 构建环境无 TTY 交互终端，无法手动确认，直接抛出错误：ERR_PNPM_IGNORED_BUILDS，构建中断

冷却机制校验#

PNPM 11 默认开启 minimumReleaseAge: 1440（24小时发布冷却），禁止安装发布时间不足24小时的新版本包。项目迭代中经常会更新内部私有包、最新开源依赖，这类包发布时间短，会触发冷却校验报错：ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION，导致 CNB 构建失败。

兼容方案#

在项目根目录 pnpm-workspace.yaml 中添加以下配置：

1
# 临时兼容CNB无交互构建：放开所有依赖构建脚本
2
dangerouslyAllowAllBuilds: true
3
# 临时关闭新版本包24小时冷却校验，适配私有包高频迭代
4
minimumReleaseAge: 0

dangerouslyAllowAllBuilds: true：绕过脚本白名单机制，允许所有第三方依赖自动执行构建脚本，解决 CNB 交互阻塞报错
minimumReleaseAge: 0：关闭包发布冷却安全策略，允许安装刚发布的新版私有包、开源依赖

明确风险#

该配置会临时关闭 PNPM11 两大核心供应链安全防护：

放开所有依赖 postinstall 恶意脚本执行风险
无法拦截账号劫持后新发的恶意版本包，无24小时安全缓冲窗口期使用边界：仅用于内部业务项目临时过渡，禁止长期永久使用，需尽快迁移至安全方案。

长期安全方案#

摒弃高危全局降级配置，采用精准白名单+局部豁免机制，保留 PNPM 核心安全能力，同时适配 CNB 构建

操作步骤:

本地有交互终端执行，自动生成可信脚本白名单 pnpm approve-builds 按需授权项目所需的构建依赖（如 esbuild、sharp、@parcel/watcher 等），自动写入配置文件
私有包豁免冷却校验：不全局关闭冷却，仅放行内部可信包
提交更新后的 pnpm-workspace.yaml 到代码仓库，CNB 直接无感知构建

最终安全配置模板

1
# 开启严格脚本校验（保留安全能力）
2
strictDepBuilds: true
3
# 仅放行项目可信的带构建脚本依赖（精准白名单）
4
allowBuilds:
5
  esbuild: true
6
  sharp: true
7
  @parcel/watcher: true
8

9
# 保留公共包24小时冷却防护
10
minimumReleaseAge: 1440
11
# 仅内部私有包豁免冷却，适配高频迭代
12
minimumReleaseAgeExclude:
13
  - "@你的组织/*"

CNB 构建命令规范#

无论临时方案还是安全方案，CNB 流水线统一使用安全构建命令，杜绝版本浮动风险：

Terminal window

1
# 锁定锁文件，禁止自动更新依赖版本
2
pnpm install --frozen-lockfile

同时在项目 package.json 锁定 PNPM 版本，避免环境策略不一致：

1
{
2
  "packageManager": "pnpm@11.4.0"
3
}

AI 摘要实现

Mon, 27 Jul 2026 00:00:00 GMT

AI 摘要提前在构建阶段生成并存入文章元数据，前端页面读取后带动画展示，页面访问无需实时调用 AI，无额外接口开销。

架构概览#

Firefly 博客的 AI 摘要功能分为两部分：

1
┌─────────────────────────────────────────────────────┐
2
│                   构建时 (Build Time)                │
3
│                                                     │
4
│  scripts/fill-descriptions/index.ts                 │
5
│  ├── 扫描 src/content/posts/ 下所有 .md/.mdx         │
6
│  ├── 跳过已有 description 的文章                      │
7
│  ├── 调用千问 API 生成摘要                            │
8
│  └── 写回 frontmatter (description + descriptionSource) │
9
└─────────────────────────────────────────────────────┘
10
                          ↓
11
┌─────────────────────────────────────────────────────┐
12
│                   运行时 (Runtime)                   │
13
│                                                     │
14
│  src/components/widget/AiSummary.astro              │
15
│  ├── 读取 description 和 descriptionSource           │
16
│  ├── IntersectionObserver 监听滚动进入视口            │
17
│  ├── 逐字打字机动画，标点处自动停顿                    │
18
│  └── astro:page-load 支持 Swup 站内导航              │
19
└─────────────────────────────────────────────────────┘

展开收起

文件目录#

文件路径	作用
`src/components/widget/AiSummary.astro`	摘要卡片 + 打字机动画
`src/pages/posts/[...slug].astro`	文章页条件渲染摘要组件
`src/content.config.ts`	`description` / `descriptionSource` 字段校验
`scripts/fill-descriptions/index.ts`	千问 API 批量补全缺失摘要
`.env`	存放 `QWEN_API_KEY`（`勿提交 Git`）

配置 API 密钥#

在项目根目录创建 .env 文件：

1
# 千问 API 配置
2
QWEN_API_KEY=你的API密钥
3
QWEN_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
4
QWEN_MODEL=qwen-plus

注意

📌 将 .env 添加到 .gitignore，避免泄露密钥！

密钥在阿里云 DashScope 控制台申请。脚本通过 import.meta.url 定位项目根目录并读取 .env 文件（兼容 Windows \r\n 换行），也可临时用环境变量：

Terminal window

1
QWEN_API_KEY=sk-xxx pnpm fill-descriptions

可选环境变量：

变量	默认值	说明
`QWEN_API_KEY`	（必填）	千问 API 密钥
`QWEN_MODEL`	`qwen-plus`	文本模型；不要用 `qwen-math-turbo` 等数学/代码模型
`QWEN_BASE_URL`	DashScope 兼容端点	使用自定义 MaaS 端点时再改

构建时脚本详解#

脚本路径：scripts/fill-descriptions/index.ts

核心配置#

1
const QWEN_BASE_URL = process.env.QWEN_BASE_URL || "https://dashscope.aliyuncs.com/compatible-mode/v1";
2
const QWEN_MODEL = process.env.QWEN_MODEL || "qwen-plus";
3
const QWEN_API_KEY = process.env.QWEN_API_KEY || "";
4
const POSTS_DIR = path.join(PROJECT_ROOT, "src/content/posts");

脚本做了什么#

递归扫描 src/content/posts/ 下所有 .md / .mdx
仅在 frontmatter 区块检测是否存在 description，不会误判正文代码块内的示例 description:
提取文章标题 + 正文前2600字作为生成上下文
调用千问 API，使用优化提示词自动生成文章摘要
校验摘要输出质量（长度校验、过滤**等无效内容），不合格自动重试生成
重写文件 frontmatter，写入 description 与 descriptionSource: ai
仅修改 frontmatter 区域，文章正文内容完全不改动

扫描与过滤#

1
/**
2
 * 判断文章是否已有 description（只检查 frontmatter 区块内，且值不能为空）
3
 */
4
function hasDescription(raw: string): boolean {
5
  const parsed = parseFrontmatter(raw);
6
  if (!parsed) return false;
7

8
  const descMatch = parsed.frontmatter.match(/^description\s*:\s*(.+)$/m);
9
  if (!descMatch) return false;
10

11
  let value = descMatch[1].trim();
12
  // 去掉引号
13
  if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
14
    value = value.slice(1, -1);
15
  }
16

17
  return value.length > 0;
18
}

展开收起

注意

⚠️ 新手陷阱：若用整篇文件匹配 description:，在正文里展示 frontmatter 示例的文章会被误判为”已有描述”。务必限定在 frontmatter 区块内检测！

上下文提取#

1
function extractContext(body: string, maxChars: number): string {
2
  const cleaned = body
3
    .replace(/^---[\s\S]*?---\n?/, "")           // 去掉 frontmatter
4
    .replace(/#{1,6}\s+/g, "")                   // 去掉标题标记
5
    .replace(/```[\s\S]*?```/g, "[代码块]")       // 代码块替换
6
    .replace(/`[^`]+`/g, "[代码]")               // 行内代码替换
7
    .replace(/!\[.*?\]\(.*?\)/g, "")             // 去掉图片
8
    .replace(/\[([^\]]*)\]\(.*?\)/g, "$1")       // 保留链接文字
9
    .replace(/\n{3,}/g, "\n\n")                  // 压缩空行
10
    .trim();
11

12
  return cleaned.length > maxChars
13
    ? `${cleaned.slice(0, maxChars)}...`
14
    : cleaned;
15
}

展开收起

提示词设计#

1
const SYSTEM_PROMPT = `你是一个以第一视角写作的个人博客作者。你的博客记录技术学习、日常生活和真实感悟。
2

3
你的任务是：读完一篇博客文章后，为它写一段友好、自然、像博客导语一样的"文章摘要"。
4

5
核心规则：
6
1. 输出只要一段摘要文字，不要标题、不要列表、不要"本文""这篇文章""总之"之类的套话。
7
2. 表达要自然、口语化，像一个真实的博主在跟读者打招呼或做开场铺垫，有一点"人味"。
8
3. 不要堆砌概念、不要写得像说明书或提纲总结。
9
4. 贴近原文真实内容，保留原作者的情绪和语气。
10
5. 技术文章保持清晰但不要生硬，生活/感悟类文章语气柔和一些。
11
6. 字数控制在 60～120 字左右，越短、越准越好，不要啰嗦。
12
7. 纯正文内容输出（不带任何前缀或说明）。`;

API 调用与重试#

1
const resp = await fetch(`${QWEN_BASE_URL}/chat/completions`, {
2
  method: "POST",
3
  headers: {
4
    "Content-Type": "application/json",
5
    Authorization: `Bearer ${QWEN_API_KEY}`,
6
  },
7
  body: JSON.stringify({
8
    model: QWEN_MODEL,
9
    messages: [
10
      { role: "system", content: SYSTEM_PROMPT },
11
      { role: "user", content: userMsg },
12
    ],
13
    temperature: 0.75,
14
    max_tokens: 256,
15
  }),
16
});

展开收起

运行脚本#

完整脚本获取：fill-descriptions/index.ts

Terminal window

1
# package.json
2
{
3
  "scripts": {
4
    "fill-descriptions": "npx tsx scripts/fill-descriptions/index.ts"
5
  },
6
}

Terminal window

1
# 终端运行脚本
2
pnpm fill-descriptions

构建前自动补全（可选）#

希望每次部署前自动补全新文章摘要，可在 package.json 的 build 前加上脚本：

Terminal window

1
{
2
  "scripts": {
3
    "build": "pnpm fill-descriptions && node scripts/generate-icons.js && npx tsx scripts/generate-lqips.ts && astro build && pagefind --site dist"
4
  }
5
}

注意：每次 build 都会扫描并可能调用 API，会消耗额度。文章量大时建议只在本地或 CI 需要时手动跑 pnpm fill-descriptions。

运行时组件详解#

组件路径：src/components/widget/AiSummary.astro

完整组件获取：AiSummary.astro

Props 定义#

1
interface Props {
2
  description: string;
3
  descriptionSource?: "manual" | "ai" | string;
4
}

模板设计#

1
<div class="ai-summary-wrapper rounded-xl mb-6">
2
  <div class="ai-summary">
3
    <div class="ai-summary-inner">
4
      <div class="ai-summary-header">
5
        <div class="ai-summary-icon">
6
          <Icon name={iconName} class="text-base" />
7
        </div>
8
        <span class="ai-summary-label">{sourceLabel}</span>
9
      </div>
10
      <p
11
        class="ai-summary-text js-ai-summary-text"
12
        data-full-text={description}
13
      ></p>
14
    </div>
15
  </div>
16
</div>

展开收起

提示

⚠️使用 class 而非固定 id，避免 Swup 多页残留冲突；用 data-typing-init 防止重复初始化。

打字机动画核心#

1
(function initAiSummaryTypewriter() {
2
  function run() {
3
    const el = document.querySelector(".js-ai-summary-text");
4
    if (!el || el.dataset.typingInit === "1") return;
5
    el.dataset.typingInit = "1";
6

7
    const fullText = el.getAttribute("data-full-text") || "";
8

9
    // 无障碍：减少动态效果
10
    if (window.matchMedia("(prefers-reduced-motion: reduce)").matches) {
11
      el.textContent = fullText;
12
      return;
13
    }
14

15
    let hasRun = false;
16
    const speed = 45;
17

18
    const observer = new IntersectionObserver(
19
      (entries) => {
20
        for (const entry of entries) {
21
          if (entry.isIntersecting && !hasRun) {
22
            hasRun = true;
23
            observer.unobserve(el);
24
            startTyping(el, fullText, speed);
25
          }
26
        }
27
      },
28
      { threshold: 0.3 },
29
    );
30

31
    observer.observe(el);
32
  }
33

34
  run();
35
  document.addEventListener("astro:page-load", run);
36
})();

展开收起

标点停顿设计#

字符	延迟	说明
普通字	45ms	基础速度
，、；:	90ms（2×）	短停顿
。！？…	135ms（3×）	长停顿

文章页集成#

在 src/pages/posts/[...slug].astro 中添加：组件获取：[…slug].astro

1
import AiSummary from "@/components/widget/AiSummary.astro";
2

3
<!-- AI 摘要 - 打字机动画 -->
4
{
5
  entry.data.description && (
6
    <AiSummary
7
      description={entry.data.description}
8
      descriptionSource={entry.data.descriptionSource}
9
    />
10
  )
11
}

Content Schema 配置#

在 src/content.config.ts 中添加：

1
type PostData = {
2
descriptionSource?: "manual" | "ai";
3
}
4

5
const postsCollection: ContentCollection<PostData> = defineCollection({
6
  schema: z.object({
7
    descriptionSource: z.enum(["manual", "ai"]).optional(),
8
  }),
9
});

优化技巧#

参数	作用	推荐值	说明
`temperature`	控制随机性	0.75	略有个性，避免死板
`max_tokens`	最大输出长度	256	摘要短，足够
`top_p`	核采样	0.9	控制生成多样性

输入优化#

去掉无关的格式标记
代码块用占位符替代（节省 token）
控制输入长度（推荐 2000-3000 字）

陷阱清单#

陷阱	说明	规避方法
API Key 泄露	将密钥硬编码到代码中	使用 .env 文件，加入 .gitignore
用整篇文件匹配 description	正文代码块里的示例 description 会被误识别为已存在摘要	只在 frontmatter 区块内检测字段
Swup 兼容	页面切换后打字机动画无法重新触发，组件失效	组件监听 `astro:page-load`，站内切页后打字机仍会正常初始化
模型选择	选用数学、代码专用模型生成文章摘要，输出内容质量差、不符合文案需求	默认 `qwen-plus`；数学/代码专用模型不适合写摘要，脚本启动时会给出警告
教程类文章	教程正文代码块中存在 `description:` 示例文本，旧脚本会误判文章已有摘要，跳过生成	当前版本仅在 frontmatter 区域检测字段，不受正文代码示例干扰，可正常补全摘要
请求无间隔	循环批量调用千问API，请求频率过高触发平台限流，脚本中断报错	添加 600ms 以上的请求间隔
输入内容过长	全文无限制传入API，消耗大量token，同时超长文本会降低AI摘要精准度	正文内容截断到 2000-3000 字后再传入模型
忽略编码问题	Windows系统读写md文件时默认编码非UTF-8，中文摘要出现乱码	读写文件时强制指定 UTF-8 编码
未校验输出	AI返回空内容、仅符号、无意义文本等无效摘要，直接写入文件	使用 sanitizeDescription 函数校验、清洗AI输出内容
提示词过于复杂	提示词冗余、逻辑混乱，AI无法准确理解摘要生成要求，产出效果差	提示词清晰简洁，分点明确告知AI生成规则与要求
使用固定 id	多页面共用相同DOM id，Swup页面缓存残留，打字机组件渲染冲突	使用 class 选择器替代固定id
空字符串误判	frontmatter 内 `description: ""` 空字符串被判定为已有摘要，跳过自动补全	使用 hasDescription 函数精准判断字段是否存在有效文本

快速检查清单#

AiSummary.astro 组件文件已创建
[...slug].astro 文章页面已引入摘要组件
content/content.config.ts 配置文件包含 descriptionSource 字段校验
.env 环境变量文件已配置 QWEN_API_KEY
执行过命令 pnpm fill-descriptions 批量生成摘要，或手动填写过 description
本地启动 pnpm dev，打开带有摘要的文章页面，滚动至摘要区域，验证打字机动画正常展示

自助友链申请

Mon, 27 Jul 2026 00:00:00 GMT

存储类型区别优势劣势对比#

存储类型	速度	收费模式	Pages 函数限制	核心优势	核心劣势	适用场景
`S3 存储`	中等	免费额度可用	不限制函数	S3 通用标准，生态工具丰富，免费额度充足，全函数兼容	免费超限后计费，无内置数据库权限，鉴权需自行开发	静态网站资源、文件备份、跨云存储、通用文件托管
`KV 存储`	极快	免费额度可用	仅 pages-edge 函数可用	内存级低延迟，API 简单，免费额度满足小型缓存，适配边缘函数	仅支持主键查询，无法存大文件，普通 Pages 函数无法调用	网站缓存、会话存储、计数器、配置文件、边缘临时热点数据
`Blob 存储`	普通	免费额度可用	支持 pages 任意函数	针对二进制大文件优化，全类型 Pages 函数无限制，冷归档低价	访问速度一般，不兼容标准 S3，跨云迁移适配差	微软云配套业务、视频备份、虚拟机快照、文档附件存储
`Supabase 存储`	最快	免费额度可用	不限制函数	存储 + PostgreSQL 一体化，自带 RLS 行级权限，配套用户认证、向量存储	免费项目数量有限，闲置项目会暂停，底层依赖第三方存储	全栈 Web/App 快速开发、用户上传素材、AI 向量知识库、小型后端项目
`COS 存储`	最快	按量收费，无永久免费	不限制函数	国内节点多，国内访问速度顶尖，深度集成腾讯 CDN，媒体处理功能完善	无免费额度，存储 / 流量 / 请求均收费，海外访问延迟偏高	国内小程序 / 网站静态资源、电商图片、短视频素材、企业数据备份

选择存储类型#

这里博主选择的是 Supabase 存储，因为最快免费额度可用不限制函数，符合博主的需求。

配置 Supabase#

进入阿里云云原生数据仓库，左上角选择离你最近的区域。这里我选择的是深圳区域
点击创建项目，选择免费测试创建，点击创建，填写项目名称项目名称需要英文的！输入数据库账号和数据库密码
首次创建需要配置专有网络和专有网络交换机，若当前区域未创建专有网络，请前往阿里云VPC控制台创建专有网络实例
进入专有网络页面，点击创建专有网络，地域选择需要和刚刚创建项目-可用区一致！填写名称，点击创建，IPv4网段选择手动输入 IPv4 地址段，输入IPv4网段随便选一个，这里我选的是192.168.0.0/16，IPv6网段选择系统分配的 IPv6 地址段
输入交换机名称和可用区选择和刚刚创建项目-可用区一致！这里我选择的是深圳可用区 F
是否开放白名单限制，这里我选择的是否！
IP 白名单，这里我选择的是0.0.0.0/0！然后点击确定，即可完成配置。
创建好后把修改数据库白名单，添加0.0.0.0/0，即可从任何 IP访问数据库。

登录 Supabase#

点击登录 Dashboard，会弹出登录账号和登录密码复制数据库账号和数据库密码，即可登录（如果设置了白名单，需要在白名单中添加当前 IP 才能登录）

SQL Editor#

登录后，左侧菜单点击SQL Editor，即可进入 SQL 编辑器，在 SQL 编辑器中执行 SQL 语句

1
INSERT INTO "public"."friends" (
2
    "id",
3
    "title",
4
    "desc",
5
    "siteUrl",
6
    "imgUrl",
7
    "tags",
8
    "status",
9
    "ip",
10
    "email",
11
    "message",
12
    "updatedAt",
13
    "createdAt",
14
    "weight" -- 新增int4权重字段
15
) VALUES
16
(
17
    '64f3b4ef-490d-4440-ad8e-5dc73034ccb9',
18
    '云原生构建',
19
    '会Fork就会CNB',
20
    'https://cnb.cool/',
21
    'https://cnb.cool/cnb/-/logos/s',
22
    '["Blog","Astro"]'::jsonb,
23
    'rejected',
24
    'unknown',
25
    NULL,
26
    NULL,
27
    '1785103334148',
28
    '1784148550477',
29
    0
30
),
31
(
32
    '80a0e1dc-7f96-42df-be62-3d0edabc77ac',
33
    '启源',
34
    '技术丶生活',
35
    'https://czxcly.cn/',
36
    'https://personal-biz.czxcly.cn/profile/avatar/2026/05/18/594c922986f34225aa6917bb0b2908ca.jpg',
37
    '["Blog","Astro"]'::jsonb,
38
    'approved',
39
    '129.204.149.174',
40
    NULL,
41
    NULL,
42
    '1785102151599',
43
    '1783301022476',
44
    0
45
),
46
(
47
    '8f652adc-0d92-4c53-9e5a-5088048b76e9',
48
    'ZhiJing''s Blog',
49
    'Go with the flow.',
50
    'https://iwexe.top',
51
    'https://iwexe.top/avatar.svg',
52
    '["Blog","Astro"]'::jsonb,
53
    'approved',
54
    '43.139.234.199',
55
    NULL,
56
    NULL,
57
    '1785102152667',
58
    '1783185799746',
59
    0
60
),
61
(
62
    'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
63
    'One',
64
    '明心见性，爱自己',
65
    'https://onedayxyy.cn/',
66
    'https://img.onedayxyy.cn/images/Teek/Teekwebsite/xyy-logo.avif',
67
    '["Blog","Astro"]'::jsonb,
68
    'approved',
69
    'unknown',
70
    NULL,
71
    NULL,
72
    '1785102169329',
73
    '1783815691854',
74
    0
75
),
76
(
77
    'a56878d9-4649-439d-b16d-abb4fa87ec7f',
78
    'gc的小站',
79
    '综合性小站,希望能帮到你!',
80
    'https://gcweb.cc',
81
    'https://www.gcweb.cc/static/img/pig.jpg',
82
    '["Blog","Astro"]'::jsonb,
83
    'approved',
84
    '223.104.116.184',
85
    NULL,
86
    NULL,
87
    '1785102168900',
88
    '1783462756928',
89
    0
90
),
91
(
92
    'b2c3d4e5-f6a7-8901-bcde-f23456789012',
93
    'Hyde',
94
    '人心中的成见是一座大山',
95
    'https://example.com/',
96
    'https://example.com/_astro/avatar.B2RZ_bo3_JV0dW.webp',
97
    '["Blog","Astro"]'::jsonb,
98
    'approved',
99
    'unknown',
100
    NULL,
101
    NULL,
102
    '1785102168100',
103
    '1783462753394',
104
    0
105
);

展开收起

执行后可以在SQL Editor中查看执行的示例数据

前端页面改造#

文件目录：

文件路径	作用
`src/config/friendsConfig.ts`	友链配置文件
`src/content/spec/friends.mdx`	友链列表页面自定义内容，已弃用
`src/pages/friends.astro`	友链列表页面组件
`src/types/friendsConfig.ts`	友链配置文件类型定义

相关文件在源码中获取，记得点个Star！将上面的文件替换掉您项目对应文件即可。

部署edgeone边缘函数#

登录进入Edgeone控制台,新增站点-进入站点详情页
在左侧菜单找到函数管理-新建函数，随便选一个模板点击下一步
填写函数名称，这里我选的是创建 Hello World，黏贴函数代码,点击创建并部署等待创建完成，通常10s左右，刷新页面即可完成部署

配置变量#

在函数管理-函数详情-环境变量与密钥中，添加以下环境变量

变量名	变量值	变量类型	变量描述	获取方式
`SUPABASE_URL`	`https://spb-xxxxxxxx.supabase.opentrust.net`	`string`	`Supabase URL`	从Supabase控制台左上角-`Connect`-`App Frameworks`获取
`SUPABASE_KEY`	`eyJ0exxxxxxx.xxxxxxxxxxxxxx.xxxxxxxxxx`	`string`	`Supabase Key`	从Supabase控制台左上角-`Connect`-`App Frameworks`获取
`ADMIN_USER`	`admin`	`string`	`登录admin后台用户名`	自定义设置
`ADMIN_PASS`	`admin`	`string`	`登录admin后台密码`	自定义设置
`PUSH_SWITCH`	`on`	`string`	`是否开启推送通知`	用于开启或关闭推送通知功能
`PUSH_PLATFORM`	`feishu`	`string`	`推送平台`	例如：`feishu`、`dingtalk`等
`PUSH_TOKEN`	`https://open.feishu.cn/open-apis/bot/v2/hook/xxx`	`string`	`飞书/钉钉webhook推送token地址`	飞书、钉钉webhook地址获取
`PUSH_SECRET`	`SEC9xxxxxxxxxx`	`string`	`钉钉平台加签密钥`	钉钉加签获取

填写完成后，一定要点击部署按钮，否则环境变量不会生效

配置域名#

配置主域名（推荐）#

进入edgeone控制台，点击makers找到您部署的 Firefly的项目，进入项目设置-域名管理-添加自定义域名，填写您的二级域名，例如：firefly.example.com，填写后去您的域名平台填写canme解析，申请免费证书，等待部署证书生效
进入服务总览-网站安全加速-进入您的站点，找到域名服务-域名管理，点击添加域名

然后域名平台填写canme解析，申请免费证书，等待部署证书生效

配置二级域名（2选1）#

进入主站-域名管理-添加域名
填写二级域名，例如：api.example.com
IP/域名填写边缘函数部署生成的默认访问域名，例如：friends-zone-3du2b1i5fnma-1312627337.eo-edgefunctions.com
推荐模板选择不使用模板，点击下一步
去您域名后台管理平台解析canme类型的域名，申请免费证书，等待部署证书生效

配置函数触发规则#

在函数管理-函数详情-新增触发规则中，添加以下触发规则

触发条件：

匹配类型	运算符	值
`HOST`	`等于`	`example.com` （选择你配置的域名）
`URL path`	`等于`	`/api*`

执行函数：

执行方式	执行函数
`执行指定函数`	friends-zone-3du2b1i5fnma-1312627337

函数触发规则

配置后端请求地址#

路径：src/pages/friends.astro

搜索example.com替换您上面配置好的二级域名，有两处要替换

访问后台#

访问https://你的域名/api/admin，登录后即可查看友友链审核管理后台页面
登录用户名密码：您环境变量中的ADMIN_USER和ADMIN_PASS里面的值，变量值中就是您后台的账号和密码

集成朋友圈与笔记本功能

Sun, 21 Jun 2026 00:00:00 GMT

提示

本文是在博主团子和蛋糕文章：用 GitHub Gist 做博客后端：零成本的说说与笔记方案基础上增加了自己实践过程的一些细节，转载无需和我联系，但请注明文章来源。如果侵权之处，请联系博主进行删除，谢谢~

目录结构#

以下是朋友圈和笔记本功能相关的核心目录结构：

1
Firefly-hyde/
2
├── astro.config.mjs                                    # 修改 - 添加路径别名
3
│
4
├── src/
5
│   ├── components/
6
│   │   └── moments/                                    # 新增目录
7
│   │       ├── MomentCard.astro                       # 新增 - 朋友圈卡片组件
8
│   │       └── MomentsCover.astro                     # 新增 - 朋友圈封面组件
9
│   │
10
│   ├── config/
11
│   │   ├── externalMomentsConfig.ts                   # 新增 - 朋友圈配置
12
│   │   ├── externalNotebooksConfig.ts                 # 新增 - 笔记本配置
13
│   │   ├── navBarConfig.ts                            # 修改 - 添加导航链接
14
│   │   └── siteConfig.ts                              # 修改 - 添加封面配置
15
│   │
16
│   ├── content/
17
│   │   ├── config.ts                                  # 修改 - 添加moments集合
18
│   │   └── moments/                                    # 新增目录
19
│   │       └── *.md                                   # 新增 - 本地朋友圈内容文件
20
│   │
21
│   ├── data/
22
│   │   └── moments.ts                                 # 新增 - 获取远程朋友圈数据脚本
23
│   │
24
│   ├── pages/
25
│   │   ├── admin/                                     # 新增目录
26
│   │   │   ├── index.astro                           # 新增 - 登录页
27
│   │   │   ├── moments.astro                         # 新增 - 朋友圈管理
28
│   │   │   └── notebooks.astro                       # 新增 - 笔记本管理
29
│   │   ├── life/notebooks/
30
│   │   │   └── remote-entry.astro                    # 新增 - 远程笔记页
31
│   │   ├── moments.astro                              # 新增 - 朋友圈主页
32
│   │   └── moments/
33
│   │       └── pinned.astro                           # 新增 - 精选朋友圈
34
│   │
35
│   ├── types/
36
│   │   └── siteConfig.ts                              # 修改 - 添加momentsCover类型
37
│   │
38
│   └── utils/
39
│       ├── content-utils.ts                           # 修改 - 添加数据获取
40
│       └── gist-api.ts                                # 新增 - Gist API工具
41
└──

展开收起

新增朋友圈/封面卡片组件#

文件路径：src/components/moments/MomentCard.astro和src/components/moments/MomentsCover.astro

完整代码：MomentCard.astro

完整代码：MomentsCover.astro

创建 Gist API 工具文件#

文件路径: src/utils/gist-api.ts

完整代码: gist-api.ts

创建朋友圈配置#

文件路径: src/config/externalMomentsConfig.ts

1
// 外部朋友圈数据源配置（基于 GitHub Gist，完全免费）
2
// 数据存储在 GitHub Gist 中，通过 GitHub API 读写
3

4
export const externalMomentsConfig = {
5
    // 是否启用外部朋友圈数据源
6
    enable: true,
7

8
    // GitHub Gist ID（创建 Gist 后从 URL 中获取）
9
    // 替换为你的 Gist ID。https://gist.github.com/<your-account>/xxxx，其中 xxxx 即为 Gist ID
10
    gistId: "替换为你的 Gist ID",
11

12
    // Gist 中的文件名
13
    fileName: "moments.json",
14

15
    // 默认作者信息
16
    defaultAuthor: "Hyde",
17
    defaultAvatar: "https://你的头像URL.jpg",
18

19
    // 后台登录密码的 SHA-256 哈希
20
    // 生成方式：在线工具:https://www.strongpasswordgenerator.org/zh-cn/sha256-hash-generator/
21
    adminPasswordHash:
22
        "b5d9ded2ab2812e8653f06fc4d3246a4b13642e8371bc74a7f1003eb4fb4e637",
23

24
    // GitHub Token（优先从环境变量 GITHUB_TOKEN 读取）
25
    githubToken: process.env.GITHUB_TOKEN || "",
26
};

展开收起

创建笔记本配置#

文件路径: src/config/externalNotebooksConfig.ts

1
// 外部笔记数据源配置（基于 GitHub Gist）
2
// 每个笔记本有独立的 Gist 仓库
3

4
export const externalNotebooksConfig = {
5
    // 是否启用外部笔记数据源
6
    enable: true,
7

8
    // 每个笔记本对应的 Gist ID
9
    // 在 https://gist.github.com 创建 Secret Gist，文件名 notebooks-entries.json，内容 []
10
    notebookGists: {
11
        "每日总结": "your-gist-id-here",
12
        "日记": "your-gist-id-here",
13
        "日常琐记": "your-gist-id-here",
14
        "学习笔记": "your-gist-id-here",
15
    } as Record<string, string>,
16

17
    // 笔记模板（Admin 页面快速选择）
18
    // {name} 会被替换为今天的日期
19
    templates: [
20
        {
21
            id: "daily",
22
            icon: "📝",
23
            name: "每日总结",
24
            title: "{name} 每日总结",
25
            content: "📍今天做了什么：\n📅今日感想：\n🔮明日计划：",
26
        },
27
        {
28
            id: "diary",
29
            icon: "📔",
30
            name: "日记",
31
            title: "{name}",
32
            content: "## 天气\n\n## 今天发生了什么\n\n## 心情\n\n",
33
        },
34
        {
35
            id: "reading",
36
            icon: "📚",
37
            name: "读书笔记",
38
            title: "",
39
            content: "## 📚 书籍信息\n\n- 书名：\n- 作者：\n\n## 核心观点\n\n## 我的感想\n\n",
40
        },
41
        {
42
            id: "free",
43
            icon: "📄",
44
            name: "空白",
45
            title: "",
46
            content: "",
47
        },
48
    ] as Array<{
49
        id: string;
50
        icon: string;
51
        name: string;
52
        title: string;
53
        content: string;
54
    }>,
55

56
    // 后台登录密码的 SHA-256 哈希（与朋友圈后台共用同一密码）
57
    adminPasswordHash:
58
        "b5d9ded2ab2812e8653f06fc4d3246a4b13642e8371bc74a7f1003eb4fb4e637",
59

60
    // GitHub Token
61
    githubToken: process.env.GITHUB_TOKEN || "",
62
};

展开收起

修改站点配置#

文件路径: src/config/siteConfig.ts

操作: 添加朋友圈封面配置

插入位置: 在 defaultAvatar 配置之后

添加代码:

1
// 朋友圈页面封面配置（微信朋友圈风格）
2
momentsCover: {
3
    enable: true,
4
    image: "https://你的封面图片URL.jpg",
5
},

修改类型定义#

文件路径: src/types/siteConfig.ts

1
// 朋友圈页面封面配置
2
momentsCover: {
3
    enable: boolean;
4
  image?: string;
5
},

修改导航栏配置#

文件路径: src/config/navBarConfig.ts

修改1 - 添加朋友圈链接:

在导航链接列表中添加：

1
LinkPresets.Moments,

修改2 - 定义链接预设:

在 LinkPresets 对象中添加：

1
Moments: {
2
  name: "朋友圈",
3
  url: "/moments/",
4
  icon: "mdi:wechat",
5
},

修改3 - 添加登录链接:

文件路径：src/components/layout/Navbar.astro

1
<LightDarkSwitch client:load></LightDarkSwitch>
2
    <a aria-label="Admin" href="/admin/" class="btn-plain scale-animation rounded-lg h-11 w-11 active:scale-90">
3
        <Icon is:inline name="material-symbols:account-circle" class="text-[1.25rem]"></Icon>
4
    </a>

修改内容配置#

文件路径: src/content.config.ts

1
// 朋友圈集合
2
const momentsCollection = defineCollection({
3
    loader: glob({ pattern: "**/*.{md,mdx}", base: "./src/content/moments" }),
4
    schema: ({ image }) =>
5
        z.object({
6
            author: z.string().optional().default(""),
7
            avatar: z.string().optional().default(""),
8
            pinned: z.boolean().optional().default(false),
9
            published: z.date(),
10
            images: z
11
                .array(image().or(z.string()))
12
                .or(z.string())
13
                .optional()
14
                .default([]),
15
            tags: z.array(z.string()).optional().default([]),
16
            location: z.string().optional().default(""),
17
            device: z.string().optional().default(""),
18
        }),
19
});
20

21
// 导出朋友圈集合
22
export const collections = {
23
    posts: postsCollection,
24
    spec: specCollection,
25
    ziyuan: ziyuanCollection,
26
    moments: momentsCollection,  // 朋友圈集合
27
};

展开收起

创建朋友圈数据获取脚本#

文件路径: src/data/moments.ts

提示

此脚本从布局文件抽离，便于维护。负责从 GitHub Gist 加载朋友圈数据并动态插入页面。

完整代码: moments.ts

创建精选朋友圈页面#

文件路径: src/pages/moments/pinned.astro

完整代码: pinned.astro

Admin 管理后台#

创建登录页#

文件路径: src/pages/admin/index.astro

核心功能: SHA-256 密码验证，登录成功后存储 token 到 localStorage

完整代码: index.astro

创建朋友圈管理页#

文件路径: src/pages/admin/moments.astro

核心功能:

从 Gist 读取朋友圈数据
新增/编辑/删除朋友圈
支持图片上传（转为 base64）
支持置顶、标签、位置

完整代码: moments.astro

创建笔记本管理页#

文件路径: src/pages/admin/notebooks.astro

核心功能:

多笔记本支持
笔记模板选择
Markdown 编辑
时间线展示

完整代码: notebooks.astro

环境变量配置#

文件路径: .env

1
# GitHub Token（用于 Gist API 认证）
2
# 获取方式：https://github.com/settings/tokens
3
# 需要 gist 权限
4
GITHUB_TOKEN=your_github_token_here

路径别名配置#

修改 Astro 配置#

文件路径: astro.config.mjs

1
import { defineConfig } from 'astro/config';
2

3
export default defineConfig({
4
    vite: {
5
        resolve: {
6
            alias: {
7
                "@": "./src",
8
                "@components": "./src/components",
9
                "@layouts": "./src/layouts",
10
                "@config": "./src/config",
11
                "@utils": "./src/utils",
12
                "@data": "./src/data",
13
            },
14
        },
15
    },
16
});

展开收起

文件清单#

文件路径	操作	说明
`src/utils/gist-api.ts`	新建	Gist API 工具函数
`src/config/externalMomentsConfig.ts`	新建	朋友圈配置
`src/config/externalNotebooksConfig.ts`	新建	笔记本配置
`src/config/siteConfig.ts`	修改	添加封面配置
`src/config/navBarConfig.ts`	修改	添加导航链接
`src/types/siteConfig.ts`	修改	添加类型定义
`src/content.config.ts`	修改	添加 moments 集合
`src/data/moments.ts`	新建	朋友圈数据获取脚本
`src/utils/content-utils.ts`	修改	添加数据获取
`src/components/moments/MomentCard.astro`	新建	朋友圈卡片组件
`src/components/moments/MomentsCover.astro`	新建	朋友圈封面组件
`src/pages/moments.astro`	新建	朋友圈主页
`src/pages/moments/pinned.astro`	新建	精选朋友圈
`src/pages/admin/index.astro`	新建	登录页
`src/pages/admin/moments.astro`	新建	朋友圈管理
`src/pages/admin/notebooks.astro`	新建	笔记本管理
`src/pages/life/notebooks/remote-entry.astro`	新建	远程笔记页
`.env`	新建	环境变量配置
`astro.config.mjs`	修改	添加路径别名

隐藏封面图

Wed, 03 Jun 2026 00:00:00 GMT

添加类型定义#

文件路径：src/types/config.ts

1
// 文章列表布局配置
2
  postListLayout: {
3
    allowCoverSwitch?: boolean; // 是否允许用户切换文章封面图显示
4
    showCover?: boolean; // 默认是否显示文章封面图
5
  };

添加配置项#

文件路径：src/config/siteConfig.ts

1
postListLayout: {
2
  allowCoverSwitch: true,  // 新增：允许切换封面图显示
3
  showCover: true,         // 新增：默认显示封面图
4
},

设置工具函数#

文件路径：src/utils/setting-utils.ts

1
// 获取默认封面图显示状态
2
export function getDefaultPostCoverImageEnabled(): boolean {
3
  return siteConfig.postListLayout.showCover ?? true;
4
}
5

6
// 从localStorage读取封面图显示状态
7
export function getStoredPostCoverImageEnabled(): boolean {
8
  if (
9
    typeof localStorage === "undefined" ||
10
    typeof localStorage.getItem !== "function"
11
  ) {
12
    return getDefaultPostCoverImageEnabled();
13
  }
14
  const stored = localStorage.getItem("postCoverImageEnabled");
15
  if (stored === null) {
16
    return getDefaultPostCoverImageEnabled();
17
  }
18
  return stored === "true";
19
}
20

21
// 设置封面图显示状态
22
export function setPostCoverImageEnabled(enabled: boolean): void {
23
  if (
24
    typeof localStorage === "undefined" ||
25
    typeof localStorage.setItem !== "function"
26
  ) {
27
    return;
28
  }
29
  localStorage.setItem("postCoverImageEnabled", String(enabled));
30
  applyPostCoverImageEnabledToDocument(enabled);
31
  if (typeof window !== "undefined") {
32
    window.dispatchEvent(
33
      new CustomEvent("postCoverImageChange", {
34
        detail: { enabled },
35
      }),
36
    );
37
  }
38
}
39

40
// 将封面图状态应用到文档
41
export function applyPostCoverImageEnabledToDocument(enabled: boolean): void {
42
  if (typeof document === "undefined") {
43
    return;
44
  }
45
  document.documentElement.setAttribute(
46
    "data-post-cover-enabled",
47
    String(enabled),
48
  );
49
}

展开收起

添加设置面板开关#

文件路径：src/components/controls/DisplaySettingsIntegrated.svelte

导入相关函数#

在文件顶部导入新添加的工具函数：

1
import {
2
  // ... 其他导入
3
  getDefaultPostCoverImageEnabled,
4
  getStoredPostCoverImageEnabled,
5
  setPostCoverImageEnabled,
6
  applyPostCoverImageEnabledToDocument,
7
} from "@utils/setting-utils";

添加状态变量#

在脚本部分添加以下状态变量：

1
const defaultPostCoverImageEnabled = getDefaultPostCoverImageEnabled();
2
const isPostCoverImageSwitchable = siteConfig.postListLayout.allowCoverSwitch ?? true;
3
let postCoverImageEnabled = $state(true);

添加切换函数#

添加切换封面图状态的函数：数：

1
function togglePostCoverImageEnabled() {
2
  postCoverImageEnabled = !postCoverImageEnabled;
3
  setPostCoverImageEnabled(postCoverImageEnabled);
4
}

在 onMount 中初始化状态#

1
// 从localStorage读取文章封面图状态
2
postCoverImageEnabled = getStoredPostCoverImageEnabled();
3
// 将状态应用到文档
4
applyPostCoverImageEnabledToDocument(postCoverImageEnabled);

添加开关 UI#

在 HTML 模板部分（布局切换区域后）添加：

1
<!-- Post Cover Image Switch Section -->
2
{#if isPostCoverImageSwitchable}
3
  <div class="mt-2 mb-2">
4
    <div class="flex gap-2 font-bold text-lg text-neutral-900 dark:text-neutral-100 transition relative ml-3 mb-2
5
        before:w-1 before:h-4 before:rounded-md before:bg-(--primary)
6
        before:absolute before:-left-3 before:top-1/2 before:-translate-y-1/2"
7
    >
8
      {i18n(I18nKey.postCoverImage)}
9
      <button aria-label="Reset to Default" class="btn-regular w-7 h-7 rounded-md active:scale-90"
10
              class:opacity-0={postCoverImageEnabled === defaultPostCoverImageEnabled}
11
              class:pointer-events-none={postCoverImageEnabled === defaultPostCoverImageEnabled}
12
              onclick={() => {
13
                postCoverImageEnabled = defaultPostCoverImageEnabled;
14
                setPostCoverImageEnabled(defaultPostCoverImageEnabled);
15
              }}>
16
        <div class="text-(--btn-content)">
17
          <Icon icon="fa7-solid:arrow-rotate-left" class="text-[0.875rem]"></Icon>
18
        </div>
19
      </button>
20
    </div>
21
    <div class="space-y-1">
22
      <button
23
        class="w-full btn-regular rounded-md py-2 px-3 flex items-center gap-3 text-left active:scale-95 transition-all relative overflow-hidden"
24
        class:bg-(--btn-regular-bg-hover)={postCoverImageEnabled}
25
        onclick={togglePostCoverImageEnabled}
26
      >
27
        <Icon icon="material-symbols:image" class="text-[1.25rem] shrink-0"></Icon>
28
        <span class="text-sm flex-1">{i18n(I18nKey.postCoverImage)}</span>
29
        <div class="w-10 h-5 rounded-full transition-all duration-200 relative"
30
             class:bg-(--primary)={postCoverImageEnabled}
31
             class:bg-(--btn-regular-bg-active)={!postCoverImageEnabled}>
32
          <div class="absolute top-0.5 w-4 h-4 bg-white rounded-full shadow transition-all duration-200"
33
               class:left-0.5={!postCoverImageEnabled}
34
               class:left-5={postCoverImageEnabled}></div>
35
        </div>
36
      </button>
37
    </div>
38
  </div>
39
{/if}

展开收起

添加样式控制#

文件路径：src/components/layout/PostCard.astro

1
/* === Hide Post Cover Image === */
2
/* 当 data-post-cover-enabled="false" 时隐藏封面图 */
3
:global([data-post-cover-enabled="false"]) .post-card-image {
4
  display: none !important;
5
}
6

7
:global([data-post-cover-enabled="false"]) .has-cover {
8
  &.post-card-wrapper {
9
    .post-card-content {
10
      width: calc(100% - 52px - 12px) !important;
11
    }
12
  }
13
}
14

15
:global([data-post-cover-enabled="false"]) .has-cover .post-card-enter-btn {
16
  display: flex !important;
17
}

展开收起

语言配置#

文件路径：src/i18n/i18nKey.ts

1
postCoverImage = "postCoverImage",

文件路径：src/i18n/languages/en.ts

1
[Key.postCoverImage]: "Post Cover Image",

文件路径：src/i18n/languages/ja.ts

1
[Key.postCoverImage]: "記事のカバー画像",

文件路径：src/i18n/languages/ru.ts

1
[Key.postCoverImage]: "Обложка поста",

文件路径：src/i18n/languages/zh_CN.ts

1
[Key.postCoverImage]: "文章封面图",

文件路径：src/i18n/languages/zh_TW.ts

1
[Key.postCoverImage]: "文章封面圖",

归档统计

Tue, 02 Jun 2026 00:00:00 GMT

获取归档列表#

文件路径：src/pages/archive.astro

1
---
2
import { getSortedPostsList } from "@/utils/content-utils";  // [!code --]
3
const sortedPostsList = await getSortedPostsList();     // [!code --]
4
<ArchivePanel sortedPosts={sortedPostsList} client:only="svelte" /> // [!code --]
5

6
import { getArchiveList } from "@/utils/content-utils";
7

8
// 获取归档列表（posts + moments + bangumi + life）
9
const archiveList = await getArchiveList();
10

11
// 计算各类型数量
12
const postsCount = archiveList.filter(item => item.type === "post").length;
13
const momentsCount = archiveList.filter(item => item.type === "moment").length;
14
const bangumiCount = archiveList.filter(item => item.type === "bangumi").length;
15
const lifeCount = archiveList.filter(item => item.type === "life").length;
16
const totalCount = postsCount + momentsCount + bangumiCount + lifeCount;
17
---
18

19
<MainGridLayout title={i18n(I18nKey.archive)}>
20
      <!-- 统计信息 -->
21
    <div class="card-base px-8 py-6 mb-6">
22
        <div class="flex flex-wrap gap-6 justify-center text-center">
23
            <div class="flex flex-col">
24
                <span class="text-3xl font-bold text-amber-500">{postsCount}</span>
25
                <span class="text-sm text-30 mt-1">{i18n(I18nKey.postList)}</span>
26
            </div>
27
            <div class="w-px bg-neutral-200 dark:bg-neutral-700"></div>
28
            <div class="flex flex-col">
29
                <span class="text-3xl font-bold text-(--primary)">{momentsCount}</span>
30
                <span class="text-sm text-30 mt-1">{i18n(I18nKey.moments)}</span>
31
            </div>
32
            <div class="w-px bg-neutral-200 dark:bg-neutral-700"></div>
33
            <div class="flex flex-col">
34
                <span class="text-3xl font-bold text-red-500 dark:text-red-400">{bangumiCount}</span>
35
                <span class="text-sm text-30 mt-1">{i18n(I18nKey.bangumi)}</span>
36
            </div>
37
            <div class="w-px bg-neutral-200 dark:bg-neutral-700"></div>
38
            <div class="flex flex-col">
39
                <span class="text-3xl font-bold text-emerald-600 dark:text-emerald-400">{lifeCount}</span>
40
                <span class="text-sm text-30 mt-1">生活</span>
41
            </div>
42
            <div class="w-px bg-neutral-200 dark:bg-neutral-700"></div>
43
            <div class="flex flex-col">
44
                <span class="text-3xl font-bold text-(--primary)">{totalCount}</span>
45
                <span class="text-sm text-30 mt-1">总计</span>
46
            </div>
47
        </div>
48
    </div>
49
  <ArchivePanel sortedPosts={archiveList} client:only="svelte" />
50
</MainGridLayout>

展开收起

更新内容工具函数文件#

文件路径：src/utils/content-utils.ts

1
---
2
import { getCategoryUrl, getPostUrlBySlug } from "@utils/url-utils";
3
import { getDiaryList } from "@/data/diary"
4
---
5

6
export interface ArchiveItem {
7
  id: string;
8
  type: "post" | "moment" | "bangumi" | "life";
9
  link?: string;
10
  data: {
11
    title: string;
12
    published: Date;
13
    tags: string[];
14
    category?: string | null;
15
  };
16
}
17

18
export async function getArchiveList(): Promise<ArchiveItem[]> {
19
  const posts = await getCollection("posts", ({ data }) => {
20
    return import.meta.env.PROD ? data.draft !== true : true;
21
  });
22
  const diaryList = getDiaryList();
23

24
  const postItems: ArchiveItem[] = posts.map((post) => ({
25
    id: post.id,
26
    type: "post",
27
    link: getPostUrlBySlug(post.id),
28
    data: {
29
      title: post.data.title,
30
      published: post.data.published,
31
      tags: post.data.tags,
32
      category: post.data.category || null,
33
    },
34
  }));
35

36
  // 将日记数据转换为归档项
37
  const momentItems: ArchiveItem[] = diaryList.map((diary) => {
38
    let title = diary.content || "";
39
    title = title.replace(/[#*`]/g, "").trim();
40
    if (title.length > 50) title = `${title.substring(0, 50)}...`;
41
    if (!title) title = i18n(I18nKey.moments) || "日常动态";
42

43
    return {
44
      id: String(diary.id),
45
      type: "moment",
46
      link: "/diary/",
47
      data: {
48
        title: title,
49
        published: new Date(diary.date),
50
        tags: diary.tags || [],
51
        category: null,
52
      },
53
    };
54
  });
55

56
  // 空数组，用于保持接口兼容性
57
  const bangumiItems: ArchiveItem[] = [];
58
  const lifeItems: ArchiveItem[] = [];
59

60
  return [...postItems, ...momentItems, ...bangumiItems, ...lifeItems].sort((a, b) => {
61
    const timeA = a.data.published.getTime();
62
    const timeB = b.data.published.getTime();
63
    return timeB - timeA;
64
  });
65
}

展开收起

定义类型#

文件路径：src/components/controls/ArchivePanel.svelte

1
interface Post {
2
  id: string;
3
  type?: "post" | "moment" | "bangumi" | "life";
4
  link?: string;
5
  data: {
6
    title: string;
7
    tags: string[];
8
    category?: string | null;
9
    published: Date;
10
  };
11
}
12

13
{@const postLink = post.link || getPostUrlBySlug(post.id)}
14
<a
15
  href={getPostUrlBySlug(post.id)}  // [!code --]
16
    href={postLink}  // [!code ++]
17
  aria-label={post.data.title}
18
  class="group btn-plain block! h-10 w-full rounded-lg hover:text-[initial]"
19
>
20

21
<div
22
                class="w-[70%] md:max-w-[65%] md:w-[65%] text-left font-bold
23
                     group-hover:translate-x-1 transition-all group-hover:text-(--primary)
24
                     text-75 pr-8 whitespace-nowrap text-ellipsis overflow-hidden flex items-center gap-2"
25
            >
26
              {#if post.type === 'post'}
27
                <span class="px-1.5 py-0.5 text-[10px] bg-amber-500 text-white rounded-md shrink-0 uppercase tracking-wider opacity-80 font-normal">
28
                  文章
29
                </span>
30
              {:else if post.type === 'moment'}
31
                <span class="px-1.5 py-0.5 text-[10px] bg-(--primary) text-white rounded-md shrink-0 uppercase tracking-wider opacity-80 font-normal">
32
                  {i18n(I18nKey.moments) || 'Moment'}
33
                </span>
34
              {:else if post.type === 'bangumi'}
35
                <span class="px-1.5 py-0.5 text-[10px] bg-red-500 text-white rounded-md shrink-0 uppercase tracking-wider opacity-80 font-normal">
36
                  {i18n(I18nKey.bangumi) || 'Record'}
37
                </span>
38
              {:else if post.type === 'life'}
39
                <span class="px-1.5 py-0.5 text-[10px] bg-emerald-600 text-white rounded-md shrink-0 uppercase tracking-wider opacity-80 font-normal">
40
                  生活
41
                </span>
42
              {/if}
43
              <span class="truncate">{post.data.title}</span>
44
            </div>

展开收起

语言配置#

文件路径：src/i18n/i18nKey.ts

1
moments = "moments",

文件路径：src/i18n/languages/en.ts

1
[Key.moments]: "Dynamic",

文件路径：src/i18n/languages/ja.ts

1
[Key.moments]: "ダイナミック",

文件路径：src/i18n/languages/ru.ts

1
[Key.moments]: "Динамика",

文件路径：src/i18n/languages/zh_CN.ts

1
[Key.moments]: "动态",

文件路径：src/i18n/languages/zh_TW.ts

1
[Key.moments]: "動態",

给博客增加单个和全部分类页面

Tue, 02 Jun 2026 00:00:00 GMT

文件目录#

1
src/
2
├── components/
3
│   └── layout/
4
│       ├── CategoryBar.astro          [分类栏组件：显示主页、归档、分类按钮，支持横向滚动]
5
├── config/
6
│   └── navBarConfig.ts                [导航栏配置：动态生成导航链接，添加分类菜单项]
7
├── i18n/
8
│   ├── i18nKey.ts                     [国际化键定义：新增 allCategories 和 searchAlbums 键]
9
│   └── languages/
10
│       ├── en.ts                      [英文翻译文件]
11
│       ├── ja.ts                      [日文翻译文件]
12
│       ├── ru.ts                      [俄文翻译文件]
13
│       ├── zh_CN.ts                   [简体中文翻译文件]
14
│       └── zh_TW.ts                   [繁体中文翻译文件]
15
├── pages/
16
│   ├── categories.astro               [全部分类页面：显示所有分类卡片列表（新增）]
17
│   └── categories/
18
│       └── [category].astro           [单个分类详情页：显示该分类文章和标签筛选（新增）]
19
└── utils/
20
    └── url-utils.ts                   [URL工具函数：新增分类相关URL生成函数]

展开收起

创建全部分类页面#

文件路径：src/pages/categories.astro

1
---
2
import { Icon } from "astro-icon/components";
3
import MainGridLayout from "@layouts/MainGridLayout.astro";
4
import { getCategoryList } from "@/utils/content-utils";
5
import I18nKey from "@i18n/i18nKey";
6
import { i18n } from "@i18n/translation";
7

8
const categories = await getCategoryList();
9
const totalPosts = categories.reduce((sum, cat) => sum + cat.count, 0);
10
---
11

12
<MainGridLayout title={i18n(I18nKey.categories)}>
13
    <!-- 页面标题 -->
14
    <div class="card-base px-8 py-6 mb-6">
15
        <h1 class="text-2xl font-bold text-(--primary) mb-2">
16
            {i18n(I18nKey.categories)}
17
        </h1>
18
        <p class="text-30 text-sm">
19
            {i18n(I18nKey.allCategories)} · {totalPosts} {i18n(I18nKey.postsCount)}
20
        </p>
21
    </div>
22

23
    <!-- 分类卡片列表 -->
24
    <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4 mb-6">
25
        {
26
            categories.map((category, index) => (
27
                <a
28
                    href={category.url}
29
                    class="card-base p-6 flex items-center gap-4 transition-all duration-300
30
                           hover:scale-[1.02] hover:shadow-lg active:scale-[0.98]
31
                           onload-animation"
32
                    style={`animation-delay: calc(var(--content-delay) + ${index * 50}ms);`}
33
                >
34
                    <div class="flex-shrink-0 w-12 h-12 rounded-full bg-(--primary)/10 flex items-center justify-center">
35
                        <Icon
36
                            name="material-symbols:folder-open"
37
                            class="text-2xl text-(--primary)"
38
                        />
39
                    </div>
40
                    <div class="flex-1 min-w-0">
41
                        <h2 class="text-lg font-bold text-90 truncate">
42
                            {category.name}
43
                        </h2>
44
                        <p class="text-sm text-30 mt-1">
45
                            {category.count} {i18n(I18nKey.postsCount)}
46
                        </p>
47
                    </div>
48
                    <div class="flex-shrink-0">
49
                        <Icon
50
                            name="material-symbols:chevron-right-rounded"
51
                            class="text-2xl text-30 transition-transform duration-200 group-hover:translate-x-1"
52
                        />
53
                    </div>
54
                </a>
55
            ))
56
        }
57
    </div>
58

59
    <!-- 空状态 -->
60
    {
61
        categories.length === 0 && (
62
            <div class="card-base px-8 py-12 text-center">
63
                <Icon
64
                    name="material-symbols:folder-off"
65
                    class="text-5xl text-30 mx-auto mb-4"
66
                />
67
                <p class="text-30">{i18n(I18nKey.bangumiNoData)}</p>
68
            </div>
69
        )
70
    }
71
</MainGridLayout>
72

73
<style>
74
    .card-base {
75
        background: var(--card-bg);
76
        border: 1px solid var(--card-border);
77
        border-radius: var(--radius-large);
78
    }
79

80
    a.card-base:hover {
81
        border-color: var(--primary);
82
    }
83

84
    a.card-base:active {
85
        background: var(--card-bg-active);
86
    }
87
</style>

展开收起

创建单个分类详情页#

文件路径：src/pages/categories/[category].astro

1
---
2
import type { GetStaticPaths } from "astro";
3
import type { CollectionEntry } from "astro:content";
4
import { getCollection } from "astro:content";
5
import { Icon } from "astro-icon/components";
6
import PostCard from "@/components/layout/PostCard.astro";
7
import MainGridLayout from "@layouts/MainGridLayout.astro";
8
import { getCategoryList } from "@/utils/content-utils";
9
import { getTagUrl, getCategoryPageUrl, getPostUrlBySlug } from "@/utils/url-utils";
10
import I18nKey from "@i18n/i18nKey";
11
import { i18n } from "@i18n/translation";
12
import { siteConfig } from "@/config";
13

14
type PostEntry = CollectionEntry<"posts">;
15

16
interface Props {
17
  categoryName: string;
18
  posts: PostEntry[];
19
  totalPosts: number;
20
  tags: { name: string; count: number }[];
21
}
22

23
export const getStaticPaths = (async () => {
24
  const categories = await getCategoryList();
25
  const allPosts = await getCollection("posts", ({ data }) => {
26
    return import.meta.env.PROD ? data.draft !== true : true;
27
  }) as PostEntry[];
28

29
  const paths: any[] = [];
30

31
  for (const category of categories) {
32
    // 过滤该分类下的文章
33
    const categoryPosts = allPosts.filter((post) => {
34
      const postCategory = post.data.category?.trim() || "";
35
      const uncategorized = i18n(I18nKey.uncategorized).toLowerCase();
36

37
      if (!category.name || category.name.toLowerCase() === uncategorized) {
38
        // 未分类：没有分类或分类为空/未分类
39
        return !postCategory || postCategory.toLowerCase() === uncategorized;
40
      }
41
      return postCategory === category.name;
42
    });
43

44
    // 按日期排序
45
    categoryPosts.sort((a, b) => {
46
      if (a.data.pinned && !b.data.pinned) return -1;
47
      if (!a.data.pinned && b.data.pinned) return 1;
48
      return new Date(b.data.published).getTime() - new Date(a.data.published).getTime();
49
    });
50

51
    // 收集该分类下所有标签
52
    const tagCountMap: Record<string, number> = {};
53
    categoryPosts.forEach((post) => {
54
      (post.data.tags || []).forEach((tag: string) => {
55
        tagCountMap[tag] = (tagCountMap[tag] || 0) + 1;
56
      });
57
    });
58
    const tags = Object.entries(tagCountMap)
59
      .sort((a, b) => b[1] - a[1])
60
      .map(([name, count]) => ({ name, count }));
61

62
    paths.push({
63
      params: { category: category.name },
64
      props: {
65
        categoryName: category.name,
66
        posts: categoryPosts,
67
        totalPosts: categoryPosts.length,
68
        tags,
69
      },
70
    });
71
  }
72

73
  return paths;
74
}) satisfies GetStaticPaths;
75

76
const { categoryName, posts, totalPosts, tags } = Astro.props;
77

78
// 解码分类名称
79
const decodedCategory = decodeURIComponent(categoryName);
80

81
let delay = 0;
82
const interval = 50;
83

84
const masonryEnabled = siteConfig.postListLayout.grid.masonry;
85
const columnWidth = siteConfig.postListLayout.grid.columnWidth || 280;
86

87
const defaultLayout = siteConfig.postListLayout.defaultMode || "list";
88
const mobileDefaultLayout =
89
  siteConfig.postListLayout.mobileDefaultMode || defaultLayout;
90
const initialLayoutClass =
91
  defaultLayout === "grid"
92
    ? "post-grid-auto grid-mode"
93
    : "flex flex-col gap-4 md:gap-4 list-mode";
94
---
95

96
<MainGridLayout title={`${decodedCategory} - ${i18n(I18nKey.categories)}`}>
97
    <!-- 面包屑导航 -->
98
    <div class="card-base px-6 py-4 mb-6">
99
        <nav class="flex items-center gap-2 text-sm text-30">
100
            <a href="/" class="hover:text-(--primary) transition-colors">
101
                <Icon name="material-symbols:home" class="inline-block align-middle" />
102
            </a>
103
            <span class="opacity-50">/</span>
104
            <a href={getCategoryPageUrl()} class="hover:text-(--primary) transition-colors">
105
                {i18n(I18nKey.categories)}
106
            </a>
107
            <span class="opacity-50">/</span>
108
            <span class="text-90 font-medium">{decodedCategory}</span>
109
        </nav>
110
    </div>
111

112
    <!-- 分类标题 -->
113
    <div class="card-base px-8 py-6 mb-6">
114
        <div class="flex items-center gap-4">
115
            <div class="w-14 h-14 rounded-full bg-(--primary)/10 flex items-center justify-center flex-shrink-0">
116
                <Icon name="material-symbols:folder-open" class="text-3xl text-(--primary)" />
117
            </div>
118
            <div>
119
                <h1 class="text-2xl font-bold text-90">{decodedCategory}</h1>
120
                <p class="text-sm text-30 mt-1">
121
                    {totalPosts} {i18n(I18nKey.postsCount)}
122
                </p>
123
            </div>
124
        </div>
125
    </div>
126

127
    <!-- 标签筛选区域 -->
128
    {
129
        tags.length > 0 && (
130
            <div class="card-base px-6 py-5 mb-6">
131
                <div class="flex items-center gap-3 mb-3">
132
                    <Icon name="material-symbols:label" class="text-lg text-(--primary)" />
133
                    <span class="text-sm font-medium text-90">{i18n(I18nKey.tags)}</span>
134
                    <span class="text-xs text-30">({tags.length})</span>
135
                </div>
136
                <div class="flex flex-wrap gap-2">
137
                    {tags.map((tag: { name: string; count: number }) => (
138
                        <a
139
                            href={getTagUrl(tag.name)}
140
                            class="btn-regular px-3 py-1.5 text-sm rounded-md
141
                                     transition-all duration-200
142
                                     hover:scale-105 hover:bg-(--primary)/20
143
                                     active:scale-95"
144
                        >
145
                            #{tag.name}
146
                            <span class="ml-1 text-xs opacity-60">({tag.count})</span>
147
                        </a>
148
                    ))}
149
                </div>
150
            </div>
151
        )
152
    }
153

154
    <!-- 文章列表 -->
155
    <div
156
        id="post-list-container"
157
        class={`transition-all duration-500 ease-in-out mb-4 ${initialLayoutClass}`}
158
        data-default-layout={defaultLayout}
159
        data-mobile-default-layout={mobileDefaultLayout}
160
        data-masonry-enabled={masonryEnabled}
161
        data-column-width={columnWidth}
162
        style={`--post-card-min-width: ${columnWidth}px;`}
163
    >
164
        {
165
            posts.length > 0 ? (
166
                posts.map((entry: PostEntry, index: number) => (
167
                    <PostCard
168
                        entry={entry}
169
                        title={entry.data.title}
170
                        tags={entry.data.tags}
171
                        category={entry.data.category}
172
                        published={entry.data.published}
173
                        updated={entry.data.updated}
174
                        url={getPostUrlBySlug(entry.id)}
175
                        image={entry.data.image}
176
                        description={entry.data.description}
177
                        draft={entry.data.draft}
178
                        pinned={entry.data.pinned}
179
                        password={!!entry.data.password}
180
                        loading={index < 2 ? "eager" : "lazy"}
181
                        class:list="onload-animation post-card-item"
182
                        style={`animation-delay: calc(var(--content-delay) + ${delay++ * interval}ms);`}
183
                    />
184
                ))
185
            ) : (
186
                <div class="card-base px-8 py-12 text-center w-full">
187
                    <Icon name="material-symbols:article" class="text-5xl text-30 mx-auto mb-4" />
188
                    <p class="text-30">{i18n(I18nKey.bangumiNoData)}</p>
189
                </div>
190
            )
191
        }
192
    </div>
193
</MainGridLayout>
194

195
<script is:inline define:vars={{ defaultLayout, mobileDefaultLayout, columnWidth }}>
196
    (function() {
197
        const savedLayout = localStorage.getItem('postListLayout');
198
        const effectiveDefault = window.innerWidth < 780 ? mobileDefaultLayout : defaultLayout;
199
        const effectiveLayout = window.innerWidth < 380 ? 'grid' : (savedLayout || effectiveDefault);
200

201
        if (effectiveLayout !== defaultLayout) {
202
            const container = document.getElementById('post-list-container');
203

204
            if (container) {
205
                container.style.transition = 'none';
206
                container.classList.remove('list-mode', 'grid-mode', 'post-grid-auto', 'flex', 'flex-col', 'gap-4', 'md:gap-4');
207

208
                if (effectiveLayout === 'grid') {
209
                    container.classList.add('grid-mode', 'post-grid-auto');
210
                } else {
211
                    container.classList.add('list-mode', 'flex', 'flex-col', 'gap-4', 'md:gap-4');
212
                }
213

214
                container.offsetHeight;
215
                container.style.transition = '';
216
            }
217
        }
218
    })();
219
</script>
220

221
<script>
222
    function initLayout() {
223
        const postListContainer = document.getElementById("post-list-container");
224
        if (!postListContainer) return;
225

226
        const savedLayout = localStorage.getItem("postListLayout");
227
        const defaultLayout =
228
            postListContainer.getAttribute("data-default-layout") || "list";
229
        const mobileDefaultLayout =
230
            postListContainer.getAttribute("data-mobile-default-layout") || defaultLayout;
231

232
        const effectiveDefault = window.innerWidth < 780 ? mobileDefaultLayout : defaultLayout;
233
        let currentLayout = savedLayout || effectiveDefault;
234

235
        if (window.innerWidth < 380) {
236
            currentLayout = "grid";
237
        }
238

239
        updatePostListLayout(currentLayout);
240
    }
241

242
    function updatePostListLayout(layout: string) {
243
        const postListContainer = document.getElementById("post-list-container");
244
        if (!postListContainer) return;
245

246
        const isCurrentGrid = postListContainer.classList.contains("grid-mode");
247
        const isCurrentList = postListContainer.classList.contains("list-mode");
248
        const currentLayout = isCurrentGrid ? "grid" : (isCurrentList ? "list" : null);
249

250
        const masonryEnabled = postListContainer.getAttribute("data-masonry-enabled") === "true";
251

252
        const applyClasses = () => {
253
            postListContainer.classList.remove("list-mode", "grid-mode", "post-grid-auto");
254
            if (layout === "grid") {
255
                postListContainer.classList.add("grid-mode");
256
                postListContainer.classList.remove("flex", "flex-col");
257
                if (masonryEnabled) {
258
                    postListContainer.classList.remove("post-grid-auto");
259
                    applyMasonryLayout();
260
                } else {
261
                    postListContainer.classList.add("post-grid-auto");
262
                    resetMasonryLayout();
263
                }
264
            } else {
265
                postListContainer.classList.add("list-mode");
266
                postListContainer.classList.add("flex", "flex-col", "gap-4", "md:gap-4");
267
                postListContainer.classList.remove("post-grid-auto");
268
                resetMasonryLayout();
269
            }
270
        };
271

272
        if (!currentLayout) {
273
            applyClasses();
274
            return;
275
        }
276

277
        if (currentLayout === layout) {
278
            if (layout === "grid" && masonryEnabled) {
279
                applyMasonryLayout();
280
            }
281
            return;
282
        }
283

284
        postListContainer.classList.add("layout-switching");
285

286
        setTimeout(() => {
287
            applyClasses();
288

289
            requestAnimationFrame(() => {
290
                postListContainer.classList.remove("layout-switching");
291
            });
292
        }, 200);
293
    }
294

295
    function resetMasonryLayout() {
296
        const container = document.getElementById("post-list-container");
297
        if (!container) return;
298

299
        container.style.height = "";
300
        container.style.position = "";
301
        container.style.display = "";
302

303
        const items = container.querySelectorAll(".post-card-item");
304
        items.forEach((item) => {
305
            // @ts-ignore
306
            item.style.position = "";
307
            // @ts-ignore
308
            item.style.top = "";
309
            // @ts-ignore
310
            item.style.left = "";
311
            // @ts-ignore
312
            item.style.width = "";
313
        });
314
    }
315

316
    function applyMasonryLayout() {
317
        const container = document.getElementById("post-list-container");
318
        if (!container) return;
319

320
        const masonryEnabled = container.getAttribute("data-masonry-enabled") === "true";
321
        if (!masonryEnabled) return;
322

323
        if (!container.classList.contains("grid-mode")) return;
324

325
        const items = Array.from(container.querySelectorAll(".post-card-item"));
326
        if (items.length === 0) return;
327

328
        const gap = 16;
329
        const columnWidth = parseInt(container.getAttribute("data-column-width") || "280");
330

331
        container.style.position = "relative";
332
        container.style.display = "block";
333

334
        const containerWidth = container.offsetWidth;
335
        const colCount = Math.max(1, Math.floor((containerWidth + gap) / (columnWidth + gap)));
336
        const itemWidth = (containerWidth - (colCount - 1) * gap) / colCount;
337

338
        const colHeights = new Array(colCount).fill(0);
339

340
        items.forEach((item) => {
341
            const colIndex = colHeights.indexOf(Math.min(...colHeights));
342
            // @ts-ignore
343
            item.style.position = "absolute";
344
            // @ts-ignore
345
            item.style.width = `${itemWidth}px`;
346
            // @ts-ignore
347
            item.style.setProperty('height', 'auto', 'important');
348

349
            // @ts-ignore
350
            const height = item.offsetHeight;
351
            const top = colHeights[colIndex];
352
            const left = colIndex * (itemWidth + gap);
353

354
            // @ts-ignore
355
            item.style.top = `${top}px`;
356
            // @ts-ignore
357
            item.style.left = `${left}px`;
358

359
            colHeights[colIndex] += height + gap;
360
        });
361

362
        container.style.height = `${Math.max(...colHeights)}px`;
363
    }
364

365
    document.addEventListener("DOMContentLoaded", function () {
366
        setTimeout(initLayout, 50);
367

368
        const imgs = document.querySelectorAll('#post-list-container img');
369
        imgs.forEach(img => {
370
            // @ts-ignore
371
            if(img.complete) return;
372
            img.addEventListener('load', () => {
373
                applyMasonryLayout();
374
            });
375
        });
376
    });
377

378
    document.addEventListener("visibilitychange", function () {
379
        if (!document.hidden) {
380
            setTimeout(initLayout, 100);
381
        }
382
    });
383

384
    window.addEventListener("layoutChange", function (event) {
385
        // @ts-ignore
386
        const newLayout = event.detail.layout;
387
        const postListContainer = document.getElementById("post-list-container");
388
        if (!postListContainer) return;
389

390
        updatePostListLayout(newLayout);
391
    });
392

393
    let resizeTimeout: any;
394
    window.addEventListener("resize", function () {
395
        clearTimeout(resizeTimeout);
396
        resizeTimeout = setTimeout(function () {
397
            initLayout();
398
        }, 250);
399
    });
400

401
    document.addEventListener("astro:page-load", function () {
402
        setTimeout(initLayout, 50);
403

404
        const imgs = document.querySelectorAll('#post-list-container img');
405
        imgs.forEach(img => {
406
            // @ts-ignore
407
            if(img.complete) return;
408
            img.addEventListener('load', () => {
409
                applyMasonryLayout();
410
            });
411
        });
412
    });
413

414
    document.addEventListener("astro:after-swap", function () {
415
        setTimeout(initLayout, 50);
416
    });
417

418
    setTimeout(initLayout, 0);
419
</script>
420

421
<style is:global>
422
    .post-grid-auto {
423
        display: grid;
424
        grid-template-columns: repeat(auto-fill, minmax(var(--post-card-min-width, 320px), 1fr));
425
        gap: 1rem;
426
    }
427

428
    @media (max-width: 767px) {
429
        .list-mode .post-meta-root {
430
            transform: scale(0.72) !important;
431
            transform-origin: top left !important;
432
            margin-bottom: 0.25rem !important;
433
            width: 139% !important;
434
        }
435
        .list-mode :global(.post-meta) {
436
            margin-bottom: 0.25rem !important;
437
            gap: 0.25rem !important;
438
        }
439
    }
440
</style>
441

442
<style>
443
    #post-list-container {
444
        transition: opacity 0.5s cubic-bezier(0.4, 0, 0.2, 1),
445
                    transform 0.5s cubic-bezier(0.4, 0, 0.2, 1);
446
    }
447

448
    #post-list-container > :global(*) {
449
        transition: opacity 0.4s cubic-bezier(0.4, 0, 0.2, 1),
450
                    transform 0.4s cubic-bezier(0.4, 0, 0.2, 1);
451
    }
452

453
    #post-list-container {
454
        transition: opacity 0.2s ease-out, transform 0.2s ease-out;
455
    }
456

457
    #post-list-container.layout-switching {
458
        opacity: 0;
459
        transform: translateY(10px);
460
    }
461

462
    #post-list-container.grid-mode :global(.post-card-wrapper) {
463
        flex-direction: column-reverse !important;
464
    }
465

466
    #post-list-container.grid-mode :global(.post-card-image) {
467
        width: 100% !important;
468
        position: relative !important;
469
        top: auto !important;
470
        right: auto !important;
471
        bottom: auto !important;
472
        border-radius: var(--radius-large) var(--radius-large) 0 0 !important;
473
    }
474

475
    #post-list-container.grid-mode :global(.post-card-content) {
476
        width: 100% !important;
477
        padding: 1rem !important;
478
    }
479

480
    #post-list-container.grid-mode :global(.no-cover .post-card-content) {
481
        padding-right: 4.5rem !important;
482
    }
483

484
    #post-list-container.grid-mode :global(.post-card-title) {
485
        font-size: 1.35rem !important;
486
        line-height: 1.75rem !important;
487
        margin-bottom: 0.5rem !important;
488
    }
489

490
    #post-list-container.grid-mode :global(.post-card-title::before) {
491
        display: none !important;
492
    }
493

494
    #post-list-container.grid-mode :global(.post-meta) {
495
        margin-bottom: 0.5rem !important;
496
        gap: 0.5rem !important;
497
    }
498

499
    #post-list-container.grid-mode :global(.post-meta .text-xl) {
500
        font-size: 1rem !important;
501
        line-height: 1.25rem !important;
502
    }
503

504
    #post-list-container.grid-mode :global(.meta-icon) {
505
        width: 1.5rem !important;
506
        height: 1.5rem !important;
507
        margin-right: 0.25rem !important;
508
    }
509

510
    #post-list-container.grid-mode :global(.post-meta .text-sm) {
511
        font-size: 0.75rem !important;
512
        line-height: 1rem !important;
513
    }
514

515
    #post-list-container.grid-mode :global(.post-meta .pinned-btn) {
516
        padding: 0.25rem 0.375rem !important;
517
    }
518
</style>

展开收起

创建URL工具函数#

文件路径：src/utils/url-utils.ts

1
export function getCategoryUrl(category: string | null): string {
2
  if (
3
    !category ||
4
    category.trim() === "" ||
5
    category.trim().toLowerCase() === i18n(I18nKey.uncategorized).toLowerCase()
6
  )
7
    return url("/categories/uncategorized/");
8
  return url(`/categories/${encodeURIComponent(category.trim())}/`);
9
}
10

11
export function getCategoryPageUrl(): string {
12
  return url("/categories/");
13
}

更新分类栏组件#

文件路径：src/components/layout/CategoryBar.astro

1
---
2
import { url, getCategoryPageUrl } from "@/utils/url-utils";
3
const categoriesUrl = getCategoryPageUrl();
4
---
5

6
<a
7
      href={categoriesUrl}
8
      class="category-pill text-sm px-3 py-1 rounded-lg whitespace-nowrap flex-shrink-0
9
             transition-colors duration-200 flex items-center justify-center"
10
      data-category-name="__categories__"
11
    >
12
      {i18n(I18nKey.categories)}
13
      <span class="text-xs opacity-60 ml-1">{categories.length}</span>
14
</a>

导航栏配置#

文件路径：src/config/navBarConfig.ts

1
// 根据页面开关动态生成导航栏配置
2
const getDynamicNavBarConfig = (): NavBarConfig => {
3
  // 基础导航栏链接
4
  const links: (NavBarLink | LinkPreset)[] = [
5
    // 主页
6
    LinkPreset.Home,
7

8
    // 文章分类
9
    {
10
      name: "分类",
11
      url: "/categories/",
12
      icon: "material-symbols:folder-open",
13
    },
14

15
    // 归档
16
    LinkPreset.Archive,
17
  ];
18
}

展开收起

语言配置#

文件路径：src/i18n/i18nKey.ts

1
allCategories = "allCategories",

文件路径：src/i18n/languages/en.ts

1
[Key.allCategories]: "All Categories",

文件路径：src/i18n/languages/ja.ts

1
[Key.allCategories]: "すべてのカテゴリ",

文件路径：src/i18n/languages/ru.ts

1
[Key.allCategories]: "Все категории",

文件路径：src/i18n/languages/zh_CN.ts

1
  [Key.allCategories]: "全部分类",

文件路径：src/i18n/languages/zh_TW.ts

1
  [Key.allCategories]: "全部分類",

恋爱计时组件

Tue, 02 Jun 2026 00:00:00 GMT

创建组件#

文件路径：src/components/widget/RelationshipTimer.astro

1
<!-- 恋爱倒计时组件 -->
2
---
3
import WidgetLayout from "@/components/common/WidgetLayout.astro";
4
import { relationshipConfig } from "@/config/relationshipConfig";
5

6
const config = relationshipConfig;
7

8
interface Props {
9
  class?: string;
10
  style?: string;
11
}
12
const className = Astro.props.class;
13
const style = Astro.props.style;
14
---
15

16
<WidgetLayout
17
  name={config.title || "恋爱时光"}
18
  id="relationship"
19
  class={className}
20
  style={style}
21
>
22
  <div class="flex flex-col items-center p-2">
23
    <!-- 顶部名称栏 -->
24
    <div class="flex items-center justify-center gap-2 mb-4 text-sm font-medium text-neutral-600 dark:text-neutral-400">
25
      <span>{config.name1}</span>
26
      <span class="text-red-500 animate-pulse">❤️</span>
27
      <span>{config.name2}</span>
28
    </div>
29

30
    <!-- 头像和爱心 -->
31
    <div class="flex items-center justify-center gap-4 mb-6">
32
      <div class="w-16 h-16 rounded-full overflow-hidden border-2 border-white dark:border-neutral-800 shadow-md transition-transform hover:scale-110">
33
        <img src={config.avatar1} alt={config.name1} class="w-full h-full object-cover" />
34
      </div>
35
      <div class="text-2xl text-red-500 transform transition-all hover:scale-125 hover:rotate-12 cursor-pointer">
36
        ❤️
37
      </div>
38
      <div class="w-16 h-16 rounded-full overflow-hidden border-2 border-white dark:border-neutral-800 shadow-md transition-transform hover:scale-110">
39
        <img src={config.avatar2} alt={config.name2} class="w-full h-full object-cover" />
40
      </div>
41
    </div>
42

43
    <!-- 计时器 -->
44
    <div class="relationship-timer flex items-center justify-center gap-x-1 text-sm whitespace-nowrap overflow-x-auto">
45
      <span class="timer-num" data-timer-years>0</span><span class="timer-unit bg-red-400">年</span>
46
      <span class="timer-num" data-timer-months>0</span><span class="timer-unit bg-red-300">月</span>
47
      <span class="timer-num" data-timer-days>0</span><span class="timer-unit bg-blue-400">天</span>
48
      <span class="timer-num" data-timer-hours>0</span><span class="timer-unit bg-orange-400">时</span>
49
      <span class="timer-num" data-timer-minutes>0</span><span class="timer-unit bg-blue-500">分</span>
50
      <span class="timer-num" data-timer-seconds>00</span><span class="timer-unit bg-purple-400">秒</span>
51
    </div>
52
  </div>
53
</WidgetLayout>
54

55
<style>
56
  @reference "tailwindcss";
57

58
  .timer-num {
59
    @apply font-bold text-neutral-700 dark:text-neutral-200 min-w-[0rem] text-center;
60
    color: var(--primary);
61
  }
62
  .timer-unit {
63
    @apply px-1 py-0.5 rounded text-[10px] text-white font-medium shrink-0;
64
  }
65
</style>
66

67
<script is:inline define:vars={{ startDateStr: config.startDate }}>
68
  function updateRelationshipTimer() {
69
    const startDate = new Date(startDateStr);
70
    const now = new Date();
71

72
    let diff = now.getTime() - startDate.getTime();
73

74
    if (diff < 0) return;
75

76
    // 计算年月日时分秒的差值
77
    let years = now.getFullYear() - startDate.getFullYear();
78
    let months = now.getMonth() - startDate.getMonth();
79
    let days = now.getDate() - startDate.getDate();
80
    let hours = now.getHours() - startDate.getHours();
81
    let minutes = now.getMinutes() - startDate.getMinutes();
82
    let seconds = now.getSeconds() - startDate.getSeconds();
83

84
    // 处理借位逻辑
85
    if (seconds < 0) {
86
      seconds += 60;
87
      minutes--;
88
    }
89
    if (minutes < 0) {
90
      minutes += 60;
91
      hours--;
92
    }
93
    if (hours < 0) {
94
      hours += 24;
95
      days--;
96
    }
97
    if (days < 0) {
98
      const lastMonth = new Date(now.getFullYear(), now.getMonth(), 0);
99
      days += lastMonth.getDate();
100
      months--;
101
    }
102
    if (months < 0) {
103
      months += 12;
104
      years--;
105
    }
106

107
    // 更新所有实例，避免移动端和电脑端 ID 冲突
108
    const update = (attr, value) => {
109
      const elements = document.querySelectorAll(`[data-timer-${attr}]`);
110
      elements.forEach(el => {
111
        el.innerText = value;
112
      });
113
    };
114

115
    update('years', years);
116
    update('months', months);
117
    update('days', days);
118
    update('hours', hours);
119
    update('minutes', minutes);
120
    update('seconds', seconds.toString().padStart(2, '0'));
121
  }
122

123
  // 立即运行并每秒更新
124
  updateRelationshipTimer();
125
  if (!window.relationshipTimerInterval) {
126
    window.relationshipTimerInterval = setInterval(updateRelationshipTimer, 1000);
127
  }
128

129
  // 监听 Swup 页面切换
130
  document.addEventListener('swup:content:replace', updateRelationshipTimer);
131
</script>

展开收起

注册组件#

文件路径：src/components/layout/SideBar.astro

1
---
2
import RelationshipTimer from "@/components/widget/RelationshipTimer.astro";  // 引入恋爱计时组件
3
---
4

5
// 组件映射表
6
const componentMap = {
7
    <!-- 恋爱计时组件 -->
8
  relationship: RelationshipTimer,
9
} satisfies Record<WidgetComponentType, typeof Profile>;

启用组件#

文件路径：src/config/sidebarConfig.ts

右侧边栏配置

1
{
2
  type: "relationship",    // 组件类型，与 componentMap 中的 key 对应
3
  enable: true,            // 是否启用
4
  position: "top",         // 组件位置：top（固定顶部）或 sticky（粘性定位）
5
  showOnPostPage: true,    // 是否在文章详情页显示
6
},

移动端配置

1
{
2
// 组件类型：恋爱计时小组件
3
type: "relationship",
4
// 是否启用该组件
5
enable: true,
6
// 是否在文章详情页显示
7
showOnPostPage: true,
8
},

配置类型定义#

文件路径：src/types/config.ts

1
// 组件配置类型定义
2
export type WidgetComponentType =
3
  | "relationship";

双方信息配置#

文件路径：src/config/relationshipConfig.ts

1
import type { RelationshipConfig } from "../types/config";
2

3
export const relationshipConfig: RelationshipConfig = {
4
  // 恋爱开始日期
5
  startDate: "2026-01-06",
6
  // 双方名称
7
  name1: "---------TSH",
8
  name2: "CXY---------",
9
  // 双方头像
10
  avatar1: "https://re.tsh520.cn/zl/tsh.jpg",
11
  avatar2: "https://re.tsh520.cn/zl/cxy.jpg",
12
  // 小组件标题
13
  title: "我和宝宝在一起已经",
14
};

Umami 访问统计卡片

Tue, 02 Jun 2026 00:00:00 GMT

提示

本文是在博主 THW 文章：为 Fuwari 添加 Umami 访问统计卡片基础上增加了自己实践过程的一些细节，转载无需和我联系，但请注明文章来源。如果侵权之处，请联系博主进行删除，谢谢~

开始#

对于静态博客而言，了解访客来源与流量趋势是很有必要的。在不自建服务器的前提下，配置简单，功能强大的 Umami 往往是我们的首选。

然而，直接挂载 Umami 的分享外链不够直观且破坏页面一致性。本文将教你如何将 Umami 的统计数据以原生组件的形式集成到 Firefly 主题的侧边栏中，让你的博客实时展示访问数据。

Umami 访问统计卡片

准备工作#

一个已部署好的Firefly博客
无服务器部署Umami统计教程：Vercel 部署
启用Umami统计的站点

获取数据#

为了获取到图中的这些数据，我们需要启用 Umami 统计的分享 URL。

你应该会得到一个类似 https://umami.example.com/share/xxxxxxxxxxxx 格式的链接。记下这个链接，现在我们只需要它就能完成所有配置。

alt text

创建组件#

文件路径：src/components/widget/UmamiStats.astro

1
---
2
import WidgetLayout from "@/components/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 id="umami-stats" 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: 'https://umami.example.com/share/xxxxxxxxxxxx',
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>

展开收起

配置参数#

在代码文件的 script 部分，填入你的分享链接：

1
const UMAMI_CONFIG = {
2
    shareUrl: 'https://umami.example.com/share/xxxxxxxxxxxx',  // ← 这里改成你自己的
3
};

系统会自动解析 API 路径、Website ID 和验证 Token。

注册组件#

文件路径：src/components/layout/SideBar.astro

1
---
2
import UmamiStats from "@/components/widget/UmamiStats.astro";  // 引入 Umami 组件
3
---
4

5
// 组件映射表
6
const componentMap = {
7
  umamiStats: UmamiStats,
8
} satisfies Record<WidgetComponentType, typeof Profile>;

配置侧边栏#

文件路径：src/config/sidebarConfig.ts

1
{
2
    // 组件类型：Umami 统计组件
3
    type: "umamiStats",
4
    // 是否启用该组件
5
    enable: true,
6
    // 组件位置
7
    position: "top",
8
    // 是否在文章详情页显示
9
    showOnPostPage: true,
10
},

修改统计周期#

默认为所有时间，如果你想要调整浏览量统计的时间范围，可以修改 fetchUmamiStats 函数内的 startAt 参数。

常用时间周期公式（单位：毫秒）：

24小时：24 * 60 * 60 * 1000 = 86400000

最近30天：30 * 24 * 60 * 60 * 1000 = 2592000000

最近90天：90 * 24 * 60 * 60 * 1000 = 7776000000

修改示例（例如改为最近 30 天）：

1
try {
2
    const endAt = Date.now();
3
    const startAt = 0; // [!code --]
4
    const startAt = Date.now() - 2592000000; //[!code ++]
5
}

这将从 30 天前开始统计浏览量。

##配置备用数据

如果遇到 API 请求失败，全新的组件会显示你配置的备用数据以保持 UI 美观。你可以在 FALLBACK_STATS 对象中修改这些数值（默认为1000）：

1
const FALLBACK_STATS = {
2
    pageviews: 1000, // 备用总浏览量
3
    visits: 1000,    // 备用访问数
4
    visitors: 1000,  // 备用游客数
5
};

结尾#

通过以上步骤，你就成功为 Fuwari 添加了具有丰富交互感、自动解析配置且支持点击查看详情的 Umami 统计卡片。

欢迎提示组件

Tue, 02 Jun 2026 00:00:00 GMT

提示

本文是在博主年华文章：Firefly 主题 WelcomeToast 组件分析基础上增加了自己实践过程的一些细节，转载无需和我联系，但请注明文章来源。如果侵权之处，请联系博主进行删除，谢谢~

欢迎提示组件

创建组件#

文件路径：src/components/features/WelcomeToast.astro

版本说明

本节贴出的是初版实现（DOM 拼接 + Tailwind 类名）。当前组件已重构为 Web Component 版本（<welcome-toast> 自定义元素 + 作用域样式），文件路径为 src/components/features/WelcomeToast.astro，详见文末「行为变化」。

src/components/WelcomeToast.astro展开收起

1
<script>
2
    const VISIT_SESSION_KEY = 'blog_visit_flag';
3
    let hasShownToast = false;
4

5
    function hasVisitedThisSession() {
6
        try {
7
            return sessionStorage.getItem(VISIT_SESSION_KEY) === '1';
8
        } catch {
9
            return false; // 隐私模式等 sessionStorage 不可用时按未访问处理
10
        }
11
    }
12

13
    function markVisitedThisSession() {
14
        try {
15
            sessionStorage.setItem(VISIT_SESSION_KEY, '1');
16
        } catch { /* 静默跳过 */ }
17
    }
18

19
    function createWelcomeToast() {
20
        const toast = document.createElement('div');
21
        toast.id = 'welcome-toast';
22
        // Tailwind 样式控制：自动适配深色模式
23
        toast.className = 'fixed bottom-4 right-4 z-50 transform translate-y-full opacity-0 transition-all duration-500 ease-out';
24

25
        //使用 bg-white dark:bg-zinc-800 强制适配颜色
26
        toast.innerHTML = `
27
            <div class="bg-white dark:bg-zinc-800 border border-gray-200 dark:border-zinc-700 rounded-lg shadow-lg p-4 max-w-xs">
28
                <div class="flex items-start gap-3">
29
                    <div class="flex-shrink-0 text-2xl">👋</div>
30
                    <div class="flex-1 min-w-0">
31
                        <p id="welcome-message" class="text-sm font-semibold text-gray-900 dark:text-gray-100">
32
                            正在加载...
33
                        </p>
34
                        <p class="text-xs text-gray-600 dark:text-gray-400 mt-2 italic">
35
                            欢迎来到我的博客
36
                        </p>
37
                    </div>
38
                    <button
39
                        onclick="closeWelcomeToast()"
40
                        class="flex-shrink-0 text-gray-400 hover:text-gray-800 dark:hover:text-gray-200 transition-colors"
41
                        aria-label="关闭"
42
                    >
43
                        <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
44
                            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12"></path>
45
                        </svg>
46
                    </button>
47
                </div>
48
            </div>
49
        `;
50
        document.body.appendChild(toast);
51
        return toast;
52
    }
53

54
    function closeWelcomeToast() {
55
        const toast = document.getElementById('welcome-toast');
56
        if (toast) {
57
            toast.classList.add('translate-y-full', 'opacity-0');
58
            toast.classList.remove('translate-y-0', 'opacity-100');
59
            setTimeout(() => { toast.remove(); }, 500);
60
        }
61
    }
62

63
    async function fetchLocation() {
64
        const controller = new AbortController();
65
        const timer = setTimeout(() => controller.abort(), 5000);
66
        try {
67
            const response = await fetch('https://v2.xxapi.cn/api/ip', { signal: controller.signal });
68
            const data = await response.json();
69
            if (data.code === 200 && data.data) {
70
                const locationText = `你好，来自${data.data.address}的朋友`;
71
                const messageEl = document.getElementById('welcome-message');
72
                if (messageEl) messageEl.textContent = locationText;
73
            }
74
        } catch (error) {
75
            const messageEl = document.getElementById('welcome-message');
76
            if (messageEl) messageEl.textContent = '你好，欢迎来到我的博客';
77
        } finally {
78
            clearTimeout(timer);
79
        }
80
    }
81

82
    async function showWelcomeToast() {
83
        if (hasShownToast || hasVisitedThisSession()) return;
84
        const toast = createWelcomeToast();
85
        setTimeout(() => {
86
            toast.classList.remove('translate-y-full', 'opacity-0');
87
            toast.classList.add('translate-y-0', 'opacity-100');
88
        }, 100);
89
        hasShownToast = true;
90
        markVisitedThisSession();
91
        // 延迟到浏览器空闲时再请求第三方 IP 定位接口，避免与首屏关键资源抢带宽
92
        const schedule = window.requestIdleCallback || function (cb) { return setTimeout(cb, 300); };
93
        schedule(() => {
94
            // 用户已提前关闭 toast 时跳过第三方请求，避免无效调用
95
            if (document.getElementById('welcome-toast')) fetchLocation();
96
        });
97
        setTimeout(() => { closeWelcomeToast(); }, 5000);
98
    }
99

100
    function initWelcome() {
101
        // 检查是否为首页（路径为 "/" 或 "/index.html"）
102
        const isHomePage = window.location.pathname === '/' || window.location.pathname === '/index.html';
103

104
        // 只在首页显示欢迎弹窗
105
        if (isHomePage) {
106
            showWelcomeToast();
107
        }
108
    }
109

110
    if (document.readyState === 'loading') {
111
        document.addEventListener('DOMContentLoaded', initWelcome);
112
        document.addEventListener('astro:page-load', initWelcome);
113
    } else {
114
        initWelcome();
115
    }
116

117
    (window as any).closeWelcomeToast = closeWelcomeToast;
118
</script>
119

120
<style>
121
    /* 样式保持不变 */
122
    #welcome-toast { max-width: calc(100vw - 2rem); }
123
    @media (max-width: 640px) {
124
        #welcome-toast {
125
            top: auto; bottom: 1rem; left: 50%; right: auto;
126
            transform: translateX(-50%) translateY(100%);
127
            width: 90%; max-width: none;
128
            transition: transform 0.5s ease-out, opacity 0.5s ease-out;
129
        }
130
        #welcome-toast.translate-y-0 { transform: translateX(-50%) translateY(0); }
131
        #welcome-toast.translate-y-full { transform: translateX(-50%) translateY(100%); }
132
    }
133
</style>

展开收起

使用组件#

文件路径：src/layouts/MainGridLayout.astro

1
---
2
import WelcomeToast from "@components/features/WelcomeToast.astro"; //欢迎提示组件
3
---
4

5
{/* 首页欢迎提示弹窗：SSR 按首页门控，非首页不下发该脚本（组件内仍有 pathname 兜底判断） */}
6
{isHomePageCheck && <WelcomeToast />}

显示逻辑配置#

访客只在首次访问时显示欢迎弹窗（原作者）

1
    function initWelcome() {
2
        // 检查是否已显示过欢迎弹窗
3
        if (!sessionStorage.getItem(VISIT_SESSION_KEY)) {
4
            sessionStorage.setItem(VISIT_SESSION_KEY, 'true');
5
            showWelcomeToast(); // 显示欢迎弹窗
6
        }
7
    }

访客只会在首页刷新时显示，非首页刷新不会显示（正在使用）

1
    function initWelcome() {
2
        // 检查是否为首页（路径为 "/" 或 "/index.html"）
3
        const isHomePage = window.location.pathname === '/' || window.location.pathname === '/index.html';
4

5
        // 只在首页显示欢迎弹窗
6
        if (isHomePage) {
7
            showWelcomeToast();
8
        }
9
    }

访客每次刷新页面时，欢迎提示组件会重新显示，不限于文章页。

1
    function initWelcome() {
2
        // 显示欢迎弹窗
3
        showWelcomeToast();
4
    }

行为变化#

26.10.03
首页首次访问：正常弹窗，空闲时请求定位 API — 与之前一致
同会话内整页刷新首页：不再重复弹窗（新行为）
非首页：不再下载/执行 WelcomeToast 脚本（新行为）
组件内pathname 判断保留，作为兜底
26.11.02
组件重构：替换为 Web Component 实现（<welcome-toast> 自定义元素 + 作用域样式 + data-state 状态机），替代原先的 DOM 拼接方案
文件路径迁移：src/components/widget/WelcomeToast.astro → src/components/features/WelcomeToast.astro
交互变化：入场动画改为 translateY + scale 组合过渡；新增关闭按钮的悬停旋转反馈；展示时长 5s → 6.5s；延迟 850ms 后弹出
定位接口改由 serviceConfig.visitorLocationUrl 配置（默认 https://v2.xxapi.cn/api/ip），留空则只显示默认欢迎语
会话标记键换为 rain_welcome_seen_v1；命中「pure」主题时不再弹出
站点名改由 siteConfig.title 注入（data-site-name），不再硬编码

实现今日一言功能

Sat, 30 May 2026 00:00:00 GMT

创建数据文件#

文件路径：src/content/ziyuan/ 目录并添加文件：quote.md

1
---
2
title: "每日一言"
3
quotes:
4
  - text: "生活不是等待暴风雨过去，而是学会在雨中跳舞。"
5
    author: "塞维涅夫人"
6
  - text: "世界上只有一种英雄主义，就是在认清生活真相之后依然热爱生活。"
7
    author: "罗曼·罗兰"
8
---

创建组件文件#

文件路径：src/components/widget/QuoteOfTheDay.astro

1
---
2
import WidgetLayout from "@/components/common/WidgetLayout.astro";
3
import { getCollection } from "astro:content";
4

5
// 从 content/ziyuan/quote.md 读取名言数据
6
const ziyuanEntries = await getCollection("ziyuan");
7
const quoteEntry = ziyuanEntries.find((e) => e.id === "quote");
8
const quoteData = quoteEntry?.data as any;
9
const quotes = quoteData?.quotes || [];
10

11
interface Props {
12
  class?: string;
13
  style?: string;
14
}
15

16
const { class: className, style } = Astro.props;
17

18
// 使用日期作为随机种子，确保同一天显示相同的名言
19
const today = new Date();
20
const dateStr = today.toISOString().split("T")[0];
21
const seed = dateStr.split("").reduce((acc, char) => acc + char.charCodeAt(0), 0);
22
const randomIndex = seed % quotes.length;
23
const quote = quotes[randomIndex] || { text: "暂无名言", author: "" };
24
---
25

26
<WidgetLayout name="✨ 今日一言" id="quote-of-the-day" class={className} style={style}>
27
  <div class="quote-content">
28
    <blockquote class="quote-text">
29
      <span class="quote-mark">"</span>
30
      {quote.text}
31
      <span class="quote-mark">"</span>
32
    </blockquote>
33
    <cite class="quote-author">—— {quote.author}</cite>
34
  </div>
35
</WidgetLayout>
36

37
<style>
38
  .quote-content {
39
    display: flex;
40
    flex-direction: column;
41
    gap: 0.75rem;
42
    padding: 0.5rem 0;
43
  }
44

45
  .quote-text {
46
    position: relative;
47
    font-style: italic;
48
    font-size: 0.9rem;
49
    line-height: 1.6;
50
    color: var(--text-color);
51
    padding: 0 0.5rem;
52
    margin: 0;
53
  }
54

55
  .quote-mark {
56
    font-size: 1.5rem;
57
    line-height: 0;
58
    vertical-align: middle;
59
    color: var(--primary);
60
    opacity: 0.6;
61
    font-family: Georgia, serif;
62
  }
63

64
  .quote-author {
65
    display: block;
66
    text-align: right;
67
    font-size: 0.75rem;
68
    color: var(--content-meta);
69
    font-style: normal;
70
    margin-top: 0.25rem;
71
  }
72

73
  /* 深色模式优化 */
74
  :global(html.dark) .quote-text {
75
    color: var(--text-color);
76
  }
77

78
  /* 悬停效果 */
79
  :global(.quote-content:hover .quote-text) {
80
    color: var(--primary);
81
    transition: color 0.2s ease;
82
  }
83
</style>

展开收起

配置数据加载方式#

在 src/content.config.ts 配置数据加载方式：

1
const ziyuanCollection = defineCollection({
2
  loader: glob({ pattern: "**/*.md", base: "./src/content/ziyuan" }),
3
  schema: z.union([
4
    z.object({
5
      title: z.string(),
6
      content: z.string(),
7
      closable: z.boolean().optional().default(true),
8
      link: z
9
        .object({
10
          enable: z.boolean().optional().default(true),
11
          text: z.string(),
12
          url: z.string(),
13
          external: z.boolean().optional().default(false),
14
        })
15
        .optional(),
16
      quotes: z.undefined().optional(),
17
    }),
18
    z.object({
19
      title: z.string(),
20
      quotes: z.array(
21
        z.object({
22
          text: z.string(),
23
          author: z.string(),
24
        })
25
      ),
26
      content: z.undefined().optional(),
27
      closable: z.undefined().optional(),
28
      link: z.undefined().optional(),
29
    }),
30
  ]),
31
});
32

33
export const collections = {
34
  ziyuan: ziyuanCollection,
35
};

展开收起

注册组件#

文件路径：src/components/layout/SideBar.astro

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

添加到组件映射表：

1
const componentMap = {
2
  quoteOfTheDay: QuoteOfTheDay,  // 添加这一行
3
};

侧边栏配置#

文件路径：src/config/sidebarConfig.ts

添加到右侧边栏

1
rightComponents: [
2
  {
3
    type: "quoteOfTheDay",  // 必须与 componentMap 的 key 一致
4
    enable: true,           // true = 启用，false = 禁用
5
    position: "sticky",        // "top" = 固定顶部，"sticky" = 粘性定位
6
    showOnPostPage: true,   // 是否在文章详情页显示
7
  },
8
  // ... 其他组件
9
],

添加到移动端底部

1
mobileBottomComponents: [
2
  {
3
      // 组件类型：今日一言
4
      type: "quoteOfTheDay",
5
      // 是否启用该组件
6
      enable: true,
7
      // 是否在文章详情页显示
8
      showOnPostPage: true,
9
  },
10
  // ... 其他组件
11
],

类型定义#

文件路径：src/types/config.ts

1
export type WidgetComponentType =
2
  | "profile"
3
  | "announcement"
4
  // ... 其他类型
5
  | "quoteOfTheDay";  // 确保这一行存在

年轻的时候是旅游重要还是攒钱重要？

Thu, 30 Apr 2026 00:00:00 GMT

独特价值#

18岁时，我们揣着打工兼职存下的钱，就能在绿皮火车的硬座上熬一整夜

住青旅像回到大学宿舍般自在，和萍水相逢的陌生人聊起梦想，眼睛里都闪着光

那时的快乐很简单：有耗不尽的体力，特种兵旅行一整天，到第二天还有精力继续开启旅行

少年心气是不可再生之物，一场说走就走的旅行，一次毫不犹豫的出发，都是青春最滚烫的印记

人生有无数个夏天，却只有一次少年的烟火人间

我们只来一次，不如真诚一点，过得肆意，活成自己并永远热烈且自由

旅行心境#

或许到了30多岁，我们终于有能力选择喝着咖啡在沙滩边看日出日落、睡一觉就能抵达异国他乡的飞机，去往年轻时日思夜想的雪山

可站在山脚下的那一刻，却少了当年的激动，多了几分家里的柴米油盐和下班的疲惫

不再忙着打卡拍照发朋友圈，只想独自坐在山顶晒晒太阳发着呆

原来，最好的旅行从来不是在准备和计划中，而是在出发的那一刻

感悟人生#

大家常说：“欲买桂花同载酒，终不似少年游”

可也别忘了，“莫道桑榆晚，为霞尚满天”

人生还很长，一程有一程的风景

20岁没有完成的事情，30岁去完成也没关系；

就算是朝花夕拾，你觉得没有意义了，那也无所谓

人生于天地间，若白驹过隙，忽然而已

所以岁月不待人，及时当勉励，重在的是”诗酒趁年华”

遗憾错过#

你一生追求的东西，其实一开始就有

18岁的你想去旅行，可你囊中羞涩，止于心动

20岁的你，朋友都叫你出去玩，可你说学业要紧，止于行动

我们总说来日方长，却忘了人只活这一次

很多事情错过一次，可能就再也没有机会了；很多远方，错过一次就再也去不成了

所有的错过，最终都成为这辈子难以忘怀的遗憾；

或许等我老了，躺在床上回想起这一生，要是因为一些事而一次次错过自己的梦想与决定，那我该多懊悔啊！

出发勇气#

很多幸福和快乐都是后知后觉，当我们身在其中的时候，或许觉得并没有什么，但过了很久以后，就会开始怀念

在所有不确定的时间里，好好珍惜当下才是最珍贵的

愿你我永远有出发的勇气和说走就走的行动力，并一直朝着梦想远航