Rollup 基础使用 #

命令行使用 #

基本命令 #

bash

# 最简单的打包
rollup src/main.js

# 指定输出文件
rollup src/main.js -o dist/bundle.js

# 指定输出格式
rollup src/main.js -o dist/bundle.js -f iife

# 生成 sourcemap
rollup src/main.js -o dist/bundle.js -m

# 使用配置文件
rollup -c

常用命令行选项 #

选项	简写	描述	示例
`--input`	`-i`	入口文件	`rollup -i src/main.js`
`--file`	`-o`	输出文件	`rollup -o dist/bundle.js`
`--format`	`-f`	输出格式	`rollup -f es`
`--name`	`-n`	UMD 名称	`rollup -n MyLib`
`--sourcemap`	`-m`	生成 sourcemap	`rollup -m`
`--watch`	`-w`	监听模式	`rollup -w`
`--config`	`-c`	配置文件	`rollup -c`
`--external`	`-e`	外部依赖	`rollup -e lodash`
`--globals`	`-g`	全局变量	`rollup -g lodash:_`
`--plugin`	`-p`	使用插件	`rollup -p node-resolve`

输出格式选项 #

bash

# IIFE - 立即执行函数（浏览器）
rollup src/main.js -f iife -o dist/bundle.js

# ESM - ES 模块
rollup src/main.js -f es -o dist/bundle.mjs

# CJS - CommonJS（Node.js）
rollup src/main.js -f cjs -o dist/bundle.cjs

# UMD - 通用模块定义
rollup src/main.js -f umd -n MyLib -o dist/bundle.umd.js

# System - SystemJS
rollup src/main.js -f system -o dist/bundle.system.js

入口文件 #

单入口 #

javascript

// rollup.config.js
export default {
  input: 'src/main.js',
  output: {
    file: 'dist/bundle.js',
    format: 'es'
  }
};

多入口 #

javascript

// 方式一：数组形式
export default {
  input: ['src/main.js', 'src/admin.js'],
  output: {
    dir: 'dist',
    format: 'es'
  }
};

// 方式二：对象形式
export default {
  input: {
    main: 'src/main.js',
    admin: 'src/admin.js',
    utils: 'src/utils.js'
  },
  output: {
    dir: 'dist',
    format: 'es'
  }
};

入口文件结构 #

text

src/
├── main.js          # 主入口
├── admin.js         # 管理入口
├── utils/
│   ├── index.js
│   └── helpers.js
└── components/
    ├── index.js
    └── Button.js

输出配置 #

单文件输出 #

javascript

export default {
  input: 'src/main.js',
  output: {
    file: 'dist/bundle.js',
    format: 'iife',
    name: 'MyApp',
    sourcemap: true,
    banner: '// Copyright 2024',
    footer: '// End of bundle'
  }
};

多文件输出 #

javascript

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

输出到目录 #

javascript

export default {
  input: ['src/main.js', 'src/admin.js'],
  output: {
    dir: 'dist',
    format: 'es',
    preserveModules: true,  // 保持模块结构
    preserveModulesRoot: 'src'
  }
};

输出选项详解 #

javascript

output: {
  file: 'dist/bundle.js',
  format: 'es',
  name: 'MyLib',
  sourcemap: true,
  sourcemapFile: 'dist/bundle.js.map',
  banner: '/* My Library v1.0.0 */',
  footer: '/* End of library */',
  intro: 'var ENV = "production";',
  outro: 'console.log("Library loaded");',
  compact: false,
  extend: false,
  exports: 'auto',
  globals: { lodash: '_' },
  assetFileNames: 'assets/[name]-[hash][extname]',
  chunkFileNames: 'chunks/[name]-[hash].js',
  entryFileNames: '[name].js'
}

外部依赖 #

基本用法 #

javascript

export default {
  input: 'src/main.js',
  external: ['lodash', 'axios', 'vue'],
  output: {
    file: 'dist/bundle.js',
    format: 'es'
  }
};

函数形式 #

javascript

export default {
  input: 'src/main.js',
  external: (id) => {
    return /lodash|axios|vue/.test(id);
  },
  output: {
    file: 'dist/bundle.js',
    format: 'es'
  }
};

排除 node_modules #

javascript

import { builtinModules } from 'module';

export default {
  input: 'src/main.js',
  external: [
    ...builtinModules,
    (id) => id.includes('node_modules')
  ],
  output: {
    file: 'dist/bundle.js',
    format: 'es'
  }
};

全局变量映射 #

javascript

export default {
  input: 'src/main.js',
  external: ['lodash', 'jquery'],
  output: {
    file: 'dist/bundle.js',
    format: 'iife',
    globals: {
      lodash: '_',
      jquery: '$'
    }
  }
};

全局变量配置 #

UMD 格式全局变量 #

javascript

export default {
  input: 'src/main.js',
  output: {
    file: 'dist/bundle.umd.js',
    format: 'umd',
    name: 'MyLibrary',
    globals: {
      lodash: '_',
      axios: 'axios'
    }
  },
  external: ['lodash', 'axios']
};

生成的代码 #

javascript

(function (global, factory) {
  typeof exports === 'object' && typeof module !== 'undefined' ? factory(require('lodash')) :
  typeof define === 'function' && define.amd ? define(['lodash'], factory) :
  (global = typeof globalThis !== 'undefined' ? globalThis : global || self, global.MyLibrary = factory(global._));
})(this, (function (_) { 'use strict';
  // ...
}));

Source Map 配置 #

基本配置 #

javascript

export default {
  input: 'src/main.js',
  output: {
    file: 'dist/bundle.js',
    format: 'es',
    sourcemap: true  // 生成 .map 文件
  }
};

Source Map 选项 #

javascript

export default {
  input: 'src/main.js',
  output: {
    file: 'dist/bundle.js',
    format: 'es',
    sourcemap: 'inline',      // 内联 sourcemap
    sourcemap: 'hidden',      // 隐藏 sourcemap
    sourcemapBaseUrl: 'https://example.com/maps/',
    sourcemapFile: 'dist/bundle.js.map',
    sourcemapPathTransform: (relativePath) => {
      return `src/${relativePath}`;
    }
  }
};

Source Map 类型 #

值	描述
`true`	生成独立的 .map 文件
`'inline'`	内联到 JS 文件中
`'hidden'`	生成但不添加注释链接

Tree-shaking 实践 #

自动 Tree-shaking #

Rollup 默认启用 Tree-shaking：

javascript

// math.js
export function add(a, b) {
  return a + b;
}

export function subtract(a, b) {
  return a - b;
}

export function multiply(a, b) {
  return a * b;
}

// main.js
import { add } from './math.js';
console.log(add(1, 2));

// 打包后只有 add 函数

避免 Tree-shaking #

javascript

// 方式一：使用 /* @__PURE__ */ 注释
export const config = /* @__PURE__ */ createConfig();

// 方式二：保留副作用
// package.json
{
  "sideEffects": ["*.css", "*.global.js"]
}

// 方式三：配置 preserveModules
export default {
  output: {
    preserveModules: true
  }
};

副作用标记 #

json

// package.json
{
  "name": "my-library",
  "sideEffects": false
}

javascript

// 或指定有副作用的文件
{
  "sideEffects": [
    "*.css",
    "*.scss",
    "./src/polyfills.js"
  ]
}

模块解析 #

相对路径导入 #

javascript

// src/main.js
import { foo } from './utils.js';
import bar from './helpers/bar.js';

绝对路径导入 #

javascript

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

export default {
  input: 'src/main.js',
  plugins: [
    resolve({
      moduleDirectories: ['node_modules', 'src']
    })
  ]
};

别名配置 #

javascript

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

export default {
  input: 'src/main.js',
  plugins: [
    alias({
      entries: [
        { find: '@', replacement: 'src' },
        { find: '@utils', replacement: 'src/utils' },
        { find: '@components', replacement: 'src/components' }
      ]
    })
  ]
};

使用示例 #

javascript

// 原来的导入
import { foo } from '../../../utils/foo.js';
import Button from '../../../components/Button.js';

// 使用别名后
import { foo } from '@utils/foo.js';
import Button from '@components/Button.js';

CommonJS 模块处理 #

安装插件 #

bash

npm install @rollup/plugin-commonjs @rollup/plugin-node-resolve --save-dev

配置使用 #

javascript

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

export default {
  input: 'src/main.js',
  output: {
    file: 'dist/bundle.js',
    format: 'es'
  },
  plugins: [
    resolve(),
    commonjs()
  ]
};

处理 CommonJS 模块 #

javascript

// 使用 CommonJS 模块
import lodash from 'lodash';
import express from 'express';

// 配置后可以正常打包

JSON 文件导入 #

安装插件 #

bash

npm install @rollup/plugin-json --save-dev

配置使用 #

javascript

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

export default {
  input: 'src/main.js',
  plugins: [json()]
};

使用示例 #

javascript

// src/main.js
import pkg from '../package.json';

console.log(pkg.name);
console.log(pkg.version);

实战示例 #

示例一：简单库打包 #

javascript

// rollup.config.js
import resolve from '@rollup/plugin-node-resolve';
import commonjs from '@rollup/plugin-commonjs';

export default {
  input: 'src/index.js',
  output: [
    {
      file: 'dist/my-lib.cjs.js',
      format: 'cjs'
    },
    {
      file: 'dist/my-lib.esm.js',
      format: 'es'
    }
  ],
  external: ['lodash'],
  plugins: [
    resolve(),
    commonjs()
  ]
};

示例二：浏览器应用 #

javascript

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

const isProduction = process.env.NODE_ENV === 'production';

export default {
  input: 'src/main.js',
  output: {
    file: 'dist/bundle.js',
    format: 'iife',
    name: 'App',
    sourcemap: true
  },
  plugins: [
    resolve({ browser: true }),
    commonjs(),
    isProduction && terser()
  ].filter(Boolean)
};

示例三：多页面应用 #

javascript

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

export default {
  input: {
    main: 'src/pages/main.js',
    admin: 'src/pages/admin.js',
    login: 'src/pages/login.js'
  },
  output: {
    dir: 'dist',
    format: 'iife',
    sourcemap: true
  },
  plugins: [
    resolve(),
    commonjs()
  ]
};

示例四：组件库打包 #

javascript

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

export default {
  input: 'src/components/index.ts',
  output: [
    {
      dir: 'dist',
      format: 'es',
      preserveModules: true,
      preserveModulesRoot: 'src'
    }
  ],
  external: ['vue', 'vue-router'],
  plugins: [
    resolve(),
    commonjs(),
    typescript()
  ]
};

调试技巧 #

查看依赖关系 #

bash

# 显示模块依赖
rollup src/main.js --silent

输出模块信息 #

javascript

import { rollup } from 'rollup';

const bundle = await rollup({
  input: 'src/main.js'
});

// 输出模块信息
console.log(bundle.watchFiles);
console.log(bundle.cache.modules);

分析打包结果 #

javascript

import { rollup } from 'rollup';

const bundle = await rollup({
  input: 'src/main.js'
});

const { output } = await bundle.generate({
  format: 'es'
});

for (const chunk of output) {
  console.log('Chunk:', chunk.fileName);
  console.log('Size:', chunk.code.length);
  console.log('Imports:', chunk.imports);
  console.log('Exports:', chunk.exports);
}

常见问题 #

问题一：找不到模块 #

bash

Error: Could not resolve './utils' from 'src/main.js'

解决方案：

javascript

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

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

问题二：CommonJS 模块报错 #

bash

Error: 'default' is not exported by node_modules/lodash/lodash.js

解决方案：

javascript

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

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

问题三：全局变量未定义 #

bash

ReferenceError: _ is not defined

解决方案：

javascript

export default {
  external: ['lodash'],
  output: {
    globals: { lodash: '_' }
  }
};

下一步 #

现在你已经掌握了 Rollup 的基础使用方法，接下来学习配置详解深入了解各种配置选项！