深入理解Rollup插件机制及Build/Output构建流程

引言

在前一章节中，我们已经掌握了 Rollup 构建工具的基本使用方法，对其核心概念有了初步了解。然而，在实际项目中，仅依靠 Rollup 内置的打包功能往往难以应对日益复杂的构建需求。真实的项目场景通常涉及模块打包之外的诸多问题，例如路径别名（alias）配置、全局变量注入以及代码压缩等。

如果将这些场景的处理逻辑直接耦合到打包核心代码中，不仅会导致打包器本身变得臃肿，还会对原有核心逻辑产生侵入性，混入大量与核心流程无关的代码，从而增加后期维护的难度。为此，Rollup 设计了一套完整的插件机制，将核心逻辑与插件逻辑分离，允许开发者按需引入插件功能，显著提升了 Rollup 的可扩展性。

接下来，我们将深入分析 Rollup 的插件机制，熟悉其完整的构建阶段和工作流程，并结合具体案例探讨插件开发的细节。在 Rollup 的打包过程中，定义了一套完整的构建生命周期。从打包开始到产物输出，中间会经历多个标志性阶段，并在不同阶段自动执行对应的插件钩子函数（Hook）。对于 Rollup 插件而言，钩子函数是最核心的部分：一方面它定义了插件的执行逻辑（即“做什么”），另一方面也声明了插件的作用阶段（即“什么时候做”），这与 Rollup 本身的构建生命周期紧密相关。

一、Rollup构建阶段

在执行 rollup 命令后，CLI 内部的主要逻辑简化如下：

// Build 阶段
const bundle = await rollup.rollup(inputOptions);
// Output 阶段
await Promise.all(outputOptions.map(bundle.write));
// 构建结束
await bundle.close();

Rollup 内部主要经历 Build 和 Output 两大阶段，具体流程如下图所示。

首先，Build 阶段主要负责创建模块依赖图，初始化各个模块的 AST（抽象语法树）以及模块之间的依赖关系。下面我们通过一个简单的例子来直观感受这一过程：

// src/index.js
import { a } from './module-a';
console.log(a);
// src/module-a.js
export const a = 1;

随后，执行如下的构建脚本：

const rollup = require('rollup');
const util = require('util');
async function build() {
  const bundle = await rollup.rollup({
    input: ['./src/index.js'],
  });
  console.log(util.inspect(bundle));
}
build();

执行上述代码后，可以看到如下的 bundle 对象信息。

{
  cache: {
    modules: [
      {
        ast: 'AST 节点信息，具体内容省略',
        code: 'export const a = 1;',
        dependencies: [],
        id: '/Users/code/rollup-demo/src/data.js',
        // 其它属性省略
      },
      {
        ast: 'AST 节点信息，具体内容省略',
        code: "import { a } from './data';\n\nconsole.log(a);",
        dependencies: [
          '/Users/code/rollup-demo/src/data.js'
        ],
        id: '/Users/code/rollup-demo/src/index.js',
        // 其它属性省略
      }
    ],
    plugins: {}
  },
  closed: false,
  // 挂载后续阶段会执行的方法
  close: [AsyncFunction: close],
  generate: [AsyncFunction: generate],
  write: [AsyncFunction: write]
}

从上述信息可以看出，经过 Build 阶段的 bundle 对象实际上并未进行模块的打包。该对象的主要作用是存储各个模块的内容及依赖关系，同时暴露 generate 和 write 方法，以便进入后续的 Output 阶段。

因此，真正的打包过程会在 Output 阶段进行，即在 bundle 对象的 generate 或 write 方法中执行。以上面的 demo 为例，我们稍微改动一下构建逻辑：

const rollup = require('rollup');
async function build() {
  const bundle = await rollup.rollup({
    input: ['./src/index.js'],
  });
  const result = await bundle.generate({
    format: 'es',
  });
  console.log('result:', result);
}
build();

重新执行项目后，可以得到如下的输出结果：

{
  output: [
    {
      exports: [],
      facadeModuleId: '/Users/code/rollup-demo/src/index.js',
      isEntry: true,
      isImplicitEntry: false,
      type: 'chunk',
      code: 'const a = 1;\n\nconsole.log(a);\n',
      dynamicImports: [],
      fileName: 'index.js',
      // 其余属性省略
    }
  ]
}

这里可以看到所有的输出信息，生成的 output 数组即为打包完成的结果。当然，如果使用 bundle.write 方法，会根据配置将最终的产物写入到指定的磁盘目录中。

因此，对于一次完整的构建过程而言，Rollup 会先进入 Build 阶段，解析各模块的内容及依赖关系；然后进入 Output 阶段，完成打包及输出的过程。针对不同的阶段，Rollup 插件会有不同的工作流程，接下来我们将详细拆解 Rollup 插件在 Build 和 Output 两个阶段的具体工作流程。

二、拆解插件工作流

2.1 插件 Hook 类型

在详细讲述 Rollup 插件工作流之前，我想先介绍不同类型的插件 Hook。这些类型代表了不同插件的执行特点，是理解 Rollup 插件工作流的基础，因此有必要进行详细拆解。

通过上文的例子，相信你可以直观地理解 Rollup 两大构建阶段（Build 和 Output）各自的原理。你可能会有疑问，这两个阶段到底与插件机制有何关系？实际上，插件的各种 Hook 可以根据这两个构建阶段分为两类：Build Hook 与 Output Hook。

Build Hook：在 Build 阶段执行的钩子函数。在这个阶段，主要进行模块代码的转换、AST 解析以及模块依赖的解析。该阶段的 Hook 对代码的操作粒度一般为模块级别，即单文件级别。
Output Hook：（官方称为 Output Generation Hook），主要进行代码的打包。对于代码而言，其操作粒度一般为 chunk 级别，而一个 chunk 通常指多个文件打包到一起的产物。

除了根据构建阶段对 Rollup 插件进行分类外，根据不同的 Hook 执行方式也会有不同的分类，主要包括 Async、Sync、Parallel、Sequential、First 这五种。在实际开发中，我们会接触到各种各样的插件 Hook，但无论哪种 Hook，都离不开这五种执行方式。接下来，让我们具体认识一下这五个函数钩子。

Async & Sync

首先是 Async 和 Sync 钩子函数，两者相对，分别代表异步和同步的钩子函数。两者最大的区别在于：同步钩子中不能包含异步逻辑，而异步钩子可以包含异步逻辑。

Parallel

Parallel 用来代表并行钩子函数。如果有多个插件实现了这个钩子的逻辑，一旦有钩子函数是异步逻辑，则并发执行钩子函数，不会等待当前钩子完成（底层使用 Promise.all）。

例如，对于 Build 阶段的 buildStart 钩子，其执行时机是在构建刚开始的时候。各个插件可以在这个钩子中做一些状态初始化操作。由于插件之间的操作通常不相互依赖，因此可以并发执行，从而提升构建性能。反之，对于需要依赖其他插件处理结果的情况（如 transform），则不适合使用 Parallel 钩子。

Sequential

Sequential 指串行的钩子函数。这种 Hook 往往适用于插件间处理结果相互依赖的情况。前一个插件 Hook 的返回值作为后续插件的入参，这种情况需要等待前一个插件执行完 Hook，获得其执行结果后，才能进行下一个插件相应 Hook 的调用，例如 transform。

First

如果有多个插件实现了这个 Hook，那么 Hook 将依次运行，直到返回一个非 null 或非 undefined 的值为止。比较典型的 Hook 是 resolveId，一旦有插件的 resolveId 返回了一个路径，将停止执行后续插件的 resolveId 逻辑。

刚刚我们介绍了 Rollup 中不同插件 Hook 的类型。实际上，不同的类型是可以叠加的，Async/Sync 可以搭配后面三种类型中的任意一种，例如一个 Hook 既可以是 Async 也可以是 First 类型。接下来，我们具体分析一下 Rollup 中的插件工作流程。

2.2 Build 阶段工作流

首先，我们来分析 Build 阶段的插件工作流程。对于 Build 阶段，插件 Hook 的调用流程如下图所示。

流程图的最上面声明了不同 Hook 的类型，即我们在上面总结的 5 种 Hook 分类。每个方块代表了一个 Hook，边框的颜色表示 Async 和 Sync 类型，方块的填充颜色表示 Parallel、Sequential 和 First 类型。

接下来，我们一步步分析 Build Hooks 的工作流程，你可以对照着图一起看。

首先经历 options 钩子进行配置的转换，得到处理后的配置对象。
随后 Rollup 会调用 buildStart 钩子，正式开始构建流程。
Rollup 先进入到 resolveId 钩子中解析文件路径（从 input 配置指定的入口文件开始）。
Rollup 通过调用 load 钩子加载模块内容。
紧接着 Rollup 执行所有的 transform 钩子来对模块内容进行自定义转换，例如 babel 转译。
现在 Rollup 拿到了模块内容，接下来进行 AST 分析，得到所有的 import 内容，并调用 moduleParsed 钩子。如果是普通的 import，则执行 resolveId 钩子，继续回到步骤 3；如果是动态 import，则执行 resolveDynamicImport 钩子解析路径。如果解析成功，则回到步骤 4 加载模块；否则回到步骤 3 通过 resolveId 解析路径。
直到所有的 import 都解析完毕，Rollup 执行 buildEnd 钩子，Build 阶段结束。

当然，在 Rollup 解析路径时，即执行 resolveId 或 resolveDynamicImport 时，有些路径可能会被标记为 external（排除），这意味着不参与 Rollup 打包过程。此时，就不会进行 load、transform 等后续处理了。

在流程图最上面，大家可能注意到了 watchChange 和 closeWatcher 这两个 Hook，这里对应的是 rollup 的 watch 模式。当你使用 rollup --watch 指令或在配置文件配置 watch: true 属性时，代表开启了 Rollup 的 watch 打包模式。此时，Rollup 内部会初始化一个 watcher 对象，当文件内容发生变化时，watcher 对象会自动触发 watchChange 钩子执行并对项目进行重新构建。在当前打包过程结束时，Rollup 会自动清除 watcher 对象并调用 closeWatcher 钩子。

2.3 Output 阶段工作流

好，接着我们来看看 Output 阶段的插件是如何工作的。这个阶段的 Hook 相比于 Build 阶段稍多，流程上也更加复杂。需要注意的是，其中涉及的 Hook 函数较多，可能会给理解整个流程带来一些困扰。因此，我会在 Hook 执行的阶段解释其大致的作用和意义，关于具体的使用大家可以去 Rollup 的官网自行查阅。毕竟这里的主线是分析插件的执行流程，掺杂太多的使用细节反而不易于理解。下面我结合一张完整的插件流程图和你具体分析一下。

以下是关于 Output 阶段工作流的说明：

执行所有插件的 outputOptions 钩子函数，对 output 配置进行转换。
执行 renderStart，并发执行 renderStart 钩子，正式开始打包。
并发执行所有插件的 banner、footer、intro、outro 钩子（底层用 Promise.all 包裹所有的这四种钩子函数）。这四个钩子功能很简单，就是往打包产物的固定位置（例如头部和尾部）插入一些自定义内容，例如协议声明内容、项目介绍等。
从入口模块开始扫描，针对动态 import 语句执行 renderDynamicImport 钩子，来自定义动态 import 的内容。
对每个即将生成的 chunk，执行 augmentChunkHash 钩子，来决定是否更改 chunk 的哈希值。在 watch 模式下即可能会多次打包的场景下，这个钩子会比较适用。
如果没有遇到 import.meta 语句，则进入下一步；否则执行如下 Case。对于 import.meta.url 语句调用 resolveFileUrl 来自定义 url 解析逻辑；对于其他 import.meta 属性，则调用 resolveImportMeta 来进行自定义解析。
接着 Rollup 会生成所有 chunk 的内容，针对每个 chunk 会依次调用插件的 renderChunk 方法进行自定义操作。也就是说，在这里可以直接操作打包产物了。
随后会调用 generateBundle 钩子，这个钩子的入参里面会包含所有的打包产物信息，包括 chunk（打包后的代码）和 asset（最终的静态资源文件）。可以在这里删除一些 chunk 或者 asset，最终这些内容将不会作为产物输出。
由于 rollup.rollup 方法会返回一个 bundle 对象，这个对象包含 generate 和 write 两个方法。两个方法唯一的区别在于后者会将代码写入到磁盘中，同时会触发 writeBundle 钩子，传入所有的打包产物信息（包括 chunk 和 asset），与 generateBundle 钩子非常相似。不过值得注意的是，这个钩子执行的时候，产物已经输出了；而 generateBundle 执行的时候，产物还并没有输出。

当上述 bundle 的 close 方法被调用时，会触发 closeBundle 钩子。到这里，Output 阶段正式结束。

到这里，我们终于梳理完了 Rollup 中完整的插件工作流程。从一开始在构建生命周期中对两大构建阶段的感性认识，到现在插件工作流的具体分析，不禁感叹 Rollup 看似简单，实则内部细节繁杂。

三、常用 Hook

实际上，开发 Rollup 插件就是在编写一个个 Hook 函数。你可以理解为一个 Rollup 插件基本就是各种 Hook 函数的组合。

1，路径解析: resolveId

resolveId 钩子一般用来解析模块路径，为 Async + First 类型（即异步优先）的钩子。这里我们拿官方的 alias 插件来说明，这个插件用法演示如下：

// rollup.config.js
import alias from '@rollup/plugin-alias';
module.exports = {
  input: 'src/index.js',
  output: {
    dir: 'output',
    format: 'cjs'
  },
  plugins: [
    alias({
      entries: [
        // 将把 import xxx from 'module-a' 
        // 转换为 import xxx from './module-a'
        { find: 'module-a', replacement: './module-a.js' },
      ]
    })
  ]
};

插件的代码简化后如下：

export default alias(options) {
  // 获取 entries 配置
  const entries = getEntries(options);
  return {
    // 传入三个参数，当前模块路径、引用当前模块的模块路径、其余参数
    resolveId(importee, importer, resolveOptions) {
      // 先检查能不能匹配别名规则
      const matchedEntry = entries.find((entry) => matches(entry.find, importee));
      // 如果不能匹配替换规则，或者当前模块是入口模块，则不会继续后面的别名替换流程
      if (!matchedEntry || !importerId) {
        // return null 后，当前的模块路径会交给下一个插件处理
        return null;
      }
      // 正式替换路径
      const updatedId = normalizeId(
        importee.replace(matchedEntry.find, matchedEntry.replacement)
      );
      // 每个插件执行时都会绑定一个上下文对象作为 this
      // 这里的 this.resolve 会执行所有插件(除当前插件外)的 resolveId 钩子
      return this.resolve(
        updatedId,
        importer,
        Object.assign({ skipSelf: true }, resolveOptions)
      ).then((resolved) => {
        // 替换后的路径即 updateId 会经过别的插件进行处理
        let finalResult: PartialResolvedId | null = resolved;
        if (!finalResult) {
          // 如果其它插件没有处理这个路径，则直接返回 updateId
          finalResult = { id: updatedId };
        }
        return finalResult;
      });
    }
  }
}

从这里你可以看到 resolveId 钩子函数的一些常用使用方式。它的入参分别是当前模块路径、引用当前模块的模块路径、解析参数，返回值可以是 null、string 或者一个对象。下面我们分情况讨论一下。

返回值为 null 时，会默认交给下一个插件的 resolveId 钩子处理。
返回值为 string 时，则停止后续插件的处理。这里为了让替换后的路径能被其他插件处理，特意调用了 this.resolve 来交给其它插件处理，否则将不会进入到其它插件的处理。
返回值为一个对象时，也会停止后续插件的处理。不过这个对象可以包含更多的信息，包括解析后的路径、是否被 external、是否需要 tree-shaking 等。不过大部分情况下，返回一个 string 就够用了。

2，load

load 为 Async + First 类型（即异步优先）的钩子，和 resolveId 类似。它的作用是通过 resolveId 解析后的路径来加载模块内容。这里，我们以官方的 image 插件为例来介绍一下 load 钩子的使用。源码简化后如下所示：

const mimeTypes = {
  '.jpg': 'image/jpeg',
  // 后面图片类型省略
};
export default function image(opts = {}) {
  const options = Object.assign({}, defaults, opts);
  return {
    name: 'image',
    load(id) {
      const mime = mimeTypes[extname(id)];
      if (!mime) {
        // 如果不是图片类型，返回 null，交给下一个插件处理
        return null;
      }
      // 加载图片具体内容
      const isSvg = mime === mimeTypes['.svg'];
      const format = isSvg ? 'utf-8' : 'base64';
      const source = readFileSync(id, format).replace(/[\r\n]+/gm, '');
      const dataUri = getDataUri({ format, isSvg, mime, source });
      const code = options.dom ? domTemplate({ dataUri }) : constTemplate({ dataUri });
      return code.trim();
    }
  };
}

从中可以看到，load 钩子的入参是模块 id，返回值一般是 null、string 或者一个对象：

如果返回值为 null，则交给下一个插件处理；
如果返回值为 string 或者对象，则终止后续插件的处理。如果是对象，可以包含 SourceMap、AST 等。

3，代码转换: transform

transform 钩子也是非常常见的一个钩子函数，为 Async + Sequential 类型（即异步串行钩子），作用是对加载后的模块内容进行自定义转换。我们以官方的 replace 插件为例，这个插件的使用方式如下：

// rollup.config.js
import replace from '@rollup/plugin-replace';
module.exports = {
  input: 'src/index.js',
  output: {
    dir: 'output',
    format: 'cjs'
  },
  plugins: [
    // 将会把代码中所有的 __TEST__ 替换为 1
    replace({
      __TEST__: 1
    })
  ]
};

事实上，transform 的内部实现也并不是很复杂，主要通过字符串替换来实现，核心逻辑简化如下：

import MagicString from 'magic-string';
export default function replace(options = {}) {
  return {
    name: 'replace',
    transform(code, id) {
      // 省略一些边界情况的处理
      // 执行代码替换的逻辑，并生成最后的代码和 SourceMap
      return executeReplacement(code, id);
    }
  }
}
function executeReplacement(code, id) {
  const magicString = new MagicString(code);
  // 通过 magicString.overwrite 方法实现字符串替换
  if (!codeHasReplacements(code, id, magicString)) {
    return null;
  }
  const result = { code: magicString.toString() };
  if (isSourceMapEnabled()) {
    result.map = magicString.generateMap({ hires: true });
  }
  // 返回一个带有 code 和 map 属性的对象
  return result;
}

transform 钩子的入参分别为模块代码、模块 ID，返回一个包含 code（代码内容）和 map（SourceMap 内容）属性的对象。当然，也可以返回 null 来跳过当前插件的 transform 处理。需要注意的是，当前插件返回的代码会作为下一个插件 transform 钩子的第一个入参，实现类似于瀑布流的处理。

4，Chunk 级代码修改: renderChunk

这里我们继续以 replace 插件举例，在这个插件中，也同样实现了 renderChunk 钩子函数：

export default function replace(options = {}) {
  return {
    name: 'replace',
    transform(code, id) {
      // transform 代码省略
    },
    renderChunk(code, chunk) {
      const id = chunk.fileName;
      // 省略一些边界情况的处理
      // 拿到 chunk 的代码及文件名，执行替换逻辑
      return executeReplacement(code, id);
    },
  }
}

可以看到这里 replace 插件为了替换结果更加准确，在 renderChunk 钩子中又进行了一次替换。因为后续的插件仍然可能在 transform 中进行模块内容转换，进而可能出现符合替换规则的字符串。

这里我们把关注点放到 renderChunk 函数本身，可以看到有两个入参，分别为 chunk 代码内容、chunk 元信息。返回值跟 transform 钩子类似，既可以返回包含 code 和 map 属性的对象，也可以通过返回 null 来跳过当前钩子的处理。

5，generateBundle

generateBundle 也是异步串行的钩子。你可以在这个钩子里面自定义删除一些无用的 chunk 或者静态资源，或者自己添加一些文件。这里我们以 Rollup 官方的 html 插件来具体说明，这个插件的作用是通过拿到 Rollup 打包后的资源来生成包含这些资源的 HTML 文件，源码简化后如下所示：

export default function html(opts: RollupHtmlOptions = {}): Plugin {
  // 初始化配置
  return {
    name: 'html',
    async generateBundle(output: NormalizedOutputOptions, bundle: OutputBundle) {
      // 省略一些边界情况的处理
      // 1. 获取打包后的文件
      const files = getFiles(bundle);
      // 2. 组装 HTML，插入相应 meta、link 和 script 标签
      const source = await template({ attributes, bundle, files, meta, publicPath, title});
      // 3. 通过上下文对象的 emitFile 方法，输出 html 文件
      const htmlFile: EmittedAsset = {
        type: 'asset',
        source,
        name: 'Rollup HTML Asset',
        fileName
      };
      this.emitFile(htmlFile);
    }
  }
}

相信从插件的具体实现中，你也能感受到这个钩子的强大作用了。入参分别为 output 配置、所有打包产物的元信息对象。通过操作元信息对象，你可以删除一些不需要的 chunk 或者静态资源，也可以通过插件上下文对象的 emitFile 方法输出自定义文件。

好，常用的 Rollup 钩子我们就先介绍到这里。相信这些知识点已经足够你应付大多数的构建场景了。顺便说一句，大家在后面的章节可以了解到，Vite 的插件机制也是基于 Rollup 来实现的。像上面介绍的这些常用钩子在 Vite 当中也随处可见，因此，掌握了这些常用钩子，也相当于给 Vite 插件的学习做下了很好的铺垫。

以上就是 Rollup 的插件机制的详细内容，更多关于 Rollup 插件机制的资料请关注本站其它相关文章！

Rollup插件机制与构建流程深度解析

引言