本站使用与维护手册

这篇是写给谁的#

这座站是静态站点：所有内容在构建时被”编译”成一堆 HTML 文件，再整体发布出去。这个特性决定了一件事 —— 写内容就是改文件，发布就是重新构建。没有后台、没有数据库里的编辑器，也没有”登录后点保存”这一步。

所以这篇手册写给两类人：

• 要往站里加内容的人：写文章、发动态、传图片、加项目、建相册、换壁纸；
• 要维护这座站的人：删内容、改配置、上线前跑自检。

读完之后，前面那些事每一件都应该能照着目录和命令自己做完，而不是靠记忆或猜。文中出现的路径都是仓库里的真实路径，命令都是可以直接复制执行的。

一、先认识六个命令#

内容维护 90% 的时间只会用到下面这几条。左侧是命令，右侧是它真正做的事：

另外三条只在特定场景用得上：pnpm check（类型与模板诊断）、pnpm type-check（纯 TypeScript 检查）、pnpm lqips（重新生成图片的模糊占位数据）。

二、写一篇文章#

1
src/content/posts/
2
├─ cpp/            ← 分类目录（决定文章的 category 归属）
3
├─ algorithm/
4
├─ linux/
5
├─ linux-net/
6
├─ mysql/
7
├─ stl/
8
├─ cpp11/
9
├─ interview/
10
├─ project/
11
└─ ai/

1
pnpm new-post project/boke-shiyong-yu-weihu-shouce

1
---
2
title: project/boke-shiyong-yu-weihu-shouce
3
published: 2026-10-09
4
description: ''
5
image: ''
6
tags: []
7
category: ''
8
draft: false
9
lang: ''
10
slug: project/boke-shiyong-yu-weihu-shouce
11
---

1
![这张图的说明](/images/posts/boke-shiyong-yu-weihu-shouce/01.png)

1
pnpm dev                      # 边写边看
2
pnpm check                    # 模板与类型诊断：0 error 才算过
3
pnpm verify:posts             # 内容自检：frontmatter、图片、链接、残留语法
4
pnpm build                    # 生产构建（这一步会真正把文章编译进 dist/）

三、必修项：把文章挂进「学习路线」#

学习路线页 /roadmap/ 的数据不在内容目录里，而在一份手工维护的配置：src/config/roadmapConfig.ts。它的结构是「主线 → 阶段 → 篇目」，篇目用 category（目录名）+ slug（文件名）成对定位：

1
// 站内允许同名篇目（cpp/vector 与 stl/vector 就是两篇），所以定位必须成对
2
s("project", "boke-shiyong-yu-weihu-shouce")
3
s("cpp", "vector", "vector · 实现")        // 第三个参数只改本页显示名
4
s("linux", "neicunguanli", undefined, true) // 第四个参数 = 跨线复用标记

规矩有三条：

1. category 与 slug 都必须能对上真实文件 —— 对不上，pnpm build 当场失败（这是故意的：路线页宁可不构建，也不静默漏掉一篇）；
2. 顺序就是页面顺序，不写”第 N 步”这类数字，所以调整顺序不需要改编号；
3. 页顶那几个数字（多少篇、多少条主线、多少个停靠点、约多少小时）是构建期实算的，不要手工维护 —— 但也因此，站内每一篇都必须至少出现在一条主线里：站内文章总数与路线页篇目并集必须相等，有专门的断言在盯着这件事。

新增一篇的标准动作，就是在合适的主线里加一行 s(category, slug)；跨线的复用篇目加第四个参数 true。

四、发一条动态#

动态（微动态）是短内容，放在 src/content/dynamic/：

1
pnpm new-dynamic 今天把学习路线的停靠点又核对了一遍。

脚本会：

1. 按 siteConfig.timezone（本站是 Asia/Shanghai）取当前时间；
2. 生成文件名 YYYY-MM-DD-HHMMSS.md；
3. 写入 published: <时间戳> 的 frontmatter 与正文。

动态的 schema 只有三个字段：published（必填）、pinned（置顶，默认 false）、location（地点，默认空）。正文就是一句话，不需要标题，也不会出现在文章列表里。

动态里同样可以插图：图片放 public/images/dynamic/（或与文章共用 public/images/ 下一层子目录），正文用 /images/... 的绝对路径引用即可 —— 规则和文章一样，走的是同一套 Markdown 管线。

五、加一个项目#

项目放在 src/content/projects/<slug>.md，一个文件一个项目，详情页地址是 /projects/<slug>/。字段如下：

1
---
2
title: "示例项目"
3
published: 2026-10-09
4
order: 5
5
description: "一句话说清它是什么、用什么写的。"
6
tags: ["Python", "LangGraph"]
7
link:
8
  - label: "源码仓库"
9
    icon: "simple-icons:gitee"
10
    value: "https://gitee.com/<你的账号>/<仓库>"
11
status: "published"
12
---

项目详情页的正文就是普通 Markdown，可以放架构图、数据表、代码片段 —— 与文章用的是同一套渲染管线。

六、建一个相册#

相册需要两处同时动手，缺一不可：

1. 在 src/config/galleryConfig.ts 的 albums 数组里加一项；
2. 在 public/gallery/<相册 id>/ 下建同名目录，把图片放进去（支持 jpg / png / webp / avif / gif）。

每一项的字段：id（唯一标识，同时是目录名与 URL）、name、description、location（拍摄地）、date（YYYY-MM-DD，用于排序）、tags、cover（可选：不填时用目录里的 cover.*，再没有就用第一张图）、password / passwordHint（可选：加密相册）。

七、加一张书签卡#

书签导航页 /booknav/ 的卡片在 src/config/booknavConfig.ts：按”分组 → 卡片”两层组织，分组用 weight 决定先后（数字大的在前），卡片要写 title / url / desc。

图标有两种来源：

• iconify 品牌图标：写 icon: "simple-icons:xxx"，构建期打包进产物；
• 本地图标：图片放 public/booknav-icons/，卡片写站内路径。

每张卡还可以给一个品牌色：iconColor: brandHex("<品牌键>")，键名定义在 src/constants/booknav-brand-colors.ts。键名打错会直接抛错，这是有意为之 —— 静默退化成灰色会让一张卡悄悄变得不一样，没人会发现。

本站已把”自动抓取第三方 favicon”的开关关掉了（favicon.enabled: false）：开着的话，每张没写图标的卡都会向第三方接口请求一次，等于把访客的浏览清单交出去。

八、照片之外：外观与站点级配置#

壁纸那一项值得多说一句：每支视频可以带取景参数（水平/垂直落点、放大倍数）。原因是素材是 2.36<1> 的超宽画面，而站点同时有手机横幅、桌面横幅、全屏壁纸几种很不一样的框 —— 不写取景参数，窄框里可能会把人物裁掉半边。⚠️ 改取景参数时一次只改一支：这是发起人明确要求过的（别按”我觉得不准”去批量重算）。

九、删除一篇文章要动哪些地方#

内容目录是数据源，但有几处是会”记住”这篇文章的，删的时候要一起清：

• 删掉 src/content/posts/<分类目录>/<slug>.md；
• 删掉它的图片目录 public/images/posts/<slug>/（这是把图片按 slug 集中存放的原因）；
• 去 src/config/roadmapConfig.ts 里删掉对应的那一行 s(category, slug) —— 不删，构建会因为”路线里指向一篇不存在的文章”而失败；
• 如果正文里有指向它的站内链接，一并改掉（pnpm verify:posts 会逐条报告失效链接）；
• 如果公告、关于页等文案里写了”站内共 N 篇”这类数字，把数字改对（站里有一条断言专门盯着公告里那句话，数字不对会判红）；
• 提交前跑一遍 pnpm verify:posts 与 pnpm build。

删除动态只需要删一个文件；删除项目要删 src/content/projects/<slug>.md，如果它的详情页被别处引用过，同样用自检脚本找出来。

十、收工前的六道自检#

改完内容，按顺序跑完这六条再提交：

前四条是”内容对不对”，后两条是”站还完整吗”。它们的意义在于：把”我记得要改哪里”变成”脚本会告诉我漏了哪里”。

十一、最容易踩的五个坑#

1. 忘了把新文章挂进学习路线 —— 构建直接失败。这不是 bug，是设计：站内每一篇都必须能被路线页解释。
2. 把图片放进 src/assets/ 再在正文里引用 —— 正文插图约定是 public/images/posts/**；src/assets/ 下的图片会被构建管线改名成带哈希的文件名，正文里的固定路径必然 404。
3. 草稿忘了改 draft: false —— 本地能看到、线上什么都没有，而且自检脚本不会报错（草稿是合法的）。发布前搜一遍 draft: true。
4. 作品名写成一句话 —— 列表卡的标题框只有一行宽度，超长的名字会被截断成一个没有信息量的前缀。标题该长就长在详情页，卡片名尽量短。
5. 改了带数字的文案没同步 —— 公告里的”共 N 篇”、页顶的统计数字，都和别人有联动：统计数字是构建期实算的（不用管），但配置里手写的数字必须自己改对，站内有断言盯着它们。

结语#

把这座站的内容维护拆开看，其实只有三种动作：放文件、改配置、跑命令。

• 放文件：src/content/** 决定”有什么内容”，public/** 决定”素材在哪”；
• 改配置：src/config/** 决定”怎么组织、怎么显示”，其中学习路线是唯一必须手工维护的清单；
• 跑命令：pnpm check / verify:posts / build / verify:ui / verify:docs 把”我是不是漏了什么”交给脚本回答。

这三件事都不需要懂前端框架。真正需要记的只有一条因果关系：内容目录里有什么，站上就有什么；而学习路线必须能解释站上的每一篇。