Rollup CSS插件配置全攻略

Rollup本身不原生支持CSS处理，导致开发者常陷入“CSS文件生成了但页面白屏”“样式未注入HTML”“PostCSS失效”“热更新不响应”等典型困境；本文直击核心痛点，系统梳理rollup-plugin-css-only与rollup-plugin-styles的关键差异——前者仅专注提取CSS却需手动配置输出路径和HTML注入，后者则灵活支持内联、提取、字符串化等多种模式，并深度解析processors数组的正确写法、watch机制的隐式依赖、sourceMap与dev标志对HMR的影响等易错细节，帮你一次性打通Rollup中CSS打包、转换与开发体验的全链路。

Rollup里CSS不打包进output？检查rollup-plugin-css-only是否漏了output配置

Rollup默认不处理.css文件，即使你import了也不会自动提取或注入。用rollup-plugin-css-only时，它只负责收集和写入CSS文件，但不会自动把CSS路径注入HTML——这点和Webpack的mini-css-extract-plugin行为不同。

常见错误现象：build后CSS文件生成了，但HTML里没，页面白屏或样式丢失。

• 必须手动在rollup.config.js中配置output的entryFileNames和assetFileNames，确保CSS输出路径可预测
• 如果用rollup-plugin-html或自定义HTML模板，得显式读取bundle.generate()返回的output中assets里的CSS文件名
• rollup-plugin-css-only不支持inject: true这种快捷方式；想自动注入就得换插件（比如rollup-plugin-styles）或自己写generateBundle钩子

想把CSS内联进JS或HTML？别用rollup-plugin-css-only，改用rollup-plugin-styles

rollup-plugin-css-only只做“提取”，而rollup-plugin-styles支持多种输出模式：内联（mode: 'inline'）、提取（'extract'）、甚至CSS-in-JS（'literal'）。很多用户卡在“为什么CSS没进JS bundle”，其实是选错了插件能力边界。

使用场景：SSR、微前端、需要动态加载样式的环境，往往要求CSS字符串可被JS直接引用。

• mode: 'inline'会把CSS编译成字符串，挂到export default上，JS里import styles from './a.css'就能拿到
• mode: 'extract'行为接近css-only，但支持fileName和insert选项，能控制插入位置
• 注意rollup-plugin-styles默认启用postcss，若项目没配postcss.config.js，可能静默失败——加processors: []可禁用

PostCSS插件不生效？确认rollup-plugin-styles的processors是数组，不是对象

很多人把PostCSS配置直接塞进processors字段，结果autoprefixer或postcss-preset-env完全没反应。根本原因是rollup-plugin-styles的processors只接受插件函数数组，不识别postcss.config.js的plugins对象结构。

常见错误现象：display: flex没加前缀、color-mix()没降级、CSS变量未展开。

• 正确写法：processors: [require('autoprefixer')(), require('postcss-preset-env')({ stage: 3 })]
• 错误写法：processors: { autoprefixer: {}, 'postcss-preset-env': { stage: 3 } }（这会被忽略）
• 若用postcss-import，注意它默认不解析node_modules里的@import，需加resolve: require('postcss-import').resolve或显式配path

开发时热更新CSS失效？rollup-plugin-serve不监听CSS变更，得靠watch或HMR插件补位

Rollup原生watch模式只监听入口JS和依赖图里的模块，默认不触发CSS变更的重构建。用rollup-plugin-serve起服务时，改了CSS文件，浏览器不会刷新，控制台也无提示。

本质是Rollup的watch机制不把CSS当作“有效模块依赖”，除非插件主动调用this.addWatchFile()。

• rollup-plugin-styles在v4+版本已内置addWatchFile，但需开启sourceMap: true或dev: true才会注册监听
• 若用rollup-plugin-css-only，它完全不监听，必须配合rollup-plugin-livereload并手动指定watch目录，例如watch: ['src/**/*.css']
• 更稳妥的做法：在rollup.config.js顶层加watch: { include: 'src/**' }，让Rollup主动扫描所有CSS变更

复杂点在于，CSS变更是否触发JS重载、是否触发HTML重写、是否需要强制刷新浏览器——这些逻辑分散在不同插件里，没统一标准。一个改动常要同时动三个配置项才见效。

今天关于《Rollup CSS插件配置全攻略》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！