重大变化：旧版 JS API

迁移用法迁移用法 permalink

¥Migrating Usage

入口点入口点 permalink

¥Entrypoints

旧版 JS API 有两个用于编译 Sass 的入口点：render 和 renderSync 接受一个选项对象，该对象包含 file（用于编译文件）或 data（用于编译字符串）。现代 API 有四个：compile 和 compileAsync 用于编译文件，compileString 和 compileStringAsync 用于编译字符串。这些函数将路径或源字符串作为其第一个参数，然后将所有其他选项的对象作为其第二个参数。与使用回调的 render 不同，compileAsync 和 compileStringAsync 返回 promise。

¥The legacy JS API had two entrypoints for compiling Sass: render and renderSync, which took in an options object that included either file (to compile a file) or data (to compile a string). The modern API has four: compile and compileAsync for compiling a file and compileString and compileStringAsync for compiling a string. These functions take a path or source string as their first argument and then an object of all other options as their second argument. Unlike render, which used a callback, compileAsync and compileStringAsync return a promise instead.

有关详细信息，请参阅 使用文档。

¥See the usage documentation for more details.

导入器导入器 permalink

¥Importers

旧版 API 中的导入器由一个函数组成，该函数接受依赖规则 URL 和包含样式表的 URL（以及异步导入器的 done 回调），并返回一个对象，该对象具有磁盘上的 file 路径或要加载的样式表的 contents。

¥Importers in the legacy API consisted of a single function that took in the dependency rule URL and the URL of the containing stylesheet (as well as a done callback for asynchronous importers) and return an object with either a file path on disk or the contents of the stylesheet to be loaded.

现代 API Importer 反而包含两种方法：canonicalize，它接受规则 URL 并返回该 URL 的规范形式；和 load，它接受规范 URL 并返回包含已加载样式表内容的对象。此拆分确保同一模块仅加载一次，并且相对 URL 一致工作。异步导入器这两种方法都返回 promise。

¥Modern API Importers instead contain two methods: canonicalize, which takes in a rule URL and returns the canonical form of that URL; and load, which takes in a canonical URL and returns an object with the contents of the loaded stylesheet. This split ensures that the same module is only loaded once and that relative URLs work consistently. Asynchronous importers have both of these methods return promises.

还有一个特殊的 FileImporter，它将所有加载重定向到磁盘上的现有文件，当从返回 file 而不是 contents 的旧版导入器迁移时应该使用它。

¥There’s also a special FileImporter that redirects all loads to existing files on disk, which should be used when migrating from legacy importers that returned a file instead of contents.

自定义函数自定义函数 permalink

¥Custom Functions

在旧版 JS API 中，自定义函数为每个 Sass 参数采用单独的 JS 参数，并为异步自定义函数提供额外的 done 回调。在现代 API 中，自定义函数改为采用包含所有 Sass 参数列表的单个 JS 参数，异步自定义函数返回一个 promise。

¥In the legacy JS API, custom functions took a separate JS argument for each Sass argument, with an additional done callback for asynchronous custom functions. In the modern API, custom functions instead take a single JS argument that contains a list of all Sass arguments, with asynchronous custom functions returning a promise.

现代 API 还使用更强大的 Value 类，该类支持所有 Sass 值类型、类型断言以及简单的映射和列表查找。

¥The modern API also uses a much more robust Value class that supports all Sass value stypes, type assertions, and easy map and list lookups.

打包器打包器 permalink

¥Bundlers

如果你使用的是调用 Sass API 而不是直接使用它的打包器或其他工具，则可能需要更改传递给该工具的配置以告诉它使用现代 API。

¥If you’re using a bundler or other tool that calls the Sass API rather than using it directly, you may need to change the configuration you pass to that tool to tell it to use the modern API.

Webpack 应该已经默认使用现代 API，但如果你收到警告，请将 api 设置为 "modern" 或 "modern-compiler"。详细信息请参见 Webpack 的文档。

¥Webpack should already use the modern API by default, but if you’re getting warnings, set api to "modern" or "modern-compiler". See Webpack’s documentation for more details.

Vite 6 默认使用现代 API。Vite 的早期版本仍然使用旧版 API，但是从 Vite 5.4 开始，你可以通过将 api 设置为 "modern" 或 "modern-compiler" 来切换它。详细信息请参见 Vite 的文档。

¥Vite 6 uses the modern API by default. Previous versions of Vite still use the legacy API, however from Vite 5.4 you can switch it by setting api to "modern" or "modern-compiler". See Vite’s documentation for more details.

对于其他工具，请查看其文档或问题跟踪器以获取有关支持现代 Sass API 的信息。

¥For other tools, check their documentation or issue tracker for information about supporting the modern Sass API.

静音警告静音警告 permalink

¥Silencing Warnings

虽然旧版 JS API 在 Dart Sass 1.45.0 中与现代 API 的发布一起被标记为弃用，但我们从 Dart Sass 1.79.0 开始发出使用它的警告。如果你还无法迁移到现代 API，但希望暂时消除警告，则可以在 silenceDeprecations 选项中传递 legacy-js-api：

¥While the legacy JS API was marked as deprecated in Dart Sass 1.45.0 alongside the release of the modern API, we began emitting warnings for using it starting in Dart Sass 1.79.0. If you’re not yet able to migrate to the modern API but want to silence the warnings for now, you can pass legacy-js-api in the silenceDeprecations option:

const sass = require('sass');

const result = sass.renderSync({
  silenceDeprecations: ['legacy-js-api'],
  ...
});

这将暂时消除警告，但旧版 API 将在 Dart Sass 2.0.0 中完全删除，因此你仍应计划尽快迁移。

¥This will silence the warnings for now, but the legacy API will be removed entirely in Dart Sass 2.0.0, so you should still plan to migrate off of it soon.