项目复盘模板

项目复盘不是流水账，也不是只写「项目顺利上线」。它要把背景、目标、约束、方案、过程、问题、结果和后续行动串成一条可验证的证据链，让未来的自己或读者知道当时为什么这样选择。

用途

项目完成、版本上线或阶段结束后，整理全过程和关键决策。
记录技术方案、选型理由、实施步骤、故障和取舍。
用可量化或可观察的指标判断结果，而不是只凭感觉。
提炼可复用的经验和明确的后续行动。

放在哪里

复盘仍然是文章，放在 docs/posts/ 下。项目类复盘通常放在「技术笔记 / 项目记录」二级目录，但二级目录不是分类。

场景	目标文件	`categories`	`permalink`	公开地址
一级分类下	`docs/posts/技术笔记/10.project-review.md`	`[技术笔记]`	`/posts/技术笔记/project-review`	`https://www.baecon.cn/posts/技术笔记/project-review`
项目记录子目录	`docs/posts/技术笔记/项目记录/20.blog-refresh-review.md`	`[技术笔记]`	`/posts/技术笔记/项目记录/blog-refresh-review`	`https://www.baecon.cn/posts/技术笔记/项目记录/blog-refresh-review`

公式：

text

文件：docs/posts/<一级分类>/[<子目录>/]<slug>.md
permalink：/posts/<一级分类>/[<子目录>/]<slug>
公开地址：https://www.baecon.cn/posts/<一级分类>/[<子目录>/]<slug>

项目记录 不是第二个 category，不要写成 categories: [技术笔记, 项目记录]。如果项目记录目录需要目录入口，另外在 docs/catalog/技术笔记/项目记录.md 创建目录页。

什么时候使用

一个项目、版本或技术改造已经结束，需要系统复盘。
过程里有重要的架构选择、权衡、延期、故障或返工。
需要向上级、团队或未来的自己交代结果和后续计划。
有可记录的目标、约束、指标和行动项。

什么时候不要使用

项目仍在进行，结论和指标尚未确定。可以先写通用文章或等到阶段结束再复盘。
只是记录一套可复现的操作步骤：使用技术教程模板。
只是普通知识总结：使用通用文章模板。
只是记录配置变更、部署命令和回滚步骤：使用建站记录模板。
没有真实数据却想编造指标。没有量化数据时应诚实写「暂无量化数据」，并说明观察方式。

完整可复制文件

markdown

---
title: VitePress 博客改版复盘
description: 复盘博客首页与文章页的改版过程，说明项目目标、约束、技术方案、实施步骤、真实问题、结果指标和后续行动，并总结可复用的决策经验。
permalink: /posts/技术笔记/项目记录/blog-refresh-review
categories:
  - 技术笔记
tags:
  - 项目复盘
  - VitePress
  - 性能优化
article: true
sidebar: true
pagefind-indexed: true
comment: true
---

# VitePress 博客改版复盘

用一两句话概括项目、复盘范围和最终结论。这里写明复盘覆盖的时间段，避免读者误以为包含后续所有迭代。

## 项目背景

说明项目为什么启动：用户需求、业务背景、旧方案的问题、触发时间和相关角色。只写必要的组织信息，敏感名称要脱敏。

- 起点：旧首页文章入口分散，移动端阅读体验一般。
- 范围：首页、文章页、分类目录和搜索入口。
- 周期：2026 年 10 月至 11 月。

## 目标与约束

### 目标

- 统一首页与文章页的视觉风格。
- 让读者在两次点击内进入目标文章。
- 保持现有 URL 和旧文章可访问。
- 将构建时间控制在一个可接受的范围。

### 约束

- 只能在现有 VitePress 和 Teek 主题基础上改造。
- 上线窗口只有一天，必须可回滚。
- 不能修改已发布文章的永久链接。
- 没有专职测试人员，需要开发自测和可观察的验证项。

## 技术方案

解释候选方案、最终选择和取舍。不要只贴架构名词。

| 决策点 | 最终选择 | 理由 | 放弃的替代方案 |
|---|---|---|---|
| 首页布局 | 保留 Teek 首页，调整卡片层级 | 改动小，现有数据流可复用 | 全量重写首页组件 |
| 文章封面 | 不写 `coverImg`，优先用正文图片，其次随机 `/home/bg*.webp`；重要分享页再显式 `coverImg` | 首页卡片更多样；分享图仍可按需固定 | 全部固定同一张背景 |
| 搜索 | 保留 Pagefind 并过滤非文章页 | 与现有配置一致 | 新增独立搜索服务 |

```text
浏览器
→ VitePress 静态页面
→ Pagefind 搜索索引
→ 静态资源与图片
```

关键取舍：优先保证链接稳定和上线风险可控，而不是同时重做所有交互。若读者需要理解实现细节，可链接到相关教程或代码提交。

## 实施过程

按阶段记录实际发生的事，不要改写成理想流程。

1. 梳理旧页面和现有链接，导出不能变化的 URL。
2. 确定首页、文章页和目录页的字段规范。
3. 改造模板与示例文章，统一封面和摘要。
4. 在本地验证侧边栏、搜索、目录和移动端布局。
5. 构建产物并检查关键页面。
6. 上线后观察错误、访问和反馈。

### 时间线

| 时间 | 里程碑 | 结果 |
|---|---|---|
| 第 1 周 | 需求与现状梳理 | 确认主要问题和不可破坏的链接 |
| 第 2 周 | 页面改造与内容迁移 | 本地预览通过 |
| 第 3 周 | 构建、修复与上线 | 完成部署 |

## 问题与解决

记录真正发生过的问题、影响、根因、临时处理和最终方案。对于尚未彻底解决的问题，也要明确剩余风险。

| 问题 | 影响 | 原因 | 解决方式 | 遗留风险 |
|---|---|---|---|---|
| 需要固定分享图却未写 `coverImg` | 分享图退回站点默认图 | 首页随机封面与 SEO 分享图是两套逻辑 | 关键文章显式写真实 `coverImg` | 普通文章可继续使用随机封面 |
| 目录页新增后列表未更新 | 读者看不到新文章 | 目录数据在启动阶段扫描 | 重启开发服务器并重新构建 | 部署流程需提醒该步骤 |
| 移动端表格横向溢出 | 阅读体验变差 | 列数过多 | 精简列并使用短标签 | 长内容表格仍需人工检查 |

## 结果指标

指标必须来自实际统计或明确观察。没有真实数据时不要编造；写「未采集」并说明原因。

| 指标 | 改造前 | 改造后 | 统计口径 |
|---|---|---|---|
| 首页进入文章的平均点击次数 | 3 次 | 2 次 | 示例数据，发布前替换 |
| 移动端首页布局异常数 | 4 个已知问题 | 0 个 | 本地与线上截图检查 |
| 构建是否成功 | 偶发失败 | 连续通过 | 构建日志 |
| 旧文章可访问率 | 未统计 | 抽查通过 | 旧 URL 清单抽查 |

同时记录无法量化但重要的结果，例如维护成本、读者反馈、团队共识或后续需求变化。

## 复盘结论

回答三个问题：

1. 哪些做法值得保留？例如先锁定 URL，再调整页面结构。
2. 哪些决定如果重做会改变？例如应更早建立封面清单。
3. 哪些结论有证据，哪些只是暂时判断？不要把个人感受写成确定事实。

示例结论：本次改版证明了「先保证链接稳定，再逐步调整视觉」是有效的；但缺少自动检查，导致封面和移动端问题依赖人工发现。

## 后续行动

把经验转成可跟踪的行动，写清负责人、时间点和完成标准。公开文章中可以只写角色，不写真实姓名。

| 行动 | 负责人 | 截止时间 | 完成标准 |
|---|---|---|---|
| 为所有旧文章补齐封面 | 内容维护者 | 2026-11-30 | 抽查 100% 有可访问封面 |
| 增加构建前的链接检查 | 开发者 | 2026-12-15 | CI 能对失效内部链接报错 |
| 整理移动端表格规范 | 文档维护者 | 2026-12-15 | 模板中给出可用的替代写法 |

复制后必须修改或确认

值	位置	应该怎么改	为什么必须确认
`title` 和正文 H1	frontmatter 与 `# VitePress 博客改版复盘`	改成完全一致的真实项目复盘标题	页面只能有一个 H1，标题会进入首页、侧边栏和搜索。
`description`	frontmatter	换成 50–150 个中文字符的复盘摘要	让读者知道项目范围、结果和可获得的经验。
`date`	frontmatter	通常不要手填；文件首次 Git commit 后启动/构建会自动写入	自动写入后不要为了「更新」而改它；更新信息用 `updated`。
`permalink`	frontmatter	改成全站唯一且匹配目录的 `/posts/...` 地址	项目记录属于路径，不应导致 URL 与分类错位。
`categories`	frontmatter	只写一级分类，例如 `[技术笔记]`	二级目录「项目记录」不是分类。
`tags`	frontmatter	改成 2–5 个项目主题标签	标签要具体，避免只写「项目」或「总结」。
`coverImg`	frontmatter	通常删除以使用正文图片/随机背景；只在需要固定卡片或分享图时写真实路径	显式写后会固定，不再随机；路径必须存在。
`article`	frontmatter	保持 `true`	确保复盘进入文章区域。
`sidebar`	frontmatter	保持 `true`	让读者能访问文章导航。
`pagefind-indexed`	frontmatter	保持 `true`	复盘可以进入站内搜索；它不是访问控制。
`comment`	frontmatter	保持 `true`	普通复盘允许讨论；涉及内部信息时不要发布。
指标、问题和行动	body	换成真实数据、真实事件和可跟踪行动	不要把示例表格、示例数字或虚构原因直接发布。
截图与 alt	body	换成真实图片，alt 描述图表或界面内容	路径采用 `/images/posts/<slug>/<file>.webp`。

可选字段

字段	什么时候用	推荐值	注意
`titleTag`	想标示这是一篇复盘	`复盘`	只是标题旁短标签，不替代 tags。
`top`	复盘需要进入首页精选	`1`	真值标记，不是排名。
`sticky`	复盘需要置顶排序	`1` 或较小数字	必须是数字，越小越靠前。
`sidebarSort`	需要覆盖侧边栏顺序	`10`、`20`	优先使用文件名数字前缀。
`inHomePost`	不想让复盘进入首页主列表	省略或 `false`	会影响首页及分类/标签的 HomePost 列表，不是隐私设置。
`updated`	需要覆盖 SEO 修改时间	`YYYY-MM-DD HH:mm:ss`	通常省略，不能代替 `date`。
`author`	需要多人署名	不写；如确需覆盖，用对象 `{ name, link }`	本站默认站点作者，普通复盘不覆盖。

文章 frontmatter 字段总表

字段	类型	省略时默认	推荐值	级别	完整说明
`title`	`string`	无可用默认；不要依赖自动推导	与正文唯一 H1 完全一致	必填	页面标题，也是首页卡片、侧边栏、搜索结果和浏览器标题的来源。复制模板后必须改成真实标题，并保证正文只有一个 H1。
`description`	`string`	SEO 会回退到站点描述；首页摘要质量不可控	50–150 个中文字符，说明问题、内容与读者收益	推荐	供 SEO 描述、首页卡片摘要和分享信息使用。应写成完整的一句话或两句话，不要堆关键词，也不要直接复制标题。
`desc`	`string`	未设置	省略	可选（旧字段）	旧目录页的兼容显示字段，主要给 catalogue 页面使用；它不是 SEO 主字段，也不参与首页摘要。新文章不要写；目录页如保留 `desc`，需与 `description` 同值。
`date`	`string`	文件首次 Git commit 的作者时间；已有值保留	通常省略，不手填；需要人工指定发布时间时才覆盖	自动维护；通常不手填	文章的创建/发布时间，用于展示、首页排序、归档和 SEO 的 `datePublished`。新文章不需要写；首次 commit 后启动/构建会写入并保持稳定。
`updated`	`string`	未显式设置；SEO 修改时间由构建或最后更新时间兜底	正常省略；确实需要覆盖时再用同一日期格式	可选	只用于覆盖 SEO 的 `dateModified`，不是文章发布时间，也不能代替 `date`。除非有明确的更新日期要展示给搜索引擎，否则不要填。
`permalink`	`string`	自动插件通常跳过已有 frontmatter，不能依赖自动生成	全站唯一：`/posts/<一级分类>/[<子目录>/]<slug>`	必填	决定文章的公开 URL。本项目要求显式填写，不能包含 `.md`，不能以 `docs/` 开头，也不能与其他页面重复。
`categories`	`string[]`	自动插件通常跳过；缺省时没有可靠分类	显式写一级分类，如 `[技术笔记]`	推荐	分类归档和分类卡片使用。只写一级分类；二级目录属于路径，不是第二个分类。一篇文章通常只写一个一级分类。
`tags`	`string[]`	`[]`	2–5 个具体标签，如 `[VitePress, 部署]`	推荐	标签用于聚合主题和搜索。标签应短而具体，避免把整句话、分类名或大量近义词都写成标签。
`coverImg`	`string` 或 `string[]`	首页卡片：正文图片随机 → `/home/bg*.webp` 随机；SEO 分享图回退站点默认	需要固定封面/分享图时才写真实路径；否则省略	可选（按需）	首页卡片优先使用；文章 Banner、OG 和分享图也会读取。显式写后不再随机；路径必须真实存在；不写时分享图不会自动取正文图。
`article`	`boolean`	在 `/posts/` 下省略时按 `true` 处理	`true`	推荐	明确声明这是文章，让首页、归档、分类和标签等文章能力正常工作。教程、复盘、随笔、题解和建站记录都应显式写 `true`。
`sidebar`	`boolean`	VitePress 默认为 `true`	`true`	推荐	控制文章页是否显示左侧文章导航。本站文章应保持 `true`；只有特殊全宽页面才考虑关闭。
`sidebarSort`	`number`	使用文件名数字前缀；没有前缀时按 `9999`	省略；确需覆盖时用 `10`、`20` 这类数字	可选	覆盖该文章在侧边栏中的排序，数字越小越靠前。优先用文件名前缀排序；同时使用两种方式会增加理解和维护成本。
`pagefind-indexed`	`boolean`	`true`	`true`	推荐	控制 Pagefind 是否索引此页。文章应保持 `true`；设为 `false` 只是不进入站内搜索，并不会把页面变成私有页面。
`comment`	`boolean`	未写 `false` 时按开启处理	`true`	推荐	控制文章评论区。普通文章保持 `true`；目录页、纯功能页或含敏感信息的页面应关闭或不要发布。
`top`	`boolean 或 number`	未设置，即不进入精选	省略；只有需要首页精选时写 `1`	可选	首页「精选文章」的真值筛选标记，不是排名：写 `1` 表示入选，数字大小本身不会排序。是否显示还受首页精选数量上限影响。
`sticky`	`number`	未设置，即不置顶	省略；确需置顶时用较小数字，如 `1`	可选	置顶排序字段，数字越小越靠前。它和 `top` 分工不同：`top` 负责进入精选卡片，`sticky` 负责置顶排序。不要用 `true` 代替数字。
`inHomePost`	`boolean`	`true`	省略或显式 `true`；只有特殊文章才写 `false`	可选	设为 `false` 时会从首页、分类页和标签页等 HomePost 列表隐藏；文章的 URL、侧边栏、归档、精选和搜索等不会自动变成私有。不要把它当作隐私开关。
`inCatalogue`	`boolean`	`true`	通常省略；不想让文章出现在目录页时写 `false`	高级	目录插件扫描开关；不影响侧栏、Pagefind、首页、归档或 RSS。
`titleTag`	`string`	无标签	省略；需要短标识时用 `原创`、`教程`、`复盘`、`题解`、`记录`	可选	标题旁的小标签，只用于视觉提示，不替代分类或标签。保持 2–4 个汉字最清晰，不要塞入长句。
`author`	`object`	使用站点级作者 `Baecon`	省略，不在单篇文章覆盖	可选（不建议）	若覆盖需用 `{ name: string, link?: string }` 对象；普通文章不要填写。

高级 VitePress 字段

以下字段属于页面布局能力，不是复盘内容字段。普通项目复盘应全部省略，需要改变布局时优先调整全站配置。

字段	类型	省略时默认	推荐值	级别	完整说明
`layout`	`string 或 false`	使用 VitePress 标准文章布局	省略	高级	切换页面布局。文章模板不需要设置；目录页才固定使用 `layout: page`。初学者不要为了外观而改它。
`outline`	`false`、数字、`[number, number]` 或 `"deep"`	由 VitePress 与主题的默认大纲配置决定	省略	高级	控制右侧标题大纲。普通文章沿用站点统一配置即可，除非全站规范明确要求，否则不要逐篇覆盖。
`aside`	`boolean` 或 `"left"`	默认跟随 VitePress 文章布局	省略	高级	控制右侧辅助栏。与全站布局相关，不应由每篇文章随意切换。
`lastUpdated`	`boolean`	跟随站点 `lastUpdated: true`	省略	高级	控制页面是否显示最后更新时间。本站已统一开启，不需要在每篇文章重复设置。
`editLink`	`boolean`	跟随站点主题配置	省略	高级	控制是否显示编辑链接。它属于站点能力，不是文章内容字段。
`pageClass`	`string`	空	省略	高级	给页面根元素追加 CSS 类，只在有配套样式时使用。随意填写不会产生视觉效果。
`layoutClass`	`string`	空	省略	高级	当前项目会把它作为布局组件 class 读取，但只有配套 CSS 才有意义；普通写作不需要填写。
`head`	`array`	`[]`	省略	高级	为单个页面追加 `<head>` 标签。站点已统一生成 SEO 和分享标签，重复配置容易冲突。
`titleTemplate`	`string 或 false`	使用站点标题模板	省略	高级	覆盖浏览器标题拼接方式。除非页面有特殊 SEO 要求，否则不要覆盖全站一致性。
`autoTitle`	`boolean`	doc 布局默认允许自动注入 H1	省略；正文已手写 H1	高级	设为 `false` 可禁止自动 H1 注入。
`articleUpdate`	`boolean 或 object`	跟随站点配置，默认启用	省略	高级	设为 `false` 隐藏文章页最近更新模块。
`articleBanner`	`boolean 或 object`	跟随站点配置；本站开启	省略	高级	设为 `false` 关闭单文章 Banner；通常仅无侧栏 doc 文章生效。
`coverBgColor`	`string`	跟随站点 defaultCoverBgColor，本站为空	省略	高级	单文章 Banner 背景色覆盖；无 Banner 时不可见。
`prev`	`boolean`	`true`（有上一页时）	省略	高级	设为 `false` 隐藏上一页链接。
`next`	`boolean`	`true`（有下一页时）	省略	高级	设为 `false` 隐藏下一页链接。

catalogue、path、pageTitle 是目录页专用字段，文章模板不要填写。若需要创建分类或子目录入口，请使用目录页模板。

章节	写什么	示例
`## 项目背景`	项目起点、问题、范围、时间和角色	说明旧方案为什么不再满足需求。
`## 目标与约束`	要达成的结果、边界、不可牺牲的条件	分别写目标、约束和验收标准。
`## 技术方案`	选择、架构、关键取舍和被放弃的替代方案	用决策表写「选择 / 理由 / 放弃项」。
`## 实施过程`	真实阶段、里程碑、返工和上线过程	按时间或阶段记录，不写成理想化流程。
`## 问题与解决`	问题、影响、根因、处理方式和遗留风险	用表格或事件小结构说明。
`## 结果指标`	量化指标和不可量化但重要的结果	写清统计口径，未知就写未采集。
`## 复盘结论`	保留什么、改变什么、证据和边界	区分事实、判断和待验证假设。
`## 后续行动`	行动、负责人、截止时间和完成标准	行动必须可跟踪，不要写空泛口号。