Sass @use：載入模組、命名空間與 with 設定

@use 是 模組系統 的主力：把另一個檔案載入進來，讓它的變數、混入 與 函式 可以在目前這個檔案裡使用。

基本用法

// _colors.scss
$brand: #2965f1;

@mixin text-brand {
  color: $brand;
}

// main.scss
@use "colors";

.btn {
  background: colors.$brand;
  @include colors.text-brand;
}

成員前面要加 命名空間，預設就是檔名（去掉開頭底線與副檔名）。

三個規定

一、必須寫在最前面。 @use 之前只能有變數宣告與註解，不能有任何 CSS 規則：

@use "colors";     // ✅ 最上面

.card { }

@use "mixins";     // ❌ Error

二、同一個檔案不能重複載入同一個模組。 寫兩次 @use "colors" 會報錯。

三、路徑不寫底線與副檔名。 寫 "colors"，不是 "_colors.scss"，規則見 分部檔。

改命名空間

檔名太長或路徑很深時，用 as 改一個短的：

@use "abstracts/variables" as v;
@use "abstracts/mixins" as mx;

.card {
  padding: v.$gap;
  @include mx.center;
}

as * 省略前綴

@use "abstracts/variables" as *;

.card {
  padding: $gap;   // 不必前綴
}

這會退回 @import 的世界

省略前綴之後就看不出 $gap 來自哪個檔案，同名成員也會直接衝突。只建議用在：

• 自己維護的、成員很少的工具檔。
• 整個專案到處都在用、加前綴反而囉嗦的斷點 混入。

第三方模組請一律保留命名空間。

載入內建模組

Sass 的 內建模組 也用 @use 載入，前面加 sass:：

@use "sass:math";
@use "sass:color";

.card {
  width: math.div(100%, 3);
  border-color: color.scale(#2965f1, $lightness: -20%);
}

每個檔案都要自己載入

模組系統沒有「全域可用」這回事。A 檔案 @use "sass:math" 不代表 B 檔案也拿得到，B 要自己寫一次。

用 with 設定模組變數

模組裡帶 !default 的變數，載入時可以改掉：

// _button.scss
$radius: 4px !default;
$height: 40px !default;

.btn {
  border-radius: $radius;
  height: $height;
}

// main.scss
@use "button" with (
  $radius: 999px,
  $height: 48px
);

這是 Sass 版的「模組設定檔」，比早期「在 @import 之前先宣告變數蓋掉」可靠得多，設定與載入寫在同一行，順序不會出錯。

with 的兩個限制

一、目標變數必須有 !default，否則報錯，理由見 變數旗標。

二、一個模組只能被設定一次。 若它已經在別處被 @use 過（哪怕是別的檔案間接載入的），再帶 with 就會失敗。解法是把設定移到 最先載入它的那個檔案，通常是入口的 main.scss。

載入路徑

@use "colors";               // 同目錄
@use "abstracts/variables";  // 子目錄
@use "../abstracts";         // 上一層的目錄（找 _index.scss）
@use "pkg:bootstrap";        // node_modules 中的套件

找不到檔案時可以用 --load-path 補上搜尋目錄，見 安裝與編譯。

一個完整的例子

// abstracts/_variables.scss
$gap: 16px !default;
$brand: #2965f1 !default;

// components/_card.scss
@use "../abstracts/variables" as v;

.card {
  padding: v.$gap;
  border-top: 3px solid v.$brand;
}

// main.scss
@use "abstracts/variables" with ($gap: 24px);
@use "components/card";

main.scss 先設定 $gap 為 24px，_card.scss 拿到的就是設定後的值，模組只會被載入一次，設定對所有使用者一致生效。

常見問題

為什麼 @use 一定要寫在檔案最上面？

Sass 規定 @use 必須出現在所有規則之前，只有變數宣告與註解可以排在它前面。這個限制讓相依關係一目了然，也保證模組在被使用之前就已經載入完成。

as 星號可以用嗎？

可以，但要節制。省略前綴之後就回到 @import 那種分不清來源的狀態，同名成員也會衝突。只建議用在自己維護、成員很少、且會在整個專案大量使用的工具檔上。

同一個模組可以 @use 兩次嗎？

同一個檔案裡不能對同一個模組寫兩次 @use，會直接報錯。不同檔案各自 @use 同一個模組是完全正常的，模組仍然只會被編譯一次。

用 with 設定變數失敗是什麼原因？

最常見的兩個原因，一是目標變數沒有加 !default，二是該模組已經在別的地方被載入過了。已經載入過的模組不能再帶 with 設定，這時應該把設定移到最先載入它的那個檔案。

延伸閱讀

模組轉發 @forward變數旗標 !default、!global已棄用的 @import內建模組有哪些？