stylelint.config.js

/**
 * StyleLint 配置文件 - 官方推荐格式
 * 适用于 Vue 3 + SCSS + TypeScript 项目
 * @type {import('stylelint').Config}
 * @see https://stylelint.io/user-guide/configure
 */
export default {
  // 继承的配置规则集
  extends: [
    'stylelint-config-standard', // 标准 CSS 规则
    'stylelint-config-standard-scss', // 标准 SCSS 规则
    'stylelint-config-standard-vue/scss', // Vue SFC 中 SCSS 的标准规则
  ],

  // 使用的插件
  plugins: [
    'stylelint-order', // CSS 属性排序插件
    'stylelint-scss', // SCSS 语法支持插件
  ],

  // 自定义规则配置
  rules: {
    // 禁用 CSS 的 at-rule 未知规则检查，改用 SCSS 的检查
    'at-rule-no-unknown': null,
    'scss/at-rule-no-unknown': true,

    // 允许 Vue 3 的伪元素选择器
    'selector-pseudo-element-no-unknown': [
      true,
      {
        ignorePseudoElements: [
          'v-deep', // Vue 2 深度选择器（兼容）
          'v-global', // Vue 3 全局选择器
          'v-slotted', // Vue 3 插槽选择器
        ],
      },
    ],

    // 允许 Vue 3 的伪类选择器
    'selector-pseudo-class-no-unknown': [
      true,
      {
        ignorePseudoClasses: [
          'deep', // :deep() Vue 3 深度选择器
          'global', // :global() Vue 3 全局选择器
          'export', // CSS Modules 导出
          'where', // CSS :where() 伪类
        ],
      },
    ],

    // 允许 Vue 3 的 CSS 函数
    'function-no-unknown': [
      true,
      {
        ignoreFunctions: [
          'v-bind', // Vue 3 CSS 变量绑定函数
          'theme', // 主题函数（如 Ant Design）
          'var', // CSS 自定义属性函数
        ],
      },
    ],

    // 颜色函数使用传统格式（兼容性更好）
    'color-function-notation': 'legacy',

    // 透明度值使用数字格式而非百分比
    'alpha-value-notation': 'number',

    // 禁用类名模式检查（适应组件库）
    'selector-class-pattern': null,

    // 禁用自定义属性模式检查
    'custom-property-pattern': null,

    // 禁用 SCSS 变量命名模式检查
    'scss/dollar-variable-pattern': null,

    // CSS 属性排序规则 - 按照逻辑分组排序
    'order/properties-order': [
      // 定位相关
      'position',
      'top',
      'right',
      'bottom',
      'left',
      'z-index',

      // 布局相关
      'display',
      'flex',
      'flex-grow',
      'flex-shrink',
      'flex-basis',
      'flex-direction',
      'flex-flow',
      'flex-wrap',
      'grid',
      'grid-template',
      'grid-template-areas',
      'grid-template-rows',
      'grid-template-columns',
      'gap',
      'row-gap',
      'column-gap',

      // 对齐相关
      'align-content',
      'align-items',
      'align-self',
      'justify-content',
      'justify-items',
      'justify-self',

      // 盒模型
      'box-sizing',
      'width',
      'min-width',
      'max-width',
      'height',
      'min-height',
      'max-height',

      // 内外边距
      'padding',
      'padding-top',
      'padding-right',
      'padding-bottom',
      'padding-left',
      'margin',
      'margin-top',
      'margin-right',
      'margin-bottom',
      'margin-left',

      // 边框
      'border',
      'border-width',
      'border-style',
      'border-color',
      'border-radius',
      'outline',

      // 背景
      'background',
      'background-color',
      'background-image',
      'background-repeat',
      'background-position',
      'background-size',

      // 字体和文本
      'color',
      'font',
      'font-family',
      'font-size',
      'font-weight',
      'line-height',
      'text-align',
      'text-decoration',
      'text-transform',

      // 其他视觉效果
      'opacity',
      'visibility',
      'overflow',
      'transform',
      'transition',
      'animation',
    ],
  },

  // 针对不同文件类型的特殊配置
  overrides: [
    {
      // Vue 单文件组件配置
      files: ['**/*.vue'],
      customSyntax: 'postcss-html',
    },
    {
      // SCSS 文件配置
      files: ['**/*.scss'],
      customSyntax: 'postcss-scss',
    },
  ],
}