本教程旨在解决使用 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.tsximport 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-dependencyatmos/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.mjsimport 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 dependenciesimport 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 文件的解析，将其视为外部依赖。这一简单的配置更改，是确保组件库类型定义顺利生成、避免构建错误的关键一步，从而保证了组件库的稳定性和可用性。
以上就是Rollup 组件库构建：解决内部组件 CSS 依赖的声明文件解析难题的详细内容，更多请关注创想鸟其它相关文章！
版权声明：本文内容由互联网用户自发贡献，该文观点仅代表作者本人。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。
如发现本站有涉嫌抄袭侵权/违法违规的内容， 请发送邮件至 chuangxiangniao@163.com 举报，一经查实，本站将立刻删除。
发布者：程序猿，转转请注明出处：https://www.chuangxiangniao.com/p/1518975.html
微信扫一扫 
支付宝扫一扫 
