基于TypeScript的React组件库安装后模块解析错误求助

AI 小北

2026-8-11

问题描述

我正在用TypeScript开发一个React组件库，直接依赖项如下：

"dependencies": {
    "@hookform/resolvers": "^2.9.10",
    "axios": "^1.1.3",
    "chart.js": "^4.0.1",
    "react-beautiful-dnd": "^13.1.1",
    "react-chartjs-2": "^5.0.1",
    "react-hook-form": "^7.39.4",
    "react-router-dom": "^6.4.3",
    "reflect-metadata": "^0.1.13",
    "yup": "^0.32.11"
  }

开发依赖项：

"devDependencies": {
    "@rollup/plugin-commonjs": "^23.0.2",
    "@rollup/plugin-json": "^5.0.1",
    "@rollup/plugin-node-resolve": "^15.0.1",
    "@rollup/plugin-typescript": "^9.0.2",
    "@types/axios": "^0.14.0",
    "@types/node": "^18.11.9",
    "@types/react": "^18.0.25",
    "@types/react-beautiful-dnd": "^13.1.2",
    "@types/yup": "^0.32.0",
    "react": "^18.2.0",
    "rollup": "^3.3.0",
    "rollup-plugin-copy": "^3.4.0",
    "rollup-plugin-dts": "^5.0.0",
    "rollup-plugin-json": "^4.0.0",
    "rollup-plugin-peer-deps-external": "^2.2.4",
    "rollup-plugin-postcss": "^4.0.2",
    "rollup-plugin-scss": "^3.0.0",
    "sass": "^1.56.1",
    "tslib": "^2.4.1",
    "typescript": "^4.9.3"
}

Rollup配置文件：

import resolve from "@rollup/plugin-node-resolve";
import commonjs from "@rollup/plugin-commonjs";
import typescript from "@rollup/plugin-typescript";
import dts from "rollup-plugin-dts";
import peerDepsExternal from "rollup-plugin-peer-deps-external";
import json from "rollup-plugin-json";
import copy from "rollup-plugin-copy";
import postcss from "rollup-plugin-postcss";

export default [
  {
    input: "src/index.ts",
    output: [
      {
        file: "dist/cjs/index.js",
        format: "cjs",
        sourcemap: true,
      },
      {
        file: "dist/esm/index.js",
        format: "esm",
        sourcemap: true,
      },
    ],
    plugins: [
      peerDepsExternal(),
      commonjs(),
      resolve(),
      json(),
      typescript({ tsconfig: "./tsconfig.json" }),
      postcss(),
      copy({
        targets: [
          {
            src: "src/index.css",
            dest: "dist",
            rename: "index.css"
          },
          {
            src: "README.md",
            dest: "dist",
            rename: "README.md"
          },
          {
            src: "package.json",
            dest: "dist",
            rename: "package.json"
          }
        ]
      })
    ],
  },
  {
    input: "dist/esm/index.d.ts",
    output: [{ file: "dist/index.d.ts", format: "esm" }],
    external: [/\.css$/],
    plugins: [dts()],
  },
];

组件库能成功构建（存在循环依赖警告），也能发布到npm和GitHub作用域包仓库，但安装测试时出现以下错误：

Module not found: Error: Can't resolve 'url','zlib','fs','path' in '[LIB_PATH]\dist\esm'

原因分析与解决方案

核心原因

url、zlib、fs、path都是Node.js的内置核心模块，浏览器环境中并不存在。问题出在Rollup打包时，没有正确处理依赖中引用这些Node内置模块的代码，将它们打包进了浏览器环境运行的产物中，导致浏览器无法识别这些模块。

你的依赖中axios是最可能引入这类模块的包——它会在Node环境下用到url、zlib等模块，但Rollup默认的配置没有针对浏览器环境过滤这些代码分支。

解决步骤

标记Node内置模块为外部依赖
在Rollup主配置对象中添加external字段，将Node内置模块排除在打包范围外，让消费环境自行处理（浏览器环境会忽略这些Node专属代码）：

// 先安装builtin-modules作为开发依赖：npm i -D builtin-modules
import builtins from 'builtin-modules'
import pkg from './package.json' assert { type: 'json' };

// 在主配置中添加
{
  input: "src/index.ts",
  output: [...],
  external: [...builtins, ...Object.keys(pkg.dependencies)],
  plugins: [...]
}

这个配置会自动排除所有Node内置模块和你的直接依赖，避免不必要的打包。

调整@rollup/plugin-node-resolve的浏览器适配
给resolve插件添加browser: true选项，让它优先解析依赖的浏览器兼容版本：
```
resolve({
  browser: true
})
```
该配置会告诉插件针对浏览器环境解析依赖，自动忽略依赖中仅Node环境有效的代码逻辑。
排查依赖的Node专属代码
如果你在组件库中使用axios时用到了Node环境特有的功能（比如自定义httpAgent），需要确保这部分代码不会被打包到浏览器产物中，或者提供浏览器兼容的替代实现。
验证打包产物
修改配置后重新构建，检查dist/esm/index.js中是否还存在对url、fs等模块的引用，若仍有残留，需进一步定位是哪个依赖引入了这些模块，针对性处理。

内容的提问来源于stack exchange，提问作者Shangab

基于TypeScript的React组件库安装后模块解析错误求助

核心原因 #

解决步骤 #

核心原因

解决步骤