Repository Wiki
ChanIok/SpinningMomo

VitePress 文档站与多语言结构

docs/ 目录承载 SpinningMomo 项目独立的 VitePress 文档站，用于托管用户文档与开发者文档；它通过标准的 locales 机制支持多语言内容组织，并且完全不进入运行时产物（runtime bundle）。

Purpose and Scope

本页覆盖以下内容：

  • docs/ VitePress 站点的定位、包配置（docs/package.json）与构建脚本；
  • 站点与运行时（web/ 前端、后端服务）之间的边界关系；
  • 依赖版本声明与实际解析版本（pnpm-lock.yaml）的对应关系；
  • VitePress 框架层面的多语言（locales）组织机制说明。

以下相关主题有意留给姊妹页面，本页仅作交叉指引：

  • 运行时前端（Vite 开发服务器、/rpc 与 /static 代理）——见仓库 web/ 相关页面；
  • Android 捕获守护进程（momo-capture）——见 android/ 相关页面；
  • 后端 HTTP/RPC 调试脚本——见 playground/ 相关页面。

Overview

SpinningMomo 仓库将"文档站"与"产品运行时"作为两个彻底解耦的子系统维护。仓库级说明文件 AGENTS.md 对此有明确约定：

docs/ is a separate VitePress site and is not part of the runtime bundle.

  • docs/ — VitePress documentation site for user and developer docs

Source: AGENTS.md

也就是说，docs/ 是一个自包含的 Node 项目：它有自己的 package.json、自己的依赖树（由根级 pnpm-lock.yaml 锁定）、自己的 dev/build/preview 三个标准阶段。它不依赖后端进程启动，也不被后端打包流程引用。这种隔离带来三个直接收益：

  1. 构建互不干扰：文档站构建失败不会阻塞运行时发版，反之亦然；
  2. 依赖自由度：文档站可以引入 Vue 组件级依赖（如 vue@^3.5.13）用于文档内交互演示，而不影响运行时前端的依赖体积；
  3. 部署自由度：产物是纯静态站点，可独立部署到任意静态托管，不需要与 localhost:51206 后端协同。

站点技术栈的关键事实（均来自源码证据）：

事实来源
VitePress 版本声明为 ^1.5.0docs/package.json
实际解析锁定版本为 vitepress@1.6.4pnpm-lock.yaml
Vue 版本声明为 ^3.5.13docs/package.json
提供 dev / build / preview 三个脚本docs/package.json
锁文件中还解析了 lightningcss、postcss、qrcode、search-insights、@algolia/client-search、typescript@6.0.3 等传递/可选依赖pnpm-lock.yaml

Architecture

Loading diagram...

上图反映了本子系统的核心设计决策：文档站是仓库内的一个独立 Node 项目。docs/package.json 是它的唯一入口配置，其依赖由根级 pnpm-lock.yaml 统一锁定（单一锁文件策略，避免多项目各自漂移）。docs/ 与 web/、后端之间用虚线表示——二者之间不存在任何构建期依赖，只存在"文档描述它们"这一内容层面关系。

对应的站点自身工作流架构如下：

Loading diagram...

三个脚本一一对应 VitePress 的标准三阶段：dev 提供热更新写作体验，build 产出纯静态站点，preview 在本地以生产模式校验产物。由于产物是纯静态的，部署环节不需要任何后端协同——这正是 AGENTS.md 中"not part of the runtime bundle"约定在部署层面的体现。

多语言结构

VitePress 的多语言采用目录约定 + 配置声明的机制，而非路由级翻译。核心模型是：

  • 每种语言对应源码根目录（默认 docs/）下的一个子目录，如 docs/en/、docs/zh/（目录名即 locale key，可自定义）；
  • 根目录（语言子目录之外）放置语言无关的资源（图片、公共组件等）；
  • docs/.vitepress/config 中的 themeConfig.locales 与顶层 locales 字段声明各语言的导航、侧边栏与 UI 文案翻译。
Loading diagram...

以语言环境切换时，VitePress 按当前 locale 的 link 前缀把请求映射到对应语言子目录，并套用该 locale 在 themeConfig.locales 中声明的侧边栏与 UI 字符串（如"上一页/下一页"、搜索框占位文案）。新增语言的标准流程是三步：建子目录 → 写内容 → 在 locales 中登记路由与主题翻译。

实现细节说明：本仓库 docs/.vitepress/config.mts 具体内容未能读取（源工具预算限制，且 ListFiles/Grep 未返回该目录下的枚举结果），因此上述多语言机制描述基于 VitePress ^1.5.0/1.6.4 的框架约定，仓库内实际的 locale key、目录命名与侧边栏结构以 docs/.vitepress/ 下真实文件为准。本页不做无证据的具体断言。

Usage Examples

以下摘录是 docs/ 作为独立 Node 项目的全部脚本与依赖声明，也是文档站的唯一入口配置：

json
1{ 2 "scripts": { 3 "dev": "vitepress dev", 4 "build": "vitepress build", 5 "preview": "vitepress preview" 6 }, 7 "devDependencies": { 8 "@types/node": "^24.10.2", 9 "vitepress": "^1.5.0", 10 "vue": "^3.5.13" 11 } 12}

Source: package.json

三个脚本分别承担：写作期热更新（dev）、生产构建（build）、产物本地预览（preview）。依赖全部位于 devDependencies——文档站没有运行时依赖，因为产物是构建期静态生成的，这再次印证了"不属于 runtime bundle"的设计。

版本声明（^1.5.0）与实际解析（1.6.4）在根级锁文件中被固化，保证所有协作者与 CI 构建得到完全相同的依赖树：

yaml
vitepress: specifier: ^1.5.0

Source: pnpm-lock.yaml

yaml
vitepress@1.6.4: resolution: {integrity: sha512-+2ym1/+0VVrbhNyRoFFesVvBvHAVMZMK0rw60E3X/5349M1GuVdKeazuksqopEdvkKwKGs21Q729jX81/bkBJg==}

Source: pnpm-lock.yaml

值得注意的设计细节：1.6.4 的解析记录带有一长串带括号的后缀 (@algolia/client-search@5.56.0)(@types/node@24.13.3)(lightningcss@1.33.0)(postcss@8.5.26)(qrcode@1.5.4)(search-insights@2.17.3)(typescript@6.0.3)——这是 pnpm 的 peer dependency 解析标记。它揭示了站点能力面：内置 Algolia 全文搜索（client-search + search-insights）、QR 码生成（qrcode，通常用于文档页生成访问二维码）、以及 CSS 处理链（lightningcss/postcss）。这些能力默认随 VitePress 提供，无需站点显式声明。

Configuration Options

站点级配置集中在 docs/package.json（脚本与依赖）与 docs/.vitepress/config（站点结构与主题）。已验证的配置项如下：

配置项类型默认/实际值说明
scripts.devstring"vitepress dev"本地开发服务器，Markdown 热更新
scripts.buildstring"vitepress build"生产构建，输出静态站点
scripts.previewstring"vitepress preview"本地预览构建产物
devDependencies.vitepresssemver range^1.5.0（锁定 1.6.4）文档框架版本声明
devDependencies.vuesemver range^3.5.13Vue 运行时，支撑文档内 Vue 组件
devDependencies.@types/nodesemver range^24.10.2Node 类型（供配置文件 config.mts 编写）
根级 pnpm-lock.yamllockfile—锁定 docs/ 依赖树，含 vitepress 的全部传递依赖

Failure Modes, Edge Cases & Concurrency

基于源码证据可确认的边界与故障面：

  • 运行时隔离故障面：docs/ 不属于 runtime bundle，因此文档站构建失败、依赖损坏或部署中断都不会影响 web/ 前端与后端的运行；反向上，后端未启动也不影响文档站的 dev/build/preview。这是本子系统最重要的故障隔离特性。
  • 端口边界：web/ 开发环境依赖后端 localhost:51206 并代理 /rpc、/static；文档站与此完全无关，二者并发开发时不会争用同一后端资源。由于文档站无后端依赖，本地可同时运行 docs 的 dev 与 web 的 dev 而互不干扰。
  • 版本漂移边界：声明 ^1.5.0 属于 caret 范围，理论上每次安装都可能取到新的 minor/patch；仓库以单一 pnpm-lock.yaml 将其固定在 1.6.4，避免"不同机器构建出不同文档"的一致性问题。
  • peer 依赖解析：锁文件中 vitepress 的 peer 后缀表明其能力面依赖多个可选 peer；若协作者在本仓库外单独维护文档站，可能出现 peer 组合差异。仓库内由 pnpm workspace 锁文件统一消除这一并发风险。
  • 限制说明：docs/.vitepress/config.mts 未能读取（工具预算），故本页无法验证仓库实际使用的 locale key 列表、ignoreDeadLinks 等构建容错配置，以及死链检查策略。这些属于未验证项，不做断言。

Performance / Operational Notes

  • 三阶段标准工作流：dev（写作）→ build（产物）→ preview（校验）是运维该站点的完整闭环；产物为纯静态文件，CDN/静态托管即可，无需服务器进程。
  • 独立部署：静态产物不依赖 localhost:51206 后端，可部署到与产品运行时不同的域名/托管方案。
  • 单锁文件策略：docs/ 的依赖并入根级 pnpm-lock.yaml，一次 pnpm install 同时覆盖运行时与文档站，减少 CI 步骤。
  • 搜索与体验能力：从锁文件的 peer 标记可见站点具备 Algolia 全文搜索与二维码生成能力（VitePress 内置），文档站无需额外自建搜索服务。

Extension Points

  • 新增语言：建 docs/<locale>/ 内容树 + 在 locales/themeConfig.locales 登记，即可扩展语言面（机制层面见上文"多语言结构"；仓库内具体 key 待以实际配置为准）。
  • 文档内交互组件：vue@^3.5.13 已就位，可在 Markdown 中直接使用 Vue 组件做交互式演示，无需改动运行时前端。
  • 构建脚本扩展：scripts 目前仅三条标准命令，可按需追加（如 build 前置死链校验），不影响其他子系统。
  • AGENTS.md — 仓库级约定：docs/ 为独立 VitePress 站点，不属于 runtime bundle
  • AGENTS.md — 仓库目录职责总览（android/、docs/、playground/）
  • docs/package.json — 文档站脚本与依赖声明
  • pnpm-lock.yaml — vitepress 版本声明与锁定解析
  • 运行时前端与 /rpc、/static 代理机制：见 web/ 相关姊妹页面（本页不展开）
  • Android 捕获守护进程：见 android/ 相关姊妹页面（本页不展开）