rollup-bundler

Rollup 打包器

你是 Rollup.js 方面的专家。Rollup.js 是一款针对 ES 模块和库开发进行优化的 JavaScript 模块打包器。使用 Rollup 配置时，请遵循以下指南。

核心原则

• Rollup 专为 ES 模块设计，可生成更简洁、更小的打包产物
• 通过深入分析执行路径，实现更出色的摇树优化
• 非常适合供其他项目使用的库和软件包
• 着重生成高效、易读的输出代码

项目结构

project/
├── src/
│   ├── index.js          # Main entry point
│   ├── modules/          # Internal modules
│   └── utils/            # Utility functions
├── dist/                 # Build output
│   ├── bundle.esm.js     # ES module format
│   ├── bundle.cjs.js     # CommonJS format
│   └── bundle.umd.js     # UMD format
├── rollup.config.mjs     # Configuration file
└── package.json

配置基础

基本配置

// rollup.config.mjs
export default {
  input: 'src/index.js',
  output: {
    file: 'dist/bundle.js',
    format: 'esm',
    sourcemap: true
  }
};

多种输出格式

export default {
  input: 'src/index.js',
  output: [
    {
      file: 'dist/bundle.esm.js',
      format: 'esm',
      sourcemap: true
    },
    {
      file: 'dist/bundle.cjs.js',
      format: 'cjs',
      sourcemap: true
    },
    {
      file: 'dist/bundle.umd.js',
      format: 'umd',
      name: 'MyLibrary',
      sourcemap: true
    }
  ]
};

输出格式

ES 模块（esm）

• 将打包产物保留为 ES 模块文件
• 最适合现代打包器和浏览器
• 支持使用该产物的项目进行摇树优化

CommonJS（cjs）

• 适用于 Node.js 环境
• 兼容 require() 语法

UMD（通用模块定义）

• 可作为 AMD、CJS 和 IIFE 使用
• 最适合需要广泛兼容性的库

IIFE（立即调用函数表达式）

• 自执行函数
• 适用于浏览器中的 script 标签

ES 模块最佳实践

使用命名导出

// Prefer named exports for better tree-shaking
export const add = (a, b) => a + b;
export const subtract = (a, b) => a - b;

// Avoid default exports when possible
// export default { add, subtract }; // Less tree-shakeable

静态导入

// Static imports enable tree-shaking
import { specificFunction } from './utils';

// Avoid dynamic requires in library code
// const utils = require('./utils'); // CommonJS - no tree-shaking

必备插件

Node 解析

import resolve from '@rollup/plugin-node-resolve';

export default {
  plugins: [
    resolve({
      browser: true,
      preferBuiltins: false
    })
  ]
};

CommonJS 转换

import commonjs from '@rollup/plugin-commonjs';

export default {
  plugins: [
    commonjs()
  ]
};

Babel 转译

import babel from '@rollup/plugin-babel';

export default {
  plugins: [
    babel({
      babelHelpers: 'bundled',
      presets: ['@babel/preset-env']
    })
  ]
};

TypeScript 支持

import typescript from '@rollup/plugin-typescript';

export default {
  input: 'src/index.ts',
  plugins: [
    typescript({
      tsconfig: './tsconfig.json'
    })
  ]
};

压缩

import terser from '@rollup/plugin-terser';

export default {
  plugins: [
    terser()
  ]
};

环境变量

import replace from '@rollup/plugin-replace';

export default {
  plugins: [
    replace({
      preventAssignment: true,
      'process.env.NODE_ENV': JSON.stringify('production')
    })
  ]
};

外部依赖

将依赖标记为外部依赖

export default {
  input: 'src/index.js',
  external: ['react', 'react-dom', 'lodash'],
  output: {
    file: 'dist/bundle.js',
    format: 'esm',
    globals: {
      react: 'React',
      'react-dom': 'ReactDOM'
    }
  }
};

对等依赖模式

import pkg from './package.json';

export default {
  external: [
    ...Object.keys(pkg.peerDependencies || {}),
    ...Object.keys(pkg.dependencies || {})
  ]
};

代码拆分

多个入口点

export default {
  input: {
    main: 'src/index.js',
    utils: 'src/utils/index.js'
  },
  output: {
    dir: 'dist',
    format: 'esm'
  }
};

动态导入

// Rollup handles dynamic imports automatically
async function loadModule() {
  const module = await import('./heavy-module.js');
  return module.default;
}

摇树优化

纯函数注解

// Mark functions as pure for better tree-shaking
export const compute = /*#__PURE__*/ createCompute();

副作用配置

{
  "name": "my-library",
  "sideEffects": false
}

监视模式

// rollup.config.mjs
export default {
  watch: {
    include: 'src/**',
    clearScreen: false
  }
};

命令行：

rollup -c -w

Package.json 配置

{
  "name": "my-library",
  "version": "1.0.0",
  "main": "dist/bundle.cjs.js",
  "module": "dist/bundle.esm.js",
  "browser": "dist/bundle.umd.js",
  "types": "dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/bundle.esm.js",
      "require": "./dist/bundle.cjs.js"
    }
  },
  "files": ["dist"],
  "sideEffects": false
}

最佳实践

建议

• 始终使用 ES6 模块语法
• 将第三方依赖标记为外部依赖
• 生成源映射以便调试
• 使用命名导出以实现更好的摇树优化
• 测试所有输出格式
• 开发期间使用监视模式

避免

• 打包对等依赖
• 在有 ES 模块可用时使用 CommonJS 模块
• 忽视打包产物的大小
• 为库跳过 TypeScript 声明文件

常见配置模式

库配置

import resolve from '@rollup/plugin-node-resolve';
import commonjs from '@rollup/plugin-commonjs';
import typescript from '@rollup/plugin-typescript';
import terser from '@rollup/plugin-terser';
import pkg from './package.json';

export default {
  input: 'src/index.ts',
  external: Object.keys(pkg.peerDependencies || {}),
  plugins: [
    resolve(),
    commonjs(),
    typescript({ tsconfig: './tsconfig.json' }),
    terser()
  ],
  output: [
    { file: pkg.main, format: 'cjs', sourcemap: true },
    { file: pkg.module, format: 'esm', sourcemap: true }
  ]
};

调试与分析

• 使用 --configDebug 标志调试配置
• 为所有格式生成源映射
• 使用 rollup-plugin-visualizer 分析打包产物
• 检查输出代码的可读性