2026/05/07 basil/personal-homepage commit: d46f69c9..530c9178

basil/personal-homepage 开发日志

这周主要围绕首页体验做了一轮打磨，顺便搭了一套前端资源同步的小机制，解决了一些此前因为部署环境差异导致的“看上去不对劲”的问题。

Gitea 活动面板：信息更清爽，时间更正常

之前 Gitea 的 feed 消息直接用原始内容展示在面板里，长又杂，可读性不好。这次在 fetch-gitea.ts 里加了一个 summarizeActivityMessage 函数，把推送、创建仓库这类事件压缩成一句简短摘要，效果和看通知列表差不多，舒服很多。同时活动条数从 3 条调到 4 条，信息量略微增加但不拥挤。

另一个长期的小别扭也一口气修掉了：全站的时间显示。组件里原本直接用运行环境的 toLocaleDateString，因为我机器时区一直是东八区，看着还好，但在部署的容器里经常变成 UTC，日志列表和 Gitea 面板上的日期就老差一天，非常影响阅读。这次新建了 src/utils/datetime.ts，硬编码使用 Asia/Shanghai 时区，输出 formatDate 和 formatDateTime 两个方法，并把日志卡片、详情页、活动面板里的日期逻辑全部替换掉。以后再也不用猜这到底是哪天的事了。

有人可能会说硬编码时区不够优雅，但说实话，这就是一个个人站，读者几乎全在 UTC+8 时区，追求抽象反而会引入不必要的复杂度。如果以后真有国际化的需要，把这里的时区选项暴露为配置项就够了。

角标图库路径修复

RandomCornerImage 组件里，之前用 fileURLToPath 从 import.meta.url 推导 public/images/gallery 的绝对路径，在某些运行或打包环境下会解析出奇奇怪怪的东西，导致随机角标图片加载失败。这一看就是典型的 Node 环境下路径陷阱。排查之后把逻辑改成直接基于当前文件所在位置的相对路径 ../../public/images/gallery，简单直接，不依赖模块 URL 转换，所有环境下都能稳定工作。

静态资源同步机制：告别“图床挂了”

这周遇到一个问题：通过 cron 定时部署时，首页有几个项目封面图显示不出来，检查日志看到网络请求超时。这些图片之前是放在一台独立文件服务上的，IP 地址一变动，或者临时网络抖动，页面就一片空白。更麻烦的是，这些资源不在仓库里，没有版本控制，出了问题只能人肉去查。

因为图片数量不多（目前就几张封面），不想为此引入 Git LFS 或扩建图床运维。权衡之后搞了一套构建时的清单式同步：在 src/content/static-assets/index.json 里维护文件列表，包含下载 URL 和目标路径，新增一个 scripts/sync-static-assets.ts 脚本，通过 npm run assets:sync 按清单把图片拉到 public/images/projects 下面。在 deploy-homepage.sh 里增加 sync_static_assets 步骤，部署前先同步资源，确保 Astro 构建时这些图片都已在本地。

这种方案的好处是不改变页面模板引用方式，图片依然是 Astro 静态资源的一部分，构建时自动 hash 并输出；缺点是部署脚本和清单路径耦合比较紧，以后清单结构变化需要同时调整脚本。但目前这规模足够了。

为了防止同步下来的图片被意外提交，.gitignore 里忽略了整个 public/images/projects，但手动把 devlog-pipeline.svg 和 gitea-activity-panel.svg 这两个自己画的图标豁免出来了。这个操作容易忘，以后要是再增加手绘原图，得记得更新豁免规则，不然可能被 git 忽略导致丢失。

临时路由提示：反代导致的“日常迷路”

这周另一个被反馈较多的问题是：偶尔访问首页会跳到奇怪的路径或直接报错。排查发现是因为当前部署阶段还在走 Nginx 反代，域名备案还没完成，某些二级路径的代理规则没跟上，导致路由异常。在问题彻底解决前，为了避免访客一头雾水，我在首页顶部加了一块 hero-notice 区域，用一句“临时访问说明”解释了当前路由可能不正常的原因，并提示正在处理中。

这就是个临时牌，硬编码在 index.astro 里，等备案下来、换成统一 Nginx 后就直接删掉。有人建议做成可配置的后台开关，但考虑这个提醒生命周期极短，做成配置项反而多余。

项目配置与个人状态更新

剩下的都是些顺手修正：

默认端口映射从 8080 改成 2000，跟现在实际部署的端口保持一致，本地开发时不用来回改环境变量。
projects/index.json 里项目名称、标签等都换成了中文，“个人主页”这个身份更明确，也把部分封面图从占位图标换成了真实的项目截图（比如 VampireLike.png）。
个人技术栈和地理位置小幅更新：我现在在长沙远程工作，所以 location 改成了 Changsha / Remote，技术栈描述也顺势调整，保持和当前状态一致。

整体来说这周改完，首页信息的准确性和可靠性提升了不止一个档次。接下来需要留意的是，临时提示在备案完成后别忘了清理，静态资源同步的清单更新流程也最好补一个简单的文档，防止未来新增封面图时忘记加条目导致链接断裂。