如何為你的 Vue 專案新增配置 Stylelint

現在已經是 9102 年了，網上許多教程和分享帖都已經過期，照著他們的步驟來會踩一些坑，如 stylelint-processor-html 已經不再維護，以及 --fix 之後 .vue 檔案只剩下 <style> 部分等。我在踩完坑跑通出滿意的效果後，維護一份新的指引，以備後續專案使用，順便分享一下。

為什麼選擇用 stylelint ？

這個問題有兩層含義，一是為什麼要使用這個樣式程式碼風格檢查工具，二是與其他工具相比，為什麼選擇 stylelint 而不是其他如 stylefmt 等。

使用 linter 的原因

對於第一個問題，相信很多小夥伴都會被歷史遺留的，或多人協同開發寫下的風格不一的樣式程式碼困擾過，最基本的就是換行、縮排和空格之爭，大家對此應該都不陌生。特別是有時候你可能會遇上如下祖傳程式碼：

#idA .classB,.classC{position:absolute;top: 0;left:0; display:-webkit-flex;display: flex;width:100%;background:url(../pic.png) no-repeat;-webkit-background-size:contain;background-size:contain }

這段程式碼從我個人風格來看存在不少問題：

1. 不推薦使用 id 選擇器來定義樣式；
2. 多重選擇器（multiple selectors）沒有換行，不清晰直觀；
3. 多個 css 規則沒有換行，擠在單行太長；
4. 使用了 -webkit-
   字首，但是專案中已經支援 autoprefixer ；
5. 屬性和值之間的空格時有時無等。

當然程式碼風格因人而異，所以才需要團隊統一。在一些早期缺乏完善的程式碼評審等制度的專案中，很容易由於程式設計師的偷懶圖方便或在一時的緊急粗糙趕工中積累下一坨對團隊其他成員不太友好、可閱讀性低、較難維護的 css 。

同類工具比較

至於第二個問題，選擇 stylelint 的原因也很簡單，它是當前所有同類工具中使用人數最多的，社群較為活躍，仍在持續維護。而且正如這個 issue 中提到，當下很多大廠都在使用，如 github 的 primer 體系就定製了一套自己的規則 stylelint-config-primer

至於 stylefmt 也曾經被推薦與 stylelint 搭配組合，不少博文都有提到。但是官方已經不推薦繼續使用，直接用 stylelint 的 --fix 選項即可。

NOTICE: Consider other tools before adopting stylefmt
If you are using stylefmt with stylelint configuration to format according to its rules, you can now use stylelint's --fix option (from v7.11.0) to autofix.

Another on the other hand, prettier supports to format not only JavaScript but also CSS, SCSS and Less code.

而沒有考慮 prettier 的原因則是它希望提供一套官方自己認可的統一風格規範，而不僅僅是個 linter 或者 formatter ，可配置項很少，定製自由度較低，不適合想要自己搞事情的團隊，更適合個人開發者去使用。

如何開始使用

安裝依賴

其實官方的 User guide 已經很全面，與 eslint 是非常相似的。

1. 安裝 stylelint

   npm i -D stylelint stylelint-config-stand

   後者 stylelint-config-stand 不是必需的，也可以自己根據文件從零開始配置規則，或者用第三方如 github 的規則 stylelint-config-primer 。

2. 安裝適配預處理語法的外掛

   以 sass 為例：

   npm i -D stylelint-scss

   不過 stylus 目前沒有發現可用性高的相關外掛，也導致 stylelint 不能解析 stylus 語法。

3. 安裝 webpack 外掛

   npm i -D stylelint-webpack-plugin

命令列使用

stylelint 搜尋目錄和檔案使用的是 glob 規則：

npx stylelint --cache **/*.{html,vue,css,sass,scss} --fix

--cache 選項可以指定使用快取，預設生成的 .stylelintcache 檔案放置於執行目錄中， --fix 選項可以指定 stylelint 自動修復不符合可修復規則的程式碼，其他更多選項可以參考官方文件。

但需要注意有一個問題，在沒有配置使用 stylelint-scss 之類的外掛前， stylelint 是不能直接解析 vue 檔案、 html 檔案等的，會報出一堆錯誤：

1:1  ✖  Unknown word   CssSyntaxError

我們可以用內建的自定義語法 postcss-html 來解析（不需安裝）：

npx stylelint **/*.{html,vue} --custom-syntax postcss-html

也可以用內建的 scss 語法支援來解析 css 檔案：

npx stylelint **/*.{css,sass,scss} --syntax scss

通過 npm 命令執行

在 scripts 中加一下就好了，對於 9102 年的前端程式設計師應該都是基本操作：

// package.json
{
    "scripts": {
        "lint:style": "stylelint **/*.{html,vue} --custom-syntax postcss-html",
        "lint:css": "stylelint **/*.{css,sass,scss} --syntax scss"
    }
}

或者（配置了 stylelint-scss 外掛後）：

{
    "scripts": {
        "lint:css": "stylelint **/*.{html,vue,css,sass,scss}"
    }
}

然後可以手動在命令列執行：

npm run lint:css
npm run lint:css -- --fix
npm run lint:css -- --cache --fix

通過 webpack 外掛執行

// webpack.conf.js
const StyleLintPlugin = require('stylelint-webpack-plugin');

module.exports = {
    ...
    'plugins': [
        ...
        new StyleLintPlugin({
            'files': ['**/*.{html,vue,css,sass,scss}'],
            'fix': false,
            'cache': true,
            'emitErrors': true,
            'failOnError': false
        })
    ]
};

stylelint 支援的所有命令列選項都可以在初始化外掛時傳遞 options 來指定，包括上文提到的 --syntax 等。更多可以參考 stylelint-webpack-plugin 官方文件。

編寫配置

配置物件

stylelint 支援 cosmiconfig 的配置方式，按如下順序查詢配置物件：

• 在 package.json 中的 stylelint 屬性
• JSON / YAML / JS 格式的 .stylelintrc 檔案（可帶字尾）
• 匯出 JS 物件的 stylelint.config.js 檔案

它的配置也非常簡單，只有 rules 、 extends 、 plugins 、 processors 、 ignoreFiles 和 defaultSeverity 。

其中 defaultSeverity 只支援 "warning" 和 "error" 兩種，用於定義全域性預設的報錯等級。但是它沒有相應的 cli 選項，實際上不太好用——比如你想 stylelint-webpack-plugin 只是警告，而 git-hooks 則是直接報錯不允許提交的時候。文件上關於如何對規則單獨配置錯誤等級有一句話提到了如何去控制：

Different reporters may use these severity levels in different way, e.g. display them differently, or exit the process differently.

但是卻沒有在其他地方或者 Developer guide 中找到任何與 reporters 有關的資訊，有可能是需要自己寫一個 formatter 。

一個簡單的配置示例：

// stylelint.config.js
module.exports = {
    'defaultSeverity': 'error',
    'extends': [ 'stylelint-config-standard' ],
    'plugins': [ 'stylelint-scss' ],
    'rules': {
        // 不要使用已被 autoprefixer 支援的瀏覽器字首
        'media-feature-name-no-vendor-prefix': true,
        'at-rule-no-vendor-prefix': true,
        'selector-no-vendor-prefix': true,
        'property-no-vendor-prefix': true,
        'value-no-vendor-prefix': true
    }
};

由於可以用 stylelint-scss 去解析檔案中的 scss 程式碼，我們暫時不需要使用官方列出的任何 processors 。

忽略檔案

雖然可以通過配置 ignoreFiles 來簡單實現，但是我們可能期望在一些遺留的老舊程式碼上先暫時不啟用 stylelint ，等後續再慢慢放開，這樣的話需要配置的檔案路徑就有點多了。為了方便我們可以再編寫一個 .stylelintignore 檔案，它的語法是跟 .gitignore 和 .eslintignore 一樣的：

# .stylelintignore
# 舊的不需打包的樣式庫
*.min.css

# 其他型別檔案
*.js
*.jpg
*.woff

# 測試和打包目錄
/test/
/dist/

# 通過反取忽略目錄
/src/component/*
!/src/component/CompA
!/src/component/CompB
# 這樣的效果是除 CompA 和 CompB 外其他目錄都會被忽略

更多可以參考 node-ignore 。

stylelint 與 eslint 同時使用 git-hooks 配置

如果專案中已經在用 husky 的 pre-commit 鉤子來執行 eslint ，現在要加 stylelint 其實很簡單：

// package.json
{
    ...
    "lint-staged": {
        "*.{vue,js}": [
            "eslint --fix",
            "git add"
        ],
        "*.{html,vue,css,sass,scss}": [
            "stylelint --fix",
            "git add",
        ]
    },
    "husky": {
        "hooks": {
            "pre-commit": "lint-staged",
        }
    }
}

唯一需要注意的是， lint-staged 預設是並行執行的，同時對 .vue 檔案做 git add 會不會有衝突？暫時未在網上見相關討論，我自己執行也沒有任何問題，如果實在擔心的話，可以將 glob 匹配分開定義。

區域性禁用規則

也是跟 eslint 類似的，我們可以通過 stylelint-disable 註釋來區域性禁用某一項規則。

<style>
    /* stylelint-disable selector-no-vendor-prefix, property-no-vendor-prefix, value-no-vendor-prefix */
    .classA {
        -webkit-transition-property: -webkit-transform;
        transition-property: -webkit-transform;
        -o-transition-property: transform;
        /* stylelint-disable declaration-block-no-duplicate-properties */
        transition-property: transform;
        transition-property: transform, -webkit-transform;
        /* stylelint-enable */
    }
</style>

但是隨之而來的是一個常見錯誤：你在檔案頭部忽略了對瀏覽器字首的提示，卻在另一個遙遠的地方由於暫時性允許同名屬性，通過 /* stylelint-enable */ 把之前所有忽略的規則都重新開啟了。所以一定要注意，只 enable 對應的規則，形成呼應：

<style>
    .classA {
        /* stylelint-disable declaration-block-no-duplicate-properties */
        transition-property: transform;
        transition-property: transform, -webkit-transform;
        /* stylelint-enable declaration-block-no-duplicate-properties */
    }
</style>

其他注意事項

1. 解析 .vue 檔案（單檔案元件）時請勿使用 processors

   網上一些過時的教程包括 github 上的討論都推薦使用 stylelint-processor-html 或者 @mapbox/stylelint-processor-arbitrary-tags 來解析 html 或 vue 中的 css ，這本身並沒有什麼問題，但是這個外掛有個 bug ，當指定 stylelint 的 --fix 後將會把 vue 檔案中 <style>...</style> 以外的部分刪掉。

   我們使用自定義語法 postcss-html 或者保留 stylelint-scss 外掛就足夠了。

2. 一些規則在跑 --fix 選項時是有 bug 的

   比如 declaration-block-semicolon-newline-after 設定 "always" 時，不允許多條 css 規則寫在一行，但自動修復後可能會出現縮排不正確：

   <style>
       .classA {
           display: block;
       }
   
       a { color: pink; top: 0; }
   </style>

   修復後（示例，之前配置時沒嘗試去找必現路徑）：

   <style>
       .classA {
           display: block;
       }
   
       a {
   color: pink;
   top: 0;
   }
   </style>

   如果你也出現這種情況，可以再指定 indentation 規則的基準縮排（ baseIndentLevel ）：

   module.exports = {
       ...
       rules: {
           ...
           'indentation': [2, {
               'baseIndentLevel': 1,
           }],
           'declaration-block-semicolon-newline-after': 'always'
       }
   };

參考連結

1. Prettier + Stylelint: Writing Very Clean CSS (Or, Keeping Clean Code is a Two-Tool Game)
2. 如何在Vue+Webpack下配置Stylelint - 簡書
3. vue單檔案元件lint error自動fix及styleLint報錯自動fix - segmentfault
4. Stylelint in .vue - 掘金

本文基於 知識共享署名-非商業性使用-相同方式共享 4.0 國際許可協議 釋出，歡迎引用、轉載或演繹，但是必須保留本文的署名 BlackStorm 以及本文連結 http://www.cnblogs.com/BlackStorm/p/add-stylelint-to-your-vue-project.html ，且未經許可不能用於商業目的。如有疑問或授權協商請與我聯絡。