样式处理
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 会自动处理 @import 和 url(),将它们重写为相对于项目根目录的路径。
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 中用绝对路径 |