前端工程化 / 系统课时

配置 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}

bash
npm add -D sass-embedded

预期输出

text
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}

ts
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}

scss
$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 处理。

scss
.card-title {
  @include card-surface;
  color: $brand-color;
}

在 src/main.ts 中使用驼峰导出名。示例假设入口 HTML 中存在 id="app" 的元素。

ts
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>`

预期结果

text
页面显示浅蓝背景、蓝色文字和圆角标题;元素 class 类似 card-module__card-title___Ab12C。

哈希部分属于动态值,实际字符会随文件内容和路径变化。

构建并定位失败

执行生产构建可同时验证 Sass 解析、全局注入、CSS Modules 导出和最终 CSS 生成。

bash
npm run build

预期输出

text
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 或组件选择器。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

配置 CSS Modules 与预处理器

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通