Skip to content
样式处理

样式处理

Vite 对 CSS 提供一等公民级别的支持,涵盖原生 CSS、CSS Modules、PostCSS 和主流预处理器。


原生 CSS

导入 CSS 文件

// 在 JS/TS 中直接导入
import './style.css'          // 全局注入
import styles from './App.module.css'  // CSS Modules

// 支持 CSS @import
// style.css
@import './reset.css';
@import './variables.css';

Vite 会自动处理 @importurl(),将它们重写为相对于项目根目录的路径。

CSS 代码分割

默认情况下,Vite 构建时会自动进行 CSS 代码分割:每个异步 chunk 的 CSS 会被提取到独立的文件中,实现按需加载。

// page.js — 动态导入
import('./page.css') // 这段 CSS 只会随 page.js 一起加载

💡 最佳实践:CSS 代码分割是自动的,不需手动配置。只有在 chunk 被使用时,它的 CSS 才会被加载。


CSS Modules

任何以 .module.css 结尾的 CSS 文件都被视为 CSS Module。

基础用法

/* Button.module.css */
.primary {
  background-color: #1890ff;
  color: white;
}
.disabled {
  opacity: 0.5;
  pointer-events: none;
}
import styles from './Button.module.css'

function Button({ disabled }) {
  return (
    <button className={`${styles.primary} ${disabled ? styles.disabled : ''}`}>
      Click me
    </button>
  )
}

编译后的类名示例:.primary._primary_abc123_1

CSS Modules 配置

// vite.config.js
export default defineConfig({
  css: {
    modules: {
      // 类名生成规则
      localsConvention: 'camelCaseOnly', // 或 'camelCase' / 'dashes' / 'dashesOnly'
      // 作用域规则
      scopeBehaviour: 'local',           // 或 'global'
      // 生成的作用域名称
      generateScopedName: '[name]__[local]___[hash:base64:5]',
      // 启用全局异常
      globalModulePaths: [/global-styles/],
      // 导出的全局名称
      exportGlobals: false,
    },
  },
})
选项 默认值 说明
localsConvention 'camelCaseOnly' 类名导出风格:camelCaseOnly 只导出驼峰版
scopeBehaviour 'local' 默认作用域:local / global
generateScopedName [name]__[local]___[hash:base64:5] 生成的类名模式
globalModulePaths [] 匹配这些路径的 .module.css 会失去本地作用域

:global 和 :local

/* 在 CSS Module 中使用全局和本地选择器 */
.text {
  color: red;
}

:global(.global-class) {
  color: blue;
}

:local(.local-class) {
  color: green;
}

/* 组合 */
.text :global(.ant-btn) {
  margin: 0;
}

PostCSS

Vite 会自动发现有 postcss.config.js 配置文件的存在并应用。

安装

npm i -D postcss autoprefixer
// postcss.config.js
export default {
  plugins: {
    autoprefixer: {},
    // ... 其他插件
  },
}

常用 PostCSS 插件

插件 功能
autoprefixer 自动添加浏览器前缀
postcss-nesting 支持 CSS Nesting 语法
postcss-preset-env 使用未来的 CSS 特性(含 autoprefixer)
tailwindcss Tailwind CSS(通常使用独立的 PostCSS 插件)
postcss-px-to-viewport px 转 vw/vh(移动端适配)
postcss-pxtorem px 转 rem

💡 最佳实践postcss.config.js 的变更需要重启 Vite 开发服务器。如果发现 PostCSS 配置不生效,先检查是否需要重启。

内联 PostCSS 配置

也可以在 vite.config.js 中内联配置:

export default defineConfig({
  css: {
    postcss: {
      plugins: {
        autoprefixer: {},
      },
    },
  },
})

预处理器(Sass / Less / Stylus)

Vite 不需要额外的插件或 loader——安装依赖后即可直接使用。

# Sass / SCSS
npm i -D sass

# Less
npm i -D less

# Stylus
npm i -D stylus
// 直接在代码中导入
import './style.scss'
import './style.less'
import './style.styl'

预处理器配置

// vite.config.js
export default defineConfig({
  css: {
    preprocessorOptions: {
      scss: {
        // 注入全局变量/mixin 到每个 scss 文件
        additionalData: `@use "@/styles/variables" as *;`,
        // Sass 配置
        api: 'modern-compiler',  // 或 'modern' / 'legacy'
        silenceDeprecations: ['legacy-js-api'],
      },
      less: {
        // 注入全局变量
        additionalData: `@import "@/styles/variables.less";`,
        // 修改变量
        modifyVars: {
          'primary-color': '#1890ff',
        },
        javascriptEnabled: true,
      },
      stylus: {
        // Stylus 选项
      },
    },
  },
})
选项 说明
additionalData 注入到每个样式文件开头的代码(用于全局变量/mixin)
api (sass) 'modern-compiler'(推荐)、'modern''legacy'
modifyVars (less) 覆写 Less 变量(配合 javascriptEnabled

🚨 陷阱additionalData 会在每个 .scss 文件头部注入代码,如果注入的是普通样式规则(而非变量/mixin),会导致样式重复输出。只注入不产生输出的代码,如变量、mixin、函数。


CSS 特有配置

export default defineConfig({
  css: {
    // 配置 CSS Modules 行为
    modules: { /* ... */ },

    // PostCSS 配置
    postcss: { /* ... */ },

    // 预处理器选项
    preprocessorOptions: { /* ... */ },

    // 开发时:是否将 CSS 内联到 JS 中(默认 false)
    // 设为 true 可减少开发时的文件数量
    devSourcemap: false,

    // CSS 的 sourcemap 精细化程度
    // 生产构建时默认关闭
    devSourcemap: false,
  },
})

@import 内联与重写

Vite 通过 postcss-import 处理 CSS 中的 @import

/* 原始 */
@import './reset.css';
@import '@/styles/variables.css';

/* Vite 处理:
  - 路径别名(@)被解析
  - node_modules 中的 CSS 也被正确内联
  - 支持 CSS Modules 方式的导入
*/

内联阈值

export default defineConfig({
  build: {
    // assetsInlineLimit: 小于此值的资源会被内联为 base64
    assetsInlineLimit: 4096,  // 4KB,默认值
    // 设为 0 禁用内联
  },
})

性能提示:小于 4KB 的图片会被内联为 base64,减少 HTTP 请求。可以根据 CDN 策略调大或调小此值。


Tailwind CSS 集成

npm i -D tailwindcss @tailwindcss/vite
// vite.config.js
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [tailwindcss()],
})
/* src/index.css */
@import "tailwindcss";

UnoCSS 集成

UnoCSS(原子化 CSS 引擎,比 Tailwind 更快更灵活):

npm i -D unocss
// vite.config.js
import UnoCSS from 'unocss/vite'

export default defineConfig({
  plugins: [UnoCSS()],
})

常见问题排查

问题 可能原因 解决方案
PostCSS 配置不生效 配置变更后未重启 重启 Vite dev server
Sass 报缺失变量 变量定义在其他文件 使用 additionalData 注入
CSS Module 类型提示缺失 没有 .d.ts 使用 vite-plugin-dts 或手写声明
全局样式覆盖不掉 CSS Module 作用域限制 使用 :global() 语法
url() 路径 404 相对路径解析错误 使用别名 @/assets/... 或在 CSS 中用绝对路径