把个人博客从视觉原型收口为可部署工程

一个个人博客最容易在“看起来已经完成”的阶段停住：主页能打开，文章能写，动画也会动。但只要内容增加、路径改变、搜索上线或部署环境换成 CI，隐含假设就开始暴露。本站的工程收口目标，是让视觉自由度、内容生产和上线过程都由可执行合同约束。

内容先于页面

文章与主题都是 Astro Content Collections 的一等条目。文章通过引用加入一个或多个主题，主题不是从目录名临时推断出来的标签。title、description、日期、封面、标签、主题引用、外壳、环境主题、阅读时间、索引和评论策略都进入 Schema；无效日期、未来更新时间、错误主题引用会在构建前失败。

路由由集中集成器读取 frontmatter 后注入，根据 chrome 选择唯一 dispatcher。内容目录不自己创建同名页面，因此不会出现两套 URL 权威。草稿和定时文章也在注入阶段处理，生产构建默认不包含未发布内容。

三档外壳是维护承诺

full 提供站点导航、页脚、环境粒子、文章元信息、目录、相关文章与读者控制；minimal 保留阅读所需的最小桥梁；none 只注入 SEO 和返回控件，正文组件必须自己承担布局、响应式与可访问性。

外壳档位不是视觉评分。最自由的页面反而负担最大：它不能依赖全站 prose CSS，也不能假设站点 Header 会提供焦点顺序。构建检查会验证 none 页面没有被自动塞入封面、站点导航或阅读器工具。

封面是内容资产，不是卡片装饰

封面与文章共置，并要求非空 alt、至少 1200×630、宽高比 1.5–2.2。列表、主题目录、首页重点文章和 Open Graph 都消费同一资产。缺少图片时使用 slug 派生的确定性几何封面，保证构建可重复，但正式项目文章优先使用真实界面、真实计算图或真实数据可视化。

这套规则解决了两个问题：UI 为图片预留稳定空间，内容生产也知道一篇文章何时仍缺正式素材。图片通过 Astro / Sharp 生成多尺寸版本，避免首页直接传输原图。

搜索、发现与长期增长

静态站在构建后运行 Pagefind。首页只承担入口，归档、标签页、主题和全文搜索形成互补路径；RSS、sitemap、robots、llms.txt 和 JSON-LD 则服务机器发现。链接检查扫描构建产物，防止内容迁移后留下站内死链。

首页左侧主题使用有限高度纵向滚动，内容增加时不会把页面无限拉长；右侧“继续阅读”保持较窄比例，并通过错位边距和色彩边条形成节奏差。移动端重点文章压缩为短封面、标题和入口，不把桌面 hero 生硬堆叠成长卡片。

两套主题与四种内容强调色

站点只保留 mist 与 abyss 两套环境主题。旧值在 Schema 中向这两套归一，保证历史内容不因迁移失效。文章/主题强调色则保持 aqua、coral、violet、gold 四种，并通过 postAccent 从主题关系稳定推导。

环境主题回答背景、表面、正文与环境光如何变化；内容强调色回答当前卡片或文章属于哪条阅读路径。两者分层，避免增加一个主题就复制整套环境 CSS。

粒子不是品牌替身

开场动画和背景粒子被保留，但它们读取语义 CSS 令牌、尊重 prefers-reduced-motion，并根据可见性和设备条件降低负载。粒子场的辨识度来自谱带、轨迹和内容边缘响应，而不是常见的“鼠标附近散开一团点”。

动效不能阻塞正文，也不能成为导航唯一反馈。首页重点文章的鼠标光场只在精确指针设备启用，移动端完全取消位移。

构建门禁

pnpm verify 先运行 Vitest，再执行完整构建。构建链依次包含 workspace 合同、脚本 TypeScript、内容审计、封面审计、Astro 类型检查、静态生成、Pagefind、产物合同、站内链接和性能预算。

这意味着“能在开发服务器看到”不是完成条件。所有新主题都必须进入 sitemap，所有文章引用都必须存在，默认封面和真实封面都要被产物检查识别，关键页面还会进入 Playwright 桌面/移动端回归。

Cloudflare Pages 部署方案

生产部署采用静态 dist/。deploy:check 核对站点 URL、公开环境变量、分析与评论配置；deploy:prepare 再检查 Cloudflare 项目配置。预览与生产命令分别指向独立分支/环境，CI 在部署前重复执行 verify。

需要人工完成的只剩外部状态：创建或选择 Cloudflare Pages 项目，配置 PUBLIC_SITE_URL、可选分析与评论变量，在仓库 Secret 中写入 API Token 和 Account ID，再绑定域名。部署文档、生产检查表、回滚方式与响应头已经进入仓库；密钥不会写入内容或构建产物。

仍然应继续做的事

真实上线后要用生产域名复查 canonical、分享卡、Pagefind 中文结果、CSP 与缓存头；用 WebPageTest 或浏览器性能记录替代仅靠构建体积推断；定期抽查外部链接与评论服务；新增大型主题时为交互模块建立独立视觉测试。

工程完备不是把待办清零，而是让剩余工作拥有明确触发条件、责任边界和验证方法。对于个人站，这比再加一套主题或一个炫酷组件更接近长期可维护。