Vite css.lightningcss 怎样切换 CSS 压缩器

如果你只是想切换 Vite 的生产环境 CSS 压缩器，改 build.cssMinify 就够了；如果希望把 CSS 的完整处理链也交给 Lightning CSS，再改 css.transformer。两者不是同一个开关。

官方地址：https://vite.dev/config/shared-options

当前 Vite 文档把 CSS 处理拆成两个层次：生产构建的压缩器由 build.cssMinify 选择，完整 CSS 处理器由 css.transformer 选择。下面按这个边界给出可直接放进 vite.config.js 的配置。

先把两个“压缩器开关”分开

常见误解是看到 css.lightningcss 就认为“已经切换了压缩器”。实际上，css.lightningcss 是 Lightning CSS 的参数对象；它只有在 Vite 使用 Lightning CSS 的相关路径时才会参与配置。

可以先用下面这张静态关系图建立位置感：应用样式先进入 Vite 的 CSS 处理层，生产构建再进入 CSS 压缩层；CSS Modules 和浏览器目标分别挂在对应的配置对象下面。图中是配置关系说明，不是某次构建的运行截图。

• build.cssMinify：只决定生产构建阶段使用哪种 CSS 压缩器。
• css.transformer：决定 CSS 的完整处理器使用 PostCSS 还是 Lightning CSS，目前属于实验性配置。
• css.lightningcss：给 Lightning CSS 传入目标浏览器、CSS Modules 等选项。

只想切换生产 CSS 压缩器：改 build.cssMinify

这是最小改动方案，适合已经依赖 PostCSS 插件、预处理器或现有 CSS 处理流程，只想比较产物压缩效果的项目。Vite 当前文档支持把它设为 'lightningcss' 或 'esbuild'，也可以设为 false 关闭 CSS 压缩。

import { defineConfig } from 'vite'

export default defineConfig({
  build: {
    // 只切换生产 CSS 压缩器，不改变现有的 CSS 处理器
    cssMinify: 'lightningcss',
  },
})

如果项目更看重与既有 esbuild 构建习惯的一致性，可以改成：

import { defineConfig } from 'vite'

export default defineConfig({
  build: {
    // 让 JavaScript 与 CSS 的生产压缩都沿用 esbuild 路径
    cssMinify: 'esbuild',
  },
})

不要把 cssMinify 写到 css 里面，也不要把 'esbuild' 误写成包名对象。它是 Vite 的构建选项，值是受支持的字符串或布尔值。

想让完整 CSS 处理链使用 Lightning CSS：改 css.transformer

当需求不只是“压缩”，还包括让 Vite 的 CSS 转换过程采用 Lightning CSS 时，使用 css.transformer: 'lightningcss'。同时，具体的 Lightning CSS 参数放在 css.lightningcss 下。

import { defineConfig } from 'vite'

export default defineConfig({
  css: {
    // 把完整 CSS 转换器切到 Lightning CSS；该能力在 Vite 中仍属实验性
    transformer: 'lightningcss',
    lightningcss: {
      // 用目标浏览器控制需要保留或转换的 CSS 能力
      targets: {
        chrome: 100,
      },
    },
  },
  build: {
    // 这里继续显式声明生产阶段的压缩选择，避免团队成员误读默认值
    cssMinify: 'lightningcss',
  },
})

这套写法的重点是：transformer 与 cssMinify 分别表达“完整处理链”和“生产压缩阶段”。如果只需要压缩器对比，不必为了它们同时切换。

CSS Modules 配置要跟着处理器走

项目使用 CSS Modules 时，配置位置也容易混淆。Vite 文档说明，css.modules 用于 PostCSS 的 CSS Modules 处理；当使用 Lightning CSS 时，应把相关选项放进 css.lightningcss.cssModules。

import { defineConfig } from 'vite'

export default defineConfig({
  css: {
    // 只有完整 CSS 处理链采用 Lightning CSS 时，才使用它的模块配置
    transformer: 'lightningcss',
    lightningcss: {
      cssModules: {
        // 保留可读的局部类名，同时加入哈希，降低名称冲突概率
        pattern: '[name]_[local]__[hash]',
      },
    },
  },
})

如果项目仍由 PostCSS 处理 CSS Modules，就继续使用 css.modules。不要同时给两套处理器写一组“看起来都能生效”的选项，否则排查最终类名时会很困难。

用浏览器目标控制转换边界

css.lightningcss.targets 不是压缩开关，而是兼容性边界。它告诉 Lightning CSS 需要面向哪些浏览器目标进行转换。目标越老，可能需要做的语法转换越多；目标越新，通常可以保留更多现代 CSS。

import { defineConfig } from 'vite'

export default defineConfig({
  css: {
    transformer: 'lightningcss',
    lightningcss: {
      // 这里表达兼容目标，不代表“压缩级别”
      targets: {
        chrome: 100,
        firefox: 100,
      },
    },
  },
})

如果只是想让文件更小，不要先去调低目标浏览器版本。先明确真实支持范围，再观察构建产物；否则可能为了压缩体积引入不必要的语法降级。

三种常见需求怎么选

一个实用判断是：如果问题描述里只有“压缩器”，先看 build.cssMinify；如果出现“转换器、兼容目标、Lightning CSS CSS Modules”，再看 css.transformer 和 css.lightningcss。

构建前后的检查清单

1. 确认配置对象层级：build.cssMinify 在 build 下，transformer 在 css 下。
2. 确认没有把 PostCSS 的 css.modules 选项误放到 Lightning CSS 路径。
3. 确认浏览器目标来自项目的真实支持范围，而不是为了追求更小文件随意调旧。
4. 执行项目已有的 npm run build，再比较构建目录中的 CSS 文件；不要只看开发服务器的样式。
5. 如果产物行为改变，优先回看处理器切换、CSS Modules 配置和目标浏览器三者，而不是盲目重复安装压缩器包。

总结一下：build.cssMinify 负责“生产阶段用谁压缩”，css.transformer 负责“完整 CSS 处理交给谁”，css.lightningcss 负责“Lightning CSS 如何转换”。把这三个职责分开，Vite 的 CSS 压缩器就能按项目需求稳定切换。

相关问题

Vite 默认使用哪个 CSS 压缩器？

当前 Vite 文档中，生产构建默认使用 Lightning CSS 压缩 CSS；如果关闭构建压缩，默认值会随之变为不压缩。需要显式对比时，直接设置 build.cssMinify。

切换到 Lightning CSS 后还要删除 PostCSS 吗？

不一定。是否保留 PostCSS 取决于项目是否依赖它的插件与处理能力。先区分只切换生产压缩，还是切换完整 CSS 处理器，再决定迁移范围。

为什么修改 css.lightningcss.targets 后产物语法变了？

因为 targets 描述的是浏览器兼容边界，会影响 Lightning CSS 是否需要转换某些 CSS 语法。它不是单纯的文件压缩比例设置。