可维护性代码组织

CSS代码组织直接影响项目可维护性，合理的文件结构和命名规范是长期维护的基础。

文件结构规划

按功能模块拆分

scss

styles/
├── base/
│   ├── _reset.scss        # 重置样式
│   ├── _variables.scss    # 变量定义
│   ├── _mixins.scss       # 混入
│   └── _typography.scss   # 排版
├── components/
│   ├── _buttons.scss      # 按钮
│   ├── _forms.scss        # 表单
│   ├── _cards.scss        # 卡片
│   └── _modals.scss       # 弹窗
├── layout/
│   ├── _grid.scss         # 网格
│   ├── _header.scss       # 头部
│   ├── _footer.scss       # 底部
│   └── _sidebar.scss      # 侧边栏
├── pages/
│   ├── _home.scss         # 首页
│   ├── _dashboard.scss    # 仪表盘
│   └── _profile.scss      # 个人中心
├── utilities/
│   ├── _helpers.scss      # 辅助类
│   └── _animations.scss   # 动画
└── main.scss              # 主入口

主入口文件

scss

// main.scss

// 1. 配置与变量
@import 'base/variables';
@import 'base/mixins';

// 2. 基础样式
@import 'base/reset';
@import 'base/typography';

// 3. 布局
@import 'layout/grid';
@import 'layout/header';
@import 'layout/footer';
@import 'layout/sidebar';

// 4. 组件
@import 'components/buttons';
@import 'components/forms';
@import 'components/cards';
@import 'components/modals';

// 5. 页面特定样式
@import 'pages/home';
@import 'pages/dashboard';
@import 'pages/profile';

// 6. 工具类
@import 'utilities/helpers';
@import 'utilities/animations';

变量管理

变量分类组织

scss

// _variables.scss

// 颜色系统
// ========================================
$color-primary: #007bff;
$color-secondary: #6c757d;
$color-success: #28a745;
$color-warning: #ffc107;
$color-danger: #dc3545;

$color-text-primary: #212529;
$color-text-secondary: #6c757d;
$color-text-muted: #adb5bd;

$color-bg-primary: #ffffff;
$color-bg-secondary: #f8f9fa;
$color-bg-dark: #343a40;

// 间距系统
// ========================================
$spacing-unit: 4px;
$spacing-xs: $spacing-unit;        // 4px
$spacing-sm: $spacing-unit * 2;    // 8px
$spacing-md: $spacing-unit * 4;    // 16px
$spacing-lg: $spacing-unit * 6;    // 24px
$spacing-xl: $spacing-unit * 8;    // 32px

// 字体系统
// ========================================
$font-family-base: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
$font-family-mono: 'SF Mono', Consolas, 'Liberation Mono', monospace;

$font-size-xs: 12px;
$font-size-sm: 14px;
$font-size-base: 16px;
$font-size-lg: 18px;
$font-size-xl: 20px;

$line-height-tight: 1.25;
$line-height-base: 1.5;
$line-height-loose: 1.75;

// 断点
// ========================================
$breakpoint-sm: 576px;
$breakpoint-md: 768px;
$breakpoint-lg: 992px;
$breakpoint-xl: 1200px;

// 层级
// ========================================
$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;

Mixin复用

通用Mixins

scss

// _mixins.scss

// 响应式断点
@mixin respond-to($breakpoint) {
  @if $breakpoint == sm {
    @media (min-width: $breakpoint-sm) { @content; }
  } @else if $breakpoint == md {
    @media (min-width: $breakpoint-md) { @content; }
  } @else if $breakpoint == lg {
    @media (min-width: $breakpoint-lg) { @content; }
  } @else if $breakpoint == xl {
    @media (min-width: $breakpoint-xl) { @content; }
  }
}

// 使用示例
.container {
  padding: $spacing-sm;

  @include respond-to(md) {
    padding: $spacing-md;
  }

  @include respond-to(lg) {
    padding: $spacing-lg;
  }
}

// 文本截断
@mixin text-truncate {
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
}

// Flex居中
@mixin flex-center {
  display: flex;
  align-items: center;
  justify-content: center;
}

// 绝对定位居中
@mixin absolute-center {
  position: absolute;
  top: 50%;
  left: 50%;
  transform: translate(-50%, -50%);
}

// 清除浮动
@mixin clearfix {
  &::after {
    content: '';
    display: table;
    clear: both;
  }
}

// 过渡动画
@mixin transition($properties...) {
  transition-property: $properties;
  transition-duration: 0.3s;
  transition-timing-function: ease-in-out;
}

组件化设计

单一职责原则

scss

// 错误：一个组件承担过多职责
.article {
  // 布局
  display: flex;
  padding: 20px;

  // 文章样式
  .title {
    font-size: 24px;
  }

  // 作者信息
  .author {
    // ...
  }

  // 评论
  .comments {
    // ...
  }
}

// 正确：职责分离
.article-card {
  display: flex;
  padding: $spacing-md;
}

.article-card__title {
  font-size: 24px;
}

.author-info {
  display: flex;
  align-items: center;
}

.comment-list {
  margin-top: $spacing-md;
}

组件结构规范

scss

// _card.scss

// 1. 组件变量
$card-border-radius: 8px;
$card-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);

// 2. 基础样式
.card {
  background: $color-bg-primary;
  border-radius: $card-border-radius;
  box-shadow: $card-shadow;
  overflow: hidden;

  // 3. 元素样式
  &__header {
    padding: $spacing-md;
    border-bottom: 1px solid rgba(0, 0, 0, 0.05);
  }

  &__title {
    font-size: $font-size-lg;
    font-weight: 600;
    @include text-truncate;
  }

  &__body {
    padding: $spacing-md;
  }

  &__footer {
    padding: $spacing-sm $spacing-md;
    background: $color-bg-secondary;
  }

  // 4. 修饰符
  &--highlighted {
    border-left: 4px solid $color-primary;
  }

  &--compact {
    .card__header,
    .card__body,
    .card__footer {
      padding: $spacing-sm;
    }
  }
}

注释规范

CSS

// ========================================
// 区块标题（大节）
// ========================================

// ----------------------------------------
// 子区块标题（小节）
// ----------------------------------------

// 单行注释说明

/*
 * 多行注释说明
 * 用于复杂逻辑
 */

// TODO: 待办事项
// FIXME: 需要修复的问题
// HACK: 临时解决方案

样式隔离策略

CSS Modules

jsx

/* Button.module.css */
.button {
  padding: 8px 16px;
  border-radius: 4px;
}

.primary {
  background: #007bff;
  color: white;
}

JavaScript

import styles from './Button.module.css';

function Button({ variant, children }) {
  return (
    <button className={`${styles.button} ${styles[variant]}`}>
      {children}
    </button>
  );
}

CSS-in-JS作用域

text

const Button = styled.button`
  padding: 8px 16px;
  border-radius: 4px;
  background: ${props => props.primary ? '#007bff' : '#6c757d'};
  color: white;
`;

要点总结

按功能模块拆分文件，入口文件统一导入
变量按类型组织：颜色、间距、字体、断点
Mixin提取通用逻辑，提高复用性
组件遵循单一职责，结构清晰
注释规范统一，便于团队协作
使用CSS Modules或CSS-in-JS实现样式隔离

📝 发现内容有误？点击此处直接编辑