rollup-plugin-postcss 是 Rollup 生态中处理 CSS 及预处理器的主流插件，需显式配置 extract 才生成独立 CSS 文件，modules 默认按 .module.css 后缀启用，PostCSS 插件须以函数数组形式传入 plugins 选项。
rollup-plugin-postcss 是目前 Rollup 生态中处理 CSS（含预处理器、CSS Modules、PostCSS 插件链）最主流的选择，但它不是“开箱即用”的万能方案——装上就跑通，往往卡在几个关键点上。
为什么 import './style.css' 后 CSS 没进 bundle，也没生成文件？
这是最常遇到的静默失败。根本原因：插件没被正确识别为“处理 .css 文件的 handler”，Rollup 直接跳过它。
-
rollup-plugin-postcss默认只处理被 import 的 CSS 文件，但不会自动提取到独立文件，除非显式开启extract - 如果你只写了
postcss()而没配extract: true或extract: 'dist/bundle.css'，CSS 会以style标签方式内联注入（仅限浏览器环境），且不生成任何 .css 文件 - SSR 或需要纯 CSS 输出的场景下，这会导致构建产物缺失样式文件
实操建议：
- 确认你的
import语句确实存在（比如import './index.css'），否则插件根本不会触发 - 必须显式配置
extract：哪怕只是extract: true，否则不会写入磁盘 - 搭配
assetFileNames控制输出路径，避免和 JS 文件名冲突：output: { assetFileNames: 'assets/[name]-[hash][extname]' }
PostCSS 插件（如 autoprefixer）不生效？检查 processors 参数结构
很多人把 postcss.config.js 里的 plugins 对象直接塞进 postcss({ plugins: {...} })，结果前缀一个没加。
立即学习“前端免费学习笔记（深入）”；
-
rollup-plugin-postcss的plugins选项只接受插件函数数组，不是对象 - 它不会自动读取项目根目录下的
postcss.config.js，除非你明确传空配置或靠自动加载逻辑（部分版本支持，但不可依赖）
常见错误写法：
postcss({ plugins: { autoprefixer: {} } }) // ❌ 静默忽略正确写法：
postcss({
plugins: [
require('autoprefixer')(),
require('postcss-preset-env')({ stage: 3 })
]
}) // ✅额外注意：
- 确保已安装对应 PostCSS 插件，例如
yarn add autoprefixer postcss-preset-env --dev - 若用
postcss-import，需确保@import路径可解析（推荐用postcss-url处理相对资源）
想让 .module.css 自动启用 CSS Modules？别关 extract，要关 modules 选项
rollup-plugin-postcss 默认对 .module.css 启用 CSS Modules，但这个行为受 modules 配置控制，和 extract 无关。
- 如果你发现
import styles from './Button.module.css'返回的是原始类名（如button），说明 Modules 没启用 - 默认启用逻辑只匹配
.module.css/.module.scss等后缀，但如果你手动设了modules: false，就会关闭它
实操建议：
- 不配置
modules字段 → 默认按文件后缀自动启用 - 显式启用：
modules: true（此时所有 .css 都走 Modules，慎用） - 自定义规则：
modules: { generateScopedName: '[name]__[local]___[hash:base64:5]' } - 如果用了
extract: true，生成的 CSS 文件仍是模块化后的类名，但 JS 中导出的对象是映射关系
和 rollup-plugin-css-only / rollup-plugin-styles 怎么选？
rollup-plugin-postcss 的定位是「PostCSS 流水线 + 可选提取」；而其他插件能力边界不同：
-
rollup-plugin-css-only：只做提取，不走 PostCSS，也不支持 Modules，适合极简纯 CSS 打包 -
rollup-plugin-styles：支持mode: 'inline'（CSS 字符串）、'extract'、'literal'，但它的processors也是数组，且默认启用 PostCSS —— 容易和postcss插件重复导致双重编译 -
rollup-plugin-import-css：纯字符串导入，无 PostCSS、无提取、无 Modules，适合 runtime 注入场景
一句话判断：
- 要 autoprefixer、stage 4 语法、变量降级 → 选
rollup-plugin-postcss - 只要把 CSS 写进 dist/styles.css，不管内容 →
rollup-plugin-css-only更轻量 - 需要 JS 里拿到
const css = '...'字符串 →rollup-plugin-import-css最直接
真正容易被忽略的点是：多个 CSS 插件同时注册时，Rollup 会按顺序尝试匹配，一旦某个插件声明了对 .css 的处理权（比如 resolveId 或 load 钩子返回非 null），后续插件就不会再处理同一文件 —— 所以不要在 config 里堆叠多个 CSS 插件。
