遷移工具

用法用法永久連結

要使用 Sass 遷移工具，請告知它您想要執行哪個遷移以及您想要遷移哪些 Sass 檔案。

sass-migrator <migration> <entrypoint.scss...>

預設情況下，遷移工具只會更改您在命令列中明確傳遞的檔案。傳遞--migrate-deps 選項會告知遷移工具也更改所有使用@use 規則、@forward 規則或@import 規則載入的樣式表。如果您想進行測試執行，以查看將進行哪些更改而不實際儲存它們，您可以傳遞 --dry-run --verbose（或簡稱為 -nv）。

$ cat style.scss
$body-bg: #000;
$body-color: #111;

@import "bootstrap";

@include media-breakpoint-up(sm) {
  .navbar {
    display: block;
  }
}
$ sass-migrator --migrate-deps module style.scss
$ cat style.scss
@use "bootstrap" with (
  $body-bg: #000,
  $body-color: #111
);

@include bootstrap.media-breakpoint-up(sm) {
  .navbar {
    display: block;
  }
}

安裝安裝永久連結

您可以從大多數可以安裝 Dart Sass 的地方安裝 Sass 遷移工具。

獨立執行獨立執行永久連結

您可以在 Windows、Mac 或 Linux 上安裝 Sass 轉換器，方法是從 GitHub 下載適用於您作業系統的套件，並將其新增至您的 PATH。

npmnpm 永久連結

如果您使用 Node.js，您也可以使用 npm 安裝 Sass 轉換器，方法是執行

npm install -g sass-migrator

ChocolateyChocolatey 永久連結

如果您在 Windows 上使用 Chocolatey 套件管理器，您可以透過執行以下指令來安裝 Sass 轉換器：

choco install sass-migrator

HomebrewHomebrew 永久連結

如果您在 Mac OS X 上使用 Homebrew 套件管理器，您可以透過執行以下指令來安裝 Dart Sass：

brew install sass/sass/migrator

全域選項全域選項永久連結

這些選項適用於所有轉換器。

--migrate-deps–migrate-deps 永久連結

此選項（縮寫為 -d）會指示轉換器不僅更改命令列中明確傳遞的樣式表，還會更改它們使用 @use 規則、@forward 規則 或 @import 規則 所依賴的任何樣式表。

$ sass-migrator module --verbose style.scss
Migrating style.scss
$ sass-migrator module --verbose --migrate-deps style.scss
Migrating style.scss
Migrating _theme.scss
Migrating _fonts.scss
Migrating _grid.scss

--load-path–load-path 永久連結

此選項（縮寫為 -I）會告知轉換器一個 載入路徑，它應該在其中尋找樣式表。可以多次傳遞此選項以提供多個載入路徑。較早的載入路徑會優先於較晚的載入路徑。

從載入路徑載入的相依性會被假設為第三方程式庫，因此即使傳遞了 --migrate-deps 選項，轉換器也不會遷移它們。

--dry-run–dry-run 永久連結

此旗標（縮寫為 -n）會指示轉換器不要將任何變更儲存到磁碟。它會改為印出它將會變更的檔案清單。這通常與 --verbose 選項 搭配使用，以同時印出將會進行的變更內容。

$ sass-migrator module --dry-run --migrate-deps style.scss
Dry run. Logging migrated files instead of overwriting...

style.scss
_theme.scss
_fonts.scss
_grid.scss

--no-unicode–no-unicode 永久連結

此旗標會指示 Sass 轉換器僅將 ASCII 字元輸出到終端機作為錯誤訊息的一部分。根據預設，或者如果傳遞了 --unicode，轉換器將會針對這些訊息輸出非 ASCII 字元。此旗標不會影響 CSS 輸出。

$ sass-migrator --no-unicode module style.scss
line 1, column 9 of style.scss: Error: Could not find Sass file at 'typography'.
  ,
1 | @import "typography";
  |         ^^^^^^^^^^^^
  '
Migration failed!
$ sass-migrator --unicode module style.scss
line 1, column 9 of style.scss: Error: Could not find Sass file at 'typography'.
  ╷
1 │ @import "typography";
  │         ^^^^^^^^^^^^
  ╵
Migration failed!

--verbose–verbose 永久連結

此旗標（縮寫為 -v）會指示轉換器將額外資訊印到控制台。根據預設，它只會印出已變更檔案的名稱，但與 --dry-run 選項 結合使用時，它也會印出這些檔案的新內容。

$ sass-migrator module --verbose --dry-run style.scss
Dry run. Logging migrated files instead of overwriting...
<==> style.scss
@use "bootstrap" with (
  $body-bg: #000,
  $body-color: #111
);

@include bootstrap.media-breakpoint-up(sm) {
  .navbar {
    display: block;
  }
}
$ sass-migrator module --verbose style.scss
Migrating style.scss

遷移遷移永久連結

顏色顏色永久連結

此遷移會將舊版顏色函式轉換為新的色彩空間相容函式。

除法除法永久連結

此遷移會將使用 / 作為除法 的樣式表轉換為使用內建的 math.div 函式。

--pessimistic–pessimistic 永久連結

預設情況下，即使遷移器不確定在評估時是否為除法，它也會將 / 運算轉換為 math.div。只有在它可以靜態確定它們正在執行其他操作時（例如，當不涉及 SassScript 或其中一個運算元是字串時），它才會保持原樣。math.div 函式目前的功能與 / 運算子相同，因此這樣做是安全的，但如果在執行階段 math.div 的其中一個引數不是數字，則可能會產生新的警告。

如果您想避免這種行為，可以傳遞 --pessimistic 旗標。使用此旗標，遷移器只會轉換它確定正在進行除法的 / 運算。這將防止任何不必要的 math.div 轉換，但如果無法靜態確定，則可能會留下一些未遷移的除法。

模組模組 永久連結

此遷移會將使用舊的 @import 規則 載入依賴項的樣式表轉換為使用 Sass 模組系統，透過 @use 規則 載入。它不只是單純地將 @import 改為 @use，而是智慧地更新樣式表，使其保持與以前相同的工作方式，包括：

• 將命名空間添加到來自其他模組的成員（變數、mixin 和函式）的使用。

• 將新的 @use 規則添加到使用成員但未導入它們的樣式表。

• 將覆蓋的預設變數轉換為 with 子句。

• 從其他檔案使用的成員中自動移除 - 和 _ 前綴（因為否則它們將被視為 私有 成員，並且只能在聲明它們的模組中使用）。

• 將 巢狀導入 轉換為使用 meta.load-css() mixin。

$ cat style.scss
$body-bg: #000;
$body-color: #111;

@import "bootstrap";

@include media-breakpoint-up(sm) {
  .navbar {
    display: block;
  }
}
$ sass-migrator --migrate-deps module style.scss
$ cat style.scss
@use "bootstrap" with (
  $body-bg: #000,
  $body-color: #111
);

@include bootstrap.media-breakpoint-up(sm) {
  .navbar {
    display: block;
  }
}

載入依賴項載入依賴項 永久連結

即使未傳遞 --migrate-deps 選項，模組遷移器也需要能夠讀取正在遷移的樣式表所依賴的所有樣式表。如果遷移器找不到依賴項，您將會收到錯誤訊息。

$ ls .
style.scss  node_modules
$ sass-migrator module style.scss
Error: Could not find Sass file at 'dependency'.
  ,
1 | @import "dependency";
  |         ^^^^^^^^^^^^
  '
  style.scss 1:9  root stylesheet
Migration failed!
$ sass-migrator --load-path node_modules module style.scss

如果您在編譯樣式表時使用 載入路徑，請確保使用 --load-path 選項 將其傳遞給遷移器。

遺憾的是，遷移器不支援自訂導入器，但它確實具有內建支援，可透過在 node_modules 中搜尋來解析以 ~ 開頭的 URL，類似於 Webpack 支援的功能。

--remove-prefix–remove-prefix 永久連結

此選項（縮寫為 -p）會在遷移變數、mixin 和函式名稱時，從其開頭移除一個識別碼前綴。不以此前綴開頭的成員將保持不變。

@import 規則 會將所有頂層成員置於一個全域作用域中，因此當它是載入樣式表的標準方法時，每個人都被鼓勵在所有成員名稱前加上前綴，以避免意外地重新定義其他樣式表的成員。模組系統解決了這個問題，因此在這些舊前綴不再必要的情況下，自動去除它們是很有用的。

$ cat style.scss
@import "theme";

@mixin app-inverted {
  color: $app-bg-color;
  background-color: $app-color;
}
$ sass-migrator --migrate-deps module --remove-prefix=app- style.scss
$ cat style.scss
@import "theme";

@mixin inverted {
  color: theme.$bg-color;
  background-color: theme.$color;
}

當您傳遞此選項時，遷移工具還會產生一個 僅匯入樣式表，它會 轉發 所有加上前綴的成員，以保留向下相容性，方便過去匯入該函式庫的使用者。

此選項可以傳遞多次，或以逗號分隔多個值。每個前綴都將從任何具有該前綴的成員中移除。如果一個成員符合多個前綴，則會移除最長相符的前綴。

--forward–forward 永久連結

此選項告訴遷移工具要使用 @forward 規則 轉發哪些成員。它支援以下設定：

• none（預設值）不轉發任何成員。

• all 轉發所有成員，除了在原始樣式表中以 - 或 _ 開頭的成員，因為在引入模組系統之前，這通常用於標記套件私有成員。

• prefixed 僅轉發以傳遞給 --remove-prefix 選項 的前綴開頭的成員。此選項只能與 --remove-prefix 選項一起使用。

所有在命令列上明確傳遞的檔案都會轉發使用 @import 規則由這些檔案遞移載入的成員。使用 --migrate-deps 選項 載入的檔案不會轉發任何新成員。此選項在遷移 Sass 函式庫時特別有用，因為它確保該函式庫的使用者仍然可以存取它定義的所有成員。

$ cat _index.scss
@import "theme";
@import "typography";
@import "components";
$ sass-migrator --migrate-deps module --forward=all style.scss
$ cat _index.scss
@forward "theme";
@forward "typography";
@forward "components";

命名空間命名空間 永久連結

此遷移允許您輕鬆更改樣式表中 @use 規則的 命名空間。如果模組遷移工具為解決衝突而產生的命名空間並不理想，或者您不想使用 Sass 根據規則的 URL 確定的預設命名空間，則此功能很有用。

--rename–rename 永久連結

您可以透過將表達式傳遞給 --rename 選項來告訴遷移工具您想要更改的命名空間。

這些表達式的格式為 <舊命名空間> to <新命名空間> 或 url <規則 URL> to <新命名空間>。在這些表達式中，<舊命名空間> 和 <規則 URL> 是 正規表達式，它們分別與現有命名空間的整體或 @use 規則的 URL 進行匹配。

對於簡單的用例，這看起來就像 --rename 'old to new'，它會將命名空間為 old 的 @use 規則重新命名為 new。

但是，您也可以使用它來完成更複雜的重新命名。例如，假設您以前有一個如下所示的樣式表：

@import 'components/button/lib/mixins';
@import 'components/input/lib/mixins';
@import 'components/table/lib/mixins';
// ...

由於所有這些 URL 在遷移到 @use 規則時都會具有預設命名空間 mixins，因此模組遷移工具最終可能會產生如下內容：

@use 'components/button/lib/mixins' as button-lib-mixins;
@use 'components/input/lib/mixins' as input-lib-mixins;
@use 'components/table/lib/mixins' as table-lib-mixins;
// ...

由於命名空間沒有衝突，所以這是有效的程式碼，但它們比需要的複雜得多。URL 的相關部分是組件名稱，因此我們可以使用命名空間遷移器來提取該部分。

如果我們使用 --rename 'url components/(\w+)/lib/mixins to \1' 執行命名空間遷移器，我們最終會得到

@use 'components/button/lib/mixins' as button;
@use 'components/input/lib/mixins' as input;
@use 'components/table/lib/mixins' as table;
// ...

這裡的重新命名指令碼表示要查找所有 URL 看起來像 components/(\w+)/lib/mixins 的 @use 規則（正規表達式中的 \w+ 表示匹配任何一個或多個字元的單字）。輸出子句中的 \1 表示替換正規表達式中第一組括號的內容（稱為群組）。

如果您希望應用多個重新命名，您可以多次傳遞 --rename 選項，或用分號或換行符分隔它們。只會使用適用於給定規則的第一個重新命名，因此您可以傳遞類似 --rename 'a to b; b to a' 的內容來交換命名空間 a 和 b。

--force–force 永久連結

預設情況下，如果兩個或多個 @use 規則在遷移後具有相同的命名空間，則遷移器將失敗，並且不會進行任何更改。

在這種情況下，您通常需要調整 --rename 指令碼以避免產生衝突，但如果您更希望強制遷移，則可以改為傳遞 --force。

使用 --force 時，如果遇到任何衝突，第一個 @use 規則將獲得其首選命名空間，而後續具有相同首選命名空間的 @use 規則將在其後添加數字後綴。