Create React App 文档站点实战基于 Docusaurus 2 构建、本地开发与部署的全流程解析【免费下载链接】create-react-appSet up a modern web app by running one command.项目地址: https://gitcode.com/gh_mirrors/cr/create-react-app本篇指南以仓库中的 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_labeldocusaurus/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生产构建输出静态产物详见下一节swizzleDocusaurus 2 的主题定制机制入口用于把主题中的组件复制进本地src/目录后二次开发deploy一键构建并推送部署见第五节。四、生产构建生成可任意托管的静态产物README 的 “Build” 章节npm run build其说明是“This command generates static content into thebuilddirectory 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 PagesREADME 最后的 “Deployment” 章节给出了一键发布命令GIT_USERYour GitHub username USE_SSH1 npm run deploy并说明“If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to thegh-pagesbranch.”如果你使用 GitHub Pages 托管这条命令是构建站点并推送到gh-pages分支的便捷方式。它对应脚本deploy: docusaurus deploy等价于先执行docusaurus build再通过gh-pages机制把产物推送到仓库的gh-pages分支。两个环境变量的含义GIT_USER告知 Docusaurus 以哪个 GitHub 用户身份推送gh-pages分支USE_SSH1强制使用 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 的最后修改人与修改时间读者可据此判断文档新鲜度。弃用公告条announcementBarannouncementBar: { 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定义标题、logoimg/logo.svg即 static/img/logo.svg以及三个右侧入口Docs站内链接到docs/getting-started、Help、GitHubthemeConfig.footer则是深色页脚分 Docs / Community / Social 三组链接并带 Facebook Open Source 的 logoimg/oss_logo.png与按当前年份动态生成的版权行copyright: Copyright © ${new Date().getFullYear()} Facebook, Inc.,此外themeConfig.algolia配置了 Algolia DocSearch 的appId/apiKey/indexNamecreate-react-app为站点提供即时全文搜索themeConfig.image: img/logo-og.png指定社交分享时的 Open Graph 封面图。七、侧边栏结构文档知识地图sidebars.json 把 44 篇文档组织成 10 个语义分组这也是理解 CRA 知识体系的最佳索引分组覆盖内容示例Welcomedocumentation-intro 文档导航说明Getting Startedgetting-started、folder-structure、available-scripts、supported-browsers-features、updating-to-new-releasesDevelopment编辑器配置、组件隔离开发、包体积分析、开发环境 HTTPSStyles and Assets样式表、CSS Modules、Sass、CSS Reset、静态资源、代码分割Building your App依赖安装、Bootstrap/Flow/TypeScript/Relay 集成、路由、环境变量、PWA、性能度量Testingrunning-tests、debugging-testsBack-End Integration开发代理、AJAX、标题与 meta 标签DeploymentdeploymentAdvanced Usage自定义模板、预渲染、advanced-configuration、alternatives-to-ejectingSupporttroubleshooting值得指出的是从源码结构看该侧边栏在 “Building your App” 分组中引用了production-build条目而docusaurus/docs/目录当前并没有同名的 Markdown 文件——可以推断这是文档迁移过程中遗留的条目Docusaurus 构建时对该缺失条目通常会给出警告但不影响其余文档渲染。若你在本地npm start后遇到构建警告可从侧边栏与文档文件的一致性角度排查。八、自定义首页与弃用状态的落地Docusaurus 约定src/pages/index.js作为站点首页。src/pages/index.js 中的Home组件展示了几个有价值的实现细节通过useDocusaurusContext读取站点配置h1与副标题直接渲染siteConfig.title与siteConfig.tagline因此首页标题与弃用标语始终与 docusaurus.config.js 单一来源保持一致无需在两处维护文案。SEO 层面的弃用声明Head中写入了meta namerobots contentnoindex /将title改为 “Create React App is deprecated.”并同步更新了description与og:title/og:description的 Open Graph 标签。从源码结构看这表明搜索引擎不应再抓取该首页访问者与爬虫都会在标题层级第一时间看到弃用信息。useBaseUrl处理资源路径首页 logo 通过useBaseUrl(img/logo.svg)引用保证站点部署在任意baseUrl下资源路径都正确。特性卡片与快速开始区页面仍保留了 “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 # 导航栏 logonavbar.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_SSH1 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/CNAMEnetlify.toml完成域名与托管接线而首页代码则把弃用状态写进了 HTML 标题与 meta 标签。掌握了这套结构你就可以用同样的方式构建和维护任意项目的官方文档站。【免费下载链接】create-react-appSet up a modern web app by running one command.项目地址: https://gitcode.com/gh_mirrors/cr/create-react-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考