00｜网站开发与维护：从源码到上线的研究总索引

摘要

“会写页面”不等于“会维护网站”。一个长期运行的个人博客，至少同时包含内容模型、构建系统、路由、响应式布局、浏览器状态、数据请求、自动化测试与部署边界。本系列以本站 blog_test2 的当前源码为唯一事实依据，将这些层次拆成九个可验证的研究对象。文章不把设计选择包装成普遍真理，而是说明：本站遇到了什么问题、采用了什么方法、代码证据在哪里、如何复现验证，以及该方案还有哪些局限。

关键词： Astro；静态站点；内容集合；浏览器运行时；性能工程；持续部署

1. 研究问题与范围

本系列回答四个递进问题：

1. 一份 Markdown 为什么最终能成为可访问的网页？
2. 顶栏、左右侧栏、目录、主题与壁纸动效如何在桌面和移动端协作？
3. 外部状态请求、后台草稿和发布脚本如何避免重复工作与误操作？
4. 代码变化如何通过测试、构建和线上证据成为可维护的版本？

讨论范围是仓库中可以直接检查的实现。当前站点使用 Astro 静态输出并部署到 GitHub Pages；公开状态服务已经接入，但云端文章写入仍由 PUBLIC_CLOUD_PUBLISH_ENABLED=false 关闭。后者是重要边界：代码中存在未来能力，不代表线上已经启用。

2. 研究方法

本系列采用近似工程论文的论证链：

flowchart LR
  A[问题与约束] --> B[源码与配置证据]
  B --> C[设计方法]
  C --> D[测试与构建验证]
  D --> E[局限与后续工作]

每篇文章都尽量给出文件路径、关键数据流和可重复的检查命令。阅读者不必先掌握 Astro，但应当边读边对照 项目源码，因为工程知识最可靠的来源不是结论，而是能被复查的证据。

3. 系列阅读路线

3.1 基础结构

• 01｜静态架构与构建链：一次请求之前发生了什么：理解依赖、构建产物、base 路径和静态托管。
• 02｜内容模型、路由与发现机制：理解文章元数据如何进入分类、标签、搜索和 RSS。
• 03｜页面布局、主题与响应式边界：理解三栏布局、移动抽屉与亮暗主题。

3.2 浏览器运行时

• 04｜从手势到画面：主页壁纸动效状态机：把“丝滑”拆成输入、进度、几何和合成四个问题。
• 05｜数据请求与性能治理：解释并发池、缓存、超时、懒加载与路由清理。
• 06｜Markdown/MDX 渲染与发布流水线：追踪一篇文章从源文件到 HTML 的全过程。

3.3 维护与交付

• 07｜管理草稿、发布脚本与写入边界：区分本地草稿、Git 发布与未启用的云写入。
• 08｜测试、CI 与 GitHub Pages 部署：说明质量门禁如何阻止回归进入生产环境。
• 09｜证据驱动的核心维护方法：用真实案例说明从现象到修复再到防复发的闭环。

4. 新手如何使用本系列

第一次阅读建议按编号前进，并在每篇末尾完成“复现实验”。遇到具体问题时则可反向查找：页面找不到文章，读第 2 篇；移动端错位，读第 3 篇；动画卡顿，读第 4、5 篇；发布不确定，读第 7、8 篇。

不要直接复制某段代码。先确认自己的部署子路径、内容结构和运行时边界是否相同。本站的 /blog_test2 是 GitHub Pages 项目站点路径；把它误当成根域路径，是最常见也最隐蔽的迁移错误之一。

5. 证据基线与可重复验证

系列完成时使用以下门禁验证当前仓库：

pnpm test
pnpm run check
pnpm run build
git diff --check

这些命令分别检验行为契约、Astro/TypeScript 类型、生产构建和补丁格式。它们不能替代真实浏览器验收，但能把许多“看起来没问题”的错误提前变成明确失败。

6. 局限

本站是个人静态博客，不是通用 CMS。本文不声称它适合多人权限管理、海量实时内容或高频写入；历史性能数据也只代表记录时的设备与版本，不能直接外推到所有网络和终端。

7. 结论

网站维护的核心不是不断堆功能，而是让“内容—构建—运行—验证—发布”形成可追踪闭环。接下来的九篇文章将逐层展开这个闭环，并把每个结论落到本站真实文件与可执行验证上。