Rollup与Rolldown配置冲突如何解决？

Question

在使用 Rollup 构建项目时，若同时引入了 Rolldown（如在适配新引擎或迁移场景中），常因二者配置格式不兼容导致构建失败。典型问题如 `input` 和 `output` 配置项在 Rollup 与 Rolldown 中解析方式不同，插件生态不互通，导致打包报错或产物不符合预期。如何在共存环境下统一配置结构，避免解析冲突？

Answer 1

在 Rollup 与 Rolldown 共存环境下统一配置结构的深度解析

1. 背景与问题引入

随着前端构建工具的演进，Rolldown 作为基于 Rust 的高性能替代方案逐渐进入开发者视野。然而，在迁移或适配新引擎的过程中，许多团队面临 Rollup 与 Rolldown 配置格式不兼容的问题。

典型表现包括：

• input 字段在 Rollup 中支持数组，而在 Rolldown 中可能仅接受字符串或对象形式
• output 配置项的嵌套结构差异导致产物路径错误
• 插件系统不互通，如 rollup-plugin-terser 在 Rolldown 下无法注册
• 环境变量解析逻辑冲突，造成条件编译失败

这些问题直接导致构建流程中断或生成不符合预期的打包产物。

2. 核心差异分析：Rollup vs Rolldown

配置项	Rollup 支持格式	Rolldown 支持格式	兼容性风险
input	string | string[] | { [key: string]: string }	{ [name: string]: string }（命名入口）	高 — 数组形式会被忽略
output.file	可选（多入口时必为 dir）	强制要求显式声明	中 — 缺失报错机制不同
plugins	Rollup 插件接口函数数组	需兼容 WASM 或原生绑定插件	极高 — 生态隔离
external	function | RegExp | string[]	仅支持 string[] 和简单 predicate	中 — 复杂逻辑失效

3. 解决方案设计思路

为实现共存环境下的配置统一，应采用“抽象配置层 + 运行时适配器”模式：

1. 定义标准化的中间配置 Schema
2. 通过预处理器将通用配置转换为目标工具专有格式
3. 利用条件判断动态加载对应构建器
4. 封装兼容性插件桥接层
5. 使用 TypeScript 接口约束配置结构
6. 集成 CI/CD 中的构建代理路由机制

4. 实践示例：统一配置转换器

interface UnifiedBuildConfig {
  entries: Record<string, string>;
  outputDir: string;
  format?: 'esm' | 'cjs';
  minify?: boolean;
  externals?: string[];
}

function rollupAdapter(config: UnifiedBuildConfig): RollupOptions {
  return {
    input: Object.values(config.entries),
    output: {
      dir: config.outputDir,
      format: config.format || 'esm',
      sourcemap: true
    },
    external: config.externals,
    plugins: [
      // 使用 rollup 插件生态
    ]
  };
}

function rolldownAdapter(config: UnifiedBuildConfig): RolldownOptions {
  return {
    input: config.entries, // 注意：必须是对象
    output: {
      path: config.outputDir,
      format: config.format || 'esm',
      minify: config.minify
    },
    external: config.externals || [],
    plugins: [] // 需使用 rolldown 兼容插件
  };
}

5. 构建流程自动化策略

借助 Node.js 脚本实现智能路由：

const builder = process.env.BUILDER === 'rolldown' ? rolldownAdapter : rollupAdapter;
const config = builder(unifiedConfig);

if (process.env.BUILDER === 'rolldown') {
  await rolldown.build(config);
} else {
  await rollup.rollup(config).then(bundle => bundle.write(config.output));
}

6. 插件生态桥接方案

由于插件系统本质不同，建议建立插件映射表：

Rollup Plugin	Rolldown Equivalent	转换方式
rollup-plugin-node-resolve	@rolldown/plugin-node-resolve	别名替换
rollup-plugin-commonjs	内置支持	移除并启用选项
rollup-plugin-terser	rolldown 内建 minify	条件启用
rollup-plugin-alias	@rolldown/plugin-alias	配置结构重映射
custom plugin function	需重写为 Vite-style 插件	抽象为中间件模式

7. 可视化构建流程决策图

graph TD
            A[启动构建] --> B{BUILDER 环境变量}
            B -- rolldown --> C[调用 rolldownAdapter]
            B -- rollup --> D[调用 rollupAdapter]
            C --> E[执行 Rolldown 构建]
            D --> F[执行 Rollup 构建]
            E --> G[输出产物到 dist/]
            F --> G
            G --> H[完成]

8. 高阶技巧：TypeScript 强类型校验

通过定义联合类型和判别式联合提升配置安全性：

type BuildTarget = 'rollup' | 'rolldown';

interface BaseConfig {
  target: BuildTarget;
  entries: Record<string, string>;
  outDir: string;
}

type ConfigWithPlugins<T> = T extends 'rollup'
  ? { plugins: RollupPlugin[] }
  : { plugins: RolldownPlugin[] };

type FinalConfig<T extends BuildTarget> = BaseConfig & ConfigWithPlugins<T>;

// 类型安全的配置工厂
function createConfig<T extends BuildTarget>(target: T): FinalConfig<T> {
  return { target, entries: {}, outDir: 'dist/', plugins: [] } as any;
}

9. 持续集成中的动态适配

在 CI/CD 流程中可通过以下方式实现无缝切换：

• 使用 .env 文件控制构建目标
• 在 GitHub Actions 中设置 matrix strategy 分别测试两种引擎
• 通过 Docker 容器封装不同运行时依赖
• 监控构建性能指标自动推荐最优路径

10. 未来展望：标准化构建配置提案

社区正在推动类似 build.config.ts 的统一标准，参考 Vite、Turbopack 等项目的做法，建议关注：

• Build System Interface (BSI) 提案
• WASM-based plugin runtime
• Declarative configuration manifest (.build.yaml)
• Cross-tool schema validator