Stylelint 16.0.0 迁移指南：全面拥抱 ESM 时代

Stylelint 16.0.0 迁移指南：全面拥抱 ESM 时代

stylelint A mighty CSS linter that helps you avoid errors and enforce conventions. 项目地址: https://gitcode.com/gh_mirrors/st/stylelint

前言

作为前端开发者，我们每天都在与 CSS 打交道，而 Stylelint 作为业界领先的 CSS 代码质量检查工具，其 16.0.0 版本的发布标志着它正式迈入了 ESM（ECMAScript Modules）时代。本文将深入解析这一重大版本更新的核心变化，帮助开发者顺利完成迁移。

核心变化概述

16.0.0 版本主要带来了以下重大变化：

1. 全面支持 ESM 模块系统
2. 多项 Node.js API 变更
3. 移除过时功能
4. CLI 行为调整

ESM 支持详解

为什么迁移到 ESM？

ECMAScript Modules 是 JavaScript 的官方标准模块系统，相比传统的 CommonJS（CJS），它具有以下优势：

• 静态分析能力更强
• 浏览器原生支持
• 更好的 tree-shaking 能力
• 更符合现代 JavaScript 发展趋势

新增的 ESM 支持

1. ESM 插件支持

现在你可以使用 ES Module 语法编写 Stylelint 插件：

import stylelint from "stylelint";

const { createPlugin } = stylelint;

const ruleFunction = (primary) => (root, result) => {
  // 规则实现
};

export default createPlugin("your-plugin/rule-name", ruleFunction);

2. ESM 自定义语法支持

自定义语法现在也可以使用 ESM 导出：

export default {
  parse(css, opts) {
    // 解析实现
  },
  stringify(node, builder) {
    // 序列化实现
  }
};

3. ESM 自定义格式化器支持

格式化器同样支持 ESM 导出：

export default function formatter(results) {
  // 格式化实现
}

CommonJS API 弃用

CommonJS API 已被标记为弃用，将在下一个主版本中移除。迁移建议：

1. 将 require/module.exports 替换为 import/export
2. 在 package.json 中添加 "type": "module"
3. 使用完整的相对路径导入（包含文件扩展名）

示例迁移对比：

// 旧版 CommonJS
const stylelint = require("stylelint");
module.exports = createPlugin(ruleName, ruleFunction);

// 新版 ESM
import stylelint from "stylelint";
export default createPlugin(ruleName, ruleFunction);

测试相关调整

测试工具变更

如果你使用 jest-preset-stylelint 测试插件，需要做以下调整：

1. 添加 Node.js 实验性标志
2. 考虑使用 jest-light-runner 解决可能的兼容性问题

或者，可以尝试新的 stylelint-test-rule-node 测试包：

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

testRule({
  // 测试配置
});

重大变更详解

1. 移除过时的样式规则

15.0.0 中标记为弃用的样式规则已被完全移除，请检查并更新你的配置文件。

2. Node.js 版本要求

最低支持的 Node.js 版本提升至 18.12.0，确保你的开发环境符合要求。

3. Node.js API 变更

返回对象结构调整

stylelint.lint() 返回的 Promise 解析对象新增了两个属性：

• report: 包含格式化后的问题报告
• code: 包含自动修复后的代码

旧属性 output 已被标记为弃用。

异步化改造

多个 API 方法变为异步：

// 旧版同步
const formatter = stylelint.formatters.json;

// 新版异步
const formatter = await stylelint.formatters.json;

4. CLI 行为变更

问题输出位置

问题报告现在输出到 stderr 而非 stdout，自动修复后的代码仍输出到 stdout。

退出码调整

标志错误退出码从 2 改为 64，2 现在专用于代码问题。

5. 安全解析器行为变更

自动修复现在总是使用 postcss-safe-parser，不再受文件扩展名限制。

迁移建议

1. 评估影响范围：检查项目中是否使用了将被移除或变更的功能
2. 逐步迁移：可以先启用 quietDeprecationWarnings 静默警告，逐步完成迁移
3. 测试覆盖：确保迁移后的测试覆盖率不受影响
4. 团队沟通：如果项目涉及多人协作，确保团队成员了解变更

结语

Stylelint 16.0.0 的 ESM 迁移是项目发展的重要里程碑，虽然带来了一些迁移成本，但为未来的功能扩展和性能优化奠定了基础。希望本文能帮助你顺利完成升级，享受更现代化的 CSS 代码检查体验。

stylelint A mighty CSS linter that helps you avoid errors and enforce conventions. 项目地址: https://gitcode.com/gh_mirrors/st/stylelint