前端工程化 / 系统课时
配置 CSS Modules 与预处理器
配置 CSS Modules 与预处理器
本课完成一套可直接落地的 Vite 样式配置:统一 CSS Modules 类名导出与构建后命名,启用 Sass,并把设计变量和 mixin 安全注入每个 SCSS 文件,同时给出构建验证与高频故障定位方法。
学习目标
- 配置 CSS Modules 的导出命名与作用域类名格式
- 为 Sass 设置全局变量、函数和 mixin 注入
- 通过最小页面与生产构建验证配置是否生效
准备 Sass 编译器
Vite 原生识别 .module.css,也能把 CSS Modules 与 .scss 组合为 .module.scss;使用 SCSS 前仍需安装对应预处理器。当前官方文档优先推荐 sass-embedded,未安装时也可使用 sass。:contentReference[oaicite:0]{index=0}
npm add -D sass-embedded预期输出
added <ID> packages, and audited <ID> packages in <TIME><ID> 与 <TIME> 会随依赖缓存、锁文件和网络状态变化。若项目已使用 sass,不必同时安装两个实现。
配置命名与全局注入
下面的 vite.config.ts 同时完成三件事:将短横线类名导出为驼峰属性、生成便于调试且避免冲突的作用域类名,并在每个 SCSS 文件前注入设计令牌。css.modules 的选项会交给 PostCSS Modules;切换为完整 Lightning CSS 转换链后,该配置不会生效。:contentReference[oaicite:1]{index=1}
import { fileURLToPath, URL } from 'node:url'
import { defineConfig } from 'vite'
export default defineConfig({
resolve: {
alias: {
'@': fileURLToPath(new URL('./src', import.meta.url)),
},
},
css: {
modules: {
localsConvention: 'camelCaseOnly',
generateScopedName: '[name]__[local]___[hash:base64:5]',
},
preprocessorOptions: {
scss: {
// 只注入变量、函数和 mixin,避免把实际样式复制到每个输出文件。
additionalData: '@use "@/styles/tokens.scss" as *;\n',
},
},
},
})additionalData 会被添加到每份 SCSS 内容之前。若其中包含真实选择器,最终包里可能出现重复样式;同时不要使用依赖当前文件目录的相对路径,应使用绝对路径或 Vite 别名。:contentReference[oaicite:2]{index=2}
创建最小验证样式
先建立只声明变量与 mixin 的 src/styles/_tokens.scss。Sass 已弃用旧式 @import,新配置应使用 @use 或 @forward 组织共享能力。:contentReference[oaicite:3]{index=3}
$brand-color: #2563eb;
$surface-color: #eff6ff;
$radius-md: 8px;
@mixin card-surface {
padding: 16px;
border-radius: $radius-md;
background: $surface-color;
}再创建 src/card.module.scss。文件名中的 .module 让 Vite 将它作为 CSS Module 处理。
.card-title {
@include card-surface;
color: $brand-color;
}在 src/main.ts 中使用驼峰导出名。示例假设入口 HTML 中存在 id="app" 的元素。
import styles from './card.module.scss'
const app = document.querySelector<HTMLDivElement>('#app')
if (!app) {
throw new Error('Missing #app element')
}
app.innerHTML = `<h1 class="${styles.cardTitle}">Vite CSS Modules</h1>`预期结果
页面显示浅蓝背景、蓝色文字和圆角标题;元素 class 类似 card-module__card-title___Ab12C。哈希部分属于动态值,实际字符会随文件内容和路径变化。
构建并定位失败
执行生产构建可同时验证 Sass 解析、全局注入、CSS Modules 导出和最终 CSS 生成。
npm run build预期输出
vite v<VERSION> building for production...
✓ <ID> modules transformed.
✓ built in <TIME>出现 Undefined variable 时,先检查 additionalData 的别名、文件名和 @use 位置;导入对象没有 cardTitle 时,检查文件是否以 .module.scss 结尾以及 localsConvention 是否为 camelCaseOnly。若输出 CSS 重复,确认全局注入文件只包含变量、函数和 mixin,不包含 body、:root 或组件选择器。