Sass 的 source map 與 Stylelint 設定

寫 Sass 時，瀏覽器看到的是編譯後的 CSS，開發者工具指出 main.css:2841，你完全不知道那對應到哪個 .scss。source map 就是補上這條線索的東西。

source map 的產生

CLI 預設就會產生：

npx sass src/main.scss dist/main.css
# → main.css 與 main.css.map

產出的 CSS 結尾會附上一行註解指向它：

/*# sourceMappingURL=main.css.map */

瀏覽器讀到之後，開發者工具的 Styles 面板就會顯示 _card.scss:12 而不是 main.css:2841。

記得在瀏覽器裡開啟

Chrome DevTools 的設定裡要勾選「Enable CSS source maps」，預設是開的但有時會被關掉。

關掉它

npx sass src/main.scss dist/main.css --no-source-map

Vite 與 Webpack 則在設定裡控制：

// vite.config.js
export default {
  css: { devSourcemap: true },   // 開發時
  build: { sourcemap: false },   // 正式建置
};

正式環境要不要留

保留	不保留
線上出問題時能直接對到原始碼	少一個檔案要傳
產出多一個 .map	不公開原始碼的組織結構

CSS 的 source map 不含敏感資訊（不像 JavaScript 可能洩漏商業邏輯），保留通常沒問題。多數團隊仍選擇關掉，純粹是為了精簡。

行號錯掉多半是鏈斷了

Sass 編譯完之後若還有 PostCSS、autoprefixer、壓縮工具接手，每一關都要把 source map 傳下去，中間有一個沒開，最後對到的位置就是錯的。

Stylelint

source map 幫你找到問題在哪，Stylelint 則在問題進版本庫之前就攔下來。

npm i -D stylelint stylelint-config-standard-scss

// .stylelintrc.json
{
  "extends": ["stylelint-config-standard-scss"],
  "rules": {
    "max-nesting-depth": 3,
    "selector-max-id": 0,
    "declaration-no-important": true,
    "scss/at-rule-no-unknown": true,
    "scss/dollar-variable-pattern": "^[a-z][a-z0-9-]*$",
    "scss/at-extend-no-missing-placeholder": true,
    "scss/no-global-function-names": true
  }
}

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

值得開的幾條規則

規則	擋下什麼
max-nesting-depth	巢狀過深，這條最有價值
scss/no-global-function-names	還在用 lighten() 這類 棄用的全域函式
scss/at-extend-no-missing-placeholder	@extend 繼承了真實類別而不是 placeholder
selector-max-id	用了 ID 選取器，優先權 會失控
declaration-no-important	到處加 !important
scss/dollar-variable-pattern	變數命名不一致

最有價值的是巢狀深度

其他多半是風格問題，交給 Prettier 就好。只有巢狀深度是真的會影響產出與 優先權 的，見 巢狀規則。

與 Prettier 分工

工具	管什麼
Prettier	縮排、引號、換行（格式）
Stylelint	巢狀深度、棄用函式、優先權（品質）

兩者一起用時，把 Stylelint 的格式類規則關掉避免打架：

npm i -D stylelint-config-prettier-scss

{
  "extends": ["stylelint-config-standard-scss", "stylelint-config-prettier-scss"]
}

接上 VS Code 與 Git

編輯器即時提示：

// .vscode/settings.json
{
  "stylelint.validate": ["css", "scss"],
  "editor.codeActionsOnSave": {
    "source.fixAll.stylelint": "explicit"
  }
}

提交前自動檢查：

{
  "lint-staged": {
    "*.scss": ["stylelint --fix", "prettier --write"]
  }
}

編輯器設定見 VS Code 必裝擴充套件。

常見問題

正式環境要不要保留 source map？

看需求。保留的話線上除錯方便，但等於公開原始碼結構，也多一個檔案要傳。CSS 的 source map 沒有敏感資訊，保留通常沒問題，只是很多團隊選擇關掉以求精簡。

為什麼開發者工具指到的行號是錯的？

多半是編譯之後又有其他工具處理過 CSS，卻沒有把 source map 一起接下去。整條鏈上的每個工具都要開啟 source map，資訊才會正確傳遞到最後。

Stylelint 檢查 SCSS 要裝什麼？

裝 stylelint 與 stylelint-config-standard-scss 這組設定，它已經包含解析 SCSS 語法所需的外掛與適用於 SCSS 的規則，不必自己一條條配。

最值得開的規則是哪一條？

限制巢狀深度的那條。它是唯一能自動擋下產出爆炸與優先權失控的規則，其他多半只是風格問題，交給格式化工具就好。

延伸閱讀

除錯 @debug、@warn、@error效能與產出品質與建置工具整合VS Code 必裝擴充套件