HelloWorld 与 Rollup 使用教程

用Rollup打包一个HelloWorld教程很简单：建项目、写代码、配置rollup、运行构建并测试。还会讲sourcemap、代码分割、插件和输出格式，配合实例一步步演示，帮助你在真实项目中上手。文章会从零开始，手把手演示如何用ES模块写组件、如何用插件处理静态资源、如何在CI里自动化构建与发布

为什么用Rollup？先把本质说清楚

把Rollup想成一个把零散代码粘成一个“光滑”包的工具。它的重点不是做复杂的开发服务器（像某些工具那样），而是把库和应用按模块打包成体积小、启动快的输出。*如果你要构建对体积敏感的库或精简的前端包，Rollup通常比传统打包器更合适。*

准备工作（你需要的东西）

• Node.js（建议 >= 14）
• npm 或 yarn
• 一个空文件夹作为项目根

下面我们从零开始做一个最简单的 HelloWorld，然后逐步扩展到更接近真实项目的场景。

一步步示范：从零到可用的 HelloWorld

1. 初始化项目

在终端里：

mkdir hello-rollup
cd hello-rollup
npm init -y

这会生成一个最基础的 package.json，接下来安装 Rollup：

npm install --save-dev rollup

2. 写源代码

创建 src 目录，并写两个简单模块，借此演示 ES 模块的打包：

// src/greet.js
export function greet(name) {
  return `Hello, ${name}!`;
}
// src/index.js
import { greet } from './greet.js';
console.log(greet('World'));

3. 添加 Rollup 配置（基础版）

在项目根创建 rollup.config.js，最简单的配置只需指定入口和输出：

export default {
  input: 'src/index.js',
  output: {
    file: 'dist/bundle.js',
    format: 'iife', // 浏览器可直接运行
    name: 'MyBundle'
  }
};

然后在 package.json 添加脚本：

"scripts": {
  "build": "rollup -c"
}

运行 npm run build，会在 dist 目录下得到 bundle.js，直接在浏览器里用 <script> 引入可以看到控制台输出。

理解配置中的关键项（用费曼法讲清楚）

把 Rollup 的配置拆成三块想：入口（input）、输出（output）和插件（plugins）。入口告诉 Rollup 从哪开始追踪依赖，输出定义最终文件的格式与位置，插件负责处理非标准语法或额外资源（比如 Node 模块解析、CommonJS 转换、打包 CSS 等）。

输出格式说明

• esm：保留 ES 模块输出，适合现代浏览器和打包库的二次打包。
• cjs：CommonJS，适合 Node 或老打包链。
• iife：自执行函数，可直接在浏览器通过全局变量使用。
• umd：通用模块定义，兼容多种环境。

进阶：常用插件与场景示例

Rollup 本身只会处理原生 ES 模块，你通常需要几个插件把体验补足。下面列出常见插件和它们为什么需要。

• @rollup/plugin-node-resolve：解析 node_modules 中的包。
• @rollup/plugin-commonjs：把 CommonJS 模块转换成 ES 模块，常见于很多 npm 包。
• @rollup/plugin-babel 或 rollup-plugin-typescript2：转译新语法或 TypeScript。
• rollup-plugin-terser：压缩输出代码。
• rollup-plugin-postcss：打包和处理样式文件。

示例：给刚才项目增加解析与压缩

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

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

export default {
  input: 'src/index.js',
  plugins: [resolve(), commonjs(), terser()],
  output: {
    file: 'dist/bundle.min.js',
    format: 'iife',
    name: 'MyBundle',
    sourcemap: true
  }
};

调试与 sourcemap

在开发时开启 sourcemap: true 很重要，这样压缩后的代码仍能映射回源文件，方便在浏览器里断点调试。不要在正式发布时忘了同时上传 source map（如果你希望别人能调试的话），但也要谨慎，source map 可能泄露源码。

代码分割（code-splitting）

当你的项目有多个入口或想把公共库分离时，Rollup 可以生成多文件输出。把 input 设为对象或数组即可：

// rollup.config.js (示例)
export default {
  input: {
    main: 'src/main.js',
    vendor: 'src/vendor.js'
  },
  output: {
    dir: 'dist',
    format: 'esm'
  },
  plugins: [resolve(), commonjs()]
};

这样输出会在 dist 里生成多个 chunk，浏览器按需加载更合理。

静态资源和样式处理（常见坑）

大多数纯 JS 打包器不会直接内嵌图片或 CSS，需要插件。常见错误是忘了处理图片引用，导致打包后路径错误。一个常见解决方案是：

• 使用 postcss 插件将 CSS 打包或提取成独立文件。
• 使用 url 或 asset 插件把小文件内联，大文件复制到输出目录。

集成到 CI（示例流程）

把构建放进 CI 流程通常很直白，关键是保证 Node 版本和依赖一致，构建脚本简单明了。一个典型流程：

• 安装依赖（npm ci 或 yarn install –frozen-lockfile）
• 运行测试
• 运行构建（npm run build）
• 把 dist 目录发布到静态托管或包管理器

举个伪脚本（CI 配置里常见）：

steps:
  - name: install
    run: npm ci
  - name: test
    run: npm test
  - name: build
    run: npm run build
  - name: publish
    run: npm run publish

对比表：Rollup 常见配置项速览

常见问题与调试小技巧（那些真实会碰到的）

• 模块未找到：确认是否安装了依赖，以及是否使用了 @rollup/plugin-node-resolve。
• CommonJS 导出问题：使用 @rollup/plugin-commonjs，并检查是否需要指定 namedExports（尽量避免，优先升级包到 ESM）。
• 运行时报错 “this is undefined”：检查输出格式，某些库期望特定格式（比如 UMD）。
• 样式或图片路径错乱：确认插件是否把静态资源复制或内联，路径是否相对输出目录。

把 Rollup 用在真实库开发中（实践建议）

如果你要发布一个库，通常会做多个输出：ESM 供现代打包器消费，CJS 供 Node 使用，另可提供一个压缩版供直接浏览器引入。package.json 常见字段：

{
  "main": "dist/my-lib.cjs.js",
  "module": "dist/my-lib.esm.js",
  "browser": "dist/my-lib.iife.js"
}

保证你的 rollup 配置能生成这些不同格式，写好 sourcemap，并在发布前做最小化测试（比如在一个空的 HTML 里引入 iife 版确认全局名正确）。

一些额外的提示（我自己常用的小技巧）

• 开发时用 rollup -c -w 来监听文件变化，节省重建时间。
• 尽量使用 ESM 源包，能减少 CommonJS 转换带来的复杂性。
• 把大依赖标记为 external（在库开发时），避免把它们打包进你的库。

参考与进一步阅读（文献名）

• Rollup 官方文档（建议作为首选参考）
• 《前端工程化实践》相关章节（讨论模块打包策略）

写到这儿，感觉像是把自己平时搭项目的步骤理了个顺序，可能还有些边界情况没覆盖到（比如 SSR、特殊的第三方包兼容性问题），但把入口、输出、插件这三块弄清楚，HelloWorld 到生产库中间的主要障碍就都能一步步拆解解决了。你要是现在去试一遍，从最简单的 iife 输出开始，遇到问题再回来查对应插件和配置，效率会高很多。