Vite构建React+Antd组件库生产环境报‘xx is not a function’错误排查

1. 组件库Vite配置的外部依赖处理 #

Vite默认会将react、react-dom这类通用框架设为外部依赖（external），不打包进组件库产物。如果消费项目未正确提供这些依赖，或版本不兼容，就会触发运行时错误。

• 检查组件库vite.config.ts中的build.rollupOptions.external配置：

  // 错误示例：若强制将react设为external，但消费项目未正确引入
  rollupOptions: {
    external: ['react', 'react-dom']
  }
  

  • 若希望组件库内置react（不推荐，会增大产物体积），可从external中移除react/react-dom；
  • 若保持external配置，必须确保消费项目已安装兼容版本的react和react-dom。

2. 组件库package.json的peerDependencies声明 #

组件库必须明确声明react和react-dom为peer依赖，要求消费项目提供对应版本：

"peerDependencies": {
  "react": "^18.0.0",
  "react-dom": "^18.0.0"
},
"peerDependenciesMeta": {
  "react": { "optional": false },
  "react-dom": { "optional": false }
}

未声明peer依赖时，消费项目可能遗漏安装react，或安装版本不匹配，导致运行时缺失react.createElement。

3. 消费项目的Vite配置校验 #

• 检查消费项目vite.config.ts的optimizeDeps.exclude，不要将组件库或react列入排除列表：

  // 错误示例：禁止这样配置
  optimizeDeps: {
    exclude: ['your-component-lib', 'react']
  }
  

• 确认resolve.alias未错误映射react路径，避免指向不存在的文件。

4. 组件库构建输出格式配置 #

若组件库采用umd/iife格式构建，必须配置全局变量映射，确保运行时能找到React：

export default defineConfig({
  build: {
    lib: {
      entry: 'src/index.ts',
      name: 'YourComponentLib',
      formats: ['es', 'umd'],
      fileName: (format) => `your-lib.${format}.js`
    },
    rollupOptions: {
      external: ['react', 'react-dom'],
      output: {
        globals: {
          react: 'React',
          'react-dom': 'ReactDOM'
        }
      }
    }
  }
})

全局变量未配置会导致umd产物无法识别React，进而触发react.createElement相关错误。

5. 组件代码导入方式检查 #

确保组件库代码统一使用ES模块导入：

import React from 'react';

避免混用require('react')这类CommonJS语法，否则构建时可能出现依赖处理异常。

快速验证步骤 #

1. 查看组件库构建后的index.js产物，搜索react.createElement，确认是否存在；
2. 检查消费项目node_modules中是否有react和react-dom，版本是否符合组件库peer依赖要求；
3. 临时移除组件库Vite配置中的external，重新构建后引入消费项目测试，若错误消失，说明是外部依赖配置导致的问题。

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