Create React App 文档站点实战：基于 Docusaurus 2 构建、本地开发与部署的全流程解析

本篇指南以仓库中的 docusaurus/website/README.md 为主线，结合 docusaurus.config.js、package.json、sidebars.json 等真实配置，完整讲解 Create React App 官方文档站点的安装、本地开发、静态构建与部署方式。读完你可以独立完成一个 Docusaurus 2 文档站点的本地起服、修改验证与静态发布，并理解 CRA 文档站当前“已弃用”状态是如何通过配置与首页代码体现的。

一、站点定位：CRA 文档站的宿主工程

Create React App 的官方文档并不是散落在 packages/ 里的零散 Markdown，而是集中由 docusaurus/ 目录下的 Docusaurus 2 静态站点工程托管：

• docusaurus/docs/：全部 44 篇官方教程 Markdown 源文件（如 getting-started.md、deployment.md、advanced-configuration.md），每篇使用 front-matter 声明 id、title、sidebar_label；
• docusaurus/website/：Docusaurus 站点工程本体，即 README.md 所在目录，包含配置、主题定制、静态资源与首页页面。

原始 README 用一句话点明了技术选型：“This website is built using Docusaurus 2, a modern static website generator.”（该站点使用 Docusaurus 2 这一现代静态网站生成器构建）。从 package.json 的依赖可以印证这一点：站点依赖 @docusaurus/core 与 @docusaurus/preset-classic（版本均为 ^2.0.0-alpha.64，即 2.0 系列的 alpha 版本线），并额外引入了 clsx 用于首页的 CSS 类名拼接。工程名被标记为 cra-docs 且 private: true，说明它只服务于文档发布，不会被发布到 npm。

二、安装与依赖准备

README 给出的第一步操作是：

npm install

需要注意一个工程细节：docusaurus/website 同时是仓库根 package.json 中 workspaces 数组的成员之一（"workspaces": ["packages/*", "docusaurus/website"]）。因此从仓库根目录执行 npm install 时，文档站点的依赖会随整个 monorepo 一起解析；单独进入该目录执行 npm install 同样可以完成站点依赖的安装。

依赖结构非常克制，核心只有五个包：

依赖	作用
@docusaurus/core	站点构建核心：MDX 解析、路由、构建管线
@docusaurus/preset-classic	经典主题预设：导航栏、页脚、文档布局、Algolia 搜索等
react / react-dom（^16.12.0）	站点页面渲染运行时
clsx	首页组件中条件类名拼接工具

browserslist 配置也值得注意：生产环境使用 >0.2%、not dead、not op_mini all 的兼容基线；开发环境仅要求浏览器最新三个大版本（Chrome / Firefox / Safari 的最后一个版本），保证本地开发构建快速。

三、本地开发：热更新的服务端

README 的 “Local Development” 章节给出的命令是：

npm start

对应 package.json 中的脚本定义：

"scripts": {
  "start": "docusaurus start",
  "build": "docusaurus build",
  "swizzle": "docusaurus swizzle",
  "deploy": "docusaurus deploy"
}

npm start 会启动一个本地开发服务器并自动打开浏览器窗口；README 特别指出：“Most changes are reflected live without having to restart the server.”（大多数修改无需重启服务器即可实时生效）。这意味着编辑 docusaurus/docs/ 下任意教程、调整 sidebars.json 分组顺序，或修改 src/ 下的页面组件，都会触发 Docusaurus 的 HMR 热更新。

四个脚本的职责划分很清晰：

• start：本地开发服务器，带热更新；
• build：生产构建，输出静态产物（详见下一节）；
• swizzle：Docusaurus 2 的主题定制机制入口，用于把主题中的组件复制进本地 src/ 目录后二次开发；
• deploy：一键构建并推送部署（见第五节）。

四、生产构建：生成可任意托管的静态产物

README 的 “Build” 章节：

npm run build

其说明是：“This command generates static content into the build directory and can be served using any static contents hosting service.”（该命令把静态内容生成到 build 目录，可以使用任何静态内容托管服务来分发）。docusaurus build 会把 44 篇文档、首页页面、自定义样式与 static/ 目录资源全部编译成纯 HTML/CSS/JS 产物。

仓库本身就演示了“任意静态托管”这一承诺：仓库根目录的 netlify.toml 将 Netlify 的构建路径直接指向该站点工程：

[build]
  base    = "docusaurus/website"
  publish = "docusaurus/website/build"
  command = "npm run build"

即 Netlify 会进入 docusaurus/website 目录执行 npm run build，然后把 build 目录作为发布产物。同时 docusaurus/website/static/CNAME 中写入的 create-react-app.dev 会被 Docusaurus 复制到产物中，配合 docusaurus.config.js 里的 url: 'https://create-react-app.dev' 完成自定义域名的绑定。

五、部署到 GitHub Pages

README 最后的 “Deployment” 章节给出了一键发布命令：

GIT_USER=<Your GitHub username> USE_SSH=1 npm run deploy

并说明：“If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the gh-pages branch.”（如果你使用 GitHub Pages 托管，这条命令是构建站点并推送到 gh-pages 分支的便捷方式）。它对应脚本 "deploy": "docusaurus deploy"，等价于先执行 docusaurus build，再通过 gh-pages 机制把产物推送到仓库的 gh-pages 分支。

两个环境变量的含义：

• GIT_USER：告知 Docusaurus 以哪个 GitHub 用户身份推送 gh-pages 分支；
• USE_SSH=1：强制使用 SSH 协议进行 git 推送，规避部分环境下 HTTPS 凭证交互失败的问题。

需要说明的适用前提：该一键命令面向 GitHub Pages 场景；如果像本仓库当前这样使用 Netlify 托管，则走 netlify.toml 声明的流水线即可，无需 npm run deploy。

六、站点配置详解：docusaurus.config.js

侧边栏与文档接入 是理解该站点如何组装的关键。配置文件导出的 siteConfig 主要包含以下要素：

基础信息

title: 'Create React App',
url: 'https://create-react-app.dev',
baseUrl: '/',
favicon: 'img/favicon/favicon.ico',

其中 tagline 已更新为弃用提示：“Create React App has been deprecated. Please visit react.dev for modern options.”，与下文提到的全局公告条一致。

docs 预设：把 docusaurus/docs 挂进来

docs: {
  path: '../docs',
  sidebarPath: require.resolve('./sidebars.json'),
  editUrl: 'https://github.com/facebook/create-react-app/edit/main/docusaurus/website',
  showLastUpdateAuthor: true,
  showLastUpdateTime: true,
},

• path: '../docs'：说明为什么文档源文件放在站点工程的上一级 docusaurus/docs/ 而不是 website/ 内部——Docusaurus 支持文档目录与站点工程分离；
• sidebarPath 指向 sidebars.json，即侧边栏完全由这份 JSON 手工编排（autogenerated 之外的人工分组模式）；
• showLastUpdateAuthor / showLastUpdateTime：在每篇文档底部展示 git 的最后修改人与修改时间，读者可据此判断文档新鲜度。

弃用公告条（announcementBar）

announcementBar: {
  id: 'deprecated',
  content: 'Create React App is deprecated. ...',
  backgroundColor: '#20232a',
  textColor: '#fff',
  isCloseable: false,
},

isCloseable: false 表示该公告条不可被关闭，确保任何访问者都会看到弃用声明。这与 tagline、首页元信息（见第七节）共同构成了站点级的弃用声明三处落点。

主题定制入口

theme: { customCss: require.resolve('./src/css/custom.css') },

把 src/css/custom.css 作为全局自定义样式注入，这是 preset-classic 官方推荐的样式覆盖方式。

导航与页脚

themeConfig.navbar 定义标题、logo（img/logo.svg，即 static/img/logo.svg）以及三个右侧入口：Docs（站内链接到 docs/getting-started）、Help、GitHub；themeConfig.footer 则是深色页脚，分 Docs / Community / Social 三组链接，并带 Facebook Open Source 的 logo（img/oss_logo.png）与按当前年份动态生成的版权行：

copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`,

此外 themeConfig.algolia 配置了 Algolia DocSearch 的 appId / apiKey / indexName（create-react-app），为站点提供即时全文搜索；themeConfig.image: 'img/logo-og.png' 指定社交分享时的 Open Graph 封面图。

七、侧边栏结构：文档知识地图

sidebars.json 把 44 篇文档组织成 10 个语义分组，这也是理解 CRA 知识体系的最佳索引：

分组	覆盖内容（示例）
Welcome	documentation-intro 文档导航说明
Getting Started	getting-started、folder-structure、available-scripts、supported-browsers-features、updating-to-new-releases
Development	编辑器配置、组件隔离开发、包体积分析、开发环境 HTTPS
Styles and Assets	样式表、CSS Modules、Sass、CSS Reset、静态资源、代码分割
Building your App	依赖安装、Bootstrap/Flow/TypeScript/Relay 集成、路由、环境变量、PWA、性能度量
Testing	running-tests、debugging-tests
Back-End Integration	开发代理、AJAX、标题与 meta 标签
Deployment	deployment
Advanced Usage	自定义模板、预渲染、advanced-configuration、alternatives-to-ejecting
Support	troubleshooting

值得指出的是：从源码结构看，该侧边栏在 “Building your App” 分组中引用了 production-build 条目，而 docusaurus/docs/ 目录当前并没有同名的 Markdown 文件——可以推断这是文档迁移过程中遗留的条目，Docusaurus 构建时对该缺失条目通常会给出警告，但不影响其余文档渲染。若你在本地 npm start 后遇到构建警告，可从侧边栏与文档文件的一致性角度排查。

八、自定义首页与弃用状态的落地

Docusaurus 约定 src/pages/index.js 作为站点首页。src/pages/index.js 中的 Home 组件展示了几个有价值的实现细节：

1. 通过 useDocusaurusContext 读取站点配置：<h1> 与副标题直接渲染 siteConfig.title 与 siteConfig.tagline，因此首页标题与弃用标语始终与 docusaurus.config.js 单一来源保持一致，无需在两处维护文案。
2. SEO 层面的弃用声明：<Head> 中写入了 <meta name="robots" content="noindex" />，将 <title> 改为 “Create React App is deprecated.”，并同步更新了 description 与 og:title / og:description 的 Open Graph 标签。从源码结构看，这表明搜索引擎不应再抓取该首页，访问者（与爬虫）都会在标题层级第一时间看到弃用信息。
3. useBaseUrl 处理资源路径：首页 logo 通过 useBaseUrl('img/logo.svg') 引用，保证站点部署在任意 baseUrl 下资源路径都正确。
4. 特性卡片与快速开始区：页面仍保留了 “Less to Learn / Only One Dependency / No Lock-In” 三张特性卡片和 npx create-react-app my-app 的快速开始代码块，方便老用户回看。

九、静态资源目录约定

Docusaurus 2 的 static/ 目录内容会在构建时原样复制到产物根目录。本仓库的 docusaurus/website/static/ 目录结构：

static/
├── CNAME                    # create-react-app.dev 自定义域名
└── img/
    ├── favicon/favicon.ico
    ├── docusaurus.svg
    ├── logo-og.png          # OG 分享图（themeConfig.image 引用）
    ├── logo.svg             # 导航栏 logo（navbar.logo.src 引用）
    ├── oss_logo.png         # 页脚 Facebook Open Source logo
    └── update.png

这解释了 docusaurus.config.js 中所有 img/... 相对路径为何不需要额外前缀——它们都是相对产物根的静态资源。

十、完整工作流速查

将 README 的四步流程汇总为一张可复现的操作表（均在 docusaurus/website 目录下执行）：

阶段	命令	结果
安装	npm install	安装 Docusaurus 2 及主题依赖
本地开发	npm start（即 docusaurus start）	本地服务器 + 浏览器自动打开，修改实时热更新
生产构建	npm run build（即 docusaurus build）	生成静态产物到 build/ 目录，可托管于任意静态服务
GitHub Pages 部署	GIT_USER=<用户名> USE_SSH=1 npm run deploy	构建并推送 gh-pages 分支
Netlify 部署（本仓库现行方案）	由 netlify.toml 驱动：base = "docusaurus/website"、command = "npm run build"、publish = "docusaurus/website/build"	推送到 git 即触发自动构建发布

结语

这个文档站工程是理解“文档即产品”的一个典型样本：44 篇教程通过 sidebars.json 形成知识地图，docusaurus.config.js 统一了站点身份、搜索、公告与主题定制，static/CNAME + netlify.toml 完成域名与托管接线，而首页代码则把弃用状态写进了 HTML 标题与 meta 标签。掌握了这套结构，你就可以用同样的方式构建和维护任意项目的官方文档站。