1. Navbar.astro：客户端指令误报#

• 症状：client:only="svelte" 被识别为非法属性。
• 药方：在组件上方添加 //@ts-ignore。虽然有点暴力，但在 Astro 处理某些 Svelte 指令的类型推断时，这是最快的止损方案。

2. ArchivePanel.svelte：分类类型冲突#

• 症状：文章分类留空时解析为 null，但组件接口只允许 string。
• 药方：将接口定义中的 category?: string 修改为 category?: string | null，拥抱多样性。

3. archive.astro：必填属性缺失#

• 症状：<ArchivePanel> 突然要求必须手动传入 tags 和 categories。
• 药方：在调用处补齐 tags={[]} 和 categories={[]}。由于组件内部会通过 URL 自动抓取，传入空数组即可满足编译器的“强迫症”。

核心报错#

[postcss] The link class does not exist. If link is a custom class, make sure it is defined within a @layer directive.

弯路与教训#

起初，我尝试在 markdown.css 里加一个空的 @layer components { .link {} } 来“骗”过编译器。

• 结果：本地构建虽然过了，但推送到生产环境（Vercel/Cloudflare）后，CI 检查认为空规则集是语法错误，导致部署全线崩溃。

终极真相#

这个 .link 类属于上游主题定义的全局类，但在多线程构建时，Vite 有时会因为缓存问题先扫描了 markdown.css 却还没加载全局定义，导致“查无此人”。

最终解法：

1. 物理删除法：直接在 markdown.css 中移除 @apply link。
2. 原子化替代：用具体的 Tailwind 类名（如 text-[var(--primary)] underline）手动实现链接样式。
3. 重启大法：清理 node_modules/.vite 和 .astro 缓存。有时候，干净的 CI 环境才是最好的调试器。