Remotion 文档站本地启动实操：从 monorepo 构建到 Docusaurus 预览的完整链路

本篇技术指南以 Remotion 仓库中的 Agent 技能文档 .agents/skills/docs/SKILL.md 为主体，拆解"准备 monorepo → 启动 Docusaurus 文档站 → 获取并打开本地 URL"这一完整工作流。读完后，你将能够独立在本地拉起 Remotion 官方文档站点，并理解 bun run start 背后串联的原始文档导出、monorepo 构建任务图与 Twoslash 代码补全等关键机制。

一、技能文档定位：/docs 背后的自动化工作流

.agents/skills/docs/SKILL.md 是 Remotion 仓库内置的一个 Agent 技能定义文件，其 frontmatter 元数据如下：

• name: docs
• description 说明了触发时机：当用户调用 /docs 或 $docs、要求启动本地文档站、或希望在 Docusaurus 中预览文档改动时启用该技能。

同名技能的接口元数据还保存在 .agents/skills/docs/agents/openai.yaml 中，其中 display_name 为 "Docs Site"、short_description 为 "Run the Remotion docs locally"、默认提示词为 "Use $docs to build Remotion and open the docs site locally."。

该技能的核心目标（原文档 Overview 一节）是：准备 Remotion monorepo，启动 Docusaurus 文档站，并在 Codex 内嵌浏览器中打开服务地址。下文按原文档的五步工作流展开，并逐一步入源码层面。

二、五步标准工作流

步骤 1：在仓库根目录安装依赖并构建 monorepo

bun i && bun run build

这一步的依据来自仓库根目录 package.json：

• build 脚本定义为 turbo run make --no-update-notifier（package.json 第 12 行），即通过 Turborepo 触发所有工作区的 make 任务；
• 仓库声明 packageManager 为 bun@1.3.3，turbo 版本为 2.9.14，因此必须使用 bun 作为运行环境；
• workspaces.packages 配置为 packages/**（附带若干排除项，如 whisper.cpp 子目录、packages/bugs 等），说明这是一个覆盖上百个包的大型 monorepo。

从 turbo.json 的任务图看，make 任务声明了 "dependsOn": ["^make"] 与 "outputs": ["dist"]（turbo.json 第 81–85 行），意味着每个包会按依赖拓扑先构建其上游依赖，最终产出各自的 dist 目录——这正是文档站能引用 workspace:* 包（如 remotion、@remotion/player、@remotion/lambda 等）的前提。

步骤 2：进入 packages/docs 启动文档站

cd packages/docs && bun run start

这一步是整条链路中最复杂的一环。查看 packages/docs/package.json 第 12 行，start 脚本实际是一个由 bun 串联的多阶段管道：

bun copy-raw-docs.ts \
  && bun fetch-prompt-submissions.ts \
  && bun update-prompt.ts \
  && cd .. && bun run build && cd docs \
  && bun prepare-browser-studio-workspace.ts \
  && [Twoslash 环境变量判断与提示] \
  && REMOTION_DOCS_DISABLE_TWOSLASH=1 docusaurus start --host 0.0.0.0

可以把它拆解为六个阶段：

1. 导出原始 Markdown：执行 copy-raw-docs.ts，把 MDX 文档转换为供外部消费者使用的纯 Markdown（详见第四节）；
2. 抓取提示词提交数据：执行 fetch-prompt-submissions.ts 与 update-prompt.ts；
3. 回到仓库根目录重新构建：cd .. && bun run build，确保文档站依赖的所有 workspace 包均为最新构建产物；
4. 准备 Browser Studio 工作区：执行 prepare-browser-studio-workspace.ts，为文档中的在线 Studio 演示环境做准备；
5. Twoslash 开发开关：脚本读取环境变量 REMOTION_DOCS_ENABLE_TWOSLASH。若为 1 则打印 "🧪 Twoslash is enabled in development."，否则提示 "⚡ Twoslash is disabled in development for faster startup." 并给出开启方式 REMOTION_DOCS_ENABLE_TWOSLASH=1 bun run start；
6. 启动 Docusaurus 开发服务器：以 REMOTION_DOCS_DISABLE_TWOSLASH=1 docusaurus start --host 0.0.0.0 收尾。注意 --host 0.0.0.0 表示监听所有网络接口，便于在容器或远程开发环境中访问。

此外，packages/docs/package.json 还暴露了与文档站相关的其他入口，例如 build-docs（生产构建）、serve/clear/deploy、lint（对 src components standalone 做 ESLint）、remotion（remotion studio src/remotion/entry.ts --no-open，用于文档站内的 Remotion 预览）、render-cards 与 render-element-previews 等。

步骤 3：保持服务运行并读取本地 URL

原文档要求：保持服务器进程运行，读取其输出中的本地 URL。默认预期为 http://localhost:3000，但若 Docusaurus 选择或报告了其他端口，应以其实际打印的 URL 为准。

这一点在 turbo.json 的 build-docs 任务（第 106–128 行）中也有呼应：env 字段显式声明了 REMOTION_DOCS_DISABLE_TWOSLASH 与 REMOTION_DOCS_ENABLE_TWOSLASH 两个环境变量参与构建缓存决策，说明这两个开关会切实影响产物内容，而非仅仅是启动提示。

步骤 4：在 Agent 内嵌浏览器中打开

原文档指示：在 Codex 内嵌浏览器中打开该 URL；若当前还没有可用的浏览器工具，先通过 tool_search 查找内嵌浏览器控制工具，再导航到本地 URL。这一步是面向 Agent 执行环境的操作约定，人工开发者直接在系统浏览器访问 http://localhost:3000 即可。

步骤 5：向用户报告结果

最后需要告知用户文档站 URL，并说明这是新启动的服务还是已在运行的服务，避免用户误以为存在两个文档服务器进程。

三、启动前的构建任务图：build-docs 依赖了什么

除了 start 流程中的 bun run build，生产构建还有一条独立的 build-docs 任务。turbo.json 第 106–128 行显示其依赖与透传配置：

• dependsOn：^make、make、@remotion/convert#build-spa、@remotion/brand#bundle、@remotion/example#bundle-testbed；
• outputs：.docusaurus、build、node_modules/.cache/twoslash（Twoslash 类型检查缓存）；
• passThroughEnv：NODE_OPTIONS、REMOTION_DOCS_LOW_MEMORY_BUILD、TWOSLASH_RECYCLE_LIMIT_BYTES、TWOSLASH_STALL_TIMEOUT_MS、TWOSLASH_WORKER_COUNT、VERCEL。

由此可以推断：文档站的生产构建不只是编译 MDX，还要求 Convert 工具的 SPA、Brand 素材包以及示例工程的 testbed 捆绑产物先行就绪；TWOSLASH_* 系列变量用于在低内存或 CI 环境下调节 Twoslash 类型检查 worker 的行为。

四、copy-raw-docs：文档站的"原始 Markdown 导出"机制

start 管道的第一步 copy-raw-docs.ts 值得单独剖析，它揭示了 Remotion 文档管线的一个独特设计：在 Docusaurus 渲染之前，先把全部文档"降级"导出为纯 Markdown。

从 copy-raw-docs.ts 源码可以看到：

1. 目录约定（第 7–11 行）：源目录为 packages/docs/docs，元素文档目录为 packages/docs/elements，输出统一落到 static/_raw/docs 与 static/_raw/elements；
2. 组件展开（第 13–36 行）：writeRawMarkdown 读取源文件后依次执行 expandRawMarkdownComponents（展开 src/raw-markdown/replace-components 定义的自定义组件）与 expandElementSourceReferences（展开 plugins/element-source-utils.js 支持的元素源码引用）；
3. noAi 过滤：hasNoAiFrontmatter（第 38–41 行）通过匹配 frontmatter 中的 noAi: true 跳过标记页面；copyRawDocs 同样跳过 article.noAi 为真的文章；
4. slug 决定输出路径（第 64–81 行）：以文章 slug 作为输出文件名，例如 transitions.mdx 可对应 transitioning.md；空 slug（首页）映射为 index.md；/index 结尾的 slug 会额外生成一份扁平 .md（例如 player/index 同时产出 player/index.md 与 player.md），让 /player.md 这类短路径也能直接命中；
5. 元素文档遍历（第 107–139 行）：copyRawElements 递归扫描 elements/ 下所有 .mdx 文件，按同样的规则输出，并为目录 index 同时写出 <dir>/index.md；
6. 幂等清理：copyRawContent（第 141–149 行）先整体删除 static/_raw 再重新拷贝，保证产物与源文档严格一致。

从源码结构看，该脚本是文档内容被 AI/第三方消费（raw markdown 分发）与 Docusaurus 渲染（完整 MDX 组件）之间的"单一事实源"层，每次 bun run start 都会重新生成。

五、Docusaurus 关键配置解析

文档站的最终形态由 packages/docs/docusaurus.config.ts 决定，几个与本地预览直接相关的要点：

1. 严格链接校验（第 31–37 行）：onBrokenLinks: 'throw' 与 onBrokenAnchors: 'throw' 使死链在构建期直接报错，MD 内部链接则降级为 warn。本地启动时如果发现死链报错，应从文档源文件本身入手修复，而不是放宽配置；
2. faster 构建栈（第 9–21 行）：当 VERCEL=1 时启用 @docusaurus/faster 的 rspack + SWC + lightningcss 全量加速；本地开发则默认走标准配置，这也是 Twoslash 在开发模式下默认关闭、"为更快启动"（见 start 脚本提示语）的原因；
3. 内容路径（第 310–348 行）：主文档插件 path: 'docs'、sidebarPath: './sidebars.ts'；另注册了 id: 'elements' 的第二文档实例（path: './elements'、routeBasePath: 'elements'、侧栏为 elements-sidebars.ts），以及 success-stories 与 learn 两个博客实例；
4. 代码高亮与类型检查（第 338–347 行）：自定义预设 ./shiki（对应 shiki.js 与 twoslash-worker.mjs）基于 shiki + @shikijs/twoslash，主题固定 github-dark，并对代码块执行真实的 TypeScript 诊断——这就是需要 TWOSLASH_WORKER_COUNT 等变量调度的原因；
5. Git 最后更新时间（第 23–24 行）：REMOTION_DOCS_DISABLE_GIT_LAST_UPDATE=1 可关闭页脚时间戳，在无 git 元数据的检出环境中有用；
6. 搜索：themeConfig.algolia 配置了 Algolia DocSearch 索引 remotion，本地预览同样可用站点内搜索。

六、关键环境变量速查

环境变量	作用	证据位置
REMOTION_DOCS_ENABLE_TWOSLASH=1	开发模式下启用 Twoslash 类型检查（否则以更快启动）	packages/docs/package.json 第 12 行、turbo.json build-docs.env
REMOTION_DOCS_DISABLE_TWOSLASH=1	docusaurus start 启动时强制关闭 Twoslash	packages/docs/package.json 第 12 行
REMOTION_DOCS_DISABLE_GIT_LAST_UPDATE=1	关闭文档页脚 Git 最后更新时间	packages/docs/docusaurus.config.ts 第 23–24 行
TWOSLASH_WORKER_COUNT / TWOSLASH_RECYCLE_LIMIT_BYTES / TWOSLASH_STALL_TIMEOUT_MS	调节生产构建中 Twoslash worker 并发与超时	turbo.json build-docs.passThroughEnv
REMOTION_DOCS_LOW_MEMORY_BUILD	低内存构建模式透传	turbo.json build-docs.passThroughEnv
VERCEL=1	切换 Docusaurus faster 全量 rspack/SWC 加速栈	packages/docs/docusaurus.config.ts 第 7–21 行

七、小结

按照 .agents/skills/docs/SKILL.md 定义的五步流程，本地拉起 Remotion 文档站的核心命令只有两条：

bun i && bun run build
cd packages/docs && bun run start

其背后的完整链路是：bun workspaces 安装依赖 → Turborepo 按 ^make 拓扑构建全部 workspace 包 → start 脚本重新导出原始 Markdown（copy-raw-docs.ts）、更新提示词数据、重建 monorepo、准备 Browser Studio 工作区 → 以 --host 0.0.0.0 启动 Docusaurus 开发服务器（默认 http://localhost:3000）→ 读取实际打印的 URL 并在浏览器中验证。理解了 turbo.json 的任务依赖、packages/docs/docusaurus.config.ts 的插件实例与上文环境变量表，你就能在文档预览异常时快速定位问题出在构建层、内容导出层还是 Docusaurus 渲染层。