新手必看：Rollup错误处理 | 15分钟学会

▌ 技术引导
Rollup错误处理是开发中绕不开的痛点，尤其在2024年及2025年的项目实践中，错误信息往往模糊不清，缺乏上下文。我踩坑时发现，很多开发者在遇到问题时直接看报错信息，却不知道这些信息背后是Rollup的模块解析、代码转换或打包逻辑导致的。实际操作中，需要通过具体配置、调试工具和日志分析来精准定位错误源。我见过的几个典型场景包括：模块无法解析、代码转换失败、依赖冲突、构建缓存污染，还有环境变量未生效。每个问题都对应不同的解决策略，比如使用`--no-cache`清除缓存、配置`resolve.alias`调整模块路径、通过`onwarn`钩子拦截并处理警告，甚至用`rollup-plugin-serve`提升调试效率。这些细节不是理论，是真实发生的，要记住，别让错误信息误导你，得主动去查。

▌ 技术参考

一 Rollup的错误系统是基于ES模块语法的，它会在运行时收集所有错误，并将其转换为用户的代码逻辑。在2025年中，我遇到最多的情况是模块路径错误，比如`import`语句中的`./utils`找不到，但Rollup不会直接报错，而是提示`Cannot find module`，这种提示对新手来说毫无意义。解决方法是使用`resolve.alias`来创建别名，例如在rollup.config.js中加入`resolve: { alias: { '@': path.resolve(__dirname, 'src') } }`，这样所有以`@`开头的模块都会映射到`src`目录，减少路径混乱。此外，2024年中某些项目会因为第三方包的相对路径问题导致错误，这时候需要检查`package.json`中的`type`字段是否为`module`，否则Rollup可能误判模块类型。

二 遇到代码转换错误时，比如ts、js、css等文件处理异常，常见的错误类型是`Cannot compile`或`Unexpected token`。这时候需要确认是否使用了正确的插件，比如`@rollup/plugin-typescript`或`postcss`。如果使用了TypeScript，确保配置文件tsconfig.json中`module`字段设置为`ESNext`，因为Rollup默认处理ES模块，而不是CommonJS。另外，2026年中某些项目会因为`@types`包未安装导致类型检查失败，这时候需要手动安装对应类型的包，例如`npm install @types/lodash --save-dev`。在构建过程中，可以通过`onwarn`钩子来拦截并处理某些警告，比如禁用“unused variable”警告，避免日志冗余。

三 当依赖冲突发生时，Rollup会因为多个包导出相同的模块名而报错。比如某个包导出了`utils`，另一个包也导出了`utils`，这时候需要使用`external`选项排除冲突模块，或通过`rollup-plugin-node-resolve`来指定优先解析的路径。2024年某个项目曾因`rollup-plugin-node-resolve`未配置`extensions`导致某些`.js`或`.ts`文件未被正确解析，关键问题在于没有将`.ts`扩展加入`extensions`数组，导致模块路径不匹配。正确配置应为`resolve: { extensions: ['.js', '.ts', '.mjs'] }`，这样Rollup就能识别所有扩展类型。此外，使用`rollup-plugin-json`可以避免JSON文件解析失败，但必须确保`package.json`中没有错误的语法。

四 构建缓存污染是2025年常见的问题之一。当某些文件未被正确更新时，Rollup可能读取旧缓存，导致构建结果不一致。解决方法是使用`--no-cache`参数强制清空缓存，或者在配置文件中设置`cache: false`。但这样做会影响构建速度，尤其是在大规模项目中。我见过一些项目因为未正确配置`watch`选项而导致缓存未及时更新，导致开发中反复出现错误。正确的做法是确保`watch`选项中的`include`和`exclude`合理，避免不必要的文件被重新编译。例如`watch: { include: 'src//' }`，这样Rollup只会监听`src`目录下的变化。

五 在某些特殊场景中，比如需要处理环境变量，Rollup本身并不支持动态变量替换，这就导致了开发者在不同环境下的构建问题。比如在2024年中，我曾因为`process.env`在构建后被替换为空，导致某些配置失效。解决方法是使用`rollup-plugin-replace`插件，手动替换环境变量。例如`replace({ 'process.env.NODE_ENV': JSON.stringify('production') })`，这样就能在构建时将环境变量替换为实际值。此外，如果项目涉及多环境构建，建议使用`rollup-plugin-envify`，它能将环境变量注入到代码中，确保不同环境下的表现一致。

六 当Rollup无法识别某些模块时，比如第三方库的`umd`或`commonjs`格式，错误信息通常会是`Unknown subpath`或`Cannot find module`。这时候需要使用`rollup-plugin-node-resolve`和`rollup-plugin-commonjs`来处理这些模块。例如，配置`resolve: { preferBuiltins: false }`，避免Rollup优先使用Node.js内置模块。在2025年中，有些项目因为未正确配置`external`而将内部模块打包进最终输出，导致体积膨胀，也引发依赖错误。正确的做法是将内部模块标记为外部，比如`external: ['lodash']`，这样它们就不会被包含进最终的bundle中。

七 在2026年中，我遇到一个典型问题：某些CSS文件在构建时因为未正确配置`postcss`插件，导致样式未被正确注入。例如，使用`rollup-plugin-postcss`时未设置`extract`为`true`，结果CSS被编译到JavaScript中，影响性能。正确的配置是`postcss: { extract: true, minimize: true }`，这样CSS会提取为单独文件。此外，如果CSS文件中使用了`@import`语法，Rollup可能无法正确处理，这时候需要使用`postcss-import`插件来解析这些引用。配置文件中应加入`plugins: [postcssImport()]`，确保导入语句被正确转换。

八 使用`rollup-plugin-terser`进行代码压缩时，如果没有处理错误，可能会导致压缩后的文件无法运行。例如，2024年某个项目在压缩时因为`terser`的`warnings`选项未正确配置，导致某些语法错误被忽略，最终打包失败。正确的做法是设置`warnings: false`，避免压缩时抛出非致命警告。此外，如果遇到`Unexpected token`错误，可能是由于`terser`无法处理某些模块，这时候可以使用`rollup-plugin-terser`的`compress`选项，比如`compress: true`，这样可以确保代码被正确压缩。同时，`rollup-plugin-terser`支持`keepFnames`参数，用于保留函数名，避免混淆。

九 在某些情况下，Rollup会因为文件编码问题导致构建失败。比如2025年中，某些项目在`ts`文件中使用了`utf-8`以外的编码，导致`rollup-plugin-tsc`无法正确解析代码。解决方法是使用`rollup-plugin-typescript2`代替`rollup-plugin-tsc`，因为它支持更多编码类型，并且在2026年中被广泛使用。此外，配置`tsc`时需确保`target`和`module`字段匹配，否则会出现`Unsupported module type`错误。例如，设置`target: 'es2022'`和`module: 'ESNext'`，可以确保代码兼容性。如果遇到构建失败，建议使用`--verbose`参数查看详细日志，这能提供更明确的错误位置。

十 遇到`rollup-plugin-eslint`报错时，错误信息通常会是`Parsing error: Unexpected token`或`Variable not defined`。这些错误往往是因为代码中存在ESLint不支持的语法，比如`async/await`或`import`语句。解决方法是确保`eslint`的`parserOptions`中`ecmaVersion`和`sourceType`设置正确。例如，配置`parserOptions: { ecmaVersion: 2022, sourceType: 'module' }`，这样ESLint就能正确解析代码。此外，某些项目在使用`@typescript-eslint/parser`时，会因为未正确配置`tsconfigPath`导致类型检查失败，这时候需要在`eslint`配置文件中指定`tsconfigPath: './tsconfig.json'`。如果遇到构建失败，建议使用`--fix`参数让ESLint自动修复部分错误。

十一 在2026年中，我发现某些项目因为`rollup-plugin-vue`未正确配置`transformAssetUrls`，导致图片、字体等静态资源未被正确替换。例如，错误信息可能是`Asset URL not found`或`File not found`。解决方法是确保`transformAssetUrls`的配置项包含`img`、`css`等标签，如`transformAssetUrls: { img: 'url', css: 'url' }`。此外，使用`rollup-plugin-vue`时，必须确保`@vitejs/plugin-vue`也正确安装，否则会出现`Missing plugin`错误。如果遇到构建失败，建议使用`--watch`参数实时监控文件变化，确保资源路径正确。

十二 当使用`rollup-plugin-node-resolve`时，如果模块路径不正确，Rollup会提示`Cannot find module`。例如，2024年中一个项目使用了`./utils`路径，但该路径不存在，导致构建失败。解决方法是使用`rollup-plugin-node-resolve`配合`rollup-plugin-commonjs`，确保模块被正确解析。此外，如果使用了`@rollup/plugin-typescript`，还需要确认`tsconfig.json`中的`outDir`是否正确，否则打包后的文件路径会出错。例如，设置`outDir: 'dist'`，确保所有输出文件都放在正确目录。如果遇到路径问题，建议使用`path.resolve`来确保相对路径转换为绝对路径。

十三 在某些项目中，`rollup-plugin-json`未正确配置会导致JSON文件未被处理。比如2025年中，一个项目将`package.json`作为模块引入，但未配置`rollup-plugin-json`，结果报错`Unknown subpath`。解决方法是安装`rollup-plugin-json`插件，并在配置文件中设置`json: true`，确保所有`.json`文件被正确读取。此外，如果JSON文件中包含`import`语句，需要使用`rollup-plugin-json`的`namedExports`参数，例如`namedExports: true`，确保导出的变量被正确识别。如果遇到JSON解析错误，建议检查文件格式是否正确，是否有额外的逗号或缺失的括号。

十四 使用`rollup-plugin-multi-file`时，如果未正确配置输出路径，会导致多个文件被合并或覆盖。比如2026年中，一个项目希望将多个组件打包为独立文件，但未设置`output.file`，结果所有组件都被打包到同一个文件中。解决方法是配置`output: { file: 'dist/index.js', format: 'umd', name: 'MyApp' }`，确保每个组件都有独立的输出路径。此外，使用`rollup-plugin-multi-file`时，需要确保`input`文件路径正确，否则会出现`File not found`错误。如果遇到合并问题，建议使用`rollup-plugin-multi-file`的`split`选项，将文件拆分为独立模块。

十五 在2024年中，我发现某些项目因为`rollup-plugin-commonjs`未正确配置导致模块无法打包。比如某个项目使用了`commonjs`模块，但未设置`transformCommonJS`为`true`，结果报错`Unknown subpath`。解决方法是确保在配置文件中加入`commonjs: true`，同时设置`external`排除Node.js内置模块，如`external: ['fs', 'path', 'os']`。此外，`rollup-plugin-commonjs`支持`ignoreGlobal`参数，可以排除某些全局模块，避免冲突。如果遇到模块转换错误，建议使用`--verbose`参数查看详细日志，确认哪些模块未被正确转换。同时，优先使用`rollup-plugin-typescript2`代替`rollup-plugin-tsc`，因为它更稳定且支持更多语法。