序栈：第一章

这不是一篇普通的站点总结，而是一份带着明确设计判断的 项目设计报告。如果把博客理解成“放文章的地方”，很多决定都会显得随意；但如果把它理解成一个持续展开的 内容系统、表达系统 与 工程系统，那么路由、搜索、SEO、封面、资源策略和文章体验，就都必须放到同一张设计图里去看。

写在前面

你可以把这一章理解成 README、架构说明、发文规范 与 演进路线 的交叉版本。它不追求把功能列满，而追求把关键判断讲透。

一、为什么“序栈”不是一个普通博客名字

很多个人博客失败，不是因为没有内容，而是因为没有结构。内容在不断增长，但阅读路径、主题层次、路由命名、搜索能力和页面协同没有跟上，于是它就会慢慢从一个站点退化成一堆文件。

“序栈”这个名字本身包含了两个判断：

1. 序 代表顺序、结构、层次与长期组织能力。
2. 栈 代表内容、页面、数据、资源与构建流程叠加起来之后形成的一套完整系统。

换句话说，这个项目从一开始就不想做成“写了就扔”的临时站点，而想做成一个能不断累积、不断被重新梳理、不断长出下一层能力的项目。

个人博客最怕的不是“功能少”，而是 今天补一个按钮、明天补一个页面、后天再补一层脚本 之后，站点开始只剩下零碎修改而没有统一方向。因此，“序栈”的第一个设计原则就是：

先把系统边界说明白，再决定每个页面该承担什么职责。

二、设计目标：到底要解决什么问题

如果设计目标不清晰，项目就会在“看起来都很有用”的功能里不断偏航。所以这一章先把目标和边界一起钉住。

2.1 核心目标矩阵

2.2 非目标也必须写进设计报告

很多看起来“以后也许能做”的东西，当前阶段其实应该明确地 不做：

• 不做复杂后台系统，发文仍以仓库为中心。
• 不做社交平台式评论体系，避免治理成本喧宾夺主。
• 不做重型前端框架改造，避免静态站点被过度客户端化。
• 不做模板式首页堆叠，优先保证文章系统本身的完成度。

三、目标用户与使用场景：谁会反复来到这个站点

站点的设计语言，不应该只对作者自己成立，也要对真实读者成立。这个博客的核心用户并不是随便路过的访客，而更像以下几类人：

真实使用场景大致有四个：

1. 作者快速发布一篇文章：只填 title、description、url、pubDatetime 和正文，就应该能完成一次高质量发布。
2. 读者按主题检索内容：通过 tags、归档和搜索弹窗，不依赖首页推荐也能完成导航。
3. 从社交平台跳转到文章详情：这要求 canonical、OG、结构化数据和封面图都足够稳定。
4. 在移动端读一篇较长技术文章：这意味着正文的字号、段距、行高、代码块密度和标题锚点都不能只是默认值。

四、信息架构：从页面集合到内容系统

表面上看，这个站点的页面种类不算多；但如果每一类页面的职责定义得足够清楚，少页面也可以构成一套稳定系统。

如果用更工程化的视角 look，这些页面其实构成了一条很清楚的内容流：

首页 -> 归档 / 标签 / 搜索 -> 文章详情页 -> 分享 / 返回 / 上下篇 -> 再次进入内容网络

这个流里最关键的不是首页，而是文章详情页。因为真正发生阅读、收藏、搜索命中、社交分享和搜索引擎收录的地方，几乎都在这里。

五、内容模型：为什么一定要把文件名和路径拆开

这个项目最关键的一条内容规则，就是 文件名服务维护，url 服务访问。

如果直接把文件名当成路由，短期内很方便，但长期问题会越来越明显：

• 文件一旦改名，旧链接稳定性就开始下降。
• 中文标题、英文 slug、SEO 关键词三者很难兼顾。
• 想做专题化路径时，文件名天然不够灵活。

所以这里采用了 frontmatter 驱动的内容模型。典型结构如下：

title: 序栈：第一章
description: 从定位、信息架构、搜索、SEO 到资源策略的完整项目设计说明。
pubDatetime: 2026-03-28T13:50:00+08:00
draft: false
unlisted: false
featured: true
tags:
  - 项目设计
  - Astro
  - MDX
url: stack-chapter-1

同时，draft 与 unlisted 两个开关也很重要，因为它们把“是否生成页面”和“是否参与公开分发”拆开了：

• draft：还在写，不应该进入任何公开环境。
• unlisted：可以访问，但 不主动参与 首页、归档、RSS 等公开分发。

六、为什么要用 MDX，而不是只停留在 Markdown

如果只是记录技术笔记，Markdown 已经足够。但如果这篇文章要同时承担“项目汇报、设计说明、规范沉淀、阅读导览”几种职责，MDX 的价值会一下子变得很明显。

6.1 MDX 在这个项目里真正解决了什么

• 它允许内容直接引入结构表达，而不是被迫把所有信息压成平铺段落。
• 它允许在长文里穿插彩色信息块、分栏卡片、状态标签、折叠说明。
• 它允许把设计报告写成既能读、又能看、还能导航的文档。
• 它允许内容写作和界面表达共用同一个文件，而不是拆成两套系统。

6.2 这一章实际用到的 MDX 能力

这篇文章本身已经用到了很多纯 Markdown 很难自然表达的东西：

• Grid 网络布局组件
• Card 多彩卡片组件
• Callout 精致旁注组件
• <details> 折叠补充说明
• 带标题的代码块
• diff 代码块和多栏结构表达

下面这段示例，基本概括了这篇文章的写法：

把它写成 <mark>长期维护系统</mark>，
后面的路由、SEO 和资源治理才有统一目标。

<Callout title="阅读提示">
  可以先读内容模型，再回来看搜索与 SEO。
</Callout>

<details>
  <summary>展开补充信息</summary>
  <p>适合放置不会打断主线叙述的说明内容。</p>
</details>

七、文章详情页、搜索、SEO 与 PWA：为什么它们必须一起设计

很多博客把这些能力拆开处理，于是结果往往是：页面能看但分享图很随意；搜索能搜但结果缺乏层级；SEO 有标题但和正文重点对不上。

这个项目选择把它们放在一起看，是因为它们共同决定了“文章是否能被找到、被读完、被转发、被记住”。

7.1 文章详情页是整个系统的中心

首页是入口，归档是目录，标签是分类，但文章详情页才是系统真正发生价值交换的地方。

7.2 搜索的真正问题不是“能搜”，而是“值不值得点”

站内搜索真正要解决的问题，是 输入后能不能快速判断哪一篇最值得点开。

因此这里的搜索设计不只关注索引能力，还关注结果是否有文章层级、摘要是否足够准、是否支持键盘导航。

搜索体验 = 索引质量 + 结果分层 + 摘要可判断性 + 跳转稳定性

7.3 SEO 不是附属品，而是内容表达的另一面

真正需要统一的是：页面标题、描述、canonical、OG 图、JSON-LD、RSS/Sitemap。

如果这些信息彼此讲的不是同一件事，搜索引擎和读者都会困惑。SEO 不是额外包装，而是内容表达在机器世界里的那一层镜像。

八、资源治理：为什么必须加防盗链解析

技术写作里大量图片来自外部平台（语雀、知乎、掘金等），直接外链会导致线上构建后无法显示或 403。

8.1 建立有边界的解析能力

1. 识别 明显存在防盗链策略的平台。
2. 改写 编译阶段自动转换图片地址。
3. 代理 由站内接口补上合理的 Header。
4. 缓存 降低重复拉取成本。

- ![示意图](https://picx.zhimg.com/example.jpg)
+ ![示意图](/api/image?url=https%3A%2F%2Fpicx.zhimg.com%2Fexample.jpg)

九、工程纪律：为什么静态博客也需要构建规则

工程纪律的目的不是搞复杂，而是把复杂度置前，让写作过程变轻。

• build:check 检查 frontmatter 完整性
• 搜索索引与构建同步
• PWA 自动生成
• README 面向实际维护需求

npm run build:check
npm run build

十、路线图：这一章之后，这个项目还会往哪走

“第一章”为后续章节留下了丰富的演进接口。

10.1 四个演进方向

• 内容层：专题化组织与系列化写作。
• 产品层：优化搜索排序与交互语言。
• 资源层：清理旧图、建立封面本地化规则。
• 工程层：增加更多构建期内容语法检查。

结语：为什么这一章必须叫“第一章”

“序栈：第一章”意味着这只是一个起点，后面还将展开关于内容组织、界面语言、搜索进阶与长期维护的深度探讨。

对我来说，“序栈”的含义从来不是把东西堆起来，而是把东西一层一层 组织起来。内容顺、页面顺、系统顺。只有这样，博客才会随着时间生长。