迁移器

用法用法 permalink

¥Usage

要使用 Sass 迁移器，请告诉 哪个迁移 你要运行以及要迁移哪些 Sass 文件：

¥To use the Sass migrator, tell it which migration you want to run and what Sass files you want to migrate:

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

默认情况下，迁移器只会更改你在命令行上显式传递的文件。传递 --migrate-deps 选项 会告诉迁移器还更改使用 @use 规则、@forward 规则 或 @import 规则 加载的所有样式表。如果你想进行测试运行以查看将进行哪些更改而不实际保存它们，则可以通过 --dry-run --verbose（或简称 -nv）。

¥By default, the migrator will only change files that you explicitly pass on the command line. Passing the --migrate-deps option tells the migrator to also change all the stylesheets that are loaded using the @use rule, @forward rule, or @import rule. And if you want to do a test run to see what changes will be made without actually saving them, you can pass --dry-run --verbose (or -nv for short).

$ 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;
  }
}

安装安装 permalink

¥Installation

你可以从大多数与安装 Dart Sass 相同的位置安装 Sass 迁移器：

¥You can install the Sass migrator from most of the same places that you can install Dart Sass:

独立式独立式 permalink

¥Standalone

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

¥You can install the Sass migrator on Windows, Mac, or Linux by downloading the package for your operating system from GitHub and [adding it to your `PATH`][adding it to your `PATH`].

npmnpm permalink

如果你使用 Node.js，你还可以通过运行以下命令使用 npm 安装 Sass 迁移器

¥If you use Node.js, you can also install the Sass migrator using npm by running

npm install -g sass-migrator

ChocolateyChocolatey permalink

如果你使用用于 Windows 的 Chocolatey 包管理器，则可以通过运行来安装 Sass 迁移器

¥If you use the Chocolatey package manager for Windows, you can install the Sass migrator by running

choco install sass-migrator

HomebrewHomebrew permalink

如果你使用 Homebrew 包管理器 for Mac OS X，则可以通过运行安装 Dart Sass

¥If you use the Homebrew package manager for Mac OS X, you can install Dart Sass by running

brew install sass/sass/migrator

全局选项全局选项 permalink

¥Global Options

这些选项可供所有迁移器使用。

¥These options are available for all migrators.

--migrate-deps–migrate-deps permalink

此选项（缩写为 -d）告诉迁移器不仅要更改在命令行上显式传递的样式表，还要更改它们依赖于使用 @use 规则、@forward 规则 或 @import 规则 的任何样式表。

¥This option (abbreviated -d) tells the migrator to change not just the stylesheets that are explicitly passed on the command line, but also any stylesheets that they depend on using the @use rule, @forward rule, or @import rule.

$ 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）告诉迁移器 加载路径 应在何处查找样式表。它可以被多次传递以提供多个加载路径。较早的加载路径将优先于较晚的加载路径。

¥This option (abbreviated -I) tells the migrator a load path where it should look for stylesheets. It can be passed multiple times to provide multiple load paths. Earlier load paths will take precedence over later ones.

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

¥Dependencies loaded from load paths are assumed to be third-party libraries, so the migrator will not migrate them even when the --migrate-deps option is passed.

--dry-run–dry-run permalink

该标志（缩写为 -n）告诉迁移器不要将任何更改保存到磁盘。相反，它会打印可能已更改的文件列表。它通常与 --verbose 选项 配合使用，以打印已进行的更改的内容。

¥This flag (abbreviated -n) tells the migrator not to save any changes to disk. It instead prints the list of files that it would have changed. This is commonly paired with the --verbose option to print the contents of the changes that would have been made as well.

$ 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 输出。

¥This flag tells the Sass migrator only to emit ASCII characters to the terminal as part of error messages. By default, or if --unicode is passed, the migrator will emit non-ASCII characters for these messages. This flag does not affect the CSS output.

$ 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 选项 结合使用时，它还会打印这些文件的新内容。

¥This flag (abbreviated -v) tells the migrator to print extra information to the console. By default, it just prints the name of files that are changed, but when combined with the --dry-run option it also prints those files’ new contents.

$ 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

迁移迁移 permalink

¥Migrations

颜色颜色 permalink

¥Color

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

¥This migration converts legacy color functions to the new color-space-compatible functions.

分配分配 permalink

¥Division

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

¥This migration converts stylesheets that use / as division to use the built-in math.div function instead.

--pessimistic–pessimistic permalink

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

¥By default, the migrator converts / operations to math.div even when it isn’t sure that it will be division when evaluated. It only leaves them as-is when it can statically determine that they’re doing something else (such as when there’s no SassScript involved, or when one of the operands is a string). The math.div function currently functions identically to the / operator, so this is safe to do, but may result in new warnings if one of the arguments to math.div at runtime is not a number.

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

¥If you want to avoid this behavior, you can pass the --pessimistic flag. With this flag, the migrator will only convert / operations that it knows for sure are doing division. This will prevent any unnecessary math.div conversions, but it’s likely to leave some division unmigrated if it can’t be statically determined.

模块模块 permalink

¥Module

此迁移转换使用旧 @import 规则 加载依赖的样式表，以便它们通过 @use 规则 使用 Sass 模块系统。它不仅仅天真地将 @import 更改为 @use，它还智能地更新样式表，以便它们继续像以前一样工作，包括：

¥This migration converts stylesheets that use the old @import rule to load dependencies so that they use the Sass module system via the @use rule instead. It doesn’t just naïvely change @imports to @uses—it updates stylesheets intelligently so that they keep working the same way they did before, including:

• 将命名空间添加到其他模块的成员（变量、混合和函数）的使用中。

  ¥Adding namespaces to uses of members (variables, mixins, and functions) from other modules.

• 将新的 @use 规则添加到使用成员的样式表而不导入它们。

  ¥Adding new @use rules to stylesheets that were using members without importing them.

• 将覆盖的默认变量转换为 with 条款。

  ¥Converting overridden default variables to with clauses.

• 自动从其他文件使用的成员中删除 - 和 _ 前缀（因为否则它们将被视为 私有的 并且只能在它们声明的模块中使用）。

  ¥Automatically removing - and _ prefixes from members that are used from other files (because otherwise they’d be considered private and could only be used in the module they’re declared).

• 将 嵌套导入 转换为使用 meta.load-css() 混入。

  ¥Converting nested imports to use the meta.load-css() mixin instead.

$ 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;
  }
}

加载依赖加载依赖 permalink

¥Loading Dependencies

模块迁移器需要能够读取其所迁移的样式表所依赖的所有样式表，即使 --migrate-deps 选项 未通过。如果迁移器无法找到依赖，你将收到错误消息。

¥The module migrator needs to be able to read all of the stylesheets depended on by the ones it’s migrating, even if the --migrate-deps option is not passed. If the migrator fails to find a dependency, you’ll get an error.

$ 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 选项 将其传递给迁移器。

¥If you use a load path when compiling your stylesheets, make sure to pass that to the migrator using the --load-path option.

不幸的是，迁移器不支持自定义导入器，但它确实支持通过在 node_modules 中搜索来解析以 ~ 开头的 URL，类似于 Webpack 支持什么。

¥Unfortunately, the migrator does not support custom importers, but it does have built-in support for resolving URLs starting with ~ by searching in node_modules, similar to what Webpack supports.

--remove-prefix–remove-prefix permalink

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

¥This option (abbreviated -p) takes an identifier prefix to remove from the beginning of all variable, mixin, and function names when they’re migrated. Members that don’t start with this prefix will remain unchanged.

@import 规则 将所有顶层成员放在一个全局作用域内，因此当它成为加载样式表的标准方法时，每个人都被激励为所有成员名称添加前缀，以避免意外地重新定义其他一些样式表。模块系统解决了这个问题，因此自动删除那些不必要的旧前缀非常有用。

¥The @import rule put all top-level members in one global scope, so when it was the standard way of loading stylesheets, everyone was incentivized to add prefixes to all their member names to avoid accidentally redefining some other stylesheet’s. The module system solves this problem, so it’s useful to automatically strip those old prefixes now that they’re unnecessary.

$ 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;
}

当你传递此选项时，迁移器还将生成一个 仅导入样式表，其中 前锋 所有带有添加回来的前缀的成员，以保留导入库的用户的向后兼容性。

¥When you pass this option, the migrator will also generate an import-only stylesheet that forwards all the members with the prefix added back, to preserve backwards-compatibility for users who were importing the library.

此选项可以多次传递，或者使用逗号分隔的多个值。每个前缀都将从拥有该前缀的任何成员中删除。如果一个成员匹配多个前缀，则最长的匹配前缀将被删除。

¥This option may be passed multiple times, or with multiple values separated by commas. Each prefix will be removed from any members that have it. If a member matches multiple prefixes, the longest matching prefix will be removed.

--forward–forward permalink

此选项告诉迁移器使用 @forward 规则 转发哪些成员。它支持以下设置：

¥This option tells the migrator which members to forward using the @forward rule. It supports the following settings:

• none（默认）不转发任何成员。

  ¥none (the default) doesn’t forward any members.

• all 转发除原始样式表中以 - 或 _ 开头的成员之外的所有成员，因为在引入模块系统之前，这通常用于标记包私有成员。

  ¥all forwards all members except those that started with - or _ in the original stylesheet, since that was commonly used to mark a package-private member before the module system was introduced.

• prefixed 仅转发以传递给 --remove-prefix 选项 的前缀开头的成员。该选项只能与 --remove-prefix 选项结合使用。

  ¥prefixed forwards only members that begin with the prefix passed to the --remove-prefix option. This option may only be used in conjunction with the --remove-prefix option.

在命令行上显式传递的所有文件都将转发由这些文件使用 @import 规则传递加载的成员。使用 --migrate-deps 选项 加载的文件不会转发任何新成员。此选项在迁移 Sass 库时特别有用，因为它确保该库的用户仍然能够访问它定义的所有成员。

¥All files that are passed explicitly on the command line will forward members that are transitively loaded by those files using the @import rule. Files loaded using the --migrate-deps option will not forward any new members. This option is particularly useful when migrating a Sass library, because it ensures that users of that library will still be able to access all the members it defines.

$ 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";

命名空间命名空间 permalink

¥Namespace

通过此迁移，你可以轻松更改样式表中 @use 规则的 命名空间。如果模块迁移器生成的用于解决冲突的命名空间不理想，或者你不想使用 Sass 根据规则的 URL 确定的默认命名空间，这非常有用。

¥This migration allows you to easily change the namespaces of the @use rules in a stylesheet. This is useful if the namespaces that the module migrator generates to resolve conflicts are non-ideal, or if you don’t want to use the default namespace that Sass determines based on the rule’s URL.

--rename–rename permalink

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

¥You can tell the migrator which namespace(s) you want it to change by passing expressions to the --rename option.

这些表达式的形式为 <old-namespace> to <new-namespace> 或 url <rule-url> to <new-namespace>。在这些表达式中，<old-namespace> 和 <rule-url> 是 常用表达，分别与整个现有命名空间或 @use 规则的 URL 匹配。

¥These expressions are of the form <old-namespace> to <new-namespace> or url <rule-url> to <new-namespace>. In these expressions, <old-namespace> and <rule-url> are regular expressions which match against the entirety of the existing namespace or the @use rule’s URL, respectively.

对于简单的用例，这看起来就像 --rename 'old to new'，它将使用命名空间 old 的 @use 规则重命名为 new。

¥For simple use cases, this just looks like --rename 'old to new', which would rename a @use rule with the namespace old to instead be new.

但是，你也可以执行此操作来完成更复杂的重命名。例如，假设你以前有一个如下所示的样式表：

¥However, you can also do this to accomplish more complicated renames. For instance, say that you previously had a stylesheet that looked like this:

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

由于所有这些 URL 在迁移到 @use 规则时都将具有默认名称空间 mixins，因此模块迁移器最终可能会生成如下内容：

¥Since all of these URLs would have the default namespace mixins when migrated to @use rules, the module migrator may end up generating something like this:

@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 的相关部分是组件名称，因此我们可以使用命名空间迁移器来提取该部分。

¥This is valid code since the namespaces don’t conflict, but they’re way more complicated than they need to be. The relevant part of the URL is the component name, so we can use the namespace migrator to extract that part out.

如果我们使用 --rename 'url components/(\w+)/lib/mixins to \1' 运行命名空间迁移器，我们最终会得到：

¥If we run the namespace migrator with --rename 'url components/(\w+)/lib/mixins to \1', we’ll end up with:

@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 表示替换正则表达式中第一组括号的内容（称为 群组）。

¥The rename script here says to find all of the @use rules whose URLs look like components/(\w+)/lib/mixins (\w+ in a regular expression means to match any word of one or more characters). The \1 in the output clause means to substitute in the contents of the first set of parentheses in the regular expression (called a group).

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

¥If you wish to apply multiple renames, you can pass the --rename option multiple times, or separate them with a semicolon or a line break. Only the first rename that applies to a given rule will be used, so you could pass something like --rename 'a to b; b to a' to swap the namespaces a and b.

--force–force permalink

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

¥By default, if two or more @use rules have the same namespace after the migration, the migrator will fail, and no changes will be made.

在这种情况下，你通常需要调整 --rename 脚本以避免产生冲突，但如果你希望强制迁移，则可以传递 --force。

¥In this case, you’ll usually want to adjust your --rename script to avoid creating conflicts, but if you’d prefer to force the migration, you can instead pass --force.

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

¥With --force, if any conflicts are encountered, the first @use rule will get its preferred namespace, while subsequent @use rules with the same preferred namespace will instead have a numerical suffix added to them.