dumi运行Taro 组件 —— 避坑指南与分享

背景：

团队内的小程序都是基于taro框架开发的，其中使用了组件库@nutui/nutui-react-taro，由于各个项目中存在很多重复的业务组件，为了提升效率以及方便后期维护，所以打算封装小程序组件库。dumi是字节跳动推出的 React 组件文档工具，配置和扩展性比较强，所以成为了组件文档化的首选方案。但是过程中遇到了一些阻塞的问题，写下本篇文章进行记录+分享，避免二次踩坑～～～😄



问题：

在写组件文档试图展示组件demo的时候，出现了一些问题，报错如下图所示：









经我调研以及AI的诊断后，发现大致的问题是我们的组件依赖@nutui/nutui-react-taro，运行文档的时候，dumi基于浏览器环境和 React 生态，直接运行在浏览器中，而 @nutui/nutui-react-taro 以及 @tarojs/components 都是小程序运行时的代码，它们内部直接访问了ENABLE_INNER_HTML， Taro.getEnv() 等，但是这些是只有在Taro 小程序构建线里，才会被 DefinePlugin 注入的全局变量。浏览器端并没有这些变量，所以 demo 一渲染就报 ENABLE_INNER_HTML is not defined 或 Invalid hook call 等错误，两者的底层适配存在天然壁垒。



解决：

发现问题后，我首先尝试通过 AI 工具辅助解决，但实际效果未达预期 ，没有定位到核心矛盾，反而陷入版本依赖不匹配的无效循环。随后意识到，dumi 作为成熟的开源文档工具，这类 “跨框架组件集成” 的场景大概率已有其他开发者遇到过。于是我前往 dumi 的 GitHub 仓库检索相关 issues，果然找到了类似的问题案例，以及相关的解决建议（ github问题链接 ），具体如下（附截图）：









虽然 GitHub 上的相关讨论给出了初步解决方向，但并未完全匹配我们的实际需求。基于该思路，我后续做了两种落地尝试，具体如下：

方案一：通过 iframe + demoUrl 外链展示 Taro Demo

核心思路是将 Taro 组件的 Demo 独立部署，再通过 dumi 的 demoUrl 参数嵌入文档：

1.单独搭建一个 Taro 项目，专门用于编写和运行 Taro 组件 Demo

2.将 Taro 项目构建为 H5 页面，部署

3.在 dumi 的组件文档中，通过demoUrl 参数引入上述 H5 部署地址，以 iframe 形式嵌入展示。

不足：该方案需将 Demo 独立为单独项目，导致 Demo 与组件源码、文档的关联性大幅减弱。后续组件库迭代时，需同步维护组件源码和独立 Demo 项目，增加了维护成本，影响开发效率。

方案二：通过 Webpack 配置替换 Taro 生态为 Web 兼容版

核心思路是在 dumi 运行环境中，通过配置适配 Taro 依赖，实现组件实时预览：在 dumi 运行 Demo 时，通过 Webpack 配置将 Taro 生态相关依赖替换为 Web 兼容版本。这样一来，dumi 可直接像解析普通 React 组件一样加载 Taro 组件，无需额外构建 H5 包或配置 demoUrl，就能实现实时预览。

该配置仅对 dumi 文档站点生效，完全不影响业务小程序本身的构建流程，两者相互隔离、互不干扰。.dumirc.js 中的具体配置如下（附截图）：







以上便是全部的分享啦。希望这些关于 dumi 集成 Taro 组件的实践经验，能为大家解决同类问题提供一些参考和帮助。

有问题欢迎交流～～～👏