基于 Docusaurus 3 构建与部署 Clappr 官方文档站点
基于 Docusaurus 3 构建与部署 Clappr 官方文档站点
Clappr 官方文档站点位于本仓库的 apps/clappr.io 目录,是一套基于 Docusaurus 3 构建的静态文档网站,承载着 Getting Started、插件开发指南、事件体系、API 参考、FAQ 等全部开发者文档。本文以该目录的 README 为核心,完整讲解文档站点的依赖安装、本地开发、静态构建与发布部署全流程,并结合仓库内的 docusaurus.config.js、sidebars.js、package.json 等真实配置文件,剖析站点导航、国际化、主题样式等细节,帮助你在本地复刻出 Clappr 官方文档环境,并将其发布到任意静态托管服务。
一、站点概览:文档仓库的组织方式
apps/clappr.io 是 monorepo(Lerna workspaces)中的一个独立包,包名为 clappr-docs,其定位就是 Clappr 项目的官方文档站点。整个站点围绕 Docusaurus 3 展开:
- 文档内容位于 apps/clappr.io/docs 目录,包含
getting_started.md、guides/events.md、guides/how_to_build_plugins.md、supported_formats.md、architecture.md、api.md、faq.md等 Markdown 文件; - 站点配置由 docusaurus.config.js 定义,包括站名、导航栏、页脚与代码高亮主题;
- 侧边栏结构由 sidebars.js 控制,决定文档在页面左侧的展示层级;
- 多语言资源存放在 apps/clappr.io/i18n 目录,目前包含英文(默认)与巴西葡萄牙语(pt-BR)两套 locale;
- 自定义组件与样式位于 apps/clappr.io/src,包括首页
HomepageFeatures组件与全局 CSS。
从 docusaurus.config.js 可以看到站点的元信息:title: 'Clappr',tagline: 'An extensible media player for web applications',baseUrl: '/',且开启了 onBrokenLinks: 'throw'——即站点构建时若出现失效链接会直接报错,这保证了文档站点链接的严谨性。
二、环境要求
根据 apps/clappr.io/package.json 与仓库根目录 package.json 中的声明,运行文档站点需要满足:
| 依赖 | 版本要求 | 说明 |
|---|---|---|
| Node.js | >= 24 |
两处 engines 字段均声明了该下限 |
| Yarn | 1.22(classic) | 仓库根目录 packageManager 字段固定为 yarn@1.22.21 |
| Docusaurus | 3.10.2(@docusaurus/core 与 @docusaurus/preset-classic) |
依赖声明见 package.json |
| React / ReactDOM | ^19.0.0 |
与 Docusaurus 3 配套的运行时 |
由于 apps/clappr.io 是 monorepo workspace(根目录 package.json 的 workspaces 字段包含 apps/* 与 packages/*),依赖建议在仓库根目录统一安装,而不是单独进入 apps/clappr.io 目录执行。官方 README 给出的安装命令同样是在项目根目录执行。
三、安装依赖
在仓库根目录执行:
yarn
该命令会按照 yarn.lock 锁定的版本为整个 monorepo(包括 apps/* 与 packages/* 下的所有包)安装依赖。由于 Docusaurus 3 的依赖树较大,首次安装可能需要一些时间。安装完成后,apps/clappr.io/node_modules 中即可使用 @docusaurus/core 与 @docusaurus/preset-classic。
四、本地开发:yarn start
yarn start
该命令实际上调用的是 apps/clappr.io/package.json 中的 docusaurus start 脚本。执行后会发生三件事:
- 启动本地开发服务器,默认监听
http://localhost:3000(Docusaurus 3 默认端口); - 自动打开浏览器窗口,直接展示文档首页;
- 启用热重载(live reload),大多数改动会即时反映到页面上,无需手动重启服务器——修改
docs目录下的 Markdown、docusaurus.config.js、sidebars.js或src下的组件/CSS 都能实时生效。
开发服务器的核心价值在于:你可以一边编辑 docs 目录下的文档,一边在浏览器中预览渲染效果,同时利用 onBrokenLinks: 'throw' 与 onBrokenMarkdownLinks: 'warn'(见 docusaurus.config.js)及时捕获链接与文档错误。
五、静态构建:yarn build
yarn build
对应脚本为 docusaurus build。执行后,Docusaurus 会完成以下工作:
- 解析并渲染 docs 下的全部 Markdown 文档,生成 HTML 页面;
- 编译 src 下的 React 组件(首页、自定义功能块等),打包 JavaScript 与 CSS 资源;
- 处理 i18n 目录中的翻译资源,为
en与pt-BR两种语言分别生成站点; - 将全部静态产物输出到
build目录。
构建产物是纯静态文件(HTML / JS / CSS / 图片),可以部署到任何静态内容托管服务(如 Nginx、对象存储静态网站托管、CDN 等),无需 Node.js 运行时支持。这正是 README 中强调的:"can be served using any static contents hosting service"。
构建前自查
由于配置了 onBrokenLinks: 'throw',如果文档中存在指向不存在的页面或资源的内链,yarn build 会直接失败并给出明确错误。这一机制保障了线上文档不会出现 404 死链,也是该站点工程质量较高的原因之一。
六、发布部署:yarn deploy
README 给出了两种部署方式,均基于 Docusaurus 内置的 docusaurus deploy 命令。
方式一:使用 SSH 认证
USE_SSH=true yarn deploy
设置环境变量 USE_SSH=true 后,Docusaurus 会使用本机的 SSH 密钥完成与远程仓库的认证,适合已在 GitHub 配置过 SSH Key 的开发者。
方式二:使用 GIT_USER 认证
GIT_USER=<Your GitHub username> yarn deploy
不依赖 SSH 时,通过 GIT_USER 环境变量传入 GitHub 用户名,Docusaurus 会结合本地的 Git 凭据完成推送。
部署到 GitHub Pages
README 特别说明:如果使用 GitHub Pages 托管,yarn deploy 是构建网站并推送到 gh-pages 分支的便捷方式。其背后逻辑是:
- 先执行一次构建,生成最新静态产物;
- 将产物提交并推送到当前仓库的
gh-pages分支; - GitHub Pages 自动从该分支发布站点。
与之对应的部署配置在 docusaurus.config.js 中已经就绪:organizationName: 'clappr'、projectName: 'clappr'——这两个字段正是 Docusaurus 计算 GitHub Pages 推送目标仓库所需的元数据。
七、站点配置深度解析:docusaurus.config.js
apps/clappr.io/docusaurus.config.js 是该站点唯一的总配置入口,全文开启了 // @ts-check 类型检查注解,便于编辑器提供自动补全。核心配置项如下:
| 配置项 | 当前值 | 作用 |
|---|---|---|
title / tagline |
Clappr / An extensible media player for web applications |
站点标题与副标题,显示在浏览器标签与首页 Hero 区 |
url |
https://clappr.io |
站点对外域名,用于生成规范的站点链接 |
baseUrl |
/ |
站点资源根路径 |
onBrokenLinks |
throw |
构建时发现失效链接直接报错 |
favicon |
img/favicon.ico |
站点图标,对应 static/img/favicon.ico |
i18n |
默认 en,支持 ['en', 'pt-BR'] |
开启国际化,默认英文、支持巴西葡萄牙语 |
presets |
classic preset |
启用 docs 侧边栏与自定义主题 CSS |
themeConfig.navbar |
导航栏含 Docs、API、GitHub、语言切换 | 对应首页顶部导航 |
themeConfig.footer |
深色页脚,含 Learn 与 Community 链接 | 对应页面底部 |
themeConfig.prism |
GitHub / Dracula 双主题 | 代码块明暗主题切换 |
其中导航栏配置(docusaurus.config.js)使用了 localeDropdown 类型的导航项,配合 i18n 配置实现页面右上角的语言切换下拉菜单——这是该站点支持多语言文档的 UI 入口。
八、文档结构与侧边栏:sidebars.js
apps/clappr.io/sidebars.js 定义了文档页面的左侧导航结构:
- 顶层依次为
getting_started(快速上手)、Guides分类(内含guides/events与guides/how_to_build_plugins)、supported_formats(支持的格式)、architecture(架构)、api(API)、faq(FAQ); Guides分类设置了type: 'generated-index',表示自动生成分类索引页;collapsed: false保证分类默认展开,提升文档可达性。
该文件直接引用了 docs 目录下的 Markdown 文件名(不含扩展名),是理解整个文档站点信息架构的关键文件。你可以在本地开发模式下修改它来调整导航顺序,热重载会立即生效。
九、文档站点的国际化:i18n 目录
站点支持英文与巴西葡萄牙语两种语言,翻译资源存放在 apps/clappr.io/i18n:
pt-BR/docusaurus-plugin-content-docs/current/:文档正文的葡萄牙语翻译,例如guides/plugins/metrics.md;pt-BR/docusaurus-theme-classic/footer.json与navbar.json:页脚与导航栏的翻译;code.json:代码与界面文案的翻译。
当访问者切换语言时,Docusaurus 会根据 locale 优先读取翻译文件,未翻译的内容回退到英文原文。如需新增语言,只需在 docusaurus.config.js 的 locales 数组中追加语言代码,并补充对应的翻译文件。
十、首页与自定义样式:src 目录
站点首页由 apps/clappr.io/src/pages/index.js 驱动,使用 @docusaurus/Translate 组件实现多语言文案,页面 Hero 区包含 "Get Started" 与 "Try a Demo" 两个按钮。首页下方的特性区块由 HomepageFeatures 组件渲染,其配套样式位于 styles.module.css。
全局样式通过 docusaurus.config.js 中的 customCss 引入,即 src/css/custom.css。所有页面级样式(如 index.module.css)采用 CSS Modules 方式局部作用,避免样式污染。
十一、站点维护辅助命令
apps/clappr.io/package.json 中还声明了其他常用脚本,属于 Docusaurus 3 的标准维护命令:
| 命令 | 脚本 | 用途 |
|---|---|---|
yarn swizzle |
docusaurus swizzle |
抽取 Docusaurus 默认主题组件到本地,便于深度定制 |
yarn clear |
docusaurus clear |
清空 Docusaurus 的构建缓存(.docusaurus 目录),解决构建异常 |
yarn serve |
docusaurus serve |
在本地预览构建产物,模拟线上部署效果 |
yarn write-translations |
docusaurus write-translations |
生成/更新多语言翻译模板文件 |
yarn write-heading-ids |
docusaurus write-heading-ids |
为文档标题生成稳定的锚点 ID |
例如,当你修改了导航栏结构或新增文档后,可用 yarn write-translations 刷新 i18n 模板,再用 yarn build 验证产物,最后通过 yarn serve 在本地模拟线上效果。
十二、与整个 Clappr 仓库的关系
文档站点包 clappr-docs 通过 Lerna 参与仓库的版本发布流程(见根目录 lerna.json 与 CHANGELOG.md)。从变更日志可以看到,文档站点的链接修复与跨站互链(如 1.1.0 的 "add website cross-linking and fix documentation")都是作为独立版本随主项目一起发布的。这意味着:
- 文档站点与播放器源码(
packages/clappr-core、packages/clappr-plugins等)共处于同一仓库,便于文档与代码同步演进; - 每次发布时
clappr-docs会独立打版本号并记录在 CHANGELOG.md 中。
在仓库根目录还可以通过 yarn dev(启动 @clappr/player 开发服务)体验播放器本体,与 yarn start(文档站点)互不冲突,两者是同一 monorepo 中相互独立的两套开发环境。
十三、从零到线上的完整操作清单
综合 README 与仓库实际配置,一次完整的文档站点发布流程如下:
# 1. 在仓库根目录安装依赖(Node >= 24,Yarn 1.22)
yarn
# 2. 本地开发,实时预览文档改动
yarn start
# 3. 构建静态产物(输出到 build/ 目录)
yarn build
# 4. 部署到 GitHub Pages(二选一)
USE_SSH=true yarn deploy
# 或
GIT_USER=<Your GitHub username> yarn deploy
# 5. 若使用非 GitHub Pages 的静态托管,直接将 build/ 目录
# 上传到任意静态站点服务即可
整个流程体现了 Docusaurus 3 文档站点的标准工作流:依赖安装 → 热更新开发 → 静态构建 → 分支推送或任意静态托管。其中 yarn deploy 的 USE_SSH 与 GIT_USER 两种认证方式,覆盖了 SSH 与 HTTPS 两类 Git 凭据场景,配合 GitHub Pages 的 gh-pages 分支机制即可实现文档的一键发布。