文章新增、修改、删除完整流程

这篇是操作手册。你不需要记住所有内部实现，但请严格按步骤执行：先确认文件位置，再写 frontmatter，然后启动开发服务器观察结果，最后构建、审计、预览、提交和部署。文章写错可以改，公开 URL 和提交历史却更麻烦，所以顺序很重要。

开始前的环境与约定

• 操作系统按 Windows 编写，编辑器推荐 VS Code。
• 仓库根目录是 E:\vitepress-teek-my-blog\teek-hyde，所有 pnpm 命令都要在这里执行。
• 项目使用 pnpm。第一次拉取代码后安装一次依赖，之后通常不用每次安装。
• 正式文章放 docs/posts/，目录入口放 docs/catalog/，正文图片放 docs/public/images/posts/。
• 不要编辑 docs/.vitepress/dist/、docs/.vitepress/cache/、docs/public/search-manifest.json 或 stats.html。
• 正式文章必须有显式、唯一、稳定的 permalink，不能依赖自动路由或自动补全。

本流程会用到下面这些命令。先知道它们各自负责什么，后面每一步再按需执行：

pnpm install
pnpm docs:dev
pnpm docs:build
pnpm docs:preview
pnpm docs:audit

命令	作用	什么时候运行
pnpm install	安装或补齐依赖	第一次拉代码、依赖变化、node_modules 损坏时
pnpm docs:dev	启动本地开发服务器，默认端口 5174	写作和实时检查时，可长期运行
pnpm docs:build	生成生产构建到 docs/.vitepress/dist/	提交前必须运行
pnpm docs:audit	检查构建产物的标题、描述、canonical、H1、图片 alt 和 sitemap	构建成功后运行
pnpm docs:preview	本地预览生产构建，默认端口 4173	提交前最后验收

如果终端提示找不到 pnpm，先解决 Node.js/pnpm 环境，不要继续下面的文件操作。命令的工作目录不对也会出现类似的假错误。

Part A：新增文章（20 步，不省略）

假设你要在已经存在的「技术笔记 / 项目记录」目录下新增一篇文章。如果你要新增的是目录本身，请先完成目录页完整流程，再回到这里。

1. 同步最新代码

这一步避免你在旧版本上新增文件，减少后续冲突。先切到 main，再拉取远端更新：

git switch main
git pull --rebase origin main

如果本地有未提交修改，不要在没有备份的情况下强拉。先确认这些修改是否属于你，必要时先提交到临时分支。遇到了冲突，先解决冲突再继续，不要删除陌生文件。

2. 在 VS Code 中打开仓库

打开正确目录，才能让 VS Code 的资源管理器、搜索和集成终端都指向同一个项目：

cd "E:\vitepress-teek-my-blog\teek-hyde"
code .

也可以在 VS Code 中选择「文件 → 打开文件夹」，选中上述路径。随后打开集成终端，确认提示符所在目录正确。

3. 安装依赖（通常只需一次）

依赖包括 VitePress、Teek、Pagefind、RSS 等工具。package.json 已定义脚本，pnpm-lock.yaml 锁定版本：

pnpm install

如果 node_modules 已存在且最近没人改依赖，可以跳过；但首次运行或不确定时，先执行它最稳妥。

4. 启动开发服务器

越早启动越好，这样新增文件后可以立即看到终端错误和页面变化：

pnpm docs:dev

终端会打印本地地址，默认是 http://localhost:5174/。保持这个终端运行，不要关闭；需要停止时在同一终端按 Ctrl+C。如果页面表现和刚改的文件不一致，先看终端是否仍在编译，再决定是否重启。

5. 决定文章属于哪个分类和子目录

先看现有结构，不要凭感觉新建分类：

docs/posts/技术笔记/                  # 一级分类：categories 通常写 技术笔记
docs/posts/技术笔记/项目记录/         # 二级目录：不单独写进 categories
docs/posts/生活随笔/
docs/posts/算法竞赛/

• 如果只是往已有目录加文章，直接进入下一步。
• 如果目标子目录的 docs/catalog/ 镜像页还不存在，先暂停，按目录页流程创建目录入口。
• 如果要新增一级分类，不要只建 posts 文件夹；还必须创建 catalog 页面、更新 Nav.ts 和两份 categoryOrder。
• 二级目录只影响位置和目录列表，categories 仍写一级分类，例如「技术笔记」。

6. 如有图片，先创建图片目录

文章图片应放在与 slug 对应的目录里。假设 slug 是 vitepress-deploy-guide：

New-Item -ItemType Directory -Force -Path "docs\public\images\posts\vitepress-deploy-guide"

为什么先建目录？因为 Markdown 里的 /images/posts/vitepress-deploy-guide/... 必须对应 docs/public 下的真实文件。图片放在 posts 目录里不会被当作公共静态资源，复制到文章旁边也无法通过 /images/... 访问。

暂时没有图片也可以先不建目录；但只要正文或封面引用自定义图片，就必须让目录和路径一致。

7. 创建文章文件

在已有分类下创建 NN.english-slug.md。编号用于侧边栏/搜索清单排序，英文 slug 便于维护，H1 和标题可以继续使用中文。

顶层文章示例：

New-Item -ItemType File -Force -Path "docs\posts\技术笔记\05.git-basics.md"

子目录文章示例：

New-Item -ItemType File -Force -Path "docs\posts\技术笔记\项目记录\01.vitepress-deploy-guide.md"

对应的公开地址必须单独用 permalink 决定，推荐如下：

源文件	推荐 permalink
docs/posts/技术笔记/05.git-basics.md	/posts/技术笔记/git-basics
docs/posts/技术笔记/项目记录/01.vitepress-deploy-guide.md	/posts/技术笔记/项目记录/vitepress-deploy-guide

不要创建 docs/posts/技术笔记/index.md。侧边栏和 search-manifest 都会跳过 index.md，它不会成为正常的文章条目。

8. 复制模板代码块

模板说明页在 docs/writing-guide/templates/。打开合适的页面后，复制页面中的完整代码块，而不是复制模板说明页自身的 frontmatter：

• 普通文章：通用文章模板
• 技术教程：技术教程模板
• 项目复盘：项目复盘模板
• 生活随笔：生活随笔模板
• 算法题解：算法题解模板
• 建站记录：建站记录模板

选择标准是文章的叙述结构，而不是你所在的目录。例如项目复盘可以放在技术笔记下，但用项目复盘模板会更合适。复制后要替换示例标题、日期、permalink、标签和封面，不能把示例值原样留下。

9. 填写每一个必填 frontmatter 字段

frontmatter 是两行 --- 之间的 YAML。它控制 URL、首页、侧边栏、搜索、评论和 SEO，不只是装饰性元数据。先写一个完整示例：

---
title: VitePress 部署指南
description: 从零完成 VitePress 博客构建、SEO 审计和 CNB 自动部署的实操记录。
permalink: /posts/技术笔记/项目记录/vitepress-deploy-guide
categories:
  - 技术笔记
tags:
  - VitePress
  - 部署
article: true
sidebar: true
pagefind-indexed: true
comment: true
---

逐项解释为什么必须这样写：

• title：页面的正式标题，也是浏览器标题、SEO 和侧边栏文字的重要来源。建议与正文 H1 完全一致。
• description：一句话说明文章解决什么问题。它会用于 meta description、社交分享、首页摘要或搜索摘要；不要复制标题敷衍，也不要堆关键词。
• date：不需要手填。文件第一次 Git commit 后，docs/.vitepress/article-date.ts 会读取第一次 commit 的作者时间，按 YYYY-MM-DD HH:mm:ss 自动写入。它不是 push 时间，也不是构建时间；尚未提交时 Teek 暂时用文件创建时间兜底，提交后再次启动或构建即可固化。只有在确实需要指定发布时间时才手动覆盖；手工日期建议写成带双引号的 "YYYY-MM-DD HH:mm:ss"，避免 YAML 将无时区时间解析成 UTC Date。
• permalink：真正的公开 URL，必须显式、唯一、稳定。本文示例是 /posts/技术笔记/项目记录/vitepress-deploy-guide，它以 /posts/ 开头，不含 .html。
• categories：一级分类数组，示例为「技术笔记」。它影响 /categories 汇总。约定与 docs/posts/ 的第一层目录一致；二级目录「项目记录」不要写进 categories。
• tags：具体主题标签数组。标签会进入 /tags 汇总和页面关键词。同一个概念统一大小写和拼写。
• coverImg：可选。需要固定首页卡片、文章 Banner 或社交分享图时才写，路径可用 /images/posts/<slug>/cover.webp 或仓库已有 /home/bgNN.webp。不写时首页卡片会优先随机取正文图片，再回退到 /home/bg*.webp；不写不会让卡片缺图，但 SEO 分享图会退回站点默认图。
• article：正式文章必须为 true。写成 false 会让文章被首页、分类、标签、归档、RSS 和 search-manifest 排除；它不会直接关闭左侧栏，也不会自动从目录页隐藏，侧栏看 sidebar，目录页看 inCatalogue。
• sidebar：正式文章为 true，显示文章左侧栏。不要为了「页面干净」随意关掉。
• pagefind-indexed：正式文章为 true，允许 Pagefind 建立全文索引。写成 false 后搜索不到正文。
• comment：正式文章为 true，显示评论入口；它是文章开关，不等于外部评论服务一定在线。

可选字段按需添加，不要为了「字段齐全」强行堆上：

• sidebarSort: 1：只用正整数调整侧边栏/搜索清单顺序，越小越靠前，优先级高于文件名编号。
• top: 1：进入首页精选文章候选，不是普通文章流置顶。
• sticky: 1：把文章置于按日期排序的文章流前面，不是侧边栏排序。
• inHomePost: false：文章会从首页、分类页和标签页等 HomePost 列表隐藏，但仍保留精选、归档、搜索等入口；这不是隐私开关。
• inCatalogue: false：文章不会出现在 catalogue: true 目录页的扫描列表中；侧边栏、Pagefind、首页、归档和 RSS 仍按各自开关工作。
• titleTag: 实战：在列表标题旁显示一个短徽标，不代替 tags。
• updated: 2026-12-01 10:00:00：只建议在确实有 SEO 更新时间需求时使用，不能伪造。

YAML 对缩进敏感。categories 和 tags 的短横线前要有一致的缩进；冒号后至少要有一个空格。保存后看开发服务器终端，比浏览器先报错往往更容易定位 YAML 问题。

10. 写一个 H1 和完整正文

正文第一行写 H1，文字与 title 保持一致：

# VitePress 部署指南

## 背景

说明为什么需要这篇教程，以及适用环境。

## 前置条件

列出 Node.js、pnpm、仓库路径和权限要求。

## 操作步骤

1. 安装依赖；
2. 执行构建；
3. 检查产物。

## 常见问题

记录容易失败的步骤和验证方式。

## 总结

回顾关键结论。

不要再写第二个 # 标题。二级标题从 ## 开始，依次使用 ###、####。一个页面只有一个 H1 是本站 SEO 审计的硬性检查；同时 H1 与 title 一致可以减少目录和搜索标题不一致。

11. 添加图片并写 alt

把图片文件放到第 6 步建立的目录，例如：

docs/public/images/posts/vitepress-deploy-guide/build-success.webp

在 Markdown 中使用站点根路径引用：

![VitePress 构建成功后的终端输出](/images/posts/vitepress-deploy-guide/build-success.webp)

每张图片都要有 alt。alt 应描述图片传递的信息，而不是写「截图」或「图片1」。文件名使用小写英文和连字符，避免空格、中文标点和大写大小写混用。部署平台通常区分大小写，本地能显示不代表线上也能显示。

如果希望首页卡片固定、或希望分享图使用自定义图片，才需要上传封面并写 frontmatter：

coverImg: /images/posts/vitepress-deploy-guide/cover.webp

12. 重启开发服务器，检查终端，再打开预期 URL

如果你是在开发服务器已经运行后才新增、删除、重命名或移动文件，请先停止它（终端按 Ctrl+C），再重新运行：

pnpm docs:dev

原因：createRewrites、侧边栏扫描、搜索清单和目录扫描在启动阶段读取文件系统；只靠 HMR 不能保证这些导航数据已经刷新。重启后再看终端：

• 有没有 YAML 解析错误？
• 有没有 Markdown 编译错误、YAML 解析错误或热更新失败？链接和图片是否存在需要在浏览器中手动检查。
• 页面是否已经重新编译？终端最后有没有 build 或热更新完成信息？

然后按 frontmatter 的 permalink 打开页面。本站 cleanUrls: true，所以地址不要加 .html：

顶层文章：http://localhost:5174/posts/技术笔记/git-basics
子目录文章：http://localhost:5174/posts/技术笔记/项目记录/vitepress-deploy-guide

如果 URL 变成了旧的 /pages/xxxxxx，说明该文曾使用历史随机地址或 permalink 没有被识别；回到第 9 步改成稳定 /posts/... 后重启开发服务器。如果页面 404，先核对源文件确实在 docs/posts/，再核对 URL 是否多了 .html 或路径拼写不一致。

13. 检查所有入口，而不是只看文章正文

文章能打开不代表所有联动正常。逐项检查：

• 首页出现文章卡片，标题、描述、日期、封面正确。
• 如果设置了 top，首页精选卡片出现文章；如果不需要，不要误写。
• 对应目录页 /catalog/技术笔记/项目记录 列出文章。
• 技术笔记文章左侧栏出现文章，排序符合预期。
• /categories 出现「技术笔记」下的文章。
• /tags 出现文章使用的每个标签。
• /archives 在正确年月出现文章。
• /search 能搜到正文关键词；搜索结果的目录分组正确。
• 评论区显示或按配置正常加载。
• 封面和正文图片都显示，浏览器控制台没有 404。

开发服务器的 Pagefind 索引、目录扫描或搜索清单可能存在启动时序差异。如果某项在开发环境暂时不完整，先重启开发服务器；最终以生产构建预览为准。

14. 运行生产构建

开发模式通过不等于生产构建通过。构建会处理路由、压缩、RSS、sitemap、Pagefind 索引和图片优化：

pnpm docs:build

构建输出在 docs/.vitepress/dist/。如果命令失败，先读第一条真实错误，不要先改多个文件。常见原因包括 YAML 缩进错误、frontmatter 未闭合、重复 permalink、代码围栏未闭合。注意：本站开启了 ignoreDeadLinks: true，构建不能替代链接和图片人工检查；构建产物不要手改，也不要提交。

15. 运行 SEO 审计

审计脚本读取 docs/.vitepress/dist/，检查 title、description、canonical、robots、OG 标签、H1 数量、图片 alt 属性和 sitemap。它不检查链接是否可访问、图片文件是否存在、摘要是否有实际内容，也不会区分空的 alt="" 和有意义 alt；这些需要人工复核：

pnpm docs:audit

必须在构建成功后运行。看到错误时按脚本输出的 URL 定位源文件，而不是直接修改 dist。比如审计说 H1 数量为 2，就回到文章正文删除多余的 #；审计说图片缺少 alt 属性，就回到 Markdown 图片语法补齐。即使审计通过，也要手动点击所有链接并确认图片真实加载。

16. 预览生产构建产物

开发服务器验证的是源码热更新，预览服务器验证的是即将部署的静态文件。先停止或保留 dev 终端，再开一个终端执行：

pnpm docs:preview

终端通常显示 http://localhost:4173/，以实际输出为准。重点再检查一次文章 URL、图片、首页卡片、目录页、侧边栏、分类、标签、归档、搜索、评论、RSS 和封面。生产预览正常，部署后才更可控。

预览完成后在终端按 Ctrl+C 停止。确认当前没有把预览端口当成开发端口继续调试。

17. 检查 Git 状态、差异和未跟踪图片

提交前必须知道会提交什么。尤其图片经常是新文件，git diff 默认不显示未跟踪文件：

git status
git status --short
git diff --stat
git diff

你要确认：

• 修改的文件都是本次任务需要的源文件。
• 图片以未跟踪或已修改状态出现在 docs/public/images/posts/...。
• 没有 docs/.vitepress/dist/、docs/.vitepress/cache/、docs/public/search-manifest.json 或 stats.html。
• 没有把别人的改动误加入。

如果 git status 里出现不属于你的大量修改，不要用 git add . 一把梭。先用 git diff -- <文件> 核对，必要时询问仓库负责人。

18. 按精确路径提交

只添加本篇文章和它们的图片。下面是完整示例，路径可按你的真实文件名替换：

git add "docs/posts/技术笔记/项目记录/01.vitepress-deploy-guide.md" "docs/public/images/posts/vitepress-deploy-guide"
git commit -m "docs: add vitepress deploy guide"

如果你还新增了目录页或配置，才额外加入：

git add "docs/catalog/技术笔记/项目记录.md" "docs/.vitepress/ConfigHyde/Nav.ts" "docs/.vitepress/sidebar.ts" "docs/.vitepress/search-manifest.ts"

不要用 git add -A 来省事，除非你已经逐项确认所有变更都属于本次任务。提交信息建议使用 docs: add 主题、docs: update 主题、docs: remove 主题 这类可读格式。

19. 推送到 main 并观察 CNB

git push origin main

推送后打开 CNB 构建页面，依次确认：

1. 安装依赖成功：pnpm install --frozen-lockfile。
2. 构建成功：pnpm docs:build。
3. SEO 审计成功：pnpm docs:audit。
4. EdgeOne 部署命令成功，部署目录是 ./docs/.vitepress/dist。
5. 如果流水线有知识库构建步骤，也确认它没有失败。

CNB 的实际流程定义在 .cnb.yml。不要在本地构建通过就直接宣布上线成功，部署步骤仍可能因为环境、令牌或平台配置失败。

20. 部署后的线上冒烟检查

打开正式域名 https://www.baecon.cn，不要只检查首页：

• 新文章 URL 返回 200，地址与 permalink 完全一致，没有 .html。
• 首页卡片、标题、描述、日期、封面正确。
• 目录页能看到文章，左侧栏条目可跳转。
• /categories、/tags、/archives 能找到文章。
• /search 能搜到正文，结果分组正确。
• 评论区和图片正常，移动端不溢出。
• /feed.rss 与 /sitemap.xml 包含预期内容。
• 浏览器开发者工具的 Network 中没有 404 图片或资源。

如果线上旧页面仍是旧内容，先确认 CNB 部署完成并强制刷新浏览器；如果新 URL 404，检查 permalink 和部署日志；如果旧 URL 因你改了 permalink 而 404，进入下面的链接与重定向处理。

完整可复制文章骨架

下面的文件内容可以直接作为普通文章起点。复制后至少替换标题、描述、日期、permalink、分类和标签；图片示例路径也要换成真实文件。需要固定封面时再额外写 coverImg。

---
title: 文章标题
description: 一句话说明这篇文章解决什么问题。
permalink: /posts/技术笔记/example-article
categories:
  - 技术笔记
tags:
  - 示例标签
article: true
sidebar: true
pagefind-indexed: true
comment: true
---

# 文章标题

## 背景

说明为什么要写这篇文章，以及读者需要的前置知识。

## 操作步骤

1. 准备环境；
2. 执行操作；
3. 验证结果。

## 示例图片

![示例图片说明](/images/posts/example-article/example.webp)

## 常见问题

| 问题 | 原因 | 解决方式 |
|---|---|---|
| 示例问题 | 示例原因 | 示例解决方式 |

## 总结

总结关键结论和下一步。

推荐的预期路径与 URL：

场景	源文件	permalink
顶层文章	docs/posts/技术笔记/05.git-basics.md	/posts/技术笔记/git-basics
子目录文章	docs/posts/技术笔记/项目记录/01.vitepress-deploy-guide.md	/posts/技术笔记/项目记录/vitepress-deploy-guide

文件名里的 NN. 是排序前缀，不推荐写进 permalink。permalink 使用人类可读的英文 slug，H1 和 title 可以继续使用中文。

Part B：修改已有文章

修改文章看似简单，但最容易犯两个错误：把发布日期当成「最后编辑时间」，以及发布后无意改变 permalink。按下面的顺序处理。

1. 先确认文章身份

用 VS Code 打开文章，先记下三件事：

• frontmatter 中的 permalink，这是公开身份；
• 文件所在的分类和子目录；
• 当前是否有未提交的修改。

git status

如果 permalink 是旧的 /pages/xxxxxx，先把这篇当作结构修复：改成预期的 /posts/...，再继续内容编辑。如果文章尚未公开发布，改 permalink 风险较低；已经发布则按第 6 步处理。

2. 安全的标题、描述和正文修改

改动	要同步修改	影响
文章标题	frontmatter title 和正文唯一 H1	浏览器标题、侧边栏、目录/搜索标题、SEO
摘要	frontmatter description	meta description、首页卡片摘要、社交分享
正文段落	只改正文	Pagefind 下次构建后更新搜索内容
加二级标题	正文 ##	右侧大纲和搜索定位会更新
改文件名	非必要不做；要改就用 git mv	可能影响目录排序和 Git 历史，不一定改变 URL

title 是元数据，H1 是正文可见标题。两者可以技术上不同，但本站推荐保持一致。如果只改 H1 不改 title，浏览器标题和页面标题会不一致；如果只改 title 不改 H1，读者看到的文章标题仍是旧的。改标题时同时搜索其他页面有没有手写旧链接。

3. 修改分类和标签

• categories 应与文章所在的一级目录保持一致。若只改 categories 不移动文件，文章物理位置和分类归属会不一致，目录页和分类页也可能对不上。
• 如果要真正更换一级分类，应同时移动文件、更新 categories、更新 permalink（推荐）并同步导航/旧链接。
• 修改 tags 会影响 /tags 汇总和关键词。删除一个标签前，确认没有其他文章也使用它。
• 分类名和标签名不要用近义词制造重复，例如同时存在「部署」「部署记录」「Deploy」。

修改后打开 /categories、/tags 和对应目录页，确认文章从旧分类消失、在新分类出现。开发服务器可能缓存扫描结果，异常时重启。

4. 替换封面和正文图片

新图片仍放在：

docs/public/images/posts/<slug>/

如果只是替换同名文件，保留原引用即可；如果改了图片文件名，必须同时更新正文 Markdown 和 coverImg。不要先删除旧文件，除非确认没有其他页面引用它。

![新图片的准确说明](/images/posts/vitepress-deploy-guide/new-image.webp)

替换图片后检查 alt 仍然准确。图片换了但 alt 还描述旧内容，是常见的可访问性错误。

5. date、lastUpdated 和 updated 的区别

• date 是文章发布日期，通常 不要 因为改了一个错别字就改它。它会改变首页、归档、分类和标签中的时间顺序。
• lastUpdated: true 已开启。提交后，VitePress 在 Git 历史可用时会显示最后提交时间；这是自然的「最后更新」。
• updated 是可选 SEO 字段。config.ts 会把它用于 article:modified_time 和 JSON-LD 的 dateModified。只有确实需要指定 SEO 修改时间时才写，且必须真实。
• 如果只是想让文章靠前，不要改 date 或伪造 updated；使用 sticky（文章流置顶）或 top（首页精选卡片），并在确认栏目规则后使用。

6. 发布后不要随意改 permalink

静态博客没有自动的 HTML 跳转。把 /posts/技术笔记/old-url 改成新地址后，旧链接会直接 404，除非托管平台配置了重定向。

如果确实必须改：

1. 记录旧 permalink。
2. 更新文章 frontmatter 的 permalink。
3. 搜索整个仓库中的旧地址并逐处更新。
4. 检查 Nav.ts、Features.ts 和目录页是否手写了旧链接。
5. 在 EdgeOne/托管平台配置旧地址到新地址的 301 重定向。
6. 构建、审计、部署后分别验证旧 URL 和新 URL。

搜索旧地址的 PowerShell 示例：

Get-ChildItem docs -Recurse -File -Include *.md,*.ts | Select-String -Pattern "/posts/技术笔记/项目记录/old-url"

如果只是文件改名而 permalink 不变，公开 URL 不变，不需要为 URL 做重定向；但仍要检查相对图片链接、侧边栏顺序和 Git 历史。图片建议始终使用 /images/... 绝对路径，这样文件移动不会破坏引用。

7. 重启开发服务器并复查

只要改了标题、分类、标签、文件位置或 frontmatter，建议停止当前 dev 进程并重新启动：

pnpm docs:dev

打开文章 URL，并重新检查首页、目录页、侧边栏、分类、标签、归档、搜索、评论和封面。改标题或标签后，旧入口应该消失或更新；如果仍显示旧值，先重启开发服务器。

8. 构建、审计和预览

pnpm docs:build
pnpm docs:audit
pnpm docs:preview

审计必须在构建后进行。人工重点检查 H1 是否仍然唯一、description 是否有实际内容、canonical 是否使用新 permalink、每张图片是否有有意义的 alt。审计不会替你检查链接、图片是否存在或空 alt；请在预览中手动验证。预览地址默认是 http://localhost:4173/，不要只检查开发服务器。

9. 查看差异、提交并推送

git status
git diff --stat
git diff
git add "docs/posts/技术笔记/项目记录/01.vitepress-deploy-guide.md"
git commit -m "docs: update vitepress deploy guide"
git push origin main

如果这次还改了图片或配置，按实际路径加入对应文件。提交前确认没有把旧图片删除后忘记加入新图片，也没有把 dist、cache 或 search-manifest 加入暂存区。

10. 线上验收和旧链接检查

部署完成后检查新页面内容和图片。如果 permalink 没变，旧 URL 应仍旧可用；如果 permalink 改变且配置了重定向，旧 URL 应 301 到新地址；如果没有配置重定向，旧 URL 会 404，这是必须提前接受的后果。

Part C：删除文章

删除比新增更容易遗漏，因为文章可能被首页、目录页、导航、其他文章和外部搜索引擎引用。先判断，再操作。

1. 评估是否应该删除

先问清楚：

• 这是彻底删除，还是内容过时、应该更新？
• 是否有外部链接、收藏或 RSS 读者仍可能访问？
• 是否需要把内容移动到另一个分类，而不是删掉？
• 删除后对应子目录是否会变空？应该保留 .gitkeep 还是连同目录页一起删除？

如果文章已发布且有一定访问量，优先考虑保留文章并更新内容；确需删除时，评估是否需要设置旧 URL 到新页面或 404 说明页的重定向。

2. 搜索所有引用

Get-ChildItem docs -Recurse -File -Include *.md,*.ts | Select-String -Pattern "/posts/技术笔记/项目记录/old-url"

把旧 URL、文章标题和文件名也可能作为搜索词。特别检查：

• docs/.vitepress/ConfigHyde/Nav.ts
• docs/.vitepress/ConfigHyde/Features.ts
• 其他文章里的手写链接
• 目录页是否有手写说明或链接
• 首页组件或配置中的固定链接

如果文章只是由目录扫描自动显示，删除文件后目录页会自动更新，不需要手动删目录列表项。若你曾在目录页正文里手写了文章链接，则必须手动删除。

3. 删除 Markdown 文件

可以在 Windows 文件资源管理器或 VS Code 资源管理器中右键删除，也可以在 PowerShell 中精确删除：

Remove-Item -LiteralPath "docs\posts\技术笔记\项目记录\01.vitepress-deploy-guide.md"

Remove-Item 不会把文件放入回收站，执行前确认路径和文件名。不要删除整个 posts 分类目录，除非你正在按目录流程删除整个分类。

4. 处理图片目录

如果图片只被这篇文章使用，可以删除对应目录。先用 git status 或其他文章搜索确认没有共享引用：

git status
Get-ChildItem docs -Recurse -File -Include *.md | Select-String -Pattern "/images/posts/vitepress-deploy-guide/"
Remove-Item -LiteralPath "docs\public\images\posts\vitepress-deploy-guide" -Recurse

最后一次删除是不可恢复的文件系统操作。如果图片可能复用，先移动到保留目录，不要直接删。共享封面如 /home/bg11.webp 不要因为删除一篇文章而删除。

5. 清理手工引用和入口

按第 2 步的搜索结果删除 /posts/... 旧链接。文章一般不会直接出现在 Nav.ts，但如果之前手工加过，需要删除对应菜单项；如果首页 Features.ts 曾把文章作为卡片入口，也要删除。若删除的是某目录的唯一文章，目录页仍可保留并显示空列表；若整个目录取消，按照目录页完整流程的删除部分处理目录页、posts 目录和旧目录 URL。

需要保留空目录以便以后使用时，放入 .gitkeep：

New-Item -ItemType File -Force -Path "docs\posts\技术笔记\项目记录\.gitkeep"

6. 重启开发服务器并复查

删除、移动文件后必须先重启开发服务器，让路由、侧边栏、目录页和搜索清单重新构建：

pnpm docs:dev

检查：

• 旧文章 URL 已不可访问或按预期进入 404。
• 目录页不再列出文章。
• 侧边栏不再显示文章。
• 首页、分类、标签、归档不再显示。
• 搜索重新构建后不再显示旧正文。
• 其他文章中的旧链接已清理。
• 图片没有出现新的 404。

开发模式不等于生产索引；完成构建后的预览才是最终搜索和路由结果。

7. 构建、审计和预览

pnpm docs:build
pnpm docs:audit
pnpm docs:preview

如果审计报旧页面仍在 sitemap，检查 dist 是否是本次构建生成，以及是否有旧文件或其他路由仍引用该 URL。不要手删 dist 中单独文件来掩盖问题，应该回到源文件 checkout 后重新构建。

8. 检查 Git 变更并提交

git status
git diff --stat
git add "docs/posts/技术笔记/项目记录/01.vitepress-deploy-guide.md" "docs/public/images/posts/vitepress-deploy-guide"
git commit -m "docs: remove vitepress deploy guide"
git push origin main

git add 对已删除文件也会记录删除。若图片保留，就不要把图片目录加入暂存区。确认提交中只包含这次删除和相关链接/配置调整。

9. 部署并处理旧 URL

推送 main 后观察 CNB 的安装、构建、审计、EdgeOne 部署步骤。部署完成后验证旧 URL：没有重定向就是 404；如果业务要求旧地址仍能访问，必须在托管平台配置重定向到替代文章或说明页。静态站本身不会生成自动跳转。

Part D：重命名或移动文章

先把两种情况分开，这是安全操作的核心：

情况	文件位置是否变化	permalink 是否变化	公开 URL	风险
只重命名/移动源文件	是	否	不变	较低；注意扫描排序、图片相对引用和 Git 历史
更换分类或更换公开 slug	可能是	是	变化	较高；必须更新站内链接并考虑旧地址重定向

1. 判断公开 URL 是否会改变

打开文章 frontmatter，看 permalink：

permalink: /posts/技术笔记/项目记录/vitepress-deploy-guide

• 如果你只是把文件从 01.old-name.md 改成 01.new-name.md，而 permalink 仍是这一行，那么公开 URL 不变。
• 如果你把文章移到另一个分类，通常应该把 permalink 改成新分类路径，并同步 categories；这时公开 URL 会变化。
• 如果你只移动文件但保留旧 permalink，页面仍能打开，但文件位置、分类归属和 URL 可能互相矛盾，长期维护容易出错。推荐移动分类时同时把 permalink 和 categories 改到新位置。

2. 确认目标目录和目录页已经存在

如果目标目录是已有分类或已有子目录，先确认 docs/posts/... 和对应的 docs/catalog/...md 都存在。若是新分类/新子目录，先按目录页完整流程完成入口，避免文章移过去后在目录结构中消失。

3. 用 git mv 移动文件

同一目录内重命名：

git mv "docs/posts/技术笔记/项目记录/01.old-slug.md" "docs/posts/技术笔记/项目记录/02.new-slug.md"

跨目录移动：

git mv "docs/posts/技术笔记/项目记录/01.old-slug.md" "docs/posts/技术笔记/新子目录/01.old-slug.md"

git mv 比手动复制再删除更容易保留文件历史。移动后先不要急着改内容，确认目标目录存在，再编辑 frontmatter。

4. 按 URL 策略更新 frontmatter

如果公开 URL 不变，只改文件名即可，保留原 permalink。如果需要改变 URL：

permalink: /posts/技术笔记/新子目录/new-slug

同时检查：

• categories 是否仍对应一级目录；
• 如果有 sidebarSort，移动后排序是否仍符合预期；
• 图片路径是否仍使用 /images/... 绝对路径；
• 文件名前缀是否与希望显示的侧边栏顺序一致；
• 旧 permalink 是否仍被其他文章、Nav 或 Features 引用。

5. 如果 slug 变化，同步移动图片目录

文章 slug 从 old-slug 变成 new-slug 时，为了长期一致，建议同步移动图片目录，并更新所有引用：

git mv "docs/public/images/posts/old-slug" "docs/public/images/posts/new-slug"

然后全文搜索旧路径：

Get-ChildItem docs -Recurse -File -Include *.md | Select-String -Pattern "/images/posts/old-slug/"

替换正文图片引用和 coverImg。如果旧图片目录被其他文章共用，不要直接移动，改为复制需要的图片或保留旧目录。

6. 重启开发服务器并验证新旧路径

移动文件后先停止并重新启动开发服务器：

pnpm docs:dev

然后再验证新旧路径。检查：

• 新文件路径下能在开发服务器找到对应页面。
• 新 permalink 能访问；如果 permalink 未变，新文件移动不应改变原 URL。
• 旧 permalink 的行为符合预期：仍可访问，或已准备重定向/404。
• 文章在正确的目录页、侧边栏、分类、标签、归档和搜索分组中。
• coverImg 和正文图片没有 404。
• 旧文件名的图片相对引用没有残留。

7. 构建、审计、预览

pnpm docs:build
pnpm docs:audit
pnpm docs:preview

移动后尤其要检查 sitemap 中是否只剩正确的新 URL、旧 URL 是否按预期处理、canonical 是否指向新 permalink。如果改了分类，还要检查 /categories 和 /tags 是否仍符合预期。

8. 提交、推送和线上验收

git status
git diff --stat
git add "docs/posts/技术笔记/项目记录/02.new-slug.md" "docs/public/images/posts/new-slug"
git commit -m "docs: move vitepress deploy guide"
git push origin main

如果这是跨分类移动或重命名涉及配置，按实际变更加入 docs/catalog、Nav.ts、Features.ts 或两份 categoryOrder。CNB 部署后验证新 URL、目录入口、导航、图片和旧链接策略。URL 改变而没有重定向时，旧链接会 404，这是静态站的正常行为，不是缓存问题。

问题定位矩阵

症状	先检查什么	常见修复
开发环境文章 404	文件位置、permalink、URL 是否带 .html	修正 frontmatter 或路径，重启 dev
打开成旧 /pages/xxxxxx	历史随机地址或 permalink 缺失	显式写 /posts/...，重启
首页不出现文章	article、inHomePost、date	改 true/删除 false，使用合法日期
侧边栏不出现	是否在 posts、是否 index.md、sidebar 是否 false	使用具名文章文件，打开 sidebar: true；article 不影响侧栏
目录页看不到文章	path、catalogue 插件、目录页是否重启	精确匹配真实目录，重启开发服务器
分类页不出现	categories 数组和一级目录	统一分类名称，确保 article true
标签页不出现	tags 数组、拼写和大小写	统一标签，重新构建
首页排序不对	date、sticky	修改日期或 sticky，不要改 sidebarSort 期待首页变化
侧边栏排序不对	文件 NN.、sidebarSort	用正整数 sidebarSort 或调整文件名前缀
封面不是随机图	coverImg	如果写了 coverImg 会固定使用；删除它才会按正文图片或 /home/bg*.webp 随机。缺失/404 时检查路径
图片线上 404	文件是否在 public、大小写、扩展名	放到 docs/public/images/posts/<slug>/，引用 /images/...
Pagefind 搜不到	pagefind-indexed、是否构建	改为 true，运行 build 后预览验证
搜索分组不对	search-manifest、sidebarSort、article	检查 posts 扫描规则并重启，不用手改 JSON
评论不显示	comment、评论 provider	打开 comment，检查外部评论配置
构建失败	终端第一条错误	先修 YAML、重复 permalink、代码围栏；链接和图片问题不会被构建自动兜底
审计有阻塞错误	H1、alt 属性、canonical、sitemap	对照审计输出修源文件；审计通过后仍要手动检查链接、图片和摘要
旧 URL 404	permalink 是否改过	配置托管平台 301 重定向，或恢复原 permalink
CNB 失败但本地通过	CNB 日志、环境变量、依赖锁文件	先本地重跑 build 和 audit，再检查平台配置

最重要的一条：出现问题时先缩小范围。 页面能打开但入口没出现，通常是 frontmatter 或扫描层；页面完全打不开，通常是 permalink 或文件路径；本地通过但线上失败，通常是构建环境、部署配置或重定向。