Project AIRI 文档站开发指南：从本地预览、类型检查到多语言侧边栏挂载的完整工作流
【免费下载链接】airi💖🧸 Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-sama's altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi
本篇指南讲解 Project AIRI 仓库中 VitePress 文档站（docs目录）的本地开发、校验构建与内容贡献流程：你会掌握如何通过pnpm dev:docs启动预览、用typecheck与build验证文档、以及新增英文页面时如何正确挂载到en侧边栏，使其不仅“能通过 URL 访问”，更“能出现在导航中”。结合仓库内的 docs/package.json、docs/.vitepress/config.ts 与 docs/netlify.toml，本篇将同时给出命令背后的真实脚本映射与配置依据，方便搜索引擎、Agent 与 LLM 直接定位到源码证据。
文档站的整体布局：按语言（locale）组织内容
Project AIRI 的官方文档站使用 VitePress 实际布局）：
docs/ ├── .vitepress/ # VitePress 站点配置、主题、组件与数据函数 │ ├── config.ts # 站点全局配置（导航、侧边栏、locales、markdown） │ ├── theme/ # 自定义主题样式与入口 │ ├── components/ # 首页/文档页自定义 Vue 组件 │ └── meta.ts # 站点名称、描述、社交链接等元信息 ├── content/ # 文档内容（即 VitePress 的 srcDir） │ ├── en/ # 英文（root locale，默认语言） │ ├── zh-Hans/ # 简体中文 │ ├── ja/ # 日语 │ ├── ko/ # 韩语 │ └── public/ # 站点级静态资源（图片、字体等） ├── package.json # 包名 @proj-airi/docs，文档站独立脚本 ├── tsconfig.json # 文档站 TS/Vue 类型检查配置 └── netlify.toml # Netlify 部署配置内容按语言组织是理解文档站的第一步：所有 Markdown 页面都位于docs/content/<locale>/之下，每个语言目录内部再按docs/、blog/、about/、references/等栏目分门别类。这个约定与 docs/.vitepress/config.ts 中的srcDir: 'content'设置一一对应——VitePress 会直接把content作为内容源目录，因此页面的相对链接、静态资源解析都以它为准。
如果你负责的文档改动涉及新语言或新栏目，首先就要在这个docs/content/<locale>树中确认目标位置，这与仓库里其它应用（如apps/stage-web、apps/stage-tamagotchi）以src/组织源码的惯例不同，属于文档站专属的“内容即目录”模式。
环境准备：pnpm 工作区与 Node 版本约束
文档站不是孤立项目，而是 monorepo 中的一个 pnpm workspace 成员。仓库根 package.json 声明了workspaces，其中明确包含docs/**；文档站的包名是@proj-airi/docs（见 docs/package.json），所有面向文档站的脚本都会通过包名精确筛选。
根 package.json 中dev:docs的真实定义是：
pnpm -rF @proj-airi/docs run dev即“递归地、仅针对@proj-airi/docs这个包执行其dev脚本”。理解这一点很重要：pnpm dev:docs不是硬编码的单个命令，而是 pnpm workspace 的过滤语法，-r表示递归进入工作区子包，-F（--filter）表示只选择@proj-airi/docs。
在运行任何 pnpm 命令之前，建议先按仓库约定准备好 Node 环境：
- 仓库通过根目录 .tool-versions 固定 Node.js 版本（当前为
nodejs 26.7.0），推荐使用 mise 之类的版本管理器读取该文件； - 启用 Corepack 以获得仓库锁定的 pnpm（根
package.json中packageManager声明为pnpm@11.24.0）； - 首次开发时执行
mise install安装固定版本，再用mise exec -- pnpm install安装依赖。
如果你已经配置过 mise 的 shell shims，那么后续命令可以直接写pnpm ...；否则需要套用mise exec -- pnpm ...的形式。
本地开发预览：pnpm dev:docs
从仓库根目录执行：
pnpm dev:docs该命令会启动 VitePress 的开发服务器。由于底层是 docs/package.json 中的vitepress dev，你得到的是标准的 VitePress 热更新开发体验：编辑docs/content/<locale>/**/*.md或docs/.vitepress下的配置文件后，浏览器会即时刷新，非常适合边写文档边校对排版、代码块高亮与侧边栏层级。
如果你习惯使用 @antfu/ni 这类统一包管理器命令的工具，可以等价地运行：
nr dev:docsnr会自动探测仓库使用的包管理器（这里是 pnpm）并转发到对应的run命令。这只是一个开发体验上的等价替换，pnpm dev:docs与nr dev:docs指向同一个脚本。
校验与构建：typecheck 与 build
改动文档后、提交之前，文档站提供了两个独立的验证命令，建议按顺序执行：
pnpm -F @proj-airi/docs typecheck pnpm -F @proj-airi/docs buildtypecheck：把 Markdown 当作 Vue 组件做静态检查
pnpm -F @proj-airi/docs typecheck对应 docs/package.json 中的vue-tsc --noEmit。关键在于 docs/tsconfig.json 的两处配置：
vueCompilerOptions.vitePressExtensions: [".md"]——让vue-tsc把.md文件当作 VitePress 扩展的 Vue 单文件组件来处理；types: ["vitepress/client", "vue"]——提供 VitePress 客户端上下文与 Vue 的类型声明。
这意味着文档里的 Vue 组件片段、frontmatter 使用方式乃至模板语法都会纳入类型检查，能从早期拦截拼写错误或类型不匹配，而不只是渲染时才暴露问题。这也解释了为什么文档站虽然全是 Markdown，却拥有与源码工程一致的严格类型检查（strict: true）。
build：生成可发布的静态站点
pnpm -F @proj-airi/docs build对应 docs/package.json 中的vitepress build，产物输出到docs/.vitepress/dist。除此之外，docs/package.json 还提供了三个与构建/预览相关的脚本：
| 脚本 | 命令 | 用途 |
|---|---|---|
build | vitepress build | 标准生产构建，产物在docs/.vitepress/dist |
build:base | BASE_URL=/docs/ vitepress build | 以子路径/docs/为 base 的构建（子路径部署场景） |
preview | vitepress preview | 本地预览已构建的产物，验证生产结果 |
build:base与 docs/.vitepress/config.ts 中的withBase辅助函数相配合：config.ts会根据环境变量BASE_URL动态拼接导航与侧边栏链接，保证站点部署在域名根路径或/docs/子路径下都能正确解析。
新增英文页面：侧边栏挂载是关键步骤
文档站新增内容的规范流程，在关联文档中有一条核心警告：
新增英文页面时，还要把它加到
docs/.vitepress/config.ts的en侧边栏中；否则该页面虽然可以通过 URL 访问，却不会出现在导航里。
也就是说，“文件存在”与“导航可见”在 VitePress 中是两回事。一个完整的“新增英文文档页”工作流如下：
- 创建内容文件：在
docs/content/en/docs/<栏目>/下新建 Markdown 文件，并在 frontmatter 中写title与description（与现有页面保持一致的元信息风格）。 - 挂载到侧边栏：打开 docs/.vitepress/config.ts，在
enlocale 的themeConfig.sidebar数组中，找到对应的分组（例如Developer Guide → Contributing分组），添加形如{ text: '页面标题', link: withBase('/en/docs/contributing/<页面名>') }的条目。 - 注意
withBase包装：侧边栏与导航中的链接一律通过withBase()生成，它读取env.BASE_URL并把站点基础路径拼到链接前，避免子路径部署时链接失效。 - 同步其它语言侧边栏：仓库配置了
root（英文）、zh-Hans、ja、ko四个 locale，每个 locale 都有独立的sidebar数组。英文侧边栏中的“Documentation Site”等条目在 docs/.vitepress/config.ts 中一一对应到各语言的docs/contributing/docs页面，因此新增或改名页面时，通常需要同步维护四份侧边栏，保持导航结构一致。
这条规则是文档站贡献中最容易踩坑的地方：只创建文件而不更新侧边栏，页面会“存在但隐形”。另外，config.ts中开启了cleanUrls: true，URL 中不需要.html后缀，侧边栏链接统一写目录/文件名路径即可。
站点配置速览：config.ts 的可复用要点
.vitepress/config.ts 是整个文档站的“控制中心”，其中有几个与文档写作直接相关的配置值得了解：
- 多语言架构（locales）：
root（en）、zh-Hans、ja、ko四个 locale 各自声明label、lang与独立的themeConfig（导航、侧边栏、按钮文案），保证多语言内容在导航层面互不干扰； - Markdown 增强插件：
markdown.config中启用了tasklist（任务列表）与footnote（脚注）两个markdown-it插件，因此文档中可以放心使用- [ ]任务列表与[^1]脚注语法（见 config.ts）； - 代码高亮主题：
markdown.theme使用 catppuccin 主题，亮色catppuccin-latte、暗色catppuccin-mocha（config.ts），代码块默认配色会随站点主题切换； - 站内搜索：
themeConfig.search.provider: 'local'，启用 VitePress 内置本地全文搜索，无需外部服务； - 其它细节：
appearance: 'dark'默认暗色外观、lastUpdated: true显示最后更新时间、sitemap生成站点地图、head中注入 Open Graph 与 Twitter 卡片等 SEO 元信息。
写作文档时引用以上能力的配置位置，比口头描述更可信；例如“页面是否出现在搜索里”其实由search.provider与页面 frontmatter 共同决定。
生产部署：netlify.toml 中的真实构建链路
仓库为文档站提供了 Netlify 部署配置 docs/netlify.toml，与本地命令形成完整的“开发—校验—部署”闭环：
[build] base = "/" command = "pnpm -F @proj-airi/docs run build" publish = "/docs/.vitepress/dist" [build.environment] NODE_VERSION = "24" NODE_OPTIONS = "--max-old-space-size=4096"几点值得注意：
- 构建命令与本地完全一致：CI 上执行的正是
pnpm -F @proj-airi/docs run build，也就是说本地通过build验证过的内容，部署结果与本地一致； - 发布目录指向
docs/.vitepress/dist，即 VitePress 的标准输出目录； - 环境变量中
NODE_VERSION = "24"是 Netlify 构建环境使用的 Node 大版本，而本地开发则以 .tool-versions 锁定的版本为准——两者不必完全相同，只要构建产物在目标环境可复现即可； - 若部署目标是域名子路径，可改用
pnpm -F @proj-airi/docs run build:base，配合BASE_URL=/docs/与withBase()完成子路径适配。
文档贡献的完整上下文
docs.md属于contributing（参与贡献）文档族，同一目录下还有一系列相关指南，建议组合阅读以形成完整工作流：
- docs/content/en/docs/contributing/index.md：开发环境搭建与首次 Pull Request 的完整流程（Fork → Clone → 建分支 → 安装依赖 → 提交 → 创建 PR），是“文档之外”的贡献规范底座；
- docs/content/en/docs/contributing/tamagotchi.md 与 docs/content/en/docs/contributing/webui.md：分别针对桌面端与 Web 端的开发指引；
- docs/content/en/docs/contributing/desktop-developer-tools.md：应用内调试工具说明；
- docs/content/en/docs/contributing/design-guidelines/index.md：设计资源与工具指南。
从仓库根 package.json 还能看到，提交前整个仓库还要求通过pnpm lint（moeru-lint .）与pnpm typecheck（递归覆盖packages/*、apps/*、server/**与docs的并行类型检查）。文档改动虽然只影响docs目录，但仍建议至少在文档站范围内跑一次typecheck，把 Markdown-as-Vue 的潜在错误扼杀在提交之前。
常见问题与排查要点
根据上面的源码证据，整理几个文档站开发中容易遇到的状况：
- 页面能通过 URL 打开但导航里找不到：几乎可以确定是漏改了 docs/.vitepress/config.ts 中对应 locale 的
sidebar。这是关联文档明确点名的第一陷阱。 - 其它语言侧边栏不同步：四个 locale 各自维护侧边栏数组，新增英文页面后，
zh-Hans、ja、ko侧边栏需要按需同步，否则多语言导航结构会出现差异。 - 构建失败与类型错误：优先检查文档中嵌入的 Vue 组件片段是否符合
vue-tsc的检查规则；vueCompilerOptions.vitePressExtensions: [".md"]会把.md纳入检查范围，错误信息会精确到文件与行号。 - 死链接策略：
config.ts中设置了ignoreDeadLinks: true，VitePress 构建时不会因个别失效内部链接而中断——但这并不意味着可以随意留死链，建议仍然人工核对新增页面间的相互引用。
从pnpm dev:docs的本地热更新，到typecheck/build的双重验证，再到en侧边栏挂载与 Netlify 部署，这条文档站开发链路在仓库中均有对应的脚本与配置文件可查证。对新手贡献者而言，最值得记住的一句话是：新增页面 = 创建docs/content/<locale>下的 Markdown 文件 + 在对应 locale 的侧边栏注册条目，两步缺一不可。
【免费下载链接】airi💖🧸 Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-sama's altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
