知识库说明

欢迎来到 FORMA 知识库。

这里把原先分散在独立文档站里的笔记、技能小册、生活记录与团队实践，统一收进 FORMA 工具台，和代码美化、Playground、图片压缩等工具放在同一张「桌面」上。

本文是整库的阅读入口：说明迁移动机、内容地图、推荐读法、页面怎么用，以及如何继续用 Markdown 写作与维护。若你只想快速上手，先看 三分钟上手，再按兴趣跳进对应分区。

三分钟上手

1. 打开 /knowledge。左侧点分类，或顶部搜索框输入关键词（如 vue、docker、摄影）。
2. 列表按置顶优先，再按 date 倒序；滚到底部会自动加载下一页（默认每页 20 篇）。
3. 点进文章后：左侧看分类 / 日期 / 标签与目录；正文区阅读；大屏右侧可看上下篇与 Series；html / css / js / vue / ts / scss / less 代码块可一键「Playground」打开演练场；右下角可回到顶部。
4. 系统补前端 / 全栈：从 JavaScript 基础 或 工程化概览 进入技能小册。
5. 部署与私有化：在列表选「服务笔记」，或搜 1panel、docker、jenkins。
6. 摄影或小说：从 学习摄影创作 进入，或列表筛选「生活笔记」。
7. 业务踩坑与组件实践：列表筛选「团队文档」，例如 执行价格弹窗。

为什么从 Rspress 迁移到 FORMA？

早期知识库以 Rspress（偏文档站 / 静态站点）独立部署：结构清晰、适合「纯文档」场景，但也带来一些摩擦。

因此在 FORMA v1.0.0 起，把原 Rspress 知识库整体迁入本站（详见 更新日志）：

• 内容仍是 Markdown：写作习惯不变，Git 可审阅、可 diff。
• 渲染交给 Nuxt Content：构建 / 开发时写入 SQLite（better-sqlite3），页面与 /api/knowledge 读同一份数据。
• 与工具台同站：侧栏即可在「工具」与「知识库」之间切换。
• 统一信息架构：category / tags / pinned / draft 一套约定，列表与接口行为一致。

迁移后立刻能感知的变化

• 地址从独立文档站变为 /knowledge/...（完整形式：https://你的域名/knowledge/...）。
• 列表可按「技能小册 / 生活笔记 / 服务笔记 / 团队文档 / 阅读指南」筛选。
• 详情页与 FORMA 主题色、浅色 / 深色模式一致。
• 需要程序读取时，可直接调接口（见 数据与接口），不必再爬静态 HTML。

这里记录了哪些内容？

知识库按用途分成四大内容分区，外加本篇阅读指南。源文件都在 content/knowledge/ 下。

总览

内容之间的关系

阅读指南（本篇）
    │
    ├─ 技能小册 ── 概念与路径（学什么）
    ├─ 服务笔记 ── 落地与踩坑（怎么装、怎么排）
    ├─ 团队文档 ── 业务现场（组件 / 性能 / 兼容）
    └─ 生活笔记 ── 兴趣与表达（摄影 / 小说 / 日常）

技术向文章之间会互相引用（例如服务笔记链到小册里的 NestJS、字体优化等）。站内链接统一为：

/knowledge/<分区>/<…路径…>

示例：content/knowledge/booklet/web/Js/basics.md → /knowledge/booklet/web/js/basics。

1. 技能小册（booklet/）

面向「把技术栈串起来」的学习路径，偏结构化笔记：不是替代官方文档，而是帮你建立地图与常用概念。

推荐入口

子目录地图

适合：系统补基础、面试前串知识点、或写业务时快速回顾某一块。

2. 生活笔记（life-notes/）

偏个人表达与长期兴趣，和技能小册分开，避免「技术文档」与「生活记录」搅在一起。

推荐入口

子目录地图

摄影建议顺序：basics → practice → scenarios（先懂原理，再敢拍，再会选场景）。

3. 服务笔记（service-notes/）

记录真实环境里的部署、排错、选型与调研，偏「做过一遍」的经验，常带截图与命令。

推荐入口

在 /knowledge 选择分类「服务笔记」，或直接用关键词搜索。常见主题示例：

子目录地图

4. 团队文档（team-documents/）

来自真实业务现场的组件设计、性能优化、兼容适配与事故复盘，编号 01–22，彼此相对独立，可按标题检索。

怎么读

1. 列表筛选「团队文档」，扫 title / description。
2. 或打开具体篇目，例如：
   • 01 · 执行价格弹窗与可配置表格
   • 02 · 防篡改水印
   • 13 · 新商家系统性能优化
3. 关注文中的技术栈版本与复盘结论；迁移到自己的项目时注意框架与组件库差异。

适合：做后台表格、H5 / 企微内嵌、上传水印、支付中转、列表性能等问题时对照。

怎么阅读？推荐路径

不同目标，建议用不同读法。

A. 访客随便逛逛

1. 打开 /knowledge，先看置顶（本篇）。
2. 左侧点一个分类，扫标题与摘要。
3. 感兴趣再进正文；不必按目录顺序读。

B. 系统补前端 / 全栈

1. JS · basics → HTML / CSS 同级目录。
2. frame（Vue / React / Angular）→ 工程化概览。
3. 需要服务端时进 后端入门，数据进 SQL，协作与部署进 uphold。
4. 每个大目录常有 index / basics 导读，优先跟表走。

C. 排生产 / 自托管问题

1. 分类选「服务笔记」，或搜 1panel、jenkins、docker、pm2、dify。
2. 对照文中命令与截图；版本以官方为准。
3. 若涉及前端基建，可交叉阅读技能小册的工程化 / NestJS 等章节。

D. 学摄影或看小说

1. 摄影：学习摄影创作 → basics → practice → scenarios。
2. 小说：从各书 start / 第一章进入，按章节阅读。
3. 记住：小说为虚构，请以文内声明为准。

E. 查业务组件与踩坑

1. 分类选「团队文档」。
2. 用搜索框输入现象关键词（如 水印、键盘、vxe-table、企微）。
3. 先读「背景 / 现象」，再读「方案 / 复盘」，最后对照自己的技术栈。

阅读时的小提示

• 摘要先行：列表里的 description 一般够判断要不要点进去。
• 用标签扫一眼：详情侧栏的 #tag 反映主题词，便于联想相关文。
• 相信目录：长文左侧 TOC 比反复滚动更高效。
• 交叉引用：正文里的站内链接已尽量改为 /knowledge/...；若遇 404，多半是路径大小写或旧链接残留。
• 批判性阅读：小册与笔记不能保证绝对正确；以官方文档与你的实践为准。

列表页与详情页怎么用？

列表页 /knowledge

详情页 /knowledge/...

站点结构与 URL 约定

content/knowledge/
├── getting-started.md           → /knowledge/getting-started
├── booklet/                     → /knowledge/booklet/...
├── life-notes/                  → /knowledge/life-notes/...
├── service-notes/               → /knowledge/service-notes/...
└── team-documents/              → /knowledge/team-documents/...

规则简述：

1. 文件路径相对 content/knowledge/，去掉 .md 即路由后缀。
2. index.md 通常对应去掉 index 的目录路径（以实际生成的 path 为准）。
3. 路径段小写：即使仓库目录是 NodeJs、Js，访问时用 nodejs、js。
4. 文内互链请写绝对路径，例如 /knowledge/booklet/web/js/basics，避免相对路径在迁移后失效。
5. 旧站形式（如 /booklet/...、裸 /life-notes/...）已废弃，请改带 /knowledge 前缀。

路径对照示例

如何撰写与维护文章？

新建一篇

1. 在对应分区目录下新建 .md（例如 content/knowledge/service-notes/service/my-note.md）。
2. 写好 Frontmatter + 正文，保存。
3. 本地执行 pnpm dev，打开列表或对应 URL 预览；构建时会进入 Content 的 SQLite。

Frontmatter 字段

Schema 定义见仓库根目录 content.config.ts。

建议的 category 取值

分类样式（强调色 / 图标）在前端 app/utils/knowledge.ts 中映射；新增分类名若未登记，会走默认样式。

完整示例

---
title: 我的笔记
description: 一段简短说明，会出现在列表摘要与搜索结果里。
category: 服务笔记
tags: [docker, ops]
date: 2026-07-22
pinned: false
---

## 背景

正文从这里开始。

::callout{color="success"}
可以用 callout 强调注意点、结论或风险。
::

### 命令示例

```bash
docker compose up -d
```

写作约定（建议）

• 一篇一个主题；大专题拆多篇，并用导读页或表格串起来。
• 标题层级连贯：# 文题（可与 title 一致）→ ## 大节 → ### 小节；避免跳级。
• 代码块标明语言（ts / vue / bash / json 等），便于高亮。
• html / css / js / vue / ts / scss / less（及 javascript / typescript / sass）代码块会显示 Playground 按钮，可回填到站内演练场；不需要时在 fence meta 加 no-playground。其他语言若也想打开，可加 playground。
• 外链写清来源；站内互链用 /knowledge/...。
• 过时命令或版本在文首或 callout 里标明「以官方为准」。
• 表格列不宜过多；手机上过宽表格会横向滚动。
• 图片尽量有说明性 alt；大图注意体积。
• 小说等虚构内容保留免责声明。

MDC / Callout 速查

正文由 MDC 渲染，配色与 FORMA / Nuxt UI 主题变量对齐。常用 callout：

::callout{color="info"}
说明、背景、补充信息。
::

::callout{color="success"}
技巧、推荐做法、正向提示。
::

::callout{color="warning"}
注意版本、安全或易踩坑点。
::

::callout{color="error"}
严重风险、勿直接照抄的危险操作。
::

::callout{color="primary"}
与本站能力相关的强调（迁移说明、产品约定等）。
::

color 可选：info / success / warning / error / primary / secondary（与 app/app.config.ts 中 prose callout 变体一致）。

代码块可带文件名与 meta（Nuxt Content / MDC 约定）。html / css / js / vue / ts / scss / less 默认显示「Playground」；加 no-playground 可关闭：

```html [demo.html]
<div class="card">Hello</div>
```

```css no-playground
/* 仅展示、不进演练场 */
.card { padding: 1rem; }
```

可直接试用（点右上角 Playground）：

<div class="card">
  <p class="eyebrow">FORMA</p>
  <h1>在演练场改我</h1>
</div>

<style>
  body {
    margin: 0;
    min-height: 100vh;
    display: grid;
    place-items: center;
    font-family: system-ui, sans-serif;
    background: #0b0f14;
    color: #e8edf2;
  }
  .card { text-align: center; padding: 2rem; }
  .eyebrow {
    margin: 0;
    font-size: 11px;
    letter-spacing: 0.2em;
    text-transform: uppercase;
    color: #8b97a5;
  }
  h1 { margin: 0.5rem 0 0; letter-spacing: -0.03em; }
</style>

数据与接口（进阶）

内容在构建 / 开发时由 @nuxt/content 写入 SQLite（依赖 better-sqlite3）。页面与 API 读的是同一份数据。返回体通常带 source: "sqlite"、connector: "better-sqlite3"，便于确认数据来源。

列表 GET /api/knowledge

示例：

GET /api/knowledge?page=1&pageSize=20&category=技能小册&q=vue

响应要点：items、total、hasMore、facets.categories（各分类计数）、facets.totalAll（当前筛选下、分类过滤前的总数，供侧栏「全部」使用）。

详情 GET /api/knowledge/<slug...>

默认只返回正文与元信息（更快）。需要上下篇时追加 surround=1：

GET /api/knowledge/booklet/web/js/basics
GET /api/knowledge/booklet/web/js/basics?surround=1

草稿（draft: true）对公开接口表现为 404。

站点地图

公开文章也会进入 /sitemap.xml（需配置 NUXT_PUBLIC_SITE_URL 以得到绝对域名）。/robots.txt 会指向该 sitemap，并禁止抓取 /api/。

本地开发与预览

pnpm install
pnpm dev

然后打开：

• 列表：http://localhost:3000/knowledge
• 本篇：http://localhost:3000/knowledge/getting-started
• 接口：http://localhost:3000/api/knowledge?page=1&pageSize=5

生产构建：

pnpm build
pnpm preview

常见问题

Q：为什么有的旧链接 404？
A：迁移后统一前缀为 /knowledge/...，且路径段小写。另有一批碎片文已合并（如 jenkins-use-1 → jenkins-1panel，web-update-1/2 → web-update，Git/Docker/Sass/Redis/摄影场景等同理）。请用列表搜索标题，或检查是否仍是旧 slug / 大小写不一致（如 Js vs js）。

Q：列表里找不到刚写的文章？
A：确认未设 draft: true；pnpm dev 是否在跑；Frontmatter 的 --- 是否成对、YAML 缩进与引号是否合法；category 是否写错导致你筛错分类。

Q：搜索好像搜不到正文里的某一句？
A：当前列表搜索匹配的是标题、摘要、分类与标签，不包含全文正文。重要关键词请写进 description 或 tags。

Q：技能小册能当完整教程吗？
A：不能替代系统课程与官方文档。它是入门地图与备忘；请搭配练习与权威资料。

Q：生活笔记里的小说是真事吗？
A：否，虚构叙事。请以各书文内声明为准。

Q：团队文档里的方案能直接拷到我的项目吗？
A：当作思路与踩坑参考。注意文中 Vue / 组件库 / 构建工具版本；直接粘贴前先对照你方技术栈。

Q：还能单独部署 Rspress 站吗？
A：内容已迁入本仓库维护。若需导出，可直接使用 content/knowledge/**/*.md；渲染与路由以 FORMA 为准。

Q：callout 不显示或样式不对？
A：请使用 ::callout{color="info"} 等形式（见上文速查），并保证结尾单独一行的 ::。配色变体以站点 app.config 为准。

Q：如何反馈错误链接或错别字？
A：直接提仓库 Issue / PR，或在团队内反馈路径与期望文案即可。

接下来可以去哪儿？

如果你在阅读中发现错误链接、过时命令或错别字，欢迎反馈——知识库会持续修正与增补。