深度剖析 Rollup TS：从原理到实战的全方位指南

引言

在现代前端工程化的浪潮中，模块打包工具已经从 Webpack 的“一站式”霸主逐渐让位给更轻量、更灵活的 Rollup。与此同时，TypeScript（TS）已成为大型项目的首选语言。如何在保持 Rollup 优秀的 Tree‑shaking 与代码分割能力的同时，顺畅地处理 TypeScript，则催生了 Rollup TS 这一组合方案。本文将从技术原理、配置细节、性能对比以及实战案例四个维度，对 Rollup TS 进行深度分析，帮助开发者在实际项目中实现最佳的构建体验。

1. Rollup 与 TypeScript 的协同原理

1.1 Rollup 的核心理念

Rollup 采用 ES Module（ESM）作为输入输出的标准，基于静态分析的方式实现 Tree‑shaking，即在打包阶段剔除未被引用的代码。其插件化架构（plugin system）允许开发者在不同的构建阶段插入自定义逻辑，从而实现代码转换、资源加载、代码分割等功能。

1.2 TypeScript 编译的两种路径

在使用 Rollup 打包 TypeScript 项目时，主要有两种实现路径：

1. 先编译后打包：使用 tsc 将 .ts 编译为 .js（保留 ES6 模块），再交给 Rollup 进行进一步优化。此方式的优点是编译过程与 Rollup 完全解耦，缺点是需要维护两套配置文件（tsconfig.json 与 rollup.config.js），且在增量编译时可能出现冗余步骤。

2. 在 Rollup 中直接编译：通过插件（如 @rollup/plugin-typescript 或 rollup-plugin-esbuild）在 Rollup 的加载阶段直接将 TypeScript 转换为 JavaScript。这样可以实现“一键构建”，并且插件本身能够读取 tsconfig.json，保持配置一致性。

1.3 Rollup TS 的实现机制

以官方插件 @[rollup](https://basebiance.com/tag/rollup/)/plugin-typescript 为例，其工作流程如下：

• 解析阶段：Rollup 调用插件的 load 钩子读取 .ts 文件内容。
• 转换阶段：插件内部使用 TypeScript 编译器 API（typescript.transpileModule）将 TypeScript 代码转为目标 JavaScript（默认 ES2015），并生成对应的 SourceMap。
• AST 替换：转换后的代码重新进入 Rollup 的 AST（抽象语法树）进行依赖分析和 Tree‑shaking。
• 输出阶段：Rollup 根据输出格式（esm、cjs、iife 等）生成最终的 bundle。

通过这种方式，Rollup TS 能够在保持 TypeScript 类型安全的同时，充分利用 Rollup 的优化能力。

2. 配置实战：从零搭建 Rollup TS 项目

2.1 项目结构示例

my-lib/├─ src/│  ├─ index.ts│  └─ utils.ts├─ tsconfig.json├─ rollup.config.js├─ package.json└─ README.md

2.2 tsconfig.json 推荐配置

{  "compilerOptions": {    "target": "ES2017",    "module": "ESNext",    "declaration": true,    "sourceMap": true,    "strict": true,    "esModuleInterop": true,    "skipLibCheck": true,    "forceConsistentCasingInFileNames": true,    "outDir": "dist"  },  "include": ["src/**/*.ts"],  "exclude": ["node_modules", "dist"]}

• module 设置为 ESNext，让 Rollup 能够直接读取 ESM。
• declaration 生成 .d.ts，对外发布库时必不可少。

2.3 rollup.config.js 完整示例

import typescript from '@rollup/plugin-typescript';import { terser } from 'rollup-plugin-terser';import resolve from '@rollup/plugin-node-resolve';import commonjs from '@rollup/plugin-commonjs';import pkg from './package.json';export default [  // ES Module 输出  {    input: 'src/index.ts',    output: [      {        file: pkg.module,        format: 'esm',        sourcemap: true      },      {        file: pkg.main,        format: 'cjs',        sourcemap: true,        exports: 'named'      }    ],    plugins: [      resolve(),      commonjs(),      typescript({ tsconfig: './tsconfig.json' }),      terser()    ],    external: ['lodash'] // 防止打包外部依赖  }];

• @rollup/plugin-typescript 正是实现 rollup ts 关键功能的核心插件。
• terser 用于生产环境压缩，保持体积最小。
• external 配置可避免将大体积的第三方库打进 bundle，进一步提升 Tree‑shaking 效果。

2.4 常见坑点及解决方案

3. 性能对比：Rollup TS vs 传统 Webpack + ts-loader

从上述数据可以看出，在 库开发 或 中小型前端项目 中，Rollup TS 往往能够提供更快的构建速度和更小的产出体积。

4. 实战案例：使用 Rollup TS 打包一个通用 UI 组件库

4.1 项目背景

某企业内部需要一个跨平台的 UI 组件库，要求：

• 支持 ESM 与 CommonJS 两种模块格式，以兼容不同的消费端。
• 输出 TypeScript 声明文件，便于业务方在 TypeScript 项目中直接使用。
• 体积控制在 100KB 以下（gzip）。

4.2 关键实现步骤

1. 代码组织：所有组件均使用 src/components/ 目录，每个组件独立 index.ts，并通过 src/[index](https://basebiance.com/tag/index/).ts 统一导出。
2. Rollup 配置：在 rollup.config.js 中加入 output.preserveModules: true，保持每个组件文件的独立输出，便于按需加载。
3. 插件链：
   • @rollup/plugin-typescript 负责 TS 编译与声明文件生成。
   • rollup-plugin-postcss 处理 CSS，配合 postcss-modules 实现 CSS Modules。
   • rollup-plugin-terser 进行代码压缩。
4. 构建脚本：

"scripts": {  "build": "rollup -c",  "build:watch": "rollup -c -w"}

5. 结果验证：使用 bundlephobia 检测体积，最终 gzip 后为 84KB，满足预期。

4.3 经验总结

• 保持 TypeScript 与 Rollup 配置同步：所有路径别名应在 tsconfig.json 与 rollup.config.js 中统一，避免模块解析错误。
• 利用 preserveModules：对组件库而言，按需加载是降低入口体积的关键，Rollup TS 能够轻松实现。
• 压缩插件的顺序：务必在 typescript 之后、terser 之前插入 postcss，确保 CSS 也能被压缩。

5. 未来趋势：Rollup TS 与新兴编译器的融合

随着 esbuild、SWC 等基于 Go / Rust 的高速编译器的崛起，Rollup 社区已经推出了 rollup-plugin-esbuild 与 @rollup/plugin-swc。这些插件同样支持 TypeScript，并且在 增量编译 与 冷启动 方面表现更佳。对追求极致构建速度的团队来说，未来可以考虑在 Rollup TS 的基础上切换到 esbuild 或 SWC，实现毫秒级的重新打包。

关于 Rollup TS 的常见问题

1️⃣ Rollup TS 能否直接生成浏览器可运行的 IIFE 包？

答：可以。只需在 output.format 中指定 iife，并在 plugins 中加入 @rollup/plugin-node-resolve 与 rollup-plugin-terser，即可生成自执行函数（IIFE）格式的 bundle，适合直接在 <script> 标签中使用。

2️⃣ 使用 Rollup TS 时，如何处理第三方库的类型声明？

答：大多数第三方库已经在 @types 或自身的 *.d.ts 中提供声明文件。确保 tsconfig.json 的 typeRoots 包含 node_modules/@types，并在 rollup.config.js 的 external 中声明这些库，Rollup 将不会将其打包进产物，只保留类型信息。

3️⃣ 为什么在使用 @rollup/plugin-typescript 时仍然会出现 TS2307: Cannot find module 错误？

答：该错误通常源于 路径别名 未在 Rollup 中正确解析。解决办法是使用 @rollup/plugin-alias 同步 tsconfig.json 中的 paths 配置，或在 typescript 插件中开启 paths 支持。

4️⃣ Rollup TS 与 Babel 的组合有什么优势？

答：当项目需要使用最新的 JavaScript 特性（如装饰器、私有字段）而 TypeScript 编译器尚未完全支持时，可以在 Rollup 中先使用 @rollup/plugin-typescript 进行类型检查，再使用 @rollup/plugin-babel 进行语法转换，实现两者优势的互补。

5️⃣ 如何在 CI 环境中使用 Rollup TS 进行构建？

答：在 CI（如 GitHub Actions、GitLab CI）中，只需执行 npm ci && npm run build。确保使用的 Node 版本与本地保持一致，并在 package.json 中锁定 @rollup/plugin-typescript、rollup 等依赖的版本，以避免构建不一致。