Middleman中的代碼質量工具：ESLint與Stylelint集成

Middleman作為靜態網站生成工具，提供了靈活的前端開發環境。為確保代碼質量與風格一致性，集成ESLint（JavaScript代碼檢查工具）和Stylelint（CSS/SCSS代碼檢查工具）是關鍵步驟。本文將詳細介紹在Middleman項目中配置這兩款工具的完整流程，幫助開發團隊建立規範化的代碼檢查工作流。

環境準備與依賴安裝

在Middleman項目中集成ESLint和Stylelint前，需確保項目已初始化Node.js環境。通過npm或yarn安裝必要依賴：

# 初始化package.json（如無）
npm init -y

# 安裝開發依賴
npm install --save-dev eslint stylelint eslint-plugin-import stylelint-config-standard-scss

上述命令安裝了核心檢查工具及SCSS支持插件。Middleman的Ruby環境與Node.js工具鏈可通過external_pipeline配置協同工作，相關配置示例可參考Middleman官方文檔。

ESLint配置與集成

創建ESLint配置文件

在項目根目錄創建.eslintrc.js文件，定義檢查規則與解析器設置：

module.exports = {
  env: {
    browser: true,
    es2021: true
  },
  extends: [
    'eslint:recommended',
    'plugin:import/errors'
  ],
  parserOptions: {
    ecmaVersion: 'latest'
  },
  rules: {
    'no-console': process.env.NODE_ENV === 'production' ? 'error' : 'warn',
    'indent': ['error', 2],
    'quotes': ['error', 'single']
  }
};

配置文件中指定了瀏覽器環境支持、推薦規則集及自定義縮進/引號規則。可根據項目需求擴展規則，如添加React支持需安裝eslint-plugin-react。

Middleman構建流程集成

修改config.rb文件，通過external_pipeline將ESLint檢查集成到開發與構建流程：

activate :external_pipeline,
  name: :eslint,
  command: build? ? 
    "npx eslint source/javascripts/**/*.js --quiet" : 
    "npx eslint source/javascripts/**/*.js --watch",
  source: ".",
  latency: 1

上述配置實現：

  • 開發模式（middleman server）：實時監控JS文件變更並執行檢查
  • 構建模式（middleman build）：執行嚴格檢查，錯誤將阻斷構建流程

Stylelint配置與SCSS支持

創建Stylelint配置文件

在項目根目錄創建.stylelintrc.js文件，配置SCSS支持與規則集：

module.exports = {
  extends: [
    "stylelint-config-standard-scss"
  ],
  rules: {
    "scss/at-rule-no-unknown": [true, {
      ignoreAtRules: ["mixin", "include", "extend"]
    }],
    "declaration-block-no-duplicate-properties": true,
    "color-no-invalid-hex": true
  }
};

配置繼承了標準SCSS規則集，並禁用對Sass特有指令（如@mixin）的未知規則檢查。可根據團隊規範添加自定義規則，如強制使用rem單位或禁止!important。

集成到Middleman構建流程

在config.rb中添加Stylelint的外部管道配置：

activate :external_pipeline,
  name: :stylelint,
  command: build? ?
    "npx stylelint source/stylesheets/**/*.{css,scss}" :
    "npx stylelint source/stylesheets/**/*.{css,scss} --watch",
  source: ".",
  latency: 1

與ESLint類似，Stylelint在開發時實時監控樣式文件變更，構建時執行嚴格檢查。兩個工具的錯誤信息將直接輸出到Middleman的終端日誌中，便於即時修復。

自動化檢查與IDE集成

Git提交前檢查

通過Husky工具在代碼提交前自動執行檢查，安裝相關依賴：

npm install --save-dev husky lint-staged

在package.json中添加配置：

{
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
  },
  "lint-staged": {
    "source/javascripts/**/*.js": ["eslint --fix"],
    "source/stylesheets/**/*.{css,scss}": ["stylelint --fix"]
  }
}

配置實現提交前自動修復可修復的代碼問題，並阻斷不符合規範的提交。此流程通過Git鈎子實現，確保代碼庫質量基線。

IDE實時反饋配置

在VS Code中安裝ESLint和Stylelint插件後，添加工作區設置（.vscode/settings.json）：

{
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true,
    "source.fixAll.stylelint": true
  },
  "stylelint.validate": ["css", "scss"],
  "eslint.validate": ["javascript"]
}

配置實現保存文件時自動修復可修復的代碼問題，配合Middleman的實時重載功能（middleman server），形成"編碼-保存-修復-預覽"的無縫開發體驗。

常見問題與解決方案

Middleman與Node版本兼容性

若遇到Node.js版本衝突，可在項目根目錄創建.nvmrc文件指定兼容版本：

v16.18.0

並通過nvm管理Node版本，確保與Middleman的Ruby環境協同工作。相關環境配置可參考Middleman troubleshooting指南。

自定義規則衝突處理

當工具規則與項目需求衝突時，可通過以下方式解決：

  1. 在配置文件的rules section覆蓋特定規則
  2. 使用內聯註釋臨時禁用檢查：
// eslint-disable-next-line no-console
console.log('調試信息');
/* stylelint-disable declaration-no-important */
.critical { color: red !important; }
  1. 創建項目專屬規則集併發布為npm包

建議定期審查規則配置，移除過時或不合理的限制，平衡代碼質量與開發效率。

總結與最佳實踐

集成ESLint和Stylelint為Middleman項目帶來以下收益：

  • 代碼一致性：自動檢測縮進、命名等風格問題
  • 錯誤預防：提前發現未定義變量、語法錯誤等問題
  • 團隊協作：統一編碼規範，減少代碼審查爭議

推薦實踐：

  1. 定期更新檢查工具與規則集
  2. 將檢查結果集成到CI/CD流程（如GitHub Actions）
  3. 結合Prettier實現代碼格式化自動化
  4. 為新團隊成員提供配置指南文檔

通過本文介紹的配置流程，開發團隊可在Middleman項目中建立完善的代碼質量保障體系，提升代碼可維護性與團隊協作效率。完整配置示例可參考Middleman代碼質量示例倉庫中的config/examples/linting/目錄。