Rollup 组件库构建：解决内部组件 CSS 依赖的声明文件解析难题

本教程旨在解决使用 Rollup 构建 typescript 组件库时，内部组件间引用（尤其涉及样式文件）导致声明文件（.d.ts）生成失败的问题。核心在于 Rollup 在处理声明文件时，无法正确解析或忽略对 css 文件的引用，需通过在 rollup-plugin-dts 配置中显式将 CSS 文件标记为外部依赖来解决。

问题背景：组件库构建中的依赖困境

在构建现代 typescript/react 组件库时，我们通常会遇到组件之间相互依赖的情况。例如，一个“分子”（molecule）组件（如 button）可能会复用一个“原子”（atom）组件（如 text），并且每个组件都可能拥有自己的样式文件。为了提高开发效率和代码可维护性，我们常使用 tsconfig.json 中的 paths 别名来简化内部模块导入。

例如，在一个典型的项目结构中：

├── src │   ├── atoms |   │   ├── Text |   |   │   ├── Text.tsx |   |   │   ├── styles.css |   |   │   └── index.ts │   ├── molecules |   │   ├── Button |   |   │   ├── Button.tsx |   |   │   ├── styles.css |   |   │   └── index.ts │   └── index.ts ├── tsconfig.JSon └── rollup.config.mjs

Button.tsx 可能会这样导入 Text 组件：

// src/molecules/Button/Button.tsx import Text from 'atoms/Text/Text.tsx'; // 使用 tsconfig.paths 别名 // ...

同时，tsconfig.json 中配置了相应的路径别名：

// tsconfig.json {   "compilerOptions": {     // ... 其他配置     "baseUrl": "src",     "paths": {       "atoms/*": ["atoms/*"],       "molecules/*": ["molecules/*"],       // ...     }   } }

在开发环境中，TypeScript 编译器和开发服务器通常能正确解析这些导入。然而，当使用 Rollup 构建生产环境的组件库时，即使 rollup.config.mjs 中已经配置了 typescript、nodeResolve 和 postcss 等插件，我们仍可能遇到以下类似 Unresolved dependencies 的警告或错误：

立即学习“前端免费学习笔记（深入）”；

(!) Unresolved dependencies https://rollupjs.org/troubleshooting/#warning-treating-module-as-external-dependency atmos/base-text/Text.tsx (imported by "dist/esm/types/molecules/Button.d.ts")

这个警告尤其令人困惑，因为它指向的是 .d.ts 文件中的导入问题，而非最终的 JavaScript 包。这表明问题可能出在声明文件（Type Declaration Files）的生成阶段。

核心问题分析：声明文件与样式导入的冲突

Rollup 在构建组件库时，通常会进行两个主要阶段的打包：

1. 主 JavaScript/ESM 包的构建： 这一阶段负责将 TypeScript 代码编译为 JavaScript，并处理 CSS、图片等资产。@rollup/plugin-typescript 负责 TypeScript 编译，@rollup/plugin-node-resolve 负责模块解析，rollup-plugin-postcss 负责处理 CSS 导入（例如，将其提取到单独的文件或注入到 JS 中）。
2. 声明文件（.d.ts）的构建： 这一阶段使用 rollup-plugin-dts 来收集所有 .d.ts 文件并将其合并成一个或几个统一的声明文件，供消费者使用。

问题的根源在于，尽管 postcss 插件在主 JavaScript 包构建时能够正确处理 CSS 导入，但 rollup-plugin-dts 在生成声明文件时，其关注点在于 TypeScript 类型信息。当一个 .tsx 文件（例如 Text.tsx）内部导入了 .css 文件时，即使这个导入在 JavaScript 输出中被 postcss 妥善处理了，其在原始 TypeScript 模块图中的痕迹仍然可能被 rollup-plugin-dts 捕获。

rollup-plugin-dts 在尝试解析这些类型依赖时，如果遇到 .css 这样的非 TypeScript 文件导入，它不知道如何处理（它不会像 postcss 那样去处理样式），因此会将其标记为“未解析的依赖”或尝试将其视为外部模块，从而导致上述警告或构建失败。警告中指向 Button.d.ts 导入 Text.tsx，实际上是 Text.tsx 内部的 CSS 导入链条在 d.ts 生成过程中引发了问题。

解决方案：为声明文件显式外部化 CSS 依赖

解决此问题的关键在于，明确告诉 Rollup 在处理声明文件时，将所有 .css 文件视为外部依赖。这意味着 rollup-plugin-dts 不会尝试解析或打包这些 CSS 导入，而是简单地忽略它们，因为它们在最终的类型定义中是不需要的，并且会在运行时由其他机制（如 CSS 加载器）处理。

Rollup 提供了 external 配置项，用于指定哪些模块或文件路径应被视为外部依赖，不被打包进当前的 bundle。我们需要将其应用于 rollup-plugin-dts 所在的配置块。

具体修改步骤：

在 rollup.config.mjs 中，找到负责生成声明文件的配置对象（通常是第二个配置对象，使用 dts 插件），然后添加 external: [/.css$/]。

修改前的 rollup.config.mjs 相关片段：

// rollup.config.mjs // ... export default [     // ... 主 JavaScript/ESM 包的配置     {         input: "dist/esm/types/index.d.ts",         output: [{ file: "dist/index.d.ts", format: "esm" }],         // external: [/.css$/], // 缺少这一行         plugins: [dts.default()], // 注意这里的 dts.default()     }, ];

修改后的 rollup.config.mjs 相关片段：

// 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'; // 用于处理 peer dependencies import postcss from 'rollup-plugin-postcss'; import dts from "rollup-plugin-dts"; // 导入 dts 插件  // 假设 packageJson 已正确导入 // import packageJson from './package.json' assert { type: 'json' };  export default [     {         input: "src/index.ts",         output: [             {                 file: 'dist/cjs/index.js', // 假设 packageJson.main 对应此路径                 format: "cjs",                 sourcemap: true,                 name: 'ui-components'             },             {                 file: 'dist/esm/index.js', // 假设 packageJson.module 对应此路径                 format: "esm",                 sourcemap: true,             },         ],         plugins: [             external(), // 确保 peer dependencies 被外部化             nodeResolve(), // 处理 node_modules 模块             commonjs(), // 转换 CommonJS 模块为 ES6             typescript({tsconfig: "./tsconfig.json"}), // TypeScript 编译             postcss({                 extract: true, // 提取 CSS 到单独文件                 modules: true, // 启用 CSS Modules                 // ... 其他 postcss 配置             }),             terser(), // 压缩 JavaScript         ],         // 确保主要包也外部化了 peer dependencies         external: ['react', 'react-dom'] // 示例，具体根据 package.json 中的 peerDependencies 调整     },     {         // 声明文件打包配置         input: "dist/esm/types/index.d.ts", // 入口文件通常是 TypeScript 编译后生成的类型文件         output: [{ file: "dist/index.d.ts", format: "esm" }],         plugins: [dts()], // 注意这里是 dts() 而不是 dts.default()，取决于插件版本和导入方式         external: [/.css$/], // 关键：将所有 .css 文件视为外部依赖     }, ];

重要提示： rollup-plugin-dts 的导入方式可能因版本而异。在某些配置中可能是 dts.default()，在另一些配置中直接是 dts()。请根据您的实际安装和 Rollup 版本调整。

通过在 dts 插件的配置中添加 external: [/.css$/]，我们明确告诉 Rollup 在生成声明文件时，遇到任何 .css 文件的导入都不要尝试解析或打包，从而避免了“Unresolved dependencies”的警告，并确保了类型定义的正确生成。

配置概览与注意事项

为了确保组件库构建的顺畅，以下是一些重要的配置要点和最佳实践：

1. tsconfig.json 配置要点：

   • “jsx”: “react”：确保 JSX 语法被正确处理。
   • “module”: “ESNext” 和 “moduleResolution”: “node”：现代模块解析标准。
   • “baseUrl” 和 “paths”：对于内部模块别名至关重要，它帮助 TypeScript 编译器理解 atoms/* 等路径。
   • “declaration”: true 和 “emitDeclarationOnly”: true：确保 TypeScript 编译器只生成 .d.ts 文件而不生成 .js 文件，因为 .js 文件由 Rollup 负责。
   • “outDir” 和 “declarationDir”：分别指定编译输出的 JavaScript 和声明文件目录。

2. rollup.config.mjs 完整结构：

   • 分离配置： 明确区分主 JavaScript/ESM 包的构建配置和声明文件（.d.ts）的构建配置。
   • 插件顺序： 插件的顺序通常很重要。例如，@rollup/plugin-node-resolve 和 @rollup/plugin-commonjs 应该在 @rollup/plugin-typescript 之前，以确保 TypeScript 能够正确解析已转换为 ES 模块的依赖。rollup-plugin-peer-deps-external 应该放在最前面，以确保 peerDependencies 被正确外部化。
   • rollup-plugin-peer-deps-external： 这个插件非常有用，它可以自动将 package.json 中 peerDependencies 列出的模块标记为外部依赖，避免将它们打包进你的组件库，减少包体积，并确保消费者使用其自己的依赖版本。
   • rollup-plugin-postcss： 确保样式文件被正确处理。extract: true 通常用于将 CSS 提取到单独的文件中。

总结

在 Rollup 构建 TypeScript 组件库的过程中，内部组件间的依赖关系，尤其是涉及样式文件的导入，可能会在声明文件生成阶段引发 Unresolved dependencies 警告。这并非因为 tsconfig.paths 或 postcss 配置不当，而是 rollup-plugin-dts 在处理非 TypeScript 资产（如 .css 文件）时，需要明确的指示。

通过在 rollup.config.mjs 中，为 rollup-plugin-dts 的配置块添加 external: [/.css$/]，我们能够有效地告诉 Rollup 忽略 .css 文件的解析，将其视为外部依赖。这一简单的配置更改，是确保组件库类型定义顺利生成、避免构建错误的关键一步，从而保证了组件库的稳定性和可用性。