2026/05/11 basil/personal-homepage commit: afa01ce2..afa01ce2

变更摘要：减少 Seafile 资源清单因端点配置产生的大量无用 diff

提交: afa01ce2
日期: 2026-05-11
仓库: personal-homepage
变更类型: 代码重构（TypeScript 脚本） + 配置更新
影响范围: 4 个文件，+149/-31

背景与动机

有一类很烦人的 diff 一直存在：Seafile 服务的访问地址偶尔会变，比如测试环境到生产环境 IP 不一样，或者域名切了。过去我们的做法是把完整的下载链接硬写在 JSON 清单里，像 http://106.12.111.150:8000/f/cfb44c4a96234a939ed2/?dl=1 这样。于是每次 base URL 一变动，static-assets/index.json 和 seafile/index.json 就会产生一整片纯前缀替换式的更改，真正有意义的改动反倒被淹没了。

这次把资源链接拆开：清单只保留文件唯一标识，脚本负责在生成阶段用统一的基础 URL 拼出完整链接，这样配置变化时 diff 会干净很多。

改动内容

1. 脚本侧：引入 baseUrl 拼接逻辑

scripts/fetch-seafile.ts
原本输出清单时直接用 resource.url 写入 JSON，现在改成 resolveResourceUrl(resource.url, input.config.baseUrl) 生成完整下载链接。核心变化是把与环境绑定的部分集中到一个 config.baseUrl，不再跟每个资源条目耦合。
scripts/sync-static-assets.ts
把内部模型从 url: string 拆成 source: string（文件标识，如图片 ID）和 seafileBaseUrl: string，生成最终链接时才去拼接，不再保存一长串带 IP 和查询参数的地址。

2. 配置清单：URL 瘦身

src/content/static-assets/index.json
所有项目的 url 从原来的 http://ip:port/f/xxxx?dl=1 改成了纯文件 ID，比如 "cfb44c4a96234a939ed2"。拼接逻辑彻底从数据里抽走。
src/content/seafile/index.json
顺带新增了一个下载条目（basil/vampire-like），保持结构和其他资源一致。

决策权衡

为什么在脚本生成时拼接，而不是构建时用环境变量注入，或者运行时在页面里拼？

这点是从“页面是纯静态的”这个前提推导出来的。personal-homepage 是构建时一次性生成的静态站点，没有动态服务端，产出的 HTML/JSON 直接拿去用。如果把拼接放到运行时，就要求前端 JS 能感知 baseUrl 并动态拼接，相当于把环境信息漏进了静态页面里，违背了“尽量把动态部分从页面抽离”的原则。现在把链路控制在脚本这一层，构建时就把完整链接敲死，页面拿到的是直接可用的结果，干净且不会因环境切换在客户端再出意外。

单点 `config.baseUrl` 会不会一坏全坏？考虑过多实例支持吗？

确实，config.baseUrl 一但写错，所有链接会集体 404。不过在我看来这反而是个优点——要么全站正常，要么一起挂掉，故障特征非常明显，一眼就能定位到配置问题。最怕的是某些链接挂了、另一些正常，那样排查起来要逐个比对，反而更容易漏。所以目前完全不担心单点这个特性，也不打算支持多 Seafile 实例或多 baseUrl 的场景。保持简单，出问题时爆炸半径大但排查路径短，划算。

消费端适配情况

将 static-assets 的 URL 改成了纯 ID 后，前端展示和下载触发逻辑也已经同步更新了拼接方式，目前没有发现遗漏或 404。引用资源的地方都统一使用了新的拼接函数，和脚本侧思路保持一致，暂时没看到没覆盖的角落。

后续关注

确认各个环境（本地、测试、生产）的 config.baseUrl 在脚本执行时都被正确注入，避免因为漏配导致批量死链。
后面或许可以在构建流程里加一个轻量校验，比如对 baseUrl 发一次 HEAD 请求，确认服务存活再继续生成，这样能在更早的阶段发现配置缺失，而不等部署后再靠“全挂了”来报警。

注：本文由模型 deepseek-v4-pro 生成（草稿与终稿同模型）。

personal-homepage Git 变更总结