SCSS 棄用 @import？！

前言

這幾天維護老舊專案順便把老舊專案升級上去，卻出現一個錯誤訊息「Deprecation Warning [import]: Sass @import rules are deprecated and will be removed in Dart Sass 3.0.0.」，所以這一篇就順便來記錄一下該如何解決吧。

Sass @import 棄用警告

1
2
3
4
5
6
7
8
9

Deprecation Warning [import]: Sass @import rules are deprecated and will be removed in Dart Sass 3.0.0.

More info and automated migrator: https://sass-lang.com/d/import

  ╷
4 │ @import 'abstracts/variables';
  │         ^^^^^^^^^^^^^^^^^^^^^
  ╵
    src/css/style.scss 4:9  root stylesheet

簡單來講就是，Sass 官方已經宣布 @import 規則將會在 Dart Sass 3.0.0 中被移除，並建議使用 @use 或 @forward 來取代 @import。

接下來我們將會嘗試了解一下這個變化會有什麼樣的問題。

如果你是使用 VSCode 的 Watch Sass 套件，那有很高機會看不到這個錯誤，因為 Watch Sass 套件的版本比較舊，但我們實際正式開發環境會是使用 Vite、Webpack 或其他工具來編譯 SCSS，所以還是會遇到這個問題。

如果你不想使用 Vite、Webpack 等工具來編譯 SCSS，你也可以考慮使用 Parcel 來編譯取代。

Sass @use 與 @forward 有什麼改變？

基本上新版就都是一律建議你不要再使用 @import，而是改用 @use 或 @forward。

假設今天有一個架構是這樣：

1
2
3
4

styles/
  abstracts/
    _variables.scss
  style.scss

然後 style/abstracts/_variables.scss 內容是：

1

$primary-color: #3498db;

接著 style/style.scss 內容是：

1
2
3
4

@import 'abstracts/variables';
body {
  background-color: $primary-color;
}

相信這是大家所熟悉的寫法。

使用 @use 的改變

但是新版之後，你必須改使用 @use，你可能會很直覺的想改成這樣：

1
2
3
4
5

@use 'abstracts/variables';

body {
  background-color: $primary-color;
}

接著你就會得到一串 Undefined variable: "$primary-color". 的錯誤訊息。

這個原因是因為使用 @use 之後，Sass 會將變數、函式和混入（mixins）封裝在模組命名空間中，什麼意思呢？當我們使用 @use 'abstracts/variables'; 時，Sass 會將 variables 這個檔案名稱作為一個命名空間，所以你必須使用 variables.$primary-color 來存取這個變數。

所以正確的使用方式是這樣：

1
2
3
4
5

@use 'abstracts/variables';

body {
  background-color: variables.$primary-color;
}

那麼這樣做有什麼好處呢？你可以避免命名衝突，當你 @import 一大推檔案時，很容易會有變數名稱重複的問題，就像…

1
2
3
4
5

// variables.scss
$primary-color: #3498db;

// another-variables.scss
$primary-color: #e74c3c;

如果是使用 @import，那麼這兩個變數就會衝突：

1
2
3
4
5
6

@import 'variables';
@import 'another-variables';

body {
  background-color: $primary-color; // 這邊就會發生衝突
}

所以到底是 #3498db 還是 #e74c3c？

因此，使用 @use 可以避免這種命名衝突的問題：

1
2
3
4
5
6

@use 'variables';
@use 'another-variables';

body {
  background-color: another-variables.$primary-color; // 明確指定使用哪個命名空間的變數
}

這是一個非常重大的更新與調整，對於較大型專案來講，我認為是非常值得更新的。

但這邊要注意一件事情，通常我們會將各種變數放在 _variables.scss，但使用 @use 後，你原本再另一個 _card.scss 想要使用 $primary-color 變數的話，你必須在 _card.scss 裡面也要 @use 'abstracts/variables';，這樣才可以使用 variables.$primary-color。

1
2
3
4
5
6
7

// styles.css
@use 'abstracts/variables';
@use 'components/card';

.card {
  background-color: variables.$primary-color;
}

1
2
3
4
5
6

// components/_card.scss
@use 'abstracts/variables';

.card {
  background-color: variables.$primary-color;
}

不然你會得到一個 Undefined variable: "$primary-color". 的錯誤訊息，畢竟我們早期使用 @import 時，是可以直接共用變數的，@import 類似建立一個全域的變數空間，所以就很容易發生命名衝突的問題。

所以當你使用 @use 時，每個檔案的引入都是獨立運作的。

當然這種 @use 的方式也很麻煩，因為你可能就不希望它叫做 variables or card，你可能希望它叫做 v or c，這時候你可以使用 as 來重新命名命名空間：

1
2
3
4
5

@use 'abstracts/variables' as v;

.card {
  background-color: v.$primary-color;
}

使用 @forward 的改變

通常我們在實戰開發上，很長建立一個 index.scss 來統一匯出所有的變數、混入、函式等，原本我們會是這樣寫：

1
2
3

// abstracts/_index.scss
@import 'variables';
@import 'mixins';

這樣我們可以一次性匯入所以可以使用的東西，這樣我們就可以在 style.scss 中這樣使用：

1
2
3
4
5

@import 'abstracts/index';
body {
  background-color: $primary-color;
  @include center-block;
}

所以你可能第一直覺就是這樣改：

1
2

// abstracts/_index.scss
@use 'variables';

但其實不太對，這樣做是會導致 Undefined variable: "$primary-color". 的錯誤訊息，畢竟前面有講過 @use 會在這個檔案中建立一個命名空間，所以你無法在 style.scss 中直接使用 variables.$primary-color。

那該怎麼做呢？這邊要改用的方式就是 @forward，所以正確的寫法是這樣：

1
2

// abstracts/_index.scss
@forward 'variables';

@forward 概念類似把這些變數、混入、函式等「轉發」出去，讓其他檔案可以直接使用。

因此我們回到 style.scss，我們就可以這樣寫：

1
2
3
4

@use 'abstracts/index' as abs;
body {
  background-color: abs.$primary-color;
}

這樣就可以正確使用 @forward 轉發出去的變數與混入了。

結論

太久沒有寫 SCSS，真是沒想到已經有這樣的變化惹 QQ