For AI agents: the complete documentation index is available at https://vite-plugin-stylelint.modyqyw.top/zh/llms.txt, the full documentation bundle is available at https://vite-plugin-stylelint.modyqyw.top/zh/llms-full.txt, and this page is available as Markdown at https://vite-plugin-stylelint.modyqyw.top/zh/guide/options.md.
  • 简体中文
  • 选项配置

    插件在一个对象里接收 Stylelint shared options 和插件特有的额外选项。files 选项总是会被插件覆盖。

    共享选项

    下面列常用的几个,其余见上面的链接。

    fix

    • 类型:boolean
    • 默认值:false

    是否让 Stylelint 改写它能修的问题。

    cache

    • 类型:boolean
    • Stylelint 默认值:false
    • 插件默认值:true

    是否启用缓存。Stylelint 默认关掉。插件默认打开,为了快一点。

    cacheLocation

    • 类型:string
    • 默认值:.stylelintcache

    缓存文件的位置。

    额外选项

    test

    • 类型:boolean
    • 默认值:false

    是否在 test 模式下运行 Stylelint。见 命令行界面 和 配置 Vitest。

    dev

    • 类型:boolean
    • 默认值:true

    是否在 serve 下运行 Stylelint。见 命令行界面。

    build

    • 类型:boolean
    • 默认值:false

    是否在 build 下运行 Stylelint。见 命令行界面。

    include

    • 类型:string | string[]
    • 默认值:["src/**/*.{css,scss,sass,less,styl,vue,svelte}"]

    要校验的文件。大多数项目不用改它。只有 include 和 exclude 范围重合时才需要调整。

    用默认设置时,插件只在 transform 钩子里调用 stylelint.lint。它用这个选项值 创建一个过滤器。过滤器决定是否调用 Stylelint,以及传什么参数。所以选项值要符合 picomatch 的写法。

    开了 lintOnStart 时,插件还会在 buildStart 钩子里调用 stylelint.lint。这时选项值原样传给 files。所以它还得是 Stylelint 认得的 glob。Stylelint 18 用 tinyglobby 解析 glob。

    关了 lintDirtyOnly 时,插件每次调用 stylelint.lint 都会传这个选项值。所以它同样得是 Stylelint 认得的 glob。Stylelint 18 用 tinyglobby 解析 glob。

    exclude

    • 类型:string | string[]
    • 默认值:['node_modules', 'virtual:']

    不要校验的文件。大多数项目不用改它。只有 include 和 exclude 范围重合时才需要调整。

    插件总是忽略虚拟模块。这里不用配置。

    用默认设置时,插件只在 transform 钩子里调用 stylelint.lint。它用这个选项值 创建一个过滤器。过滤器决定是否调用 Stylelint,以及传什么参数。所以选项值要符合 picomatch 的写法。

    开了 lintOnStart,或者关了 lintDirtyOnly 时,这个选项值不生效。要排除这些文件,得改 include 值。

    stylelintPath

    • 类型:string
    • 默认值:"stylelint"

    用于校验的 Stylelint 路径。底层用 dynamic import 加载。请先读 Vite server.fs 选项。

    formatter

    • 类型:string
    • 默认值:"string"

    格式化器的名称、路径或函数。插件把它传给 Stylelint 的格式化器选项,把校验结果转成人类或机器可读的字符串。

    lintInWorker

    • 类型:boolean
    • 默认值:false

    在 worker 里校验。

    放到 worker 里校验,Vite 跑得更快。代价是构建不会因为 Stylelint 报错停下来,Vite 原生遮罩层也没了。终端照样打印错误。开 lintInWorker 时自定义遮罩层依然可用。

    vite-plugin-checker 解决的是同一个问题。挑一个顺手的就行。

    customOverlay

    • 类型:boolean | CustomOverlayOptions
    • 默认值:false
    interface CustomOverlayOptions {
      initialIsOpen?: boolean | "error";
      position?: "tl" | "tr" | "bl" | "br";
      theme?: Partial<Record<ThemeKey, string>>;
      zIndex?: number;
    }

    用插件的自定义遮罩层,替代 Vite 原生错误遮罩层。

    原生遮罩层把 Stylelint 带 ANSI 颜色的 string 输出原样渲染。浏览器里颜色丢失,或者直接显示转义字符。自定义遮罩层原生渲染结构化结果。它还能配合 lintInWorker 使用,原生遮罩层做不到。

    环境里没有 DOM 入口时(小程序、SSR、无头测试),插件不注入运行时。它警告一次,之后只打到终端。

    • false:保留 Vite 原生遮罩层。配合 lintInWorker 时完全没有遮罩层。
    • true:使用自定义遮罩层,默认样式。
    • {...}:使用自定义遮罩层,按给定配置定制样式。

    这个选项只在 serve 下生效。build 模式下始终保留原生 context.error 的阻塞行为。

    lintOnStart

    • 类型:boolean
    • 默认值:false

    在 buildStart 钩子里,把 include 匹配到的文件校验一次。

    没有缓存、又没开 lintInWorker 时,Vite 第一次启动会明显变慢。

    lintDirtyOnly

    • 类型:boolean
    • 默认值:true

    在 buildStart 之外,只校验本次请求涉及的文件。被 exclude 匹配到的文件跳过。

    关掉这个选项时,插件改为按 include 和 exclude 的值判断要校验哪些文件。

    emitError

    • 类型:boolean
    • 默认值:true

    输出发现的错误。

    emitErrorAsWarning

    • 类型:boolean
    • 默认值:false

    把发现的错误当警告输出。做原型时可以打开。

    emitWarning

    • 类型:boolean
    • 默认值:true

    输出发现的警告。

    emitWarningAsError

    • 类型:boolean
    • 默认值:false

    把发现的警告当错误输出。