迁移器

用法Usage permalink

要使用 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;
  }
}

安装Installation permalink

您可以从大多数安装 Dart Sass 的地方安装 Sass 迁移器。

独立Standalone permalink

您可以通过从GitHub 下载适用于您操作系统的软件包，并将其添加到您的 PATH 中，在 Windows、Mac 或 Linux 上安装 Sass 迁移器。

npmnpm permalink

如果您使用 Node.js，您也可以使用npm 安装 Sass 迁移器，方法是 运行

npm install -g sass-migrator

ChocolateyChocolatey permalink

如果您使用 适用于 Windows 的 Chocolatey 包管理器，您可以通过 运行以下命令来安装 Sass 迁移器。

choco install sass-migrator

HomebrewHomebrew permalink

如果您使用 适用于 Mac OS X 的 Homebrew 包管理器，您可以通过 运行以下命令来安装 Dart Sass。

brew install sass/sass/migrator

全局选项Global Options permalink

这些选项适用于所有 迁移器。

--migrate-deps–migrate-deps permalink

此选项（简写为 -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 permalink

此选项（简写为 -I）告诉迁移器一个加载路径，迁移器应该在那里查找样式表。它可以多次传递以提供多个加载路径。较早的加载路径优先于较后的 加载路径。

从加载路径加载的依赖项被认为是第三方库，因此即使传递了--migrate-deps 选项，迁移器也不会迁移它们。

--dry-run–dry-run permalink

此标志（简写为 -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 permalink

此标志告诉 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 permalink

此标志（简写为 -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

迁移Migrations permalink

颜色Color permalink

此迁移将旧版颜色函数转换为新的与颜色空间兼容的 函数。

除法Division permalink

此迁移将使用/ 作为除法 的样式表转换为使用内置的 math.div 函数。

--pessimistic–pessimistic permalink

默认情况下，即使迁移器不确定在评估时是否会进行除法，它也会将 / 操作转换为 math.div。它只在可以静态确定它们正在执行其他操作时（例如，当没有 SassScript 参与时，或者其中一个操作数是字符串时），才将它们保留为原样。math.div 函数目前与 / 运算符的功能相同，因此这样做是安全的，但如果 math.div 在运行时的某个参数不是 数字，可能会导致新的警告。

如果您想避免这种行为，可以传递 --pessimistic 标志。使用此标志，迁移器只会转换它确切知道正在执行除法的 / 操作。这将防止任何不必要的 math.div 转换，但如果无法静态确定，它可能会留下一些未迁移的除法。

模块Module permalink

此迁移将使用旧版@import 规则 加载依赖项的样式表转换为使用@use 规则 加载依赖项，以便使用 Sass 模块系统。它不仅仅是将 @import 转换为 @use，它会智能地更新样式表，使它们保持与以前相同的工作方式， 包括

• 向来自其他 模块的成员（变量、Mixins 和函数）的使用添加命名空间。

• 向在没有导入 它们的情况下使用成员的样式表添加新的 @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;
  }
}

加载依赖项Loading Dependencies permalink

模块迁移器需要能够读取它正在迁移的样式表所依赖的所有样式表，即使没有传递--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 选项 将其传递给迁移器。

不幸的是，迁移器不支持自定义导入器，但它确实内置了对解析以 ~ 开头的 URL 的支持，方法是在 node_modules 中搜索，类似于 Webpack 支持的方式。

--remove-prefix–remove-prefix permalink

此选项（缩写为-p）接受一个标识符前缀，用于在迁移时从所有变量、mixin 和函数名的开头删除。不以该前缀开头的成员将保持 不变。

The @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 permalink

此选项告诉迁移器哪些成员使用@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";

命名空间Namespace permalink

此迁移允许您轻松更改样式表中@use 规则的命名空间。这在模块迁移器为解决冲突而生成的命名空间不理想的情况下，或者您不想使用 Sass 根据规则的 URL 确定的默认命名空间时很有用。

--rename–rename permalink

您可以通过将表达式传递给--rename 选项来告诉迁移器您希望它更改哪些命名空间。

这些表达式采用<old-namespace> to <new-namespace> 或url <rule-url> to <new-namespace> 的形式。在这些表达式中，<old-namespace> 和<rule-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';
// ...

由于迁移到@use 规则后，所有这些 URL 的默认命名空间都将为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（正则表达式中的\w+ 表示匹配一个或多个字符的任何单词）的@use 规则。输出子句中的\1 表示用正则表达式中第一组括号（称为组）的内容替换。

如果您希望应用多个重命名，您可以多次传递--rename 选项，或者用分号或换行符将它们隔开。只使用第一个应用于给定规则的重命名，因此您可以传递类似--rename 'a to b; b to a' 的内容来交换命名空间a 和b。

--force–force permalink

默认情况下，如果迁移后两个或多个@use 规则具有相同的命名空间，迁移器将失败，并且不会进行任何更改 。

在这种情况下，您通常需要调整您的--rename 脚本以避免创建冲突，但如果您更愿意强制迁移，则可以改为传递--force。

使用--force，如果遇到任何冲突，第一个@use 规则将获得其首选命名空间，而后续具有相同首选命名空间的@use 规则将改为添加数字后缀 。