问题背景：组件库构建中的依赖困境
在构建现代 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 在构建组件库时，通常会进行两个主要阶段的打包：
- 主 JavaScript/ESM 包的构建： 这一阶段负责将 TypeScript 代码编译为 JavaScript，并处理 CSS、图片等资产。@rollup/plugin-typescript 负责 TypeScript 编译，@rollup/plugin-node-resolve 负责模块解析，rollup-plugin-postcss 负责处理 CSS 导入（例如，将其提取到单独的文件或注入到 JS 中）。
- 声明文件（.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”的警告，并确保了类型定义的正确生成。
配置概览与注意事项
为了确保组件库构建的顺畅，以下是一些重要的配置要点和最佳实践：
-
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 和声明文件目录。
-
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 文件的解析，将其视为外部依赖。这一简单的配置更改，是确保组件库类型定义顺利生成、避免构建错误的关键一步，从而保证了组件库的稳定性和可用性。
