前端Rollup配置规范书

前端Rollup配置规范书一、Rollup基础配置规范1.1配置文件命名与结构Rollup配置文件统一命名为rollup.config.js，放置于项目根目录下。配置文件采用ES模块导出方式，默认导出一个配置对象或配置对象数组（适用于多入口场景）。基础结构如下：import{defineConfig}from'rollup';exportdefaultdefineConfig({input:'src/index.js',output:{file:'dist/bundle.js',format:'es'},plugins:[]});配置对象需包含input、output核心字段，plugins字段根据需求添加。所有配置项需按照功能模块进行分组，通过空行分隔不同功能区块，提升可读性。1.2入口文件配置单入口场景：input字段设置为字符串类型，指定项目主入口文件路径，推荐使用src/index.js作为标准入口路径。多入口场景：input字段设置为对象类型，键为输出文件的名称标识，值为对应入口文件路径。示例如下：input:{main:'src/index.js',utils:'src/utils/index.js'}多入口配置需保证每个入口文件职责清晰，避免业务逻辑交叉。1.3输出配置规范输出配置output为对象或对象数组，需严格遵循以下规范：输出格式：format字段根据使用场景选择合适的值：es：ES模块格式，适用于现代浏览器及ES模块环境cjs：CommonJS格式，适用于Node.js环境umd：通用模块定义，同时支持浏览器和Node.js环境iife：立即执行函数，适用于浏览器全局变量场景输出文件命名：单入口场景：推荐使用dist/[name].js格式，[name]默认取入口文件名多入口场景：需配置dir字段指定输出目录，entryFileNames设置为[name].js代码压缩：生产环境必须开启代码压缩，通过terser插件实现，禁止在输出配置中手动配置压缩参数sourcemap：开发环境设置sourcemap:true，生产环境设置sourcemap:'hidden'，便于代码调试同时避免暴露源码结构二、插件使用规范2.1插件安装与管理所有Rollup插件必须通过npm或yarn进行安装，禁止直接引入未打包的插件源码。插件版本需在package.json中锁定，使用^或~符号进行版本范围控制，避免因版本升级导致构建失败。推荐使用以下命令安装插件：npminstallrollup-plugin-terser--save-dev插件安装完成后，需在配置文件顶部通过ES模块方式导入，导入语句需按照插件名称字母顺序排列。2.2核心插件配置2.2.1转译插件（@rollup/plugin-babel）用于将ES6+代码转译为兼容目标环境的代码。配置规范如下：importbabelfrom'@rollup/plugin-babel';plugins:[babel({babelHelpers:'bundled',exclude:'node_modules/**',presets:['@babel/preset-env']})]必须设置exclude:'node_modules/**'，避免转译第三方依赖babelHelpers推荐使用bundled模式，减少代码体积需配合.babelrc或babel.config.js文件进行详细转译配置2.2.2解析插件（@rollup/plugin-node-resolve）用于解析Node.js模块路径，使Rollup能够识别node_modules中的依赖。配置规范：importresolvefrom'@rollup/plugin-node-resolve';plugins:[resolve({extensions:['.js','.jsx','.ts','.tsx'],preferBuiltins:false})]extensions需包含项目中使用的所有文件扩展名preferBuiltins设置为false，避免优先使用Node.js内置模块2.2.3CommonJS转换插件（@rollup/plugin-commonjs）将CommonJS模块转换为ES模块，使Rollup能够处理使用CommonJS规范的第三方依赖。配置示例：importcommonjsfrom'@rollup/plugin-commonjs';plugins:[commonjs({include:'node_modules/**',extensions:['.js']})]需注意该插件应在node-resolve插件之后使用，确保先解析模块路径再进行格式转换。2.3插件使用顺序Rollup插件的执行顺序对构建结果有重要影响，需严格遵循以下顺序：模块解析类插件（如node-resolve）格式转换类插件（如commonjs）转译类插件（如babel）代码优化类插件（如terser）输出类插件（如rollup-plugin-copy）插件数组中需按照上述顺序排列，避免因执行顺序错误导致构建异常。三、环境区分配置规范3.1开发与生产环境分离通过process.env.NODE_ENV环境变量区分开发和生产环境，配置文件需支持两种环境的差异化配置。推荐使用rollup-plugin-replace插件注入环境变量：importreplacefrom'@rollup/plugin-replace';plugins:[replace({preventAssignment:true,'process.env.NODE_ENV':JSON.stringify(process.env.NODE_ENV)})]在package.json中配置对应的脚本命令：{"scripts":{"build":"rollup-c--environmentNODE_ENV:production","dev":"rollup-c-w--environmentNODE_ENV:development"}}3.2开发环境配置开发环境需优先保证构建速度和调试便利性，配置规范如下：开启sourcemap:true，便于代码调试禁用代码压缩和混淆开启监听模式（-w参数），实现文件变化自动重新构建配置本地开发服务器，推荐使用rollup-plugin-serve和rollup-plugin-livereload插件启用代码热替换（HMR），提升开发效率3.3生产环境配置生产环境需优先保证代码体积和运行性能，配置规范如下：开启sourcemap:'hidden'，生成隐藏的sourcemap文件启用terser插件进行代码压缩和混淆配置treeshake:true，开启摇树优化，移除未使用的代码启用rollup-plugin-analyzer插件分析包体积，优化依赖结构配置输出文件哈希，实现静态资源缓存：output:{file:'dist/bundle.[hash].js',format:'es'}四、TypeScript项目配置规范4.1基础配置TypeScript项目需安装@rollup/plugin-typescript插件，并在项目根目录创建tsconfig.json文件。Rollup配置示例如下：importtypescriptfrom'@rollup/plugin-typescript';exportdefaultdefineConfig({input:'src/index.ts',output:{file:'dist/bundle.js',format:'es'},plugins:[typescript({tsconfig:'./tsconfig.json',sourceMap:true})]});4.2TypeScript编译选项tsconfig.json需包含以下核心配置：{"compilerOptions":{"target":"ES2020","module":"ESNext","strict":true,"esModuleInterop":true,"skipLibCheck":true,"forceConsistentCasingInFileNames":true,"moduleResolution":"node","resolveJsonModule":true,"outDir":"dist","sourceMap":true},"include":["src/**/*"],"exclude":["node_modules","dist"]}target设置为ES2020，保证代码兼容性和现代语法支持strict设置为true，开启严格类型检查module设置为ESNext，与Rollup的ES模块输出格式保持一致4.3类型声明文件输出生产环境构建需生成类型声明文件，配置typescript插件的declaration和declarationDir选项：typescript({tsconfig:'./tsconfig.json',declaration:true,declarationDir:'dist/types',sourceMap:true})类型声明文件需输出到dist/types目录下，便于其他项目引用。五、性能优化配置规范5.1摇树优化（TreeShaking）Rollup原生支持摇树优化，需确保以下配置正确：输出格式设置为es或cjstreeshake字段设置为true（生产环境默认开启）项目代码使用ES模块语法，避免使用CommonJS的require语法在package.json中配置sideEffects字段，标记具有副作用的文件：{"sideEffects":["*.css","src/polyfills.js"]}正确配置sideEffects可以避免摇树优化误删具有副作用的代码。5.2代码分割配置通过output.manualChunks配置实现代码分割，将公共依赖和业务代码分离，提升加载性能。配置示例如下：output:{dir:'dist',format:'es',manualChunks:{react:['react','react-dom'],lodash:['lodash-es']}}代码分割需遵循以下原则：将体积较大的第三方依赖单独打包将多个入口共享的公共代码提取为单独的chunk避免过度分割，控制chunk数量在合理范围内5.3缓存配置通过rollup-plugin-cache插件实现构建缓存，提升二次构建速度。配置示例：importcachefrom'rollup-plugin-cache';plugins:[cache({enabled:process.env.NODE_ENV==='development'})]缓存仅在开发环境启用，生产环境需禁用缓存以保证构建结果的一致性。六、错误处理与日志规范6.1错误处理配置配置onwarn和onerror回调函数，统一处理构建过程中的警告和错误：exportdefaultdefineConfig({onwarn(warning,warn){//忽略特定类型的警告if(warning.code==='UNUSED_EXTERNAL_IMPORT')return;warn(warning);},onerror(error){console.error('Rollup构建失败:',error.message);process.exit(1);}});需根据项目需求过滤不必要的警告，同时确保错误信息能够清晰展示问题所在。6.2构建日志配置使用rollup-plugin-log插件配置构建日志，便于排查构建问题：importlogfrom'rollup-plugin-log';plugins:[log({clear:true,timestamp:true})]日志需包含时间戳、构建阶段、文件处理进度等信息，便于定位构建耗时较长的环节。七、第三方依赖处理规范7.1外部依赖配置通过external字段标记不需要打包到输出文件中的外部依赖，适用于在运行时动态加载的场景。配置示例：external:['react','react-dom']外部依赖需满足以下条件：依赖包体积较大，且在运行环境中已存在依赖包需要通过CDN引入，减少打包体积依赖包存在多个版本，需要在运行时动态选择7.2依赖版本管理所有第三方依赖需在package.json中明确指定版本号，禁止使用*或未锁定的版本范围。推荐使用npmls命令检查依赖树，避免依赖版本冲突。7.3依赖分析与优化定期使用rollup-plugin-analyzer插件分析依赖包体积，优化依赖结构：importanalyzerfrom'rollup-plugin-analyzer';plugins:[analyzer({summaryOnly:true,limit:10})]对于体积较大的依赖包，可考虑以下优化方案：使用替代方案，选择体积更小的同类库按需引入依赖包的子模块，避免全量引入对依赖包进行二次打包，移除未使用的功能八、配置文件扩展与复用规范8.1基础配置复用将通用配置提取到单独的文件中，通过ES模块导入实现配置复用。例如创建rollup.config.base.js文件：import{defineConfig}from'rollup';importresolvefrom'@rollup/plugin-node-resolve';importcommonjsfrom'@rollup/plugin-commonjs';exportdefaultdefineConfig({plugins:[resolve(),commonjs()]});在环境特定的配置文件中导入基础配置并进行扩展：importbaseConfigfrom'./rollup.config.base';import{defineConfig}from'rollup';exportdefaultdefineConfig({...baseConfig,output:{file:'dist/bundle.js',format:'es'}});8.2多环境配置文件对于复杂项目，可创建多个环境特定的配置文件：rollup.config.dev.js：开发环境配置d.js：生产环境配置rollup.config.test.js：测试环境配置在package.json中配置对应的脚本命令：{"scripts":{"build":"rollup-cd.js","dev":"rollup-crollup.config.dev.js-w","test":"rollup-crollup.config.test.js"}}8.3配置工具函数封装对于重复使用的配置逻辑，可封装为工具函数，提升配置文件的可维护性。例如创建rollup.utils.js文件：exportfunctioncreateOutputConfig(format,outputPath){return{file:outputPath,format,sourcemap:process.env.NODE_ENV==='development'};}在配置文件中使用工具函数：import{createOutputConfig}from'./rollup.utils';exportdefaultdefineConfig({output:createOutputConfig('es','dist/bundle.js')});九、配置文件维护规范9.1版本控制Rollup配置文件需纳入版本控制系统，每次配置变更需提交清晰的变更说明。变更说明需包含以下内容：变更原因影响范围测试验证情况9.2文档维护配置文件中需添加必要的注释，说明关键配置项的作用和使用场景。对于复杂的配置逻辑，需在项目文档中进行详细说明，便于团队成员理解和维护。9.3定期审查每季度对Rollup配置文件进行一次全面审查，审查内容包括：插件版本是否需要更新配置项是否符合最新的规范构