一个真实的困境
去年团队来了个新同事，他问了我一个问题：
“这个页面的样式怎么改不动？加!important都没用，前面已经有5个!important了…”
我打开浏览器DevTools，看到一个按钮的样式被7个不同的选择器覆盖。更可怕的是，一个全局的.active类被用在了5个完全不相关的组件里，每个都长得不一样。
这不是个例。随着项目膨胀，CSS成了最难维护的部分。
于是我们花了两周时间，重构了整个项目的CSS架构。今天，我把这套方案分享出来。
一、CSS架构的核心问题
| 问题 | 表现 | 后果 |
|---|---|---|
| 全局污染 | 一个样式影响多个组件 | 改A坏B |
| 命名冲突 | 多个相同类名 | 样式覆盖混乱 |
| 代码冗余 | 重复写相同样式 | 体积膨胀 |
| 难以维护 | 改一处要改10处 | 开发效率低 |
| 主题切换 | 硬编码颜色值 | 改主题成本高 |
二、目录结构设计
这是经过3个项目验证的目录结构：
text
styles/ ├── abstracts/ # 抽象层（不输出CSS） │ ├── _variables.styl # 设计变量 │ ├── _mixins.styl # 混合宏 │ ├── _functions.styl # 函数 │ └── _constants.styl # 常量（z-index等） ├── base/ # 基础层（重置、排版） │ ├── _reset.styl │ ├── _typography.styl │ └── _animation.styl ├── components/ # 组件层（独立UI组件） │ ├── _button.styl │ ├── _card.styl │ ├── _modal.styl │ └── _form.styl ├── layouts/ # 布局层（页面结构） │ ├── _header.styl │ ├── _footer.styl │ └── _sidebar.styl ├── pages/ # 页面层（页面特有样式） │ ├── home.styl │ └── detail.styl ├── themes/ # 主题层 │ ├── _light.styl │ └── _dark.styl ├── vendors/ # 第三方库覆盖 │ └── _swiper.styl └── main.styl # 入口文件分层原则：
- 上层可以依赖下层
- 下层不能依赖上层
- abstracts > base > components > layouts > pages
三、变量系统设计
3.1 颜色系统
stylus
// abstracts/_variables.styl // ========== 品牌色 ========== $color-primary = #00a1d6 $color-primary-light = lighten($color-primary, 10%) $color-primary-dark = darken($color-primary, 10%) $color-primary-disabled = rgba($color-primary, 0.4) // ========== 功能色 ========== $color-success = #00b894 $color-warning = #fdcb6e $color-error = #ff7675 $color-info = #74b9ff // ========== 灰度色 ========== $gray-100 = #f8f9fa $gray-200 = #e9ecef $gray-300 = #dee2e6 $gray-400 = #ced4da $gray-500 = #adb5bd $gray-600 = #6c757d $gray-700 = #495057 $gray-800 = #343a40 $gray-900 = #212529 // ========== 语义化颜色 ========== $text-primary = $gray-900 $text-secondary = $gray-600 $text-disabled = $gray-400 $text-inverse = #ffffff $bg-primary = #ffffff $bg-secondary = $gray-100 $bg-overlay = rgba(0, 0, 0, 0.5) $border-light = $gray-200 $border-base = $gray-300 $border-dark = $gray-4003.2 间距系统
stylus
// 基于8px网格系统 $spacing-0 = 0 $spacing-1 = 4px $spacing-2 = 8px $spacing-3 = 12px $spacing-4 = 16px $spacing-5 = 20px $spacing-6 = 24px $spacing-8 = 32px $spacing-10 = 40px $spacing-12 = 48px $spacing-16 = 64px $spacing-20 = 80px $spacing-24 = 96px // 语义化间距 $spacing-xs = $spacing-1 $spacing-sm = $spacing-2 $spacing-md = $spacing-4 $spacing-lg = $spacing-6 $spacing-xl = $spacing-83.3 响应式断点
stylus
// 移动优先，从小到大 $breakpoint-sm = 576px // 手机横屏 $breakpoint-md = 768px // 平板 $breakpoint-lg = 992px // 桌面 $breakpoint-xl = 1200px // 大屏 $breakpoint-2xl = 1400px // 超大屏 // 响应式混合宏（见mixins）3.4 层级系统
stylus
$z-index-dropdown = 1000 $z-index-sticky = 1020 $z-index-fixed = 1030 $z-index-modal-backdrop = 1040 $z-index-modal = 1050 $z-index-popover = 1060 $z-index-tooltip = 1070 $z-index-toast = 1080四、Mixins库
stylus
// abstracts/_mixins.styl // ========== 响应式 ========== // 移动优先写法 respond-to($breakpoint) if $breakpoint == sm @media (min-width: $breakpoint-sm) {block} else if $breakpoint == md @media (min-width: $breakpoint-md) {block} else if $breakpoint == lg @media (min-width: $breakpoint-lg) {block} else if $breakpoint == xl @media (min-width: $breakpoint-xl) {block} // 桌面优先写法（可选） respond-below($breakpoint) if $breakpoint == sm @media (max-width: $breakpoint-sm - 1) {block} else if $breakpoint == md @media (max-width: $breakpoint-md - 1) {block} // ========== 布局 ========== // 弹性盒子居中 flex-center() display: flex justify-content: center align-items: center // 文本省略 ellipsis() overflow: hidden white-space: nowrap text-overflow: ellipsis // 多行省略（需要指定行数） ellipsis-multiline($lines = 2) display: -webkit-box -webkit-line-clamp: $lines -webkit-box-orient: vertical overflow: hidden // 清除浮动 clearfix() &::after content: '' display: table clear: both // ========== 视觉效果 ========== // 三角形 triangle($direction, $size, $color) width: 0 height: 0 if $direction == up border-left: $size solid transparent border-right: $size solid transparent border-bottom: $size solid $color else if $direction == down border-left: $size solid transparent border-right: $size solid transparent border-top: $size solid $color else if $direction == left border-top: $size solid transparent border-bottom: $size solid transparent border-right: $size solid $color else if $direction == right border-top: $size solid transparent border-bottom: $size solid transparent border-left: $size solid $color // 自定义滚动条 custom-scrollbar($width = 6px, $track = #f1f1f1, $thumb = #c1c1c1) &::-webkit-scrollbar width: $width height: $width &::-webkit-scrollbar-track background: $track border-radius: $width &::-webkit-scrollbar-thumb background: $thumb border-radius: $width &:hover background: darken($thumb, 10%) // ========== 动画 ========== // 平滑过渡 transition($properties...) transition-property: $properties transition-duration: $duration-base transition-timing-function: $easing-ease // 加载骨架屏 skeleton() background: linear-gradient(90deg, #f0f0f0 25%, #e0e0e0 50%, #f0f0f0 75%) background-size: 200% 100% animation: loading 1.5s infinite @keyframes loading 0% background-position: 200% 0 100% background-position: -200% 0五、组件样式规范
5.1 BEM命名规范
stylus
// components/_button.styl // Block（块） .c-button display: inline-flex align-items: center justify-content: center padding: $spacing-2 $spacing-4 border-radius: $radius-base font-size: $font-size-base cursor: pointer transition: all $duration-fast // Modifier（修饰符） &--primary background: $color-primary color: white &:hover background: $color-primary-dark &--secondary background: transparent border: 1px solid $color-primary color: $color-primary &--disabled opacity: 0.5 cursor: not-allowed // Element（元素） &__icon margin-right: $spacing-2 &__text // 样式5.2 组件样式封装
vue
<!-- 推荐：使用scoped + BEM --> <template> <div class="video-card"> <img class="video-card__cover" :src="cover" /> <div class="video-card__info"> <h3 class="video-card__title">{{ title }}</h3> <span class="video-card__count">{{ viewCount }}次播放</span> </div> </div> </template> <style scoped lang="stylus"> .video-card display: flex padding: $spacing-3 &__cover width: 160px height: 90px border-radius: $radius-sm &__info flex: 1 margin-left: $spacing-3 &__title font-size: $font-size-base font-weight: $font-weight-medium ellipsis() &__count font-size: $font-size-sm color: $text-secondary </style>六、主题切换方案
6.1 CSS变量 + Stylus变量结合
stylus
// themes/_light.styl :root --color-primary: #00a1d6 --bg-primary: #ffffff --text-primary: #212529 --border-color: #e9ecef // themes/_dark.styl [data-theme="dark"] --color-primary: #0d6efd --bg-primary: #1a1a2e --text-primary: #eeeeee --border-color: #2d2d3dstylus
// 使用CSS变量 .c-button background: var(--color-primary) color: var(--text-primary)6.2 动态切换主题
javascript
// utils/theme.js export const themes = { light: 'light', dark: 'dark' } export function setTheme(theme) { document.documentElement.setAttribute('data-theme', theme) localStorage.setItem('theme', theme) } export function initTheme() { const saved = localStorage.getItem('theme') const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches if (saved) { setTheme(saved) } else if (prefersDark) { setTheme(themes.dark) } else { setTheme(themes.light) } }七、性能优化
7.1 关键CSS提取
javascript
// vue.config.js module.exports = { css: { extract: { ignoreOrder: true }, loaderOptions: { stylus: { additionalData: ` @import "@/styles/abstracts/_variables.styl" @import "@/styles/abstracts/_mixins.styl" ` } } } }7.2 按需加载
javascript
// 路由级样式分割 const Home = () => import(/* webpackChunkName: "home" */ './views/Home.vue') // 组件样式默认就是按需的（scoped）7.3 避免样式重复
stylus
// ❌ 错误：每个组件都定义相同的样式 // ✅ 正确：提取公共样式到base层 // base/_typography.styl h1, .h1 { font-size: $font-size-3xl } h2, .h2 { font-size: $font-size-2xl }八、Lint与格式化
json
// .stylelintrc.json { "extends": "stylelint-config-standard", "rules": { "indentation": 2, "string-quotes": "double", "color-hex-length": "short", "selector-class-pattern": "^[a-z][a-zA-Z0-9-]+$", "max-nesting-depth": 3 } }json
// package.json { "scripts": { "lint:css": "stylelint 'src/**/*.{vue,styl}'", "lint:css:fix": "stylelint 'src/**/*.{vue,styl}' --fix" } }写在最后
这套CSS架构方案已经在我经手的3个中大型项目中验证过：
- 项目A：50+页面，0次样式冲突
- 项目B：从零搭建，2周完成主题切换
- 项目C：维护3年，CSS代码量增长300%，维护成本仅增长20%
核心原则：
- 变量先行，不要硬编码
- 分层清晰，依赖单向
- BEM命名，避免冲突
- scoped隔离，按需加载
