用 elastic/eui-docusaurus-preset 为 Docusaurus 注入 Elastic UI 设计体系主题、插件与本地开发全指南【免费下载链接】euiElastic UI Framework 项目地址: https://gitcode.com/GitHub_Trending/eu/euielastic/eui-docusaurus-preset是 Elastic UI FrameworkEUI官方为自身文档站eui.elastic.co定制的 Docusaurus preset它将 EUI 自定义主题与一组精选 Docusaurus 插件打包成开箱即用的配置。读完本文你将掌握该 preset 的完整组成、每个配置项的真实作用与源码级实现原理能够在自己项目中快速接入 EUI 文档风格并学会如何在 monorepo 中构建、打包并与官方文档站联动调试。为什么需要这样一个 presetEUIElastic UI Framework本身是一套完整的设计系统包含组件库、主题令牌tokens与文档站。当团队希望用 Docusaurus 承载文档又希望文档站具备与 eui.elastic.co 一致的外观与交互时直接使用 Docusaurus 默认的 classic 主题是不够的——Docusaurus 默认依赖其自带 CSS 框架 Infima而 Infima 的全局样式会与 EUI 设计系统产生冲突详见下文「ignore-styles-plugin」一节。elastic/eui-docusaurus-preset源码位于 packages/docusaurus-preset/src/index.ts的定位就是解决这个问题它以 Docusaurus 的 preset 构造函数 机制将elastic/eui-docusaurus-theme主题和一组经过挑选的插件封装为一个统一入口让使用者只需在docusaurus.config.ts中声明一个 preset 即可获得完整的 EUI 文档站能力。preset 的组成两个主题与一批插件preset 内部由**主题Themes和插件Plugins**两部分构成。从源码preset()函数的返回值{ themes, plugins }可以确认它把配置一次性交给 Docusaurus 处理。主题Themes主题说明docusaurus/theme-classicDocusaurus 基础主题为兼容性所必需elastic/eui-docusaurus-themeEUI 自定义主题负责以 EUI 组件和令牌替换 classic 主题组件从 packages/docusaurus-preset/src/index.ts 可以看到两个主题通过require.resolve()解析后依次加入themes数组且 classic 主题必须在前——EUI 主题在 packages/docusaurus-theme/src/index.ts 中通过getThemePath()指向../lib/theme它会基于 classic 主题进行组件级覆盖Swizzling。插件Plugins插件说明默认启用ignore-styles-plugin阻止 Infima 及部分继承样式污染全局 CSS是docusaurus/plugin-content-docs文档页面支持是可配置docusaurus/plugin-content-pages静态页面支持是可配置docusaurus/plugin-svgrSVG 导入支持是可配置docusaurus/plugin-content-blog博客支持是可配置docusaurus/plugin-sitemap站点地图生成用于 SEO仅生产构建docusaurus/plugin-google-analyticsGoogle Analytics 集成配置了才启用docusaurus/plugin-google-tag-managerGoogle Tag Manager 集成配置了才启用docusaurus/plugin-google-gtagGoogle Global Site Tag 集成配置了才启用插件的启用逻辑源码级解析preset()函数packages/docusaurus-preset/src/index.ts揭示了上表的启用规则docs、pages、svgr三个插件通过makePluginConfig()无条件加入有选项时返回[require.resolve(plugin), options]元组形式无选项时仅返回模块路径blog只有在options.blog ! false时才加入即传入blog: false可以显式关闭博客sitemap只在process.env.NODE_ENV production时加入开发模式下不生成 sitemap三个 Google 系插件Analytics / Tag Manager / Gtag只有在对应的选项键存在时才启用因此是典型的「按需开启」设计。一个实用的工具函数是makePluginConfigpackages/docusaurus-preset/src/index.ts它负责把「纯字符串模块名」规范化为 Docusaurus 接受的string | [string, PluginOptions]两种形态保证无论是否传选项都能被正确解析。快速上手安装与配置安装 preset 与 theme注意从 v1.1.0 开始见 packages/docusaurus-preset/changelogs/CHANGELOG_2025.mdelastic/eui-docusaurus-theme从dependencies移到了peerDependencies因此使用方必须同时显式安装 preset 和 theme二者缺一不可# npm npm install elastic/eui-docusaurus-preset elastic/eui-docusaurus-theme # pnpm pnpm add elastic/eui-docusaurus-preset elastic/eui-docusaurus-theme # Yarn yarn add elastic/eui-docusaurus-preset elastic/eui-docusaurus-theme从 packages/docusaurus-preset/package.json 可以看到其 peer 约束elastic/eui-docusaurus-theme ^2.8.0、react ^18.0.0 || ^19.0.0、react-dom ^18.0.0 || ^19.0.0也就是说 preset 本身支持 React 18 与 19 两个大版本。在 docusaurus.config.ts 中声明const config: Config { // ... presets: [ [ require.resolve(elastic/eui-docusaurus-preset), { docs: { sidebarPath: ./sidebars.ts, }, } satisfies Preset.Options, ], ], // ... }require.resolve用于让 Docusaurus 在编译期精确定位 preset 的入口文件选项对象通过satisfies Preset.Options获得完整的类型检查保障Options类型从./options导出。配置项全解Options 类型速查表preset 的配置项在 packages/docusaurus-preset/src/options.ts 中统一定义每个字段直接透传给对应的 Docusaurus 官方插件并复用其原生的选项类型例如DocsPluginOptions、BlogPluginOptions。完整字段如下选项类型说明docsDocsPluginOptions透传给docusaurus/plugin-content-docspagesPagesPluginOptions透传给docusaurus/plugin-content-pagessvgrSVGRPluginOptions透传给docusaurus/plugin-svgrsitemapSitemapPluginOptions透传给docusaurus/plugin-sitemap仅生产构建生效themeThemeOptions透传给docusaurus/theme-classicblogfalse \| BlogPluginOptions透传给docusaurus/plugin-content-blog传false可关闭博客googleAnalyticsGAPluginOptions存在该键时启用 GA 插件googleTagManagerGTMPluginOptions存在该键时启用 GTM 插件gtagGtagPluginOptions存在该键时启用 Gtag 插件实战参考EUI 官方文档站的配置EUI 官方文档站 packages/website/docusaurus.config.ts 是该 preset 的最佳实践范例其真实配置展示了多个选项的组合用法presets: [ [ require.resolve(elastic/eui-docusaurus-preset), { docs: { sidebarPath: ./sidebars.ts, editUrl: https://github.com/elastic/eui/tree/main/packages/website/, admonitions: { keywords: [accessibility], extendDefaults: true, }, }, blog: { showReadingTime: true, editUrl: https://github.com/elastic/eui/tree/main/packages/website/, }, googleTagManager: googleTagManagerId { containerId: googleTagManagerId, }, } satisfies EuiPresetOptions, ], ],其中值得借鉴的细节docs.admonitions.keywords: [accessibility]为文档扩展了自定义 admonition 关键字同时extendDefaults: true保留默认的note、tip、warning等类型googleTagManager的值由环境变量DOCS_GOOGLE_TAG_MANAGER_ID驱动未设置时为undefined从而精确控制插件启停——这正是前文所述「存在该键才启用」规则的工程化应用官方站还通过future.experimental_faster启用了 SWC/Rspack 等提速特性并将importSource指向emotion/react与主题的 Emotion 渲染管线保持一致。为什么官方强烈推荐 preset 而不是单独用 themeDocusaurus 默认使用 Infima其自带 CSS 框架为 classic 主题提供样式。EUI 主题虽然基于 classic 主题但 Infima 的全局样式经常会覆盖或冲突 EUI 设计系统导致外观不一致。这正是ignore-styles-plugin存在的原因。从 packages/docusaurus-preset/src/index.ts 可以看到它的实现通过configureWebpack()为两个路径挂上null-loader把样式模块「空加载」掉test: /node_modules\/infima/丢弃 Infima 样式test: /node_modules\/docusaurus\/theme-common\/lib\/hooks\/styles.css丢弃 theme-common 中继承下来的样式。这样 EUI 组件就不会被 Infima 的全局规则污染。该插件只存在于 preset 内因此若单独使用 theme不走 presetInfima 样式冲突问题依然存在——这就是官方「强烈推荐使用 preset 而非独立 theme」的根本原因。如果你确实只需要主题可以参照 packages/docusaurus-theme/README.md 的「Theme only」一节在docusaurus.config.ts中手动同时声明两个主题const config: Config { // ... themes: [ require.resolve(docusaurus/theme-classic), // Required for compatibility require.resolve(elastic/eui-docusaurus-theme), ], // ... }仅用主题时的环境准备单独使用主题或本地调试主题时还需要完成三项前置准备详见 packages/docusaurus-theme/README.md安装所需依赖包yarn add emotion/react emotion/css elastic/charts在项目tsconfig.json中配置 Emotion 的 JSX 运行时与模块解析{ extends: docusaurus/tsconfig, compilerOptions: { baseUrl: ., jsxImportSource: emotion/react, moduleResolution: nodenext } }配置 Babel添加babel/preset-react让 Emotion 接管importSourcemodule.exports { presets: [ require.resolve(docusaurus/core/lib/babel/preset), [ babel/preset-react, { runtime: automatic, importSource: emotion/react }, ], ], };主题的底层实现Swizzling 与 Root 包装EUI 主题之所以能「替换」classic 主题靠的是 Docusaurus 的 Swizzling 目录结构可以看到它对DocRoot、DocItem、DocSidebarItem、Navbar、Footer、MDXComponents、CodeBlock、Admonition、TOCCollapsible等几乎所有核心组件都提供了基于 EUI 组件的自定义实现。其中 packages/docusaurus-theme/src/theme/Root.tsx 负责「用EuiProvider包装整个站点」它通过AppThemeProvider管理明暗模式用 Emotion 的CacheProviderGlobal注入 reset 样式、Infima 兼容样式与 EUI 全局样式并根据颜色模式动态加载elastic/charts的明/暗主题 CSS。文件注释也如实指出了当前方案的一个已知权衡Emotion 样式在客户端动态加载与 Docusaurus 的 SSR 内容存在时序差因此组件会在mounted后才渲染以避免明显的样式闪动与布局偏移代价是首屏短暂空白官方计划未来改为服务端注入 HTML。本地开发构建 preset 与主题环境要求该包要求见 packages/docusaurus-preset/README.mdNode.js当前仓库 .nvmrc 指定版本为24.19.0corepack用于锁定 Yarn 版本。安装依赖与构建# 安装依赖 yarn # 构建包产出 lib/ 目录 yarn build # 监听模式构建文件变更时自动重新编译 yarn startbuild脚本在 packages/docusaurus-preset/package.json 中定义为tscstart定义为tsc --watch。:::warning 该包配置了增量构建tsc在你重命名或删除文件时可能不会把最新变更同步到lib目录。遇到这种情况请重新执行yarn build做一次完整构建。 :::与 EUI 官方文档站联动调试从 monorepo 根目录启动官方文档站实时查看主题效果yarn workspace elastic/eui-website start修改主题时可以把这个命令与主题的 watch 模式yarn start配合使用一边改源码、一边在文档站上即时预览。用本地构建的 preset 测试你自己的 Docusaurus 项目如果你不想直接改动官方文档站可以按以下流程在自己的 Docusaurus 项目中验证 preset 的改动。第一步创建干净的 Docusaurus 项目npx create-docusauruslatest my-website classic --typescript第二步构建并打包 preset 与 theme在 EUI monorepo 根目录执行# 构建两个包 yarn workspace elastic/eui-docusaurus-theme build yarn workspace elastic/eui-docusaurus-preset build # 打包 theme cd packages/docusaurus-theme yarn pack --filename docusaurus-theme.tgz # 打包 preset cd ../docusaurus-preset yarn pack --filename docusaurus-preset.tgz第三步在你的项目中安装依赖先安装 EUI 及其运行时依赖# npm npm install elastic/eui elastic/charts emotion/react emotion/css moment # pnpm pnpm add elastic/eui elastic/charts emotion/react emotion/css moment # Yarn yarn add elastic/eui elastic/charts emotion/react emotion/css moment再安装本地打包产物将/path/to/eui替换为你的 monorepo 实际路径# npm npm install /path/to/eui/packages/docusaurus-preset/docusaurus-preset.tgz /path/to/eui/packages/docusaurus-theme/docusaurus-theme.tgz # pnpm pnpm add /path/to/eui/packages/docusaurus-preset/docusaurus-preset.tgz /path/to/eui/packages/docusaurus-theme/docusaurus-theme.tgz # Yarn yarn add /path/to/eui/packages/docusaurus-preset/docusaurus-preset.tgz /path/to/eui/packages/docusaurus-theme/docusaurus-theme.tgz之所以要安装elastic/charts、emotion/react等包是因为主题组件内部依赖它们见 packages/docusaurus-theme/package.json 的dependencies清单其中包含elastic/charts、elastic/eui-theme-borealis、emotion/react、emotion/css、moment、prism-react-renderer、react-live等。然后按照上文「Usage」一节的写法在项目的docusaurus.config.ts中声明本地 preset。第四步迭代修改当你修改 preset 或 theme 后重新构建并打包两个包在你的项目中重新安装.tgz产物重启 Docusaurus 开发服务器# npm npm run start # pnpm pnpm start # Yarn yarn start进阶导航栏右侧链接changelog / github / figmaEUI 文档站导航栏右侧有一组特殊链接EUI Changelog、GitHub、Figma这也是主题提供的开箱能力。在themeConfig.navbar.items中为条目添加component属性即可取值限定为changelog | github | figmathemeConfig: { // ... navbar: { // ... items: [ // ... { href: https://github.com/elastic/eui/tree/main/packages/eui/changelogs, label: EUI Changelog, position: right, component: changelog, }, { href: https://github.com/elastic/eui, label: GitHub, position: right, component: github, }, { href: https://www.figma.com/community/file/964536385682658129, label: Figma, position: right, component: figma, }, ], }, // ... }官方文档站的真实配置packages/website/docusaurus.config.ts正是这样使用component: changelog与component: github的Figma 链接当前被注释禁用理由是社区 Figma 文件已过时待更新后会重新启用——这也提醒你在自己的项目中按需取舍。源码导读与延伸阅读如果你想深入 preset 的实现细节以下文件是最佳入口packages/docusaurus-preset/src/index.tspreset 主入口主题/插件装配与全部启停逻辑packages/docusaurus-preset/src/options.tsOptions与ThemeConfig类型定义基于 Docusaurus classic preset 的 options 结构packages/docusaurus-preset/package.json构建脚本与 peer 依赖约束packages/docusaurus-theme/src/index.ts主题插件的挂载实现getThemePath/getTypeScriptThemePathpackages/docusaurus-theme/src/theme/Root.tsxEuiProvider根包装、Emotion 全局样式与图表主题加载packages/docusaurus-theme/src/theme/theme.d.tsSwizzle 后theme-original/*模块的类型重声明是理解主题覆盖面的关键packages/website/docusaurus.config.ts官方文档站完整配置堪称该 preset 的活教材packages/docusaurus-preset/changelogs/CHANGELOG_2025.md版本变更记录可追踪 peer 依赖调整等演进细节。掌握以上内容后你不仅能开箱即用地搭建出 EUI 风格的 Docusaurus 文档站还能在需要时对 preset 与主题进行本地定制、打包和验证把 EUI 的设计体系完整地带入自己的项目。【免费下载链接】euiElastic UI Framework 项目地址: https://gitcode.com/GitHub_Trending/eu/eui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考