如何发布React组件库至NPM并解决aa.TextEncoder构造函数错误

数据老陈

2026-7-13

解决React组件库引入react-dom-server导致的TextEncoder错误

方法1：调整NX构建配置排除服务端依赖

若使用自定义Webpack配置，在webpack.config.js中添加externals配置，将react-dom/server标记为外部依赖，避免打包进组件库：
```
module.exports = {
  externals: {
    'react-dom/server': 'react-dom/server'
  }
};
```

若使用NX默认Rollup构建器，在项目的project.json的targets.build.options中添加external字段：

{
  "targets": {
    "build": {
      "options": {
        "external": ["react-dom/server"]
      }
    }
  }
}

配置后，组件库不会包含服务端代码，而是由使用该库的项目提供相关依赖，避免客户端环境触发服务端API错误。

方法2：排查代码中的隐式服务端引入

检查组件库代码，确认是否在自定义hooks、工具函数或第三方依赖中，间接导入了react-dom/server的API（如renderToString这类服务端渲染方法）。
删除或替换这些服务端专属代码，确保所有代码仅依赖react、react-dom/client这类客户端API。

方法3：修正React18的导入路径

确保组件中所有react-dom的导入都使用客户端专属路径：

// 正确的客户端导入方式
import { createRoot } from 'react-dom/client';
// 禁止导入服务端模块
// import { renderToString } from 'react-dom/server';

若为第三方依赖间接引入服务端模块，可尝试升级依赖版本；或在Webpack配置中通过resolve.alias将react-dom/server指向空模块：
```
module.exports = {
  resolve: {
    alias: {
      'react-dom/server': false // 也可指向项目内的空JS文件
    }
  }
};
```

方法4：用条件导出区分客户端/服务端入口

在组件库的package.json中添加条件导出，明确指定浏览器环境的入口，保证客户端加载的代码完全不含服务端依赖：

{
  "exports": {
    ".": {
      "import": "./dist/esm/index.js",
      "require": "./dist/cjs/index.js",
      "browser": "./dist/browser/index.js"
    }
  }
}