# vite-plugin-stylelint [![npm](https://img.shields.io/npm/v/vite-plugin-stylelint)](https://www.npmjs.com/package/vite-plugin-stylelint) [![GitHub license](https://img.shields.io/github/license/ModyQyW/vite-plugin-stylelint)](https://github.com/ModyQyW/vite-plugin-stylelint/blob/master/LICENSE) Vite Stylelint 插件，默认在 `transform` 生命周期中运行 Stylelint，支持自定义。 支持 Vite v2 ~ v5。要求 `node>=18`。 你可能需要 [Vite ESLint 插件](https://github.com/ModyQyW/vite-plugin-eslint2)。 ## 安装 ```sh npm install vite-plugin-stylelint -D ``` `vite-plugin-stylelint` 不会为你安装和配置 Stylelint。你应该自己处理这些。
Stylelint@16 ```sh npm install stylelint@^16 -D ```
Stylelint@15 ```sh npm install stylelint@^15 -D ```
Stylelint@14 ```sh npm install stylelint@^14 -D ```
Stylelint@13 ```sh npm install stylelint@^13 @types/stylelint@^13 -D ```
## 使用 ```typescript // vite.config.ts import { defineConfig } from 'vite'; import stylelint from 'vite-plugin-stylelint'; export default defineConfig({ plugins: [stylelint(options)], }); ``` ## 选项 你可以给这个插件传递 Stylelint [shared options](https://stylelint.io/user-guide/usage/options) 和 [Node.js API options](https://stylelint.io/user-guide/usage/node-api)。 ```typescript // vite.config.ts import { defineConfig } from 'vite'; import stylelint from 'vite-plugin-stylelint'; export default defineConfig({ plugins: [ stylelint({ // 推荐启用自动修复 fix: true, ..., }), ], }); ``` 额外的选项和解释列写在下方。 ### `test` - 类型：`boolean` - 默认值：`false` 在 `test` 模式下运行 Stylelint。查看 [命令行界面](https://cn.vitejs.dev/guide/#command-line-interface) 和 [配置 Vitest](https://cn.vitest.dev/guide/) 了解更多。 ### `dev` - 类型：`boolean` - 默认值：`true` 在 `serve` 命令下运行 Stylelint。查看 [命令行界面](https://cn.vitejs.dev/guide/#command-line-interface) 了解更多。 ### `build` - 类型：`boolean` - 默认值：`false` 在 `build` 命令下运行 Stylelint。查看 [命令行界面](https://cn.vitejs.dev/guide/#command-line-interface) 了解更多。 ### `cache` - 类型：`boolean` - 默认值：`true` 启用时，存储已处理的文件的结果。默认启用以提高速度。 ### `cacheLocation` - 类型：`string` - 默认值：`.stylelintcache` 缓存位置的文件或目录的路径。`.stylelintcache` 是 Stylelint 的默认缓存位置。 ### `include` - 类型：`string | string[]` - 默认值：`['src/**/*.{css,scss,sass,less,styl,vue,svelte}']` 这个选项指定你想要校验的文件模式。在绝大部分情况下，你并不需要调整它，除非你正在使用 Nuxt 等框架，或者 `include` 和 `exclude` 范围有重合。 如果你正在使用插件默认设置，插件只会在 `transform` 生命周期中调用 [stylelint.lint](https://stylelint.io/user-guide/node-api/)。这个选项值会被用于 [创建一个过滤器](https://github.com/rollup/plugins/blob/master/packages/pluginutils/README.md#createfilter) 来确定是否该调用以及调用参数。这意味着选项值需要满足 [picomatch@2.3.1](https://github.com/micromatch/picomatch/tree/2.3.1) 的要求。 如果你启用了 `lintOnStart` 选项，插件还会在 `buildStart` 生命周期中调用 `stylelint.lint`。这个选项值不会用于创建过滤器，而是直接用作调用参数。这意味着这个选项值还需要满足 [globby@11.1.0](https://github.com/sindresorhus/globby/tree/v11.1.0) 的要求。 如果你禁用了 `lintDirtyOnly` 选项，插件每次调用 `stylelint.lint` 时都会将该选项值作为调用参数。这意味着这个选项值也需要满足 `globby@11.1.0` 的要求。 ### `exclude` - 类型：`string | string[]` - 默认值：`['node_modules', 'virtual:']` 这个选项指定你不想要校验的文件模式。在绝大部分情况下，你并不需要调整它，除非你正在使用 Nuxt 等框架，或者 `include` 和 `exclude` 范围有重合。 如果你正在使用插件默认设置，插件只会在 `transform` 生命周期中调用 [stylelint.lint](https://stylelint.io/user-guide/node-api/)。这个选项值会被用于 [创建一个过滤器](https://github.com/rollup/plugins/blob/master/packages/pluginutils/README.md#createfilter) 来确定是否该调用以及调用参数。这意味着选项值需要满足 [picomatch@2.3.1](https://github.com/micromatch/picomatch/tree/2.3.1) 的要求。 如果你启用了 `lintOnStart` 选项或者禁用了 `lintDirtyOnly` 选项，这个选项值不会生效。你需要调整 `include` 值以包含该选项值。 ### `stylelintPath` - 类型：`string` - 默认值：`'stylelint'` Stylelint 路径，用于校验文件。底层使用使用 [dynamic import](https://javascript.info/modules-dynamic-imports)。请先阅读 [Vite server.fs 选项](https://cn.vitejs.dev/config/server-options.html#server-fs-strict)。 ### `formatter` - 类型：`StylelintFormatterType | StylelintFormatter` - 默认值：`'string'` 格式化器的名称、路径或函数实现。 用于 [设置格式化器](https://stylelint.io/user-guide/usage/options#formatter)，以便将校验结果转换为人类或机器可读的字符串。 ### `lintInWorker` - 类型：`boolean` - 默认值：`false` 在 [worker](https://nodejs.org/api/worker_threads.html#portpostmessagevalue-tran) 校验。默认禁用。 在 worker 中校验时，Vite 的构建过程会更快。即使终端显示了错误，Vite 的构建过程也不会停止。 这与 [vite-plugin-checker](https://github.com/fi3ework/vite-plugin-checker) 类似，但 [vite-plugin-checker](https://github.com/fi3ework/vite-plugin-checker) 可以在浏览器中显示错误。 ### `lintOnStart` - 类型：`boolean` - 默认值：`false` 在 `buildStart` 生命周期中校验 `include` 选项指定的文件一次以发现潜在的错误。默认禁用。 如果你没有缓存而且没有启用 `lintInWorker`，这将大大降低 Vite 的初次启动速度。 ### `lintDirtyOnly` - 类型：`boolean` - 默认值：`true` 在 `buildStart` 生命周期之外运行 Stylelint 时，只校验修改过的文件。默认启用。 禁用时，会校验 `include` 选项值对应的文件。 ### `chokidar` - 类型：`boolean` - 默认值：`false` 在 Chokidar `change` 事件中而不是在 `transform` 生命周期中运行 Stylelint。默认禁用。 启用后，可以校验通过 `@import` 导入的样式文件。 如果你启用这个选项，建议也启用 `lintOnStart`。 ### `emitError` - 类型：`boolean` - 默认值：`true` 输出发现的错误。默认启用。 ### `emitErrorAsWarning` - 类型：`boolean` - 默认值：`false` 将发现的错误作为警告输出。默认禁用，但你可能会在开发原型时启用这个。 ### `emitWarning` - 类型：`boolean` - 默认值：`true` 输出发现的警告。默认启用。 ### `emitWarningAsError` - 类型：`boolean` - 默认值：`false` 将发现的警告作为错误输出。默认禁用。 ## FAQ
我需要这个插件吗？

绝大部分情况下不需要。

在 Webpack 使用 stylelint-webpack-plugin 是很常见的，而这个插件在 Vite 中做着几乎一样的事情。

但是，我们的 IDE 可能已经提供了我们需要的所有信息。对于 VSCode，我们只需要添加 Stylelint 插件。 WebStorm 已经内置了这个功能。我们也可以在命令行或者 CI 中运行 Stylelint。

我们有这么多方法运行 Stylelint，没有太大必要在 Vite 中运行 Stylelint，这也就意味着我们在绝大部分情况下不需要这个插件。

如果你真的很需要查看错误和警告，请尝试启用 lintInWorker 选项，它会在 console 中打印信息。

或者尝试一下 vite-plugin-checker，它会在浏览器中打印信息。

Cache 失效

这个问题应该只会在启动 Vite 出现校验错误时出现。如果你有更好的解决方案，欢迎 PR。:)

使用这个插件时 Vite 很慢
## 例子 查看 [examples](https://github.com/ModyQyW/vite-plugin-stylelint/tree/main/examples)。 ## 改动日志 查看 [CHANGELOG.md](./CHANGELOG.md)。 ## 致谢 最初从 [gxmari007/vite-plugin-eslint](https://github.com/gxmari007/vite-plugin-eslint) 分叉出来。 ## License MIT ## [赞助者们](https://github.com/ModyQyW/sponsors)

sponsors