TypeORM 文档站点实操指南：基于 Docusaurus 的安装、本地开发、构建与部署

本文围绕 TypeORM 官方文档站点（docs/ 目录）的维护与构建流程展开。TypeORM 是一个支持 PostgreSQL、MySQL、MariaDB、SQLite、SQL Server、Oracle 等数据库的 TypeScript/JavaScript ORM，其官方文档网站完全构建在 Docusaurus 之上。读完本篇，你将掌握如何在本地安装依赖、启动热更新开发服务器、生成静态构建产物，以及通过 SSH 或非 SSH 方式部署站点，并了解站点配置、侧边栏组织、旧链接重定向等配套工程细节。

文档站点的技术底座

docs/ 目录是独立的网站工程，其 package.json 中声明了包名 @typeorm/docs，并锁定了运行环境要求：

• 包管理器：packageManager 字段固定为 pnpm@10.33.4，所有命令都应以 pnpm 执行；
• Node 版本：engines.node 要求 >=20.0；
• 核心依赖：@docusaurus/core、@docusaurus/preset-classic、@docusaurus/plugin-client-redirects 均处于 ^3.10.1，配合 React 19（react / react-dom 均为 ^19.2.7）与 TypeScript ^5.9.3；
• 扩展插件：docusaurus-lunr-search（基于 lunr 的全文搜索）、@signalwire/docusaurus-plugin-llms-txt（面向 LLM 的 llms.txt 内容生成）、@mdx-js/react（支持 MDX 文档，如 transactions.mdx）。

文档内容本身存放在 docs/docs/ 目录下，按主题划分为 data-source、entity、relations、migrations、query-builder、drivers、guides 等子目录，以及 getting-started.md、indexes.md、logging.md 等顶层文档，与站点侧边栏的组织方式一一对应。

安装依赖

文档站点的 README（docs/README.md）给出的第一步命令是：

pnpm install

该命令在 docs/ 工作目录下执行，依据根部的 pnpm-lock.yaml 恢复依赖。由于 package.json 中通过 pnpm.ignoredBuiltDependencies 忽略了 core-js 的构建脚本，安装过程不会执行该包的 postinstall 构建逻辑。

本地开发：热更新服务器

pnpm run start

start 脚本在 package.json 中定义为 docusaurus start。它会启动 Docusaurus 的本地开发服务器并自动打开浏览器窗口；大部分修改（如编辑 Markdown/MDX 文档）都会实时热更新反映到页面中，无需重启服务器。

package.json 中还预置了其他常用脚本，可用于开发排障：

脚本	实际命令	用途
build	docusaurus build	生成生产构建
serve	docusaurus serve	本地预览 build 产物
clear	docusaurus clear	清除 .docusaurus 缓存与构建产物
deploy	docusaurus deploy	构建并部署（见下文）
swizzle	docusaurus swizzle	将主题组件复制到本地以便定制
write-heading-ids	docusaurus write-heading-ids	生成标题锚点 ID
write-translations	docusaurus write-translations	生成国际化翻译文件骨架

生产构建

pnpm run build

该命令（即 docusaurus build）将整站静态内容生成到 build 目录中，产物可以被任意静态内容托管服务直接承载。构建时 Docusaurus 会读取 docusaurus.config.ts 中的全局配置，其中几个对构建行为有直接影响的项：

• onBrokenLinks: "throw"：构建时遇到死链直接报错失败，保证产物中不存在失效引用；
• url: "https://typeorm.io" 与 baseUrl: "/"：声明生产环境站点地址与挂载路径，影响 sitemap、绝对链接生成；
• themeConfig.prism：代码块高亮采用 github 主题（深色为 dracula），并额外注册 typescript、bash、sql 等语言——这与文档中大量数据库示例代码相匹配；
• scripts 字段按 NODE_ENV === "production" 条件注入第三方脚本（统计、问答挂件），开发模式下不注入，因此 pnpm run start 启动的本地开发环境页面是干净的。

构建完成后可以用 pnpm run serve 在本机预览产物，确认无误再行部署。

部署

README 给出了两条部署路径，均基于 pnpm deploy（即 docusaurus deploy）：

使用 SSH 部署：

USE_SSH=true pnpm deploy

不使用 SSH（HTTPS + 用户名）：

GIT_USER=<Your GitHub username> pnpm deploy

当站点托管在 GitHub Pages 上时，deploy 命令是一条捷径：它先执行构建，再把产物推送到 gh-pages 分支。USE_SSH=true 表示 git push 时走 SSH 协议（需要本机已配置 SSH key）；否则走 HTTPS 协议，此时必须通过 GIT_USER 环境变量提供 GitHub 用户名以便 git 认证。

部署目标仓库由 docusaurus.config.ts 中的 organizationName: "typeorm" 与 projectName: "typeorm" 共同决定，即推送到 typeorm/typeorm 仓库的 gh-pages 分支。

文档内容如何组织成侧边栏

sidebars.ts 定义了唯一的 tutorialSidebar，它是导航骨架：Getting Started 之后依次是 Data Source、Entity、Relations、Migrations、Working with Entity Manager、Query Builder、Drivers、Guides、Help、Releases 等分类。值得注意的是其两种混合写法：

• 顶层文档（如 indexes、transactions、logging、using-cli）直接以字符串 id 声明；
• 目录型分类使用 { type: "autogenerated", dirName: "..." }，由 Docusaurus 自动扫描 docs/docs/<dirName>/ 下文件生成条目。

docusaurus.config.ts 中 presets[0].docs.sidebarPath 指向 ./sidebars.ts，且 navbar.items 里的 "Docs" 入口绑定 sidebarId: "tutorialSidebar"，三者构成从导航栏到侧边栏再到文档页的完整链路。

旧链接重定向：URL 变更不丢流量

文档站点经历过目录结构调整，@docusaurus/plugin-client-redirects 插件负责把旧 URL 平滑重定向到新位置，规则集中维护在 redirects.ts 中，并被 docusaurus.config.ts 的 plugins 数组引入。例如：

{ from: "/docs", to: "/docs/getting-started" }
{ from: "/entities", to: "/docs/entity/entities" }
{ from: "/relations", to: "/docs/relations/relations" }
{ from: "/working-with-repository", to: "/docs/working-with-entity-manager/working-with-repository" }
{ from: "/select-query-builder", to: "/docs/query-builder/select-query-builder" }

可以推断，这套规则覆盖了旧版（0.3 时代）文档站点的扁平 URL 体系，而配置文件中导航栏的 "Version 0.3.x" 下拉项也印证了新旧两套文档并存的分发策略。维护文档新增或移动页面时，应同步在该文件中补充重定向，避免存量外部引用 404。

面向 LLM 的 llms.txt 与站内搜索

除标准构建外，站点还通过 @signalwire/docusaurus-plugin-llms-txt 插件生成 llms.txt 内容：docusaurus.config.ts 中通过 contentSelectors 指定了多个正文选择器（如 .theme-doc-markdown、article、main），并开启 enableLlmsFullTxt，让 LLM/Agent 可以直接抓取纯文本版文档。docusaurus-lunr-search 插件则提供站内全文检索。这两个插件都参与构建流程，属于 pnpm run build 产出的一部分。

定制主题与自定义组件

站点样式与自定义组件位于 docs/src/：

• docs/src/css/custom.css 被配置项 theme.customCss 引用，是全局样式覆盖入口；
• docs/src/constants/databases.ts 声明了 10 个受支持数据库（CockroachDB、Google Spanner、MariaDB、MongoDB、MS SQL Server、MySQL、Oracle、PostgreSQL、SAP HANA、SQLite）的名称与图标，对象键顺序即展示顺序；
• docs/src/components/tabs/database-tabs.tsx 基于该常量实现了 <DatabaseTabs> / <DatabaseTab> 组件，可在 MDX 文档中以标签页形式为不同数据库展示各自的配置差异，并对未知或重复的 value 抛出明确错误；
• docs/src/pages/ 下是首页与维护者页面（index.tsx、maintainers.tsx 及对应 CSS Module、maintainers.json 数据）。

TypeScript 与路径别名

tsconfig.json 继承了 @docusaurus/tsconfig 并设置 baseUrl: "."，注释中明确说明该文件不参与编译、仅用于编辑器体验；这也解释了文档源码中为何可以随意混用 ./sidebars 与 @site/src/... 两种导入路径。

小结

TypeORM 文档站点的日常维护流程可以归纳为：pnpm install 安装依赖 → pnpm run start 热更新开发 → 修改 docs/docs/ 下的 Markdown/MDX 内容（必要时在 sidebars.ts、redirects.ts 中登记导航与重定向）→ pnpm run build 验证静态产物 → USE_SSH=true pnpm deploy 或 GIT_USER=<Your GitHub username> pnpm deploy 推送到 gh-pages 分支。整个链路完全基于 Docusaurus 3 + pnpm 的标准工作流，构建期通过 onBrokenLinks: "throw" 与重定向表保证链接健康度。