使用Rollup构建组件库时无法导入自定义组件的问题排查

我正在尝试用Rollup构建自定义组件库，本地开发时在Button组件里通过import Text from '/atoms/Text/Text.tsx'导入Text组件能正常运行，但执行Rollup构建时出现未解析依赖警告。

文件夹结构 #

├── src
│   ├── components
|   │   ├── Text
|   |   │   ├── Text.tsx
|   |   │   ├── styles.css
|   |   │   └── index.ts
│   │   └── index.ts
│   └── index.ts
│   ├── molecules
|   │   ├── Button
|   |   │   ├── Button.tsx
|   |   │   ├── styles.css
|   |   │   └── index.ts
│   │   └── index.ts
│   └── index.ts
├── styles
│   └── general.ts
│   └── index.ts
├── package.json
└── package-lock.json

导入语句 #

import Text from '/atoms/Text/Text.tsx'

构建警告 #

(!) Unresolved dependencies
atmos/base-text/Text.tsx (imported by "dist/esm/types/molecules/Button.d.ts")

tsconfig.json #

{
  "compilerOptions":{
    "target":"es2016",
    "jsx":"react",
    "module":"ESNext",
    "moduleResolution":"node",
    "declaration":true,
    "emitDeclarationOnly":true,
    "sourceMap":true,
    "outDir":"dist",
    "declarationDir":"types",
    "allowSyntheticDefaultImports":true,
    "esModuleInterop":true,
    "forceConsistentCasingInFileNames":true,
    "strict":true,
    "skipDefaultLibCheck":true,
    "skipLibCheck":true,
    "allowImportingTsExtensions": true,
    "baseUrl":"src",
    "rootDir": "src",
    "paths":{
      "atoms/*":[
        "atoms/*"
      ],
      "molecules/*":[
        "molecules/*"
      ],
      "styles/*":[
        "styles/*"
      ],
    }
  }
}

rollup.config.mjs #

import resolve, {nodeResolve} from "@rollup/plugin-node-resolve";
import commonjs from "@rollup/plugin-commonjs";
import typescript from "@rollup/plugin-typescript";
import {terser} from 'rollup-plugin-terser';
import external from 'rollup-plugin-peer-deps-external'
import postcss from 'rollup-plugin-postcss'
import dts from "rollup-plugin-dts";

export default [
    {
        input: "src/index.ts",
        output: [
            {
                file: packageJson.main,
                format: "cjs",
                sourcemap: true,
                name: 'ui-components'
            },
            {
                file: packageJson.module,
                format: "esm",
                sourcemap: true,
            },
        ],
        plugins: [
            resolve(),
            commonjs(),
            external(),
            postcss(),
            terser(),
            nodeResolve(),
            typescript({tsconfig: "./tsconfig.json"}),
        ],
    },
    {
        input: "dist/esm/types/index.d.ts",
        output: [{ file: "dist/index.d.ts", format: "esm" }],
        external: [/\.css$/],
        plugins: [dts.default()],
    },
];

核心问题 #

1. 路径映射与实际目录不匹配：tsconfig里配置的paths指向atoms/*，但实际目录是src/components，导致TypeScript别名完全失效。
2. 导入路径写法错误：使用/atoms/...根路径导入，本地开发依赖IDE或dev server的特殊解析，Rollup默认不识别这种路径，也不会自动关联tsconfig的baseUrl和paths。
3. Rollup未处理tsconfig路径别名：默认插件不支持解析tsconfig的paths配置，需要额外插件处理。
4. 声明文件路径未解析：dts插件合并声明文件时，未解析的别名路径导致依赖找不到。

修复步骤 #

1. 统一目录与路径映射 #

要么把src/components改名为src/atoms，要么修改tsconfig的paths：

// tsconfig.json
"paths":{
  "components/*":[
    "components/*"
  ],
  "molecules/*":[
    "molecules/*"
  ],
  "styles/*":[
    "styles/*"
  ]
}

2. 修正导入路径 #

使用tsconfig配置的别名，去掉开头斜杠，建议通过index.ts导出后导入：

// Button.tsx
import Text from 'components/Text'
// 或者保留文件后缀
import Text from 'components/Text/Text.tsx'

3. 让Rollup支持路径别名 #

安装@rollup/plugin-alias并配置：

npm install @rollup/plugin-alias --save-dev

修改rollup.config.mjs：

import alias from '@rollup/plugin-alias';
// ...其他导入

export default [
    {
        input: "src/index.ts",
        output: [/* ... */],
        plugins: [
            alias({
                entries: [
                    { find: 'components', replacement: './src/components' },
                    { find: 'molecules', replacement: './src/molecules' },
                    { find: 'styles', replacement: './src/styles' }
                ]
            }),
            resolve(), // 保留一个resolve即可，去掉nodeResolve()
            commonjs(),
            external(),
            postcss(),
            terser(),
            typescript({tsconfig: "./tsconfig.json"}),
        ],
    },
    {
        input: "dist/esm/types/index.d.ts",
        output: [{ file: "dist/index.d.ts", format: "esm" }],
        external: [/\.css$/],
        plugins: [dts.default()],
    },
];

4. 修复声明文件生成问题 #

把tsconfig里的emitDeclarationOnly改为false，让Rollup的typescript插件统一处理编译和声明生成，避免路径混乱。

5. 清理冗余配置 #

移除rollup配置中重复的nodeResolve()，确保package.json里的main和module字段正确指向dist目录下的输出文件。

内容的提问来源于stack exchange，提问作者four-eyes