Dart Sass 命令行接口
用法用法 permalink
¥Usage
Dart Sass 可执行文件可以以两种模式之一调用。
¥The Dart Sass executable can be invoked in one of two modes.
一对一模式一对一模式 permalink
¥One-to-One Mode
sass <input.scss> [output.css]
一对一模式将单个输入文件 (input.scss
) 编译到单个输出位置 (output.css
)。如果未传递输出位置,则编译后的 CSS 将打印到终端。
¥One-to-one mode compiles a single input file (input.scss
) to a single output
location (output.css
). If no output location is passed, the compiled CSS is
printed to the terminal.
如果输入文件的扩展名是 .scss
,则解析为 SCSS;如果扩展名是 .sass
,则解析为 缩进语法;如果扩展名是 .css
,则解析为 纯 CSS。如果它没有这三个扩展名之一,或者它来自标准输入,则默认情况下会将其解析为 SCSS。这可以通过 --indented
标志 进行控制。
¥The input file is parsed as SCSS if its extension is .scss
, as the
indented syntax if its extension is .sass
, or as plain CSS if its
extension is .css
. If it doesn’t have one of these three extensions, or if it
comes from standard input, it’s parsed as SCSS by default. This can be
controlled with the --indented
flag.
可以传递特殊字符串 -
来代替输入文件,以告诉 Sass 从 标准输入 读取输入文件。除非传递 --indented
标志,否则 Sass 将默认将其解析为 SCSS。
¥The special string -
can be passed in place of the input file to tell Sass to
read the input file from standard input. Sass will default to parsing it as
SCSS unless the --indented
flag is passed.
多对多模式多对多模式 permalink
¥Many-to-Many Mode
- Dart Sass
- since 1.4.0
sass [<input.scss>:<output.css>] [<input/>:<output/>]...
多对多模式将一个或多个输入文件编译为一个或多个输出文件。输入与输出用冒号分隔。它还可以将一个目录中的所有 Sass 文件编译为另一个目录中同名的 CSS 文件。
¥Many-to-many mode compiles one or more input files to one or more output files. The inputs are separated from the outputs with colons. It can also compile all Sass files in a directory to CSS files with the same names in another directory.
# Compiles style.scss to style.css.
$ sass style.scss:style.css
# Compiles light.scss and dark.scss to light.css and dark.css.
$ sass light.scss:light.css dark.scss:dark.css
# Compiles all Sass files in themes/ to CSS files in public/css/.
$ sass themes:public/css
当编译整个目录时,Sass 将忽略名称以 _
开头的 部分文件。你可以使用部分来分离样式表,而无需创建一堆不必要的输出文件。
¥When compiling whole directories, Sass will ignore partial files whose names
begin with _
. You can use partials to separate out your stylesheets without
creating a bunch of unnecessary output files.
选项选项 permalink
¥Options
输入输出输入输出 permalink
¥Input and Output
这些选项控制 Sass 如何加载其输入文件以及如何生成输出文件。
¥These options control how Sass loads its input files and how it produces output files.
--stdin
–stdin permalink
该标志是告诉 Sass 它应该从 标准输入 读取其输入文件的另一种方式。当它通过时,不能传递任何输入文件。
¥This flag is an alternative way of telling Sass that it should read its input file from standard input. When it’s passed, no input file may be passed.
$ echo "h1 {font-size: 40px}" | sass --stdin h1.css
$ echo "h1 {font-size: 40px}" | sass --stdin
h1 {
font-size: 40px;
}
--stdin
标志不能与 多对多模式 一起使用。
¥The --stdin
flag may not be used with many-to-many mode.
--indented
–indented permalink
该标志告诉 Sass 将输入文件解析为 缩进语法。如果在 多对多模式 中使用它,则所有输入文件都将解析为缩进语法,尽管 使用 中的文件将像往常一样确定其语法。相反,--no-indented
可用于强制将所有输入文件解析为 SCSS。
¥This flag tells Sass to parse the input file as the indented syntax. If it’s
used in many-to-many mode, all input files are parsed as the indented
syntax, although files they use will have their syntax determined as usual.
The inverse, --no-indented
, can be used to force all input files to be parsed
as SCSS instead.
当输入文件来自 标准输入 时,--indented
标志最有用,因此无法自动确定其语法。
¥The --indented
flag is mostly useful when the input file is coming from
standard input, so its syntax can’t be automatically determined.
$ echo -e 'h1\n font-size: 40px' | sass --indented -
h1 {
font-size: 40px;
}
--load-path
–load-path permalink
此选项(缩写为 -I
)为 Sass 添加了一个额外的 加载路径 来查找样式表。它可以被多次传递以提供多个加载路径。较早的加载路径将优先于较晚的加载路径。
¥This option (abbreviated -I
) adds an additional load path for Sass to look
for stylesheets. It can be passed multiple times to provide multiple load paths.
Earlier load paths will take precedence over later ones.
$ sass --load-path=node_modules/bootstrap/dist/css style.scss style.css
--pkg-importer=node
–pkg-importer=node permalink
- Dart Sass
- since 1.71.0
此选项(缩写为 -p node
)将 Node.js pkg:
导入器 添加到加载路径的末尾,以便样式表可以使用 Node.js 模块解析算法加载依赖。
¥This option (abbreviated -p node
) adds the Node.js pkg:
importer to the
end of the load path, so that stylesheets can load dependencies using the
Node.js module resolution algorithm.
将来可能会添加对其他内置 pkg:
导入器的支持。
¥Support for additional built-in pkg:
importers may be added in the future.
$ sass --pkg-importer=node style.scss style.css
--style
–style permalink
此选项(缩写为 -s
)控制生成的 CSS 的输出样式。Dart Sass 支持两种输出样式:
¥This option (abbreviated -s
) controls the output style of the resulting CSS.
Dart Sass supports two output styles:
-
expanded
(默认)将每个选择器和声明写在自己的行上。¥
expanded
(the default) writes each selector and declaration on its own line. -
compressed
删除尽可能多的额外字符,并将整个样式表写在一行上。¥
compressed
removes as many extra characters as possible, and writes the entire stylesheet on a single line.
$ sass --style=expanded style.scss
h1 {
font-size: 40px;
}
$ sass --style=compressed style.scss
h1{font-size:40px}
--no-charset
–no-charset permalink
- Dart Sass
- since 1.19.0
该标志告诉 Sass 永远不要发出 @charset
声明或 UTF-8 字节顺序标记。默认情况下,或者如果传递了 --charset
,如果样式表包含任何非 ASCII 字符,Sass 将插入 @charset
声明(在扩展输出模式下)或字节顺序标记(在压缩输出模式下)。
¥This flag tells Sass never to emit a @charset
declaration or a UTF-8
byte-order mark. By default, or if --charset
is passed, Sass will insert
either a @charset
declaration (in expanded output mode) or a byte-order mark
(in compressed output mode) if the stylesheet contains any non-ASCII characters.
$ echo 'h1::before {content: "👭"}' | sass --no-charset
h1::before {
content: "👭";
}
$ echo 'h1::before {content: "👭"}' | sass --charset
@charset "UTF-8";
h1::before {
content: "👭";
}
--error-css
–error-css permalink
- Dart Sass
- since 1.20.0
该标志告诉 Sass 在编译过程中发生错误时是否发出 CSS 文件。这个 CSS 文件在注释和 body::before
的 content
属性中描述了错误,这样你就可以在浏览器中看到错误消息,而无需切换回终端。
¥This flag tells Sass whether to emit a CSS file when an error occurs during
compilation. This CSS file describes the error in a comment and in the
content
property of body::before
, so that you can see the error message in
the browser without needing to switch back to the terminal.
默认情况下,如果你要编译为磁盘上的至少一个文件(而不是标准输出),则会启用错误 CSS。即使在编译为标准输出时,你也可以显式传递 --error-css
来启用它,或者传递 --no-error-css
来在所有地方禁用它。禁用后,当发生错误时,--update
标志 和 --watch
标志 将删除 CSS 文件。
¥By default, error CSS is enabled if you’re compiling to at least one file on
disk (as opposed to standard output). You can pass --error-css
explicitly to
enable it even when you’re compiling to standard out, or --no-error-css
to
disable it everywhere. When it’s disabled, the --update
flag and
--watch
flag will delete CSS files instead when an error occurs.
$ sass --error-css style.scss style.css
/* Error: Incompatible units em and px.
* ,
* 1 | $width: 15px + 2em;
* | ^^^^^^^^^^
* '
* test.scss 1:9 root stylesheet */
body::before {
font-family: "Source Code Pro", "SF Mono", Monaco, Inconsolata, "Fira Mono",
"Droid Sans Mono", monospace, monospace;
white-space: pre;
display: block;
padding: 1em;
margin-bottom: 1em;
border-bottom: 2px solid black;
content: "Error: Incompatible units em and px.\a \2577 \a 1 \2502 $width: 15px + 2em;\a \2502 ^^^^^^^^^^\a \2575 \a test.scss 1:9 root stylesheet";
}
Error: Incompatible units em and px.
╷
1 │ $width: 15px + 2em;
│ ^^^^^^^^^^
╵
test.scss 1:9 root stylesheet
--update
–update permalink
- Dart Sass
- since 1.4.0
如果传递了 --update
标志,Sass 将仅编译其依赖修改时间晚于生成相应 CSS 文件的样式表。更新样式表时它还会打印状态消息。
¥If the --update
flag is passed, Sass will only compile stylesheets whose
dependencies have been modified more recently than the corresponding CSS file
was generated. It will also print status messages when updating stylesheets.
$ sass --update themes:public/css
Compiled themes/light.scss to public/css/light.css.
源映射源映射 permalink
¥Source Maps
- Dart Sass
- since 1.3.0
Source maps are files that tell browsers or other tools that consume CSS how that CSS corresponds to the Sass files from which it was generated. They make it possible to see and even edit your Sass files in browsers. See instructions for using source maps in Chrome and Firefox.
Dart Sass 默认为其发出的每个 CSS 文件生成源映射。
¥Dart Sass generates source maps by default for every CSS file it emits.
--no-source-map
–no-source-map permalink
如果传递了 --no-source-map
标志,Sass 将不会生成任何源映射。它不能与其他源映射选项一起传递。
¥If the --no-source-map
flag is passed, Sass won’t generate any source maps. it
cannot be passed along with other source map options.
$ sass --no-source-map style.scss style.css
--source-map-urls
–source-map-urls permalink
此选项控制 Sass 生成的源映射如何链接回有助于生成 CSS 的 Sass 文件。Dart Sass 支持两种类型的 URL:
¥This option controls how the source maps that Sass generates link back to the Sass files that contributed to the generated CSS. Dart Sass supports two types of URLs:
-
relative
(默认值)使用从源映射文件位置到 Sass 源文件位置的相对 URL。¥
relative
(the default) uses relative URLs from the location of the source map file to the locations of the Sass source file. -
absolute
使用 Sass 源文件的绝对file:
网址。请注意,绝对 URL 只能在编译 CSS 的同一台计算机上运行。¥
absolute
uses the absolutefile:
URLs of the Sass source files. Note that absolute URLs will only work on the same computer that the CSS was compiled.
# Generates a URL like "../sass/style.scss".
$ sass --source-map-urls=relative sass/style.scss css/style.css
# Generates a URL like "file:///home/style-wiz/sassy-app/sass/style.scss".
$ sass --source-map-urls=absolute sass/style.scss css/style.css
--embed-sources
–embed-sources permalink
此标志告诉 Sass 将有助于生成 CSS 的 Sass 文件的全部内容嵌入到源映射中。这可能会产生非常大的源映射,但它保证源在任何计算机上都可用,无论 CSS 如何提供。
¥This flag tells Sass to embed the entire contents of the Sass files that contributed to the generated CSS in the source map. This may produce very large source maps, but it guarantees that the source will be available on any computer no matter how the CSS is served.
$ sass --embed-sources sass/style.scss css.style.css
--embed-source-map
–embed-source-map permalink
此标志告诉 Sass 将源映射文件的内容嵌入到生成的 CSS 中,而不是创建单独的文件并从 CSS 链接到它。
¥This flag tells Sass to embed the contents of the source map file in the generated CSS, rather than creating a separate file and linking to it from the CSS.
$ sass --embed-source-map sass/style.scss css.style.css
其他选项其他选项 permalink
¥Other Options
--watch
–watch permalink
- Dart Sass
- since 1.6.0
此标志(缩写为 -w
)的作用类似于 --update
标志,但在第一轮编译完成后,Sass 保持打开状态,并在样式表或其依赖发生变化时继续编译样式表。
¥This flag (abbreviated -w
) acts like the --update
flag, but after the
first round compilation is done Sass stays open and continues compiling
stylesheets whenever they or their dependencies change.
Sass 仅监视你在命令行上按原样传递的目录、你在命令行上传递的文件名的父目录以及加载路径。它不会根据文件的 @import
/@use
/@forward
规则监视其他目录。
¥Sass watches only the directories that you pass as-is on the command line,
parent directories of filenames you pass on the command line, and load paths. It
does not watch additional directories based on a file’s @import
/@use
/
@forward
rules.
$ sass --watch themes:public/css
Compiled themes/light.scss to public/css/light.css.
# Then when you edit themes/dark.scss...
Compiled themes/dark.scss to public/css/dark.css.
--poll
–poll permalink
- Dart Sass
- since 1.8.0
该标志只能与 --watch
一起传递,告诉 Sass 经常手动检查源文件的更改,而不是依赖操作系统在发生更改时通知它。如果你在远程驱动器上编辑 Sass,而操作系统的通知系统无法正常工作,则这可能是必要的。
¥This flag, which may only be passed along with --watch
, tells Sass to manually
check for changes to the source files every so often instead of relying on the
operating system to notify it when something changes. This may be necessary if
you’re editing Sass on a remote drive where the operating system’s notification
system doesn’t work.
$ sass --watch --poll themes:public/css
Compiled themes/light.scss to public/css/light.css.
# Then when you edit themes/dark.scss...
Compiled themes/dark.scss to public/css/dark.css.
--stop-on-error
–stop-on-error permalink
- Dart Sass
- since 1.8.0
该标志告诉 Sass 在检测到错误时立即停止编译,而不是尝试编译其他可能不包含错误的 Sass 文件。它在 多对多模式 中最有用。
¥This flag tells Sass to stop compiling immediately when an error is detected, rather than trying to compile other Sass files that may not contain errors. It’s mostly useful in many-to-many mode.
$ sass --stop-on-error themes:public/css
Error: Expected expression.
╷
42 │ h1 {font-face: }
│ ^
╵
themes/light.scss 42:16 root stylesheet
--interactive
–interactive permalink
- Dart Sass
- since 1.5.0
该标志(缩写为 -i
)告诉 Sass 以交互模式运行,你可以在其中编写 SassScript 表达式 并查看其结果。交互模式还支持 变量 和 @use
规则。
¥This flag (abbreviated -i
) tells Sass to run in interactive mode, where you
can write SassScript expressions and see their results. Interactive mode
also supports variables and @use
rules.
$ sass --interactive
>> 1px + 1in
97px
>> @use "sass:map"
>> $map: ("width": 100px, "height": 70px)
("width": 100px, "height": 70px)
>> map.get($map, "width")
100px
--color
–color permalink
该标志(缩写为 -c
)告诉 Sass 发出 终端颜色,相反的 --no-color
告诉它不发出颜色。默认情况下,如果它看起来像是在支持颜色的终端上运行,它将发出颜色。
¥This flag (abbreviated -c
) tells Sass to emit terminal colors, and the
inverse --no-color
tells it not to emit colors. By default, it will emit
colors if it looks like it’s being run on a terminal that supports them.
$ sass --color style.scss style.css
Error: Incompatible units em and px.
╷
1 │ $width: 15px + 2em
│ ^^^^^^^^^^
╵
style.scss 1:9 root stylesheet
$ sass --no-color style.scss style.css
Error: Incompatible units em and px.
╷
1 │ $width: 15px + 2em
│ ^^^^^^^^^^
╵
style.scss 1:9 root stylesheet
--no-unicode
–no-unicode permalink
- Dart Sass
- since 1.17.0
该标志告诉 Sass 仅将 ASCII 字符作为错误消息的一部分发送到终端。默认情况下,或者如果传递了 --unicode
,Sass 将为这些消息发出非 ASCII 字符。该标志不会影响 CSS 输出。
¥This flag tells Sass only to emit ASCII characters to the terminal as part of
error messages. By default, or if --unicode
is passed, Sass will emit non-ASCII
characters for these messages. This flag does not affect the CSS output.
$ sass --no-unicode style.scss style.css
Error: Incompatible units em and px.
,
1 | $width: 15px + 2em;
| ^^^^^^^^^^
'
test.scss 1:9 root stylesheet
$ sass --unicode style.scss style.css
Error: Incompatible units em and px.
╷
1 │ $width: 15px + 2em;
│ ^^^^^^^^^^
╵
test.scss 1:9 root stylesheet
--verbose
–verbose permalink
此标志告诉 Sass 在编译时发出所有弃用警告。默认情况下,当使用弃用的功能时,Sass 只会针对给定的弃用类型发出五个警告,并且会静音除此以外的任何警告。
¥This flag tells Sass to emit all deprecation warnings when compiling. By default, Sass only emits five warnings for a given deprecation type when deprecated features are used, and silences any warnings beyond that.
$ sass --verbose style.scss style.css
--quiet
–quiet permalink
该标志(缩写为 -q
)告诉 Sass 在编译时不要发出任何警告。默认情况下,当使用已弃用的功能或遇到 @warn
规则 时,Sass 会发出警告。它还会使 @debug
规则 静音。
¥This flag (abbreviated -q
) tells Sass not to emit any warnings when compiling.
By default, Sass emits warnings when deprecated features are used or when the
@warn
rule is encountered. It also silences the @debug
rule.
$ sass --quiet style.scss style.css
--quiet-deps
–quiet-deps permalink
该标志告诉 Sass 不要发出来自依赖的弃用警告。它认为通过 加载路径 传递导入的任何文件都是 "依赖"。该标志不影响 @warn
规则 或 @debug
规则。
¥This flag tells Sass not to emit deprecation warnings that come from
dependencies. It considers any file that’s transitively imported through a load
path to be a "dependency". This flag doesn’t affect the @warn
rule or the
@debug
rule.
$ sass --load-path=node_modules --quiet-deps style.scss style.css
--fatal-deprecation
–fatal-deprecation permalink
- Dart Sass
- since 1.59.0
此选项告诉 Sass 将特定类型的弃用警告视为错误。例如,此命令告诉 Sass 将 /
-as-division 的弃用警告视为错误:
¥This option tells Sass to treat a particular type of deprecation warning as
an error. For example, this command tells Sass to treat deprecation
warnings for /
-as-division as errors:
$ sass --fatal-deprecation=slash-div style.scss style.css
Error: Using / for division outside of calc() is deprecated and will be removed in Dart Sass 2.0.0.
Recommendation: math.div(4, 2) or calc(4 / 2)
More info and automated migrator: /documentation/breaking-changes/slash-div
This is only an error because you've set the slash-div deprecation to be fatal.
Remove this setting if you need to keep using this feature.
╷
1 │ a { b: (4/2); }
│ ^^^
╵
style.scss 1:9 root stylesheet
The following deprecation IDs can be passed to this option:
ID | Deprecated In | Description |
---|---|---|
call-string | 0.0.0 | Passing a string directly to meta.call(). |
elseif | 1.3.2 | @elseif. |
moz-document | 1.7.2 | @-moz-document. |
relative-canonical | 1.14.2 | Imports using relative canonical URLs. |
new-global | 1.17.2 | Declaring new variables with !global. |
color-module-compat | 1.23.0 | Using color module functions in place of plain CSS functions. |
slash-div | 1.33.0 | / operator for division. |
bogus-combinators | 1.54.0 | Leading, trailing, and repeated combinators. |
strict-unary | 1.55.0 | Ambiguous + and - operators. |
function-units | 1.56.0 | Passing invalid units to built-in functions. |
duplicate-var-flags | 1.62.0 | Using !default or !global multiple times for one variable. |
null-alpha | 1.62.3 | Passing null as alpha in the JS API. |
abs-percent | 1.65.0 | Passing percentages to the Sass abs() function. |
fs-importer-cwd | 1.73.0 | Using the current working directory as an implicit load path. |
css-function-mixin | 1.76.0 | Function and mixin names beginning with –. |
mixed-decls | 1.77.7 | Declarations after or between nested rules. |
feature-exists | 1.78.0 | meta.feature-exists |
color-4-api | 1.79.0 | Certain uses of built-in sass:color functions. |
color-functions | 1.79.0 | Using global color functions instead of sass:color. |
legacy-js-api | 1.79.0 | Legacy JS API. |
import | 1.80.0 | @import rules. |
global-builtin | 1.80.0 | Global built-in functions that are available in sass: modules. |
或者,你可以传递 Dart Sass 版本,将该版本中存在的所有弃用视为错误。例如,--fatal-deprecation=1.33.0
会将上表中直到 slash-div
为止的所有弃用视为错误,但将任何较新的弃用视为警告。
¥Alternatively, you can pass a Dart Sass version to treat all deprecations that
were present in that version as errors. For example,
--fatal-deprecation=1.33.0
would treat all deprecations in the
table above up to and including slash-div
as errors, but leave any newer
deprecations as warnings.
--future-deprecation
–future-deprecation permalink
- Dart Sass
- since 1.59.0
此选项告诉 Sass 尽早选择未来类型的弃用警告,即使弃用尚未激活也会发出警告。此选项可以与 --fatal-deprecation
结合使用,以触发错误而不是警告,以防将来弃用。
¥This option tells Sass to opt-in to a future type of deprecation warning
early, emitting warnings even though the deprecation is not yet active. This
option can be combined with --fatal-deprecation
to emit errors instead of
warnings for a future deprecation.
$ sass --future-deprecation=import style.scss style.css
Deprecation Warning on line 1, column 9 of style.scss:
Sass @import rules will be deprecated in the future.
Remove the --future-deprecation=import flag to silence this warning for now.
╷
1 │ @import 'dependency';
│ ^^^^^^^^^^^^
╵
There are no future deprecations in the latest version of Dart Sass.
--silence-deprecation
–silence-deprecation permalink
- Dart Sass
- since 1.74.0
如果你希望暂时忽略弃用,此选项会告诉 Sass 静音特定类型的弃用警告。上面 --fatal-deprecation
部分列出的任何弃用都可以在此处传递,但不支持传递版本。
¥This option tells Sass to silence a particular type of deprecation warning if
you wish to temporarily ignore the deprecation. Any of the deprecations listed
in the --fatal-deprecation
section above can be passed here, though passing
in a version is not supported.
$ sass --silence-deprecation=slash-div style.scss style.css
--trace
–trace permalink
该标志告诉 Sass 在遇到错误时打印完整的 Dart 或 JavaScript 堆栈跟踪。Sass 团队使用它来调试错误。
¥This flag tells Sass to print the full Dart or JavaScript stack trace when an error is encountered. It’s used by the Sass team for debugging errors.
$ sass --trace style.scss style.css
Error: Expected expression.
╷
42 │ h1 {font-face: }
│ ^
╵
themes/light.scss 42:16 root stylesheet
package:sass/src/visitor/evaluate.dart 1846:7 _EvaluateVisitor._addExceptionSpan
package:sass/src/visitor/evaluate.dart 1128:12 _EvaluateVisitor.visitBinaryOperationExpression
package:sass/src/ast/sass/expression/binary_operation.dart 39:15 BinaryOperationExpression.accept
package:sass/src/visitor/evaluate.dart 1097:25 _EvaluateVisitor.visitVariableDeclaration
package:sass/src/ast/sass/statement/variable_declaration.dart 50:15 VariableDeclaration.accept
package:sass/src/visitor/evaluate.dart 335:13 _EvaluateVisitor.visitStylesheet
package:sass/src/visitor/evaluate.dart 323:5 _EvaluateVisitor.run
package:sass/src/visitor/evaluate.dart 81:10 evaluate
package:sass/src/executable/compile_stylesheet.dart 59:9 compileStylesheet
package:sass/src/executable.dart 62:15 main
--help
–help permalink
该标志(缩写为 -h
)打印本文档的摘要。
¥This flag (abbreviated -h
) prints a summary of this documentation.
$ sass --help
Compile Sass to CSS.
Usage: sass <input.scss> [output.css]
sass <input.scss>:<output.css> <input/>:<output/>
...
--version
–version permalink
该标志打印 Sass 的当前版本。
¥This flag prints the current version of Sass.
$ sass --version