@wlydfe/stylelint-config

一个开箱即用的 Stylelint 配置包，支持 Vue、SCSS 和 Prettier 集成。

✨ 特性

• 🎯 开箱即用 - 默认启用 Vue、SCSS、CSS 排序和 Prettier 支持
• 🔧 高度可配置 - 支持灵活的自定义配置和规则覆盖
• 🚀 现代化 - 基于最新的 Stylelint 16.x 版本
• 📦 一键安装 - 只需安装一个包，所有依赖自动包含
• 🎨 智能默认 - 合理的默认规则配置，减少配置复杂度
• 🚫 零配置 - 无需手动安装 postcss-html、stylelint-config-* 等依赖包

📦 安装

✨ 一键安装，自动包含所有依赖！

# 使用 pnpm
pnpm add --save-dev stylelint @wlydfe/stylelint-config postcss-html stylelint-config-recess-order stylelint-config-recommended-vue stylelint-config-standard-scss stylelint-order stylelint-prettier

注意: 你只需要安装这两个包！当你安装 @wlydfe/stylelint-config 时，所有必要的依赖（如 postcss-html、stylelint-config-recess-order、stylelint-config-recommended-vue、stylelint-config-standard-scss、stylelint-order、stylelint-prettier 等）都会自动安装。

🚀 快速开始

基础用法

// stylelint.config.js
import { wlyd } from '@wlydfe/stylelint-config'

export default wlyd()

自定义配置

// stylelint.config.js
import { wlyd } from '@wlydfe/stylelint-config'

export default wlyd({
  // 自定义规则
  rules: {
    'color-hex-length': 'short',
    'max-line-length': 80,
  },
  // 忽略文件
  ignoreFiles: ['**/*.min.css'],
})

📚 API 参考

主要函数

wlyd(config?)

主要的配置创建函数，返回完整的 Stylelint 配置。

参数：

• config (可选): 用户自定义配置，类型为 Config & PresetOptions

返回值：

• Config: 完整的 Stylelint 配置对象

createConfig(config?)

创建 Stylelint 配置的底层函数。

参数：

• config (可选): 用户自定义配置

返回值：

• Config: Stylelint 配置对象

createBaseConfig(options?)

创建基础配置的函数。

参数：

• options (可选): 预设选项，类型为 PresetOptions

返回值：

• Config: 基础配置对象

预设配置

import { presets } from '@wlydfe/stylelint-config'

// 基础配置
export default presets.base

// Vue 专用配置
export default presets.vue

// SCSS 专用配置
export default presets.scss

// 启用排序的配置
export default presets.order

// Prettier 集成配置
export default presets.prettier

// 严格模式配置
export default presets.strict

⚙️ 配置选项

PresetOptions

| 选项 | 类型 | 默认值 | 描述 | | ---------- | --------- | ------- | ---------------------- | | vue | boolean | true | 是否启用 Vue 支持 | | scss | boolean | true | 是否启用 SCSS 支持 | | order | boolean | true | 是否启用 CSS 属性排序 | | prettier | boolean | true | 是否启用 Prettier 集成 | | strict | boolean | false | 是否启用严格模式 |

严格模式规则

当启用严格模式时，会应用以下额外规则：

• at-rule-no-unknown: 禁止未知的 at 规则
• selector-pseudo-class-no-unknown: 禁止未知的伪类选择器
• selector-pseudo-element-no-unknown: 禁止未知的伪元素选择器
• property-no-unknown: 禁止未知的属性
• declaration-block-no-duplicate-properties: 禁止重复的属性声明
• declaration-block-no-redundant-longhand-properties: 禁止冗余的长手属性
• declaration-block-no-shorthand-property-overrides: 禁止简写属性覆盖
• declaration-no-important: 禁止使用 !important
• declaration-block-single-line-max-declarations: 单行最大声明数
• max-nesting-depth: 最大嵌套深度
• selector-max-compound-selectors: 最大复合选择器数量
• selector-max-specificity: 最大选择器特异性

📁 文件支持

支持的文件类型

• .css - 标准 CSS 文件
• .scss - SCSS 文件
• .vue - Vue 单文件组件
• .html - HTML 文件中的样式

语法支持

• CSS: 标准 CSS 语法
• SCSS: SCSS 语法和变量
• Vue: Vue 单文件组件中的样式
• HTML: HTML 文件中的 <style> 标签

🔧 使用示例

基础项目配置

// stylelint.config.js
import { wlyd } from '@wlydfe/stylelint-config'

export default wlyd()

自定义规则配置

// stylelint.config.js
import { wlyd } from '@wlydfe/stylelint-config'

export default wlyd({
  rules: {
    // 颜色相关规则
    'color-hex-length': 'short',
    'color-named': 'never',

    // 长度相关规则
    'max-line-length': 100,
    'max-nesting-depth': 4,

    // 选择器规则
    'selector-max-compound-selectors': 5,
    'selector-class-pattern': '^[a-z][a-zA-Z0-9]+$',
  },
})

禁用特定功能

// stylelint.config.js
import { wlyd } from '@wlydfe/stylelint-config'

export default wlyd({
  vue: false, // 禁用 Vue 支持
  scss: false, // 禁用 SCSS 支持
  order: false, // 禁用 CSS 排序
  prettier: false, // 禁用 Prettier 集成
})

使用预设配置

// stylelint.config.js
import { presets } from '@wlydfe/stylelint-config'

// 使用严格模式配置
export default presets.strict

// 或者基于预设进行扩展
export default {
  ...presets.base,
  rules: {
    'color-hex-length': 'short',
  },
}

📋 脚本命令

在 package.json 中添加以下脚本：

{
  "scripts": {
    "lint:css": "stylelint \"src/**/*.{css,scss,vue}\"",
    "lint:css:fix": "stylelint \"src/**/*.{css,scss,vue}\" --fix"
  }
}

🔍 常见问题

Q: 如何忽略特定文件？

A: 在配置中添加 ignoreFiles 选项：

export default wlyd({
  ignoreFiles: ['**/*.min.css', 'dist/**/*', 'node_modules/**/*'],
})

Q: 如何自定义 SCSS 变量命名规则？

A: 默认配置已经禁用了 SCSS 变量命名规则，如果需要自定义：

export default wlyd({
  rules: {
    'scss/dollar-variable-pattern': '^[a-z][a-zA-Z0-9]+$',
  },
})

Q: 如何集成到 CI/CD 流程？

A: 在 CI 配置中添加检查命令：

# GitHub Actions 示例
- name: Lint CSS
  run: npm run lint:css

Q: 为什么我安装了这个包后，stylelint 仍然报错找不到某些依赖？

A: 确保你安装的是最新版本。如果问题仍然存在，可以尝试删除 node_modules 和 package-lock.json（或 yarn.lock、pnpm-lock.yaml），然后重新安装：

rm -rf node_modules package-lock.json
npm install

Q: 为什么我需要安装 stylelint？不能只安装配置包吗？

A: stylelint 是核心程序，而配置包只是告诉它如何运行。这就像你需要先安装 Node.js 才能运行 npm 包一样。stylelint 作为 peer dependency 是因为：

1. 版本兼容性: 不同版本的 stylelint 可能有不同的 API
2. 避免重复: 防止多个包安装不同版本的 stylelint
3. 最佳实践: 这是 npm 生态系统的标准做法

Q: 安装后仍然报错 "Cannot find module 'stylelint-config-xxx'" 怎么办？

A: 这通常是因为依赖没有正确安装。尝试以下步骤：

1. 确保安装了最新版本：npm install @wlydfe/stylelint-config@latest
2. 清除缓存：npm cache clean --force
3. 重新安装：rm -rf node_modules package-lock.json && npm install
4. 检查 node_modules 中是否有这些包

Q: 为什么我在 pnpm-lock.yaml 中找不到 stylelint-order 等依赖？

A: 这是正常的！这些依赖现在被正确分类在 dependencies 中，而不是 devDependencies。当你安装 @wlydfe/stylelint-config 包时：

1. 这些依赖会被自动安装：stylelint-order、stylelint-config-recess-order 等
2. 它们会出现在你的 node_modules 中：可以直接使用
3. pnpm-lock.yaml 会显示正确的依赖关系：在 dependencies 部分

如果你仍然找不到，可能是因为：

• 使用了旧版本的包
• 缓存问题
• 包管理器配置问题

建议重新安装最新版本。

Q: 为什么这些依赖包不在你的 package.json 的 dependencies 中？

A: 这是一个设计决策！我们将这些依赖包放在了 dependencies 中，因为：

1. 运行时需要：用户使用配置包时需要这些依赖才能正常工作
2. 自动安装：当用户安装你的包时，这些依赖会自动安装
3. 避免版本冲突：防止与用户项目中的版本产生冲突
4. 符合最佳实践：配置包需要将这些依赖作为运行时依赖

用户只需要安装 stylelint 和你的配置包即可，其他依赖会自动处理。

Q: 为什么我安装了配置包后，stylelint 仍然没有生效？

A: 这通常是因为缺少必要的依赖。现在我们的配置包已经包含了所有必要的依赖，但如果你仍然遇到问题，请检查：

1. 确保安装了 stylelint：npm install --save-dev stylelint
2. 确保安装了最新版本的配置包：npm install @wlydfe/stylelint-config@latest
3. 检查配置文件：确保你的 stylelint.config.js 正确导入了配置
4. 清除缓存：npm cache clean --force

如果问题仍然存在，可以尝试：

rm -rf node_modules package-lock.json
npm install

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License - 详见 LICENSE 文件

👥 作者

goodswifter [email protected]

如果这个项目对你有帮助，请给它一个 ⭐️