Next.js+TypeScript项目使用自制react-enigma-pin-lock组件包遇导入错误

可能的原因及对应解决方案 #

1. 组件包打包配置不兼容Next.js #

Vite默认的库打包输出格式，可能没兼顾Next.js依赖的CommonJS/ES模块解析逻辑，导致默认导出无法被正确识别。

• 修改组件包的vite.config.ts，确保同时输出两种格式并配置正确的导出映射：

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  build: {
    lib: {
      entry: 'src/index.tsx', // 替换成你的组件入口路径
      name: 'EnigmaPinLock',
      formats: ['es', 'cjs'], // 同时生成ES和CommonJS格式
      fileName: (format) => `react-enigma-pin-lock.${format}.js`,
    },
    rollupOptions: {
      external: ['react', 'react-dom'], // 排除React依赖，避免重复打包
      output: {
        globals: {
          react: 'React',
          'react-dom': 'ReactDOM',
        },
        exports: 'default', // 确保CommonJS格式下默认导出生效
      },
    },
  },
});

• 重新执行npm run build打包组件包，再重新发布或本地测试。

2. TypeScript类型定义未正确声明默认导出 #

即使代码里写了默认导出，若类型定义文件没同步声明，Next.js的TS检查会报错，也会干扰模块解析。

• 手动检查组件包dist目录下的index.d.ts，确保包含默认导出声明：

import EnigmaPinLock from './EnigmaPinLock';
export default EnigmaPinLock;

• 或者调整组件包的tsconfig.json，确保类型生成配置正确：

{
  "compilerOptions": {
    "declaration": true,
    "declarationDir": "dist",
    "module": "ESNext",
    "target": "ES2015",
    "esModuleInterop": true, // 开启后TS能更好处理默认导出的兼容问题
    "skipLibCheck": true
  }
}

3. Next.js模块解析策略差异 #

Next.js对模块的解析逻辑和Vite不同，可能导致默认导出无法被识别，可先尝试兼容命名导入：

• 在组件包入口文件中同时添加默认导出和命名导出：

export default EnigmaPinLock;
export { EnigmaPinLock }; // 新增命名导出

• 在Next.js项目中改用命名导入测试：

import { EnigmaPinLock } from 'react-enigma-pin-lock';

如果这种方式能正常运行，说明是默认导出的解析兼容问题，后续可通过打包配置优化来支持两种导入方式。

4. 本地测试的缓存问题 #

如果是用npm link/yarn link本地测试组件包，Next.js可能缓存了旧的模块内容，导致修改不生效：

• 删除Next.js项目的.next文件夹，重启开发服务器；
• 重新打包组件包，再在Next.js项目中重新链接或安装本地包。

5. 组件包package.json配置错误 #

确保package.json里的入口字段指向正确的打包文件：

{
  "name": "react-enigma-pin-lock",
  "version": "1.0.0",
  "main": "./dist/react-enigma-pin-lock.cjs.js", // CommonJS入口
  "module": "./dist/react-enigma-pin-lock.es.js", // ES模块入口
  "types": "./dist/index.d.ts", // 类型定义文件路径
  "exports": {
    ".": {
      "import": "./dist/react-enigma-pin-lock.es.js",
      "require": "./dist/react-enigma-pin-lock.cjs.js",
      "types": "./dist/index.d.ts"
    }
  }
}

exports字段是现代模块解析的标准配置，能帮助Next.js正确匹配不同环境下的模块文件。

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