Rollup踩坑记录：路由配置 | 零性能问题

▌ 技术引导
Rollup 作为主流的打包工具，其路由配置和零性能问题这两个关键词背后藏了不少血泪史。我之前在两个项目中遇到路由配置错误导致应用崩溃，其中一个是由于模块导入路径不一致，另一个是由于静态资源路径没处理好。配置路由时一定得盯紧 `rollup.config.js` 中的 `output` 部分，尤其是 `entry` 和 `file` 的映射关系。我曾用过 `@rollup/plugin-vite` 来做路由处理，但没设置好 `resolve` 配置，导致模块无法找到。零性能问题听起来很美好，但实际在构建过程中，如果没做 `tree-shaking` 和 `code-splitting`，打包体积会爆炸。我曾因为没加 `preserveModules`，打包后所有模块合并成一个，热更新都卡顿。想要零性能问题，必须得在 `output` 配置里明确指定 `format` 和 `entryPoints`，同时在 `plugins` 里使用 `@rollup/plugin-commonjs` 和 `@rollup/plugin-node-resolve`。另外，路径处理时一定要用 `rollup-plugin-replace` 来替换开发环境和生产环境的路径，别想着用 `process.env`，容易出错。

▌ 技术参考
一
Rollup 路由配置的核心问题在于模块路径的映射和输出结构的控制。在 `rollup.config.js` 中，`output` 部分的 `entry` 和 `file` 配置至关重要。例如，如果你使用 `@rollup/plugin-vite`，它的默认行为是将 `index.html` 作为入口，而你如果想用其他 HTML 文件，必须在 `vite.config.js` 中手动指定。或者，如果你使用 `@rollup/plugin-node-resolve`，它会自动解析模块路径，但如果路径没有使用 `@` 或 `~` 开头，会陷入查找死循环。我之前在一个项目中没有配置 `resolve.alias`，导致 `import 'something'` 导入路径不对，整个项目运行不了。解决方法是通过 `resolve.alias` 明确指定模块别名，比如 `'@/utils'`: 'src/utils/index.js'，这样能避免路径混乱。

二
零性能问题的实现依赖于 `tree-shaking` 和 `code-splitting` 的正确配置。`tree-shaking` 会自动去除未使用的代码，但如果模块没有标记为 `sideEffects`，可能会保留无用代码。在 `rollup.config.js` 中，我曾使用 `@rollup/plugin-terser` 压缩代码，但忘了配置 `@rollup/plugin-alias`，导致构建时依赖项冲突。更关键的是，`format` 选择错误，比如把 `iife` 当作生产环境的输出格式，反而增加了构建时间。正确的做法是把 `format` 设置为 `umd` 或 `esm`，并配合 `@rollup/plugin-commonjs` 转换 CommonJS 模块。另外，`output.entryPoints` 配置不当也会导致打包体积失控，特别是多个入口文件被错误合并。

三
路由配置的常见坑点包括路径拼接错误、文件类型不匹配和动态导入兼容性问题。例如，我之前在 `@rollup/plugin-vite` 中使用 `import.meta.glob` 引入多个页面组件，但没在 `output` 中设置 `file` 为 `index.html`，结果所有页面都打包进了一个文件里，导致体积爆炸。解决方法是通过 `output` 明确指定主文件，并利用 `@rollup/plugin-replace` 替换环境变量，比如 `process.env.NODE_ENV`。在动态导入场景下，`@rollup/plugin-commonjs` 可能无法正确解析 `import()` 语法，导致打包失败。这时候可以使用 `@rollup/plugin-typescript` 的 `dynamicImport` 选项，或者在 `output` 中设置 `moduleId` 为 `true`，让 Rollup 自动生成模块 ID。

四
构建性能优化的关键在于减少打包时间与输出体积。我曾遇到一个项目，因为模块大量重复，打包时出现了内存溢出。这时候必须开启 `@rollup/plugin-terser` 的 `compress` 选项，同时在 `rollup.config.js` 中设置 `output.sourcemap` 为 `false`，避免生成源映射文件。另外，`@rollup/plugin-node-resolve` 的 `browser` 选项配置错误，会导致模块被错误地解析为 Node 模块，从而引入不必要的依赖。我曾经在 `browser: true` 情况下，导入了 `fs` 模块，结果打包后体积翻倍。正确的做法是避免导入 Node 内置模块，或者使用 `@rollup/plugin-commonjs` 来替换它们。如果使用了 `@rollup/plugin-typescript`，记得关闭 `sourceMap` 和 `declaration`，避免额外开销。

五
Rollup 的路由配置需要与构建工具深度整合，尤其是 `@rollup/plugin-vite` 和 `@rollup/plugin-node-resolve`。我之前在一个项目中，直接在 `rollup.config.js` 中写 HTML 路由，结果发现文件被错误打包，热更新也无法正常工作。最终改用 `@rollup/plugin-vite` 来处理 HTML 文件，并通过 `vite.config.js` 设置 `rollupPlugins`。同时，`@rollup/plugin-node-resolve` 的 `extensions` 配置不全，导致 `.ts`、`.tsx` 文件无法被正确识别。这时候必须手动添加 `.ts`、`.tsx`、`.js`、`.jsx` 等扩展，否则会引发模块找不到错误。另外，`@rollup/plugin-commonjs` 的 `ignoreDynamic` 选项非常有用，尤其是在处理 `import()` 语法时，能避免打包时的性能损耗。

六
在处理路由文件时，`@rollup/plugin-vite` 的 `rollupOptions` 要配置 `input` 和 `output`，否则会把所有 HTML 文件打包到一个文件里。一个常见的错误是忘记设置 `output.file`，导致所有 HTML 文件都被视为入口，结果打包体积暴涨。我之前在一次部署中，因为没指定 `output.file`，反而把所有页面文件合并成了一个，导致页面加载缓慢。正确的做法是通过 `rollupOptions.input` 指定入口文件，再用 `rollupOptions.output.file` 指定输出路径。同时，`@rollup/plugin-vite` 的 `ssr` 选项配置错误，会导致 SSR 环境下路由失效，要确保它只在客户端使用，或者通过 `mode` 来判断。

七
零性能问题的背后是 Rollup 的构建优化策略。我曾在一个项目中因为没有使用 `@rollup/plugin-terser`，导致 JS 文件体积过大，压缩后体积减少一半。同时，`@rollup/plugin-typescript` 的 `target` 选项如果设置为 `esnext`，反而增加了打包时间。我之前在 `target` 设置为 `es5` 时，构建时间反而缩短了，因为减少了类型检查的范围。此外，`@rollup/plugin-commonjs` 的 `strictRequires` 选项设为 `true`，会强制处理所有 `require` 语句，避免模块被错误解析，这在某些路由场景下至关重要。如果配置不当，会导致模块路径错误，进而引发打包失败。

八
路由配置与 `@rollup/plugin-vite` 插件的配合至关重要。我之前在开发阶段使用 `@rollup/plugin-vite` 来处理 HTML 文件，但没配置 `resolve`，导致模块路径映射错误。正确的做法是通过 `resolve` 的 `alias` 来处理路径，比如 `'@/': 'src/'`。这能避免 `import` 路径错误，减少模块查找时间。另外，`@rollup/plugin-vite` 的 `cssCodeSplit` 选项如果设为 `true`，会把 CSS 文件拆出，避免打包体积膨胀，同时提升加载效率。我在一次项目中因为没开启这个选项，导致 CSS 文件被混进 JS 文件中，页面加载变慢。这个细节我后来才意识到，浪费了几个小时调试。

九
Rollup 的构建性能与 `@rollup/plugin-commonjs` 的配置息息相关。我曾在一个项目中，模块全部是 CommonJS 风格，但 `@rollup/plugin-commonjs` 的 `transformers` 选项没配置好，导致模块被错误地转换，打包体积失控。这时候我不得不手动编写 `transformer` 来处理特定模块，或者直接关闭 `@rollup/plugin-commonjs`，改用 `@rollup/plugin-node-resolve`。同时，`@rollup/plugin-terser` 的 `mangle` 选项设为 `true` 时，能显著减少代码体积，但有时会把模块名改掉，导致后续热更新失败。我之前因为这个错误，不得不在 `terserOptions` 中添加 `keepFnName: true`，避免模块名被压缩掉。

十
零性能问题的实现还依赖于 `@rollup/plugin-typescript` 的配置。我曾在一个项目中，由于 `@rollup/plugin-typescript` 没有开启 `noEmit`，导致所有 TypeScript 文件都被编译成 JS 文件，结果打包时间翻倍。正确的做法是让 `@rollup/plugin-typescript` 仅做类型检查，不输出文件，或者使用 `@rollup/plugin-typescript` 的 `exclude` 选项来过滤不需要编译的文件。此外，`@rollup/plugin-typescript` 的 `rollupOptions` 配置不能完全依赖它，还得配合 `@rollup/plugin-commonjs` 来处理模块转换，否则 Node 模块会被错误解析，导致报错。

十一
Rollup 的路由配置在构建过程中容易出现路径污染问题。我之前在 `@rollup/plugin-node-resolve` 中配置了 `alias`，但没设置 `browser` 为 `true`，结果导致模块在浏览器中解析失败，依赖项找不到。这时候我必须在 `resolve` 中明确设置 `browser: true`，让 Rollup 仅识别浏览器可用模块。另外，`@rollup/plugin-vite` 的 `rollupOptions` 中的 `input` 配置要避免重复引用，否则会导致模块被多次打包。我曾因为输入文件引用了多个组件，导致重复打包，最终文件体积超出预期。解决方法是通过 `@rollup/plugin-vite` 的 `rollupOptions.input` 指定入口文件，避免不必要的依赖引入。

十二
在使用 `@rollup/plugin-vite` 时，路由配置不能仅仅依赖 HTML 文件。我曾在一个项目中，误以为只需要配置 `index.html` 就能处理路由，结果发现所有页面都被打包成一个文件。正确的做法是通过 `@rollup/plugin-vite` 的 `rollupOptions.input` 来处理多个 HTML 文件，并在 `output` 中通过 `file` 明确指定每个页面的输出路径。同时，`@rollup/plugin-vite` 的 `ssr` 选项配置错误会导致 SSR 无法正常工作，尤其是在多页面应用中。这时候需要通过 `mode` 来判断是否是 SSR 环境，或者直接关闭 `ssr` 选项，避免不必要的处理。

十三
零性能问题的实现需要适配不同的输出格式。我曾在一个项目中使用 `@rollup/plugin-umd`，但没配置 `name` 和 `format`，导致输出文件无法被正确加载。这时候必须在 `output` 中明确指定 `name` 和 `format`，比如 `format: 'umd'` 和 `name: 'myApp'`，这样打包后的文件才能被正确引用。另外，`@rollup/plugin-commonjs` 的 `ignoreDynamic` 选项在某些路由场景下非常关键，尤其是处理 `import()` 语法时，可以避免打包时间过长。我之前因为没开启这个选项，导致构建时间增加 200%。

十四
Rollup 的路由配置需要考虑开发与生产环境的差异。我曾在一个项目中，因为没配置 `@rollup/plugin-replace`，导致开发环境中的 `process.env.NODE_ENV` 在生产环境中被错误替换，结果出现路径错误。正确的做法是通过 `replace` 插件在构建时替换变量，比如 `process.env.NODE_ENV === 'development'` 会被替换成 `true` 或 `false`，这会影响动态路径的生成。此外，`@rollup/plugin-node-resolve` 的 `extensions` 配置如果遗漏了 `.ts`、`.tsx`，会导致 TypeScript 文件无法被正确解析，进而影响路由配置。这时候必须手动添加所有所需扩展，避免模块找不到错误。

十五
零性能问题的实现涉及多个插件的协同工作，包括 `@rollup/plugin-commonjs`、`@rollup/plugin-node-resolve` 和 `@rollup/plugin-typescript`。我曾在一个项目中，因为 `@rollup/plugin-commonjs` 的 `transformers` 选项没配置，导致部分模块被错误转换，最终文件体积异常。这时候必须通过 `transformers` 明确指定模块转换规则，或者直接关闭某些不需要的功能。此外，`@rollup/plugin-typescript` 的 `sourceMap` 选项如果设为 `true`，会导致构建时间增加，甚至内存溢出。我之前在生产环境构建时，因为没关闭这个选项，导致构建失败，后来才意识到问题所在。

十六
Rollup 路由配置与 `@rollup/plugin-vite` 的整合需要特别注意 `rollupOptions` 的配置。我之前在 `rollupOptions.input` 中写错了路径，导致所有模块被错误打包，最终整个项目崩溃。正确的做法是通过 `input` 指定入口文件，并在 `output` 中通过 `file` 明确输出路径。同时，`@rollup/plugin-vite` 的 `cssCodeSplit` 选项如果设为 `true`，会把 CSS 文件拆出，避免打包体积膨胀。我之前因为这个选项未启用，导致 CSS 文件被混进 JS 文件中，页面加载变慢，后来才意识到需要配置这个选项。

十七
零性能问题的实现还需要考虑模块的打包策略。例如，`@rollup/plugin-commonjs` 的 `ignoreDynamic` 选项可以控制动态导入的处理方式，避免不必要的打包。我之前在项目中因为没开启这个选项，导致所有 `import()` 语句都被打包进主文件，体积增加了一倍。此外，`@rollup/plugin-typescript` 的 `target` 设置为 `es5` 可以减少打包体积，但也会增加类型检查的开销。我之前在开发阶段设为 `esnext`，导致构建时间过长，后来才调整回来。这种配置需要根据项目需求权衡利弊，不能一概而论。

十八
Rollup 的路由配置需要处理文件类型与模块系统的兼容性问题。我曾在一个项目中，因为 `@rollup/plugin-node-resolve` 没有配置 `extensions`，导致 `.ts` 文件无法被正确识别，模块找不到错误频频出现。这时候必须手动添加 `.ts`、`.tsx` 等扩展，让 Rollup 识别所有文件类型。此外，`@rollup/plugin-vite` 的 `rollupOptions.output` 配置不当会导致资源路径错误，特别是当静态资源未被正确拷贝时。我之前因为没配置 `rollupOptions.output` 的 `assetsDir`，导致所有图片和字体文件被错误打包，最终页面样式失效。

十九
零性能问题的实现还应该结合 `@rollup/plugin-serve` 来处理热更新。我曾在一个项目中，因为 `@rollup/plugin-serve` 的 `watch` 配置错误，导致热更新时模块路径被错误解析，打包失败。正确的做法是通过 `@rollup/plugin-serve` 的 `serve` 选项，指定正确的模块路径，确保热更新能正常工作。此外，`@rollup/plugin-node-resolve` 的 `preferRelative` 选项设置为 `true`，能减少模块查找时间，提升构建性能。我之前因为没配置这个选项，导致模块查找时间长达 10 秒，严重影响开发效率。

二十
Rollup 的路由配置要避免全局依赖污染。我曾在一个项目中，因为 `@rollup/plugin-node-resolve` 没有配置 `browser` 为 `true`，导致模块被错误解析为 Node 模块，进而引入不必要的依赖。这时候必须在 `resolve` 中设置 `browser: true`，让 Rollup 仅识别浏览器可用模块。同时，`@rollup/plugin-typescript` 的 `types` 选项配置错误，会导致类型检查失败，进而影响模块解析。我之前因为没设置 `types: ['./types/index.d.ts']`，导致类型检查无法正常进行，模块路径错误频发。这种细节容易被忽略，但对整体构建稳定性影响巨大。