迁移到 16.0.0

此版本包含重大或破坏性更改。

我们已将源代码迁移到 ECMAScript 模块 (ESM) - 为期一年的努力，旨在允许 ESM 插件、自定义语法和格式化程序，并朝着更新我们的纯 ESM 依赖项迈出一步。

为了给社区提供迁移到 ESM 的时间，我们将发布一个混合包以支持（现在已弃用）CommonJS Node.js API，直到我们的下一个主要版本。

重大更改

我们已

添加了对 ESM 插件的支持
添加了对 ESM 自定义语法的支持
添加了对 ESM 自定义格式化程序的支持
弃用了 CommonJS Node.js API
重构以在内部使用 .mjs 和 .cjs 扩展名

添加了对 ESM 插件的支持

您现在可以创建 ESM 插件。

例如

import stylelint from "stylelint";

const {
  createPlugin,
  utils: { report, ruleMessages, validateOptions }
} = stylelint;

const ruleName = "foo-org/foo-bar";

const messages = ruleMessages(ruleName, {
  rejected: (selector) => `Unexpected "foo"`
});

const meta = {
  url: "https://foo.org/foo-bar"
};

const ruleFunction = (primary, secondaryOptions) => {
  return (root, result) => {
    const validOptions = validateOptions(/* .. */);

    if (!validOptions) return;

    /* .. */

    report({
      /* .. */
    });
  };
};

ruleFunction.ruleName = ruleName;
ruleFunction.messages = messages;
ruleFunction.meta = meta;

export default createPlugin(ruleName, ruleFunction);

我们已更新我们的插件开发者指南，其中包含更多 ESM 语法示例。

添加了对 ESM 自定义语法的支持

您现在可以创建 ESM 自定义语法。

例如

import postcss from "postcss";

function parse(css, opts) {
  /* .. */
}

function stringify(node, builder) {
  /* .. */
}

export default { parse, stringify };

有关更多示例，请参阅开发者指南中的自定义语法部分。

添加了对 ESM 自定义格式化程序的支持

您现在可以创建 ESM 自定义格式化程序。

例如

export default function yourOwnFormatter(results) {
  /* .. */
}

有关更多示例，请参阅开发者指南中的自定义格式化程序部分。

弃用 CommonJS API

我们已弃用 CommonJS Node.js API，并将在下一个主要版本中将其删除，以便我们可以更新我们的纯 ESM 依赖项。

如果您是插件作者或使用 stylelint.lint() 来整理文件，则弃用将影响您。自定义语法和格式化程序不受影响，因为它们不会使用 Node.js API。

要迁移到 ESM，您应该

将所有 require()/module.export 替换为 import/export
如果您没有使用 .mjs 扩展名，请在 package.json 中添加 "type": "module"
仅对导入使用完整的相对文件路径，例如，import x from '.'; → import x from './index.js';

我们还建议您

将 package.json 中的 "engines" 字段更新为 "node": ">=18.12.0"
从所有文件中删除 'use strict';
在 package.json 中添加 "exports": "./index.js"
对 Node.js 内置导入使用 node: 协议

有关更多详细信息，请参阅 Node.js 文档中的 ESM。

插件

例如，要迁移您的插件以使用 import 和 export

-const stylelint = require("stylelint");
+import stylelint from "stylelint";

 const {
   createPlugin,
   utils: { report, validateOptions },
 } = stylelint;

 const ruleFunction = (primary, secondaryOptions) => { /* .. */ };

 ruleFunction.ruleName = ruleName;
 ruleFunction.messages = messages;
 ruleFunction.meta = meta;

-module.exports = createPlugin(ruleName, ruleFunction);
+export default createPlugin(ruleName, ruleFunction);

如果您使用我们的 testRule 模式测试您的插件，您可以

更新到我们 jest-preset-stylelint 包的最新版本
尝试我们新的 stylelint-test-rule-node 包，它使用 node:test|assert

`jest-preset-stylelint`

预设需要 --experimental-vm-modules Node.js 标志才能支持 ESM。您可以使用 cross-env 包在您的 npm-run-script 中设置 NODE_OPTIONS 环境变量

 {
   "scripts": {
-    "test": "jest",
+    "test": "cross-env NODE_OPTIONS=\"--experimental-vm-modules --no-warnings\" jest --runInBand",
   }
 }

（cross-env 处于维护模式，因为它被认为已完成。）

如果您遇到错误（例如，在 Node.js 18 上运行预设时出现段错误），您可以尝试在您的 Jest 配置中使用 jest-light-runner

 export default {
   preset: "jest-preset-stylelint",
   setupFiles: ["./jest.setup.js"],
+  runner: "jest-light-runner",
 };

该运行程序的覆盖范围支持有限。

`stylelint-test-rule-node`

要尝试我们新的 stylelint-test-rule-node 包，您应该将其导入到您的测试文件中

+import { testRule } from "stylelint-test-rule-node";

 testRule({
   /* .. */
 });

并更新您的 npm-run-script

 {
   "scripts": {
-    "test": "jest"
+    "test": "node --test"
   }
 }

该包使用 node:test，它在 Node.js 18 中是实验性的，但在 20 中是稳定的。覆盖范围支持也是实验性的。

如果您有其他 Jest 测试，您需要调整它们以使用 node:test，例如 expect() 变为 assert()。

`stylelint.lint()`

例如，要迁移使用 stylelint.lint() 的代码以使用 import 和顶级 await

-const stylelint = require("stylelint");
+import stylelint from "stylelint";

-stylelint.lint(options).then((result) => { console.log(result); });
+const result = await stylelint.lint(options);
+console.log(result);

您将在用户指南中找到有关 ESM Node.js API 的更多详细信息。

使用 CommonJS Node.js API 将触发弃用警告。如果您还没有准备好迁移到 ESM，您可以使用 quietDeprecationWarnings 选项来隐藏警告。

 const stylelint = require("stylelint");

 const resultPromise = stylelint.lint({
   /* .. */
+  quietDeprecationWarnings: true
 });

重构以在内部使用 `.mjs` 和 `.cjs` 扩展名

我们现在在内部使用 .mjs 和 .cjs 扩展名来支持混合包。此更改不会影响我们的公共 API，但会影响您的插件 require 内部文件。

我们建议您将文件复制到您的项目中，而不是导入它们，因为我们将在下一个主要版本中删除对它们的访问权限。

但是，您可以在下一个主要版本发布之前不安全地继续 import 或 require 这些文件，方法是更新您的导入

 // ESM
-import('stylelint/lib/utils/typeGuards.js');
+import('stylelint/lib/utils/typeGuards.mjs');

 // CommonJS
-require('stylelint/lib/utils/typeGuards.js');
+require('stylelint/lib/utils/typeGuards.cjs');

破坏性更改

我们已

删除了已弃用的样式规则
删除了对 Node.js 小于 18.12.0 的支持
更改了 Node.js API 返回的已解析对象
更改了 Node.js API stylelint.formatters 对象
更改了 Node.js API stylelint.rules 对象
更改了 Node.js API stylelint.utils.checkAgainstRule() 函数
更改了 CLI 以将问题打印到 stderr
更改了 CLI 针对标志错误的退出代码
更改了默认语法行为，以始终使用安全解析器，无论扩展名如何，都使用 fix

删除了已弃用的样式规则

我们已删除了我们在 15.0.0 中弃用的样式规则。

您应该从配置对象中删除这些规则。有关更多详细信息，请参阅 15.0.0 迁移指南。

删除了对 Node.js 小于 18.12.0 的支持

Node.js 14 和 16 已达到生命周期结束。我们已删除对它们的支持以更新一些依赖项。

您应该使用 Node.js 的 18.12.0 或更高版本。

更改了 Node.js API 返回的已解析对象

我们已更改了 stylelint.lint() 返回的 Promise 的已解析对象，以便新的

report 属性包含格式化的问题
code 属性包含自动修复的代码

我们已弃用 output 属性，以支持新的 report 和 code 属性，我们将在下一个主要版本中将其删除。

如果您使用 stylelint.lint() 来整理源字符串，并且 fix 选项为 true，则 report 属性将包含格式化的问题，而 code 属性将包含修复的代码。

 const result = await stylelint.lint({
   code: "a {}",
   fix: true
 });
-const fixedCode = result.output;
+const formattedProblems = result.report;
+const fixedCode = result.code;

如果您使用 stylelint.lint() 来整理文件，则 code 属性将始终为 undefined。

更改了 Node.js API `stylelint.formatters` 对象

我们已更改了 Node.js API 中的 stylelint.formatters 对象，以便每个格式化程序都是一个 Promise 函数。

-const formatter = stylelint.formatters.json;
+const formatter = await stylelint.formatters.json;

更改了 Node.js API `stylelint.rules` 对象

我们已更改了 Node.js API 中的 stylelint.rules 对象，以便每个规则都是一个 Promise 函数。

-const rule = stylelint.rules['block-no-empty'];
+const rule = await stylelint.rules['block-no-empty'];

更改了 Node.js API `stylelint.utils.checkAgainstRule()` 函数

我们已更改了 Node.js API 中的 stylelint.utils.checkAgainstRule() 函数，以便它是一个异步函数。

-checkAgainstRule({ /* .. */ });
+await checkAgainstRule({ /* .. */ });

更改了 CLI 以将问题打印到 stderr

我们已更改了 CLI 以将问题打印到 stderr 而不是 stdout。

如果您使用 --fix 和 --stdin 选项，CLI 将将修复的代码打印到 stdout，并将任何问题打印到 stderr。

如果您使用 > 来重定向标准输出（例如，来自自定义格式化程序），您可以改用 --output-file 标志

-npx stylelint "*.css" --custom-formatter custom-formatter.js > output.txt
+npx stylelint "*.css" --custom-formatter custom-formatter.js --output-file output.txt

更改了 CLI 针对标志错误的退出代码

我们已将 CLI 标志错误的退出代码从 2 更改为 64，以便 2 保留用于整理问题。

如果您是使用 CLI 的编辑器集成作者，现在可以区分标志错误和 lint 问题。

更改了默认语法行为，无论扩展名如何，始终使用 `fix` 与 `safe-parser` 一起使用

我们已更改默认语法行为，无论文件扩展名如何，始终在自动修复 CSS 代码时使用 postcss-safe-parser。以前，只有 .css、.pcss 或 .postcss 文件使用 postcss-safe-parser 自动修复。

迁移到 16.0.0

重大更改​

添加了对 ESM 插件的支持​

添加了对 ESM 自定义语法的支持​

添加了对 ESM 自定义格式化程序的支持​

弃用 CommonJS API​

插件​

jest-preset-stylelint​

stylelint-test-rule-node​

stylelint.lint()​

重构以在内部使用 .mjs 和 .cjs 扩展名​

破坏性更改​

删除了已弃用的样式规则​

删除了对 Node.js 小于 18.12.0 的支持​

更改了 Node.js API 返回的已解析对象​

更改了 Node.js API stylelint.formatters 对象​

更改了 Node.js API stylelint.rules 对象​

更改了 Node.js API stylelint.utils.checkAgainstRule() 函数​

更改了 CLI 以将问题打印到 stderr​

更改了 CLI 针对标志错误的退出代码​

更改了默认语法行为，无论扩展名如何，始终使用 fix 与 safe-parser 一起使用​