博客重构日志：Astro 6、Tailwind v4 与日报系统

2026 年 5 月，Misaka Network Blog 完成了一次迟到的集中重构。这篇文章记录主要变化和过程中踩到的坑。

为什么是现在

博客上次更新是 1 月。中间四个月，Astro 从 5 升到了 6，Tailwind CSS 从 v3 跳到了 v4，npm 的过时依赖警告越堆越长。与此同时，日常的技术碎片——配置备忘、踩坑记录、临时思路——散落在 Obsidian、编辑器草稿和浏览器标签页里，没有一个统一的归档入口。

两个需求撞在一起：升级依赖债务，顺便把日报系统落地。于是一次性推到了 main 上。

Astro 5 → 6：意料之外的顺利

Astro 6 的升级比预想中省心。官方迁移指南覆盖了几乎所有破坏性变更，content.config.ts 里的 glob loader 和 Zod schema 原封不动就能跑，内容集合 API 保持向后兼容。升级后构建产物体积略有缩减，冷启动速度有可感知的提升——没遇到什么阻力，算是本次重构里最平静的一环。

Tailwind CSS v3 → v4：耗时最长的一战

Tailwind v4 是整个升级过程中最折腾的部分。

首先是集成方式的变更。@astrojs/tailwind 这个官方集成包在 v4 发布后被标记为废弃，需要换成 @tailwindcss/vite 直接接入 Vite 管道。这意味着 Tailwind 不再是一个 Astro 插件，而是一个 Vite 插件——集成层次下移了一层，配置入口也随之改变。

然后是配置文件的迁移。v3 时代熟悉的 tailwind.config.mjs 不复存在，所有配置直接写入 CSS 文件，通过 @theme 指令声明。品牌色、自定义间距、字体栈，全部从 JavaScript 对象搬进 global.css。习惯了在 JS 里写配置的人需要适应这种「一切回到 CSS」的哲学转变。

@apply 的 !important 语法也从 ! 前缀变成了后缀，而搜索替换的时候 ! 是一个太常见的字符，正则不太好写，只能一行行肉眼确认。

最后还有一个跨平台坑。Windows 环境下执行 npm install 后，package-lock.json 会写入平台相关的 native 模块路径（比如 @rollup/rollup-linux-x64-gnu）。如果在 WSL 里再跑一次安装，锁文件会被覆盖成 Linux 版本，回到 Windows 端构建就炸了。解决方案很粗暴但有效：所有 npm 操作只允许在 Windows 端执行。

日报系统：把散落的信息归档

日报系统的核心思路很简单：用 Astro 的内容集合，新建一个独立的 daily collection。

每篇日报就是一个 Markdown 文件，frontmatter 只保留三个字段：date、summary 和 tags，正文自由发挥。路由层面对应两个页面——/daily 作为分页列表，/daily/[slug] 作为单篇详情，导航栏同步加入入口链接。列表页采用每页 30 条的分页方案，交互模式和博客文章列表保持一致。

比起维护零散的笔记文件或依赖外部工具，纳入 Astro 内容集合的好处是：搜索、标签、RSS 这些博客已有的基础设施，日报默认就能复用。

迁移到自托管

原来的 Cloudflare Pages 部署换成了 1Panel + OpenResty 自托管。CI/CD 依然是 GitHub Actions 驱动——推送 main 分支后自动构建并 rsync 到服务器。SSL 通过 Let’s Encrypt 签发，域名保持不变。整个迁移的中断时间基本在 DNS 切换的 TTL 窗口内，没有造成明显的访问中断。

一份给 AI 读的说明书

原来有一份 CLAUDE.md 给 Claude Code 用，但随着切换到 OpenCode 的多 Agent 工作流，CLAUDE.md 的适用范围变得很窄。这次重构把它升级成了 AGENTS.md——不绑定特定工具，面向所有 AI 编程助手。

内容做了系统性梳理：Tailwind v4 的迁移要点、日报系统的架构说明、npm 跨平台操作规范、还有整个内容管理系统的细节（排序逻辑的时间戳陷阱、Mermaid 渲染队列、FOUC 防护策略这些不读代码很难猜到的坑）。本质上是把开发过程中「希望 AI 一开始就知道的事情」写下来，减少后续沟通成本。

几点教训

SemVer 的主版本号变更不等于平滑升级。真正决定迁移难度的不是文档里的 breaking changes 列表，而是 peer dependencies 的错误提示——那些东西才是运行时的硬约束。

依赖升级最好在版本发布后尽早跟进。四个月的空窗听起来不长，但两个主版本叠在一起，迁移成本已经不是线性叠加了。

日报系统验证了一个简单的道理：把散落的记录收进统一的内容集合，维护成本比管理多个独立文档低得多。建立一个 schema，剩下的交给框架。写东西的门槛越低，越容易坚持。