LichtFeld Studio 是一个用于训练、检视、编辑、自动化与导出 3D Gaussian Splatting 场景的原生应用，其官方技术文档站点位于仓库docs目录，基于 Docusaurus 静态站点生成器构建。本篇指南以 docs/README.md 为骨架，完整讲解该文档站点的环境准备、本地开发、实时预览与生产构建流程，并结合仓库内的package.json、docusaurus.config.ts与文档目录结构进行源码级纵深解读。读完本文，你将能独立在任意机器上搭建该文档站点开发环境、进行热更新迭代，并产出可被任意静态托管服务承载的构建产物。

一、文档站点概览：Docusaurus + pnpm + TypeScript

LichtFeld Studio 的文档站点不是普通的 Markdown 文件夹，而是一个完整的 Docusaurus 工程。仓库根目录下docs/中承载了站点源码、内容与构建配置：

• 站点生成器：Docusaurus（核心与经典预设均为3.8.1，见 docs/package.json）；
• 包管理器：pnpm，并在package.json的packageManager字段中锁定为pnpm@10.11.0；
• 前端技术栈：React 19、React DOM 19，配合@mdx-js/react与prism-react-renderer实现 MDX 与代码高亮；
• 配置方式：TypeScript 配置文件 docs/docusaurus.config.ts 与 docs/tsconfig.json；
• 内容组织：站点文档主体位于 docs/docs/，覆盖开发指南、功能特性与安装说明等多个栏目。

docs/README.md明确强调了一条重要的使用约束：所有命令均需在docs目录下执行。这是因为package.json、pnpm-lock.yaml与 Docusaurus 配置都位于docs内，若在仓库根目录直接运行pnpm start将无法找到对应的工程配置。因此后续所有操作都以docs作为工作目录，例如cd docs之后再执行命令。

二、环境准备：Node.js 与 pnpm

根据 docs/README.md，构建文档站点需要两个前置条件：

docs/package.json中engines.node明确为>=18.0，且packageManager字段记录了精确的 pnpm 版本与校验哈希，这意味着使用 Corepack 或pnpm@10.11.0可以获得与 CI、维护者完全一致的依赖解析环境。开发机上安装好 Node.js 18+ 后，通过任意官方渠道安装 pnpm 即可进入下一步。

三、本地开发：安装依赖并启动热更新服务

1. 安装依赖

在docs目录下执行：

pnpm install

该命令会根据docs/pnpm-lock.yaml（锁定文件共一万余行，完整记录了 Docusaurus 3.8.1 及其传递依赖的精确版本）安装全部依赖。由于 lockfile 已提交入库，pnpm install会按锁定版本安装，保证不同机器上的依赖树一致。

2. 启动开发服务器

pnpm start

该命令对应 docs/package.json 中的"start": "docusaurus start"，其行为包括：

• 启动本地开发服务器并自动打开浏览器窗口；
• 监听源文件变更，大部分改动无需重启服务器即可实时反映在页面中（热更新）；
• 提供开发期错误提示与断链警告反馈。

在开发模式下，你修改docs/docs/下的 Markdown/MDX 文档、docs/src/css/custom.css样式或 docs/docusaurus.config.ts 配置，浏览器都会就近刷新，非常适合边写作边校对。

3. 常用开发辅助脚本

除start外，docs/package.json还提供了若干开发配套命令：

其中typecheck依赖 docs/tsconfig.json，该配置继承了@docusaurus/tsconfig，并将.docusaurus与build目录排除在编译范围之外，保证类型检查只针对站点源码与配置文件。

四、生产构建：生成静态产物并部署

文档站点的发布环节同样简单，在docs目录下执行：

pnpm build

该命令对应"build": "docusaurus build"，会将全部文档内容编译为静态站点输出到build目录。docs/README.md明确指出：构建产物可以被任意静态内容托管服务直接承载——这意味着无论是 GitHub Pages、对象存储、Nginx、CDN 还是自建文件服务器，只需将docs/build下的文件原样发布即可上线，无需任何后端运行时。

构建产物本地预览

若想在发布前验证构建结果，可使用配套命令：

pnpm serve

它对应docusaurus serve，会在本地以静态方式托管build目录，模拟线上访问效果，便于检查路由、资源路径与最终渲染是否正常。

部署

docs/package.json还内置了pnpm deploy（docusaurus deploy），可配合托管平台完成一键部署；默认配置 docs/docusaurus.config.ts 中预留了organizationName/projectName等 GitHub Pages 部署字段（当前处于注释状态），实际部署时需按托管目标填写url与baseUrl。

五、站点配置深度解读：docusaurus.config.ts

作为文档站点的中枢，docs/docusaurus.config.ts 定义了站点的全部关键行为，理解它有助于你安全地调整站点而不破坏构建：

• 站点身份：title为LichtFeld Studio，favicon指向img/favicon.ico（静态资源位于 docs/static/img/）；
• 路由布局：docs.routeBasePath设为/，即文档直接挂载在站点根路径，而非/docs子路径；blog: false关闭了博客模块，站点只承载技术文档；
• 严格链接校验：onBrokenLinks: 'throw'、onBrokenMarkdownLinks: 'warn'——任何失效的内部链接都会导致构建失败或告警，这是文档质量的一道自动化闸门，也解释了为何文档中的相对路径必须保持正确；
• 国际化：i18n.defaultLocale为en，当前仅启用英文；
• 代码高亮：prism.theme使用 GitHub 亮色主题、darkTheme使用 Dracula 暗色主题，并额外注册了powershell语言支持，与仓库内大量.ps1构建脚本（如根目录的build_lichtfeld.ps1、eval/benchmark_mipnerf360.ps1）的文档展示需求相匹配；
• 自定义样式：theme.customCss指向./src/css/custom.css，即 docs/src/css/custom.css，可在不重写主题组件的前提下覆盖全局样式；
• 导航与页脚：顶部导航栏与页脚均配置了指向项目主页的入口，页脚采用深色风格。

future.v4标志位也已开启，用于提前兼容即将到来的 Docusaurus v4 行为——这是仓库在当前版本上的前瞻性配置，升级大版本前可留意其影响。

六、文档内容组织：docs/docs 目录结构

站点正文全部位于 docs/docs/，采用按主题分栏的目录结构，与构建流程共同构成完整的文档工程：

• installation/：安装指南，含 Windows 源码构建说明，并记录了对 Windows Defender 误报的处理流程（包括用Get-FileHash -Algorithm SHA256校验构建产物哈希、向微软安全中心提交申诉等维护者操作）；
• development/：面向开发者的工作流文档，围绕执行工作流而非源码归属组织，涵盖 MCP 指南（含编辑器接入、数据集加载与训练、导出场景等 Recipes）、组件（Components）、RmlUI 样式、UI 设计语言、开发者标志与诊断（flags）、偏好与用户存储、场景重建等主题；
• features/：功能特性文档，包括 GUT、PoseOptimizer（poseopt）、主题（themes）与延时摄影（timelapse）等模块；
• faq.md：常见问题，当前内容指向项目 Wiki；
• index.md：站点首页，标注sidebar_position: 1作为侧边栏首项。

各目录通过_category_.json声明分类元数据（如 docs/docs/development/mcp/category.json、docs/docs/development/mcp/recipes/category.json 等），控制栏目在侧边栏中的位置与折叠行为；顶层页面则用 frontmatter 的sidebar_position字段排序。你在新增文档时，只需把 Markdown 文件放入对应栏目目录，Docusaurus 会自动将其纳入侧边栏与搜索索引。

七、版本与依赖基线速查

docs/package.json中可确认的关键版本基线如下，供搭建环境时对齐：

• @docusaurus/core、@docusaurus/preset-classic：3.8.1
• react/react-dom：^19.0.0
• typescript：~5.6.2
• packageManager：pnpm@10.11.0
• engines.node：>=18.0

浏览器兼容目标（browserslist）也已在工程中预置：生产环境面向全球使用率大于 0.5% 且仍在维护的浏览器，开发环境面向最近三个大版本的 Chrome、Firefox 与 Safari。

八、常见问题与注意事项

1. 命令必须在docs目录下执行：package.json与锁文件均在docs内，从仓库根目录运行会提示找不到工程；先cd docs再执行pnpm install/pnpm start/pnpm build。
2. 构建因断链失败：配置将onBrokenLinks设为throw，文档中任何指向不存在文件的相对链接都会让pnpm build失败，这是刻意为之的质量约束，修复链接即可通过。
3. 缓存导致的异常表现：若改配置或目录后行为异常，先执行pnpm clear清理.docusaurus缓存再重新start。
4. Node 版本过低：低于 18 的 Node 无法满足engines.node要求，安装器或 Corepack 会给出提示，请升级运行时。
5. 部署前的最后一步：发布前用pnpm build生成docs/build静态产物，并用pnpm serve本地预检；该产物与仓库源码解耦，可交由任意静态托管服务发布。

综上所述，LichtFeld Studio 的文档站点是一条完整、可复现的静态站点流水线：以 pnpm 锁定依赖版本，以 Docusaurus 3.8.1 + React 19 构建，以start支撑实时写作、以build产出可随处托管的静态产物，并以严格断链校验守护文档质量。掌握 docs/README.md 中这套流程，你就能像维护代码一样维护这套技术文档，并随时将其发布到任意静态托管环境。