re-lint-soso

re-lint-soso 是前端编码规范工程化的配套 Lint 工具，可以为项目一键接入规范、一键扫描和修复规范问题，保障项目的编码规范和代码质量。

背景

我们引入了多个业界流行的 Linter，并根据规范内容定制了规则包，它们包括：

| 规范 | Lint 工具 | 配套规则包（npm） | 当前版本 | | ----------------------------------------------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------- | -------- | | JavaScript / TypeScript / Node / React / Vue 编码规范 | ESLint | eslint-config-re | 1.1.0 | | CSS / SCSS 编码规范 | stylelint | stylelint-config-re | 1.1.0 | | Git 规范 | commitlint | commitlint-config-re | 1.1.0 | | 文档规范 | markdownlint | markdownlint-config-re | 1.1.0 |

可以看到这些 Linter 和规则包众多且零散，全部安装它们会给项目增加十几个依赖，接入和升级成本都比较高。

re-lint-soso 收敛屏蔽了这些依赖和配置细节，提供简单的 CLI 和 Node.js API，让项目能够一键接入、一键扫描、一键修复、一键升级，并为项目配置 git commit 卡口，降低项目接入规范的成本。

CLI 使用

安装

在终端执行：

npm install re-lint-soso -D

⚠️ 老项目（仍锁 ESLint 7 / 老 stylelint / 老 prettier 2.x）： 上述命令会因 peer dependency 冲突（[email protected] 期望 eslint ^8.0.0）而 ERESOLVE 失败，请改用：

npm install re-lint-soso -D --legacy-peer-deps

--legacy-peer-deps 在 npm 7+ / pnpm 6 / yarn classic 都可用，让 npm 沿用 npm 6 时代的"装了再说"行为。

⚠️ CI / 非交互环境：re-lint-soso init 命令必须通过 inquirer 选择"项目语言/框架/stylelint/Prettier"，没有 --yes / --eslintType 之类的非交互 flag。在 CI 或 docker 中跑 init 必然 hang，请改用 Node API：

const { init } = require('re-lint-soso');
await init({
  cwd: process.cwd(),
  eslintType: 'index', // 或 'typescript' / 'react' / 'typescript/react' / 'node' / 'es5' 等
  enableESLint: true,
  enableStylelint: true,
  enableMarkdownlint: true,
  enablePrettier: true,
  disableNpmInstall: true,
  rewriteConfig: true,
});

安装完成后，可执行 re-lint-soso -h 以验证安装成功。

使用

re-lint-soso init：一键接入

在项目根目录执行 re-lint-soso init，即可一键接入规范，为项目安装规范 Lint 所需的依赖和配置。

具体会做以下事情：

• 安装各种依赖：包括 Linter 依赖，如 ESLint ^8.0.0、stylelint ^14.0.0、commitlint（@commitlint/cli ^17.0.0）、markdownlint ^0.28.1 等；配置依赖，如 eslint-config-re ^1.1.0、stylelint-config-re ^1.1.0、commitlint-config-re ^1.1.0、markdownlint-config-re ^1.1.0 等
• 上述版本均与 re-spec 仓库下 packages/*/package.json#peerDependencies 严格对齐；如果你在安装时遇到 peer 冲突，可检查宿主项目是否锁定更老的版本
• 写入各种配置文件，包括：
  • .eslintrc.js、.eslintignore：ESLint 配置（继承 eslint-config-re/<language>/<dsl>，如 eslint-config-re/typescript/react）及黑名单文件
  • .stylelintrc.js、.stylelintignore：stylelint 配置（继承 stylelint-config-re）及黑名单文件
  • commitlint.config.js：commitlint 配置（注意使用短名 extends: ['re']，不要用全名 commitlint-config-re，这是 commitlint 的命名约定）
  • .markdownlint.json、.markdownlintignore：markdownlint 配置及黑名单文件
  • .prettierrc.js：符合规范的 Prettier 配置
  • .editorconfig：符合规范的 editorconfig
  • .vscode/extensions.json：写入规范相关的 VSCode 插件推荐，包括 ESLint、stylelint、markdownlint、prettier 等
  • .vscode/settings.json：写入规范相关的 VSCode 设置，设置 ESLint 和 stylelint 插件的 validate 及保存时自动运行 fix，如果选择使用 Prettier，会同时将 prettier-vscode 插件设置为各前端语言的 defaultFormatter，并配置保存时自动格式化
  • re-lint-soso.config.js：re-lint-soso 包的一些配置，如启用的功能等
• 配置 git commit 卡口：使用 husky 设置代码提交卡口，在 git commit 时会运行 re-lint-soso commit-file-scan 和 re-lint-soso commit-msg-scan 分别对提交文件和提交信息进行规范检查。re-lint-soso commit-file-scan 默认仅对 error 问题卡口，如果你想对 warn 问题也卡口，可以增加 --strict 参数以开启严格模式

注 1：如果项目已经配置过 ESLint、stylelint 等 Linter，执行 re-lint-soso init 将会提示存在冲突的依赖和配置，并在得到确认后进行覆盖：

注 2：如果项目的 .vscode/ 目录被 .gitignore 忽略，可以在拉取项目后单独执行 re-lint-soso init --vscode 命令写入 .vscode/extensions.json 和 .vscode/settings.json 配置文件

注 3：husky v3 与 v8 配置不同。[email protected] 默认按 husky v3 方式把 husky.hooks 写入 package.json；如果你已经在用 husky v8（npx husky init 后改为 .husky/<hook> 文件），请在初始化后手动删除 package.json#husky，并把以下两个脚本迁移到 .husky/pre-commit 与 .husky/commit-msg：

# .husky/pre-commit
npx --no-install re-lint-soso commit-file-scan
# .husky/commit-msg
npx --no-install re-lint-soso commit-msg-scan

commit-msg-scan 命令在内部调用 commitlint -E $HUSKY_GIT_PARAMS，需要你在项目里直接安装 @commitlint/cli@^17.0.0；commitlint.config.js 使用短名 extends: ['re']，详见 [email protected] README。

re-lint-soso scan：一键扫描

在项目的根目录执行命令，即可扫描项目的规范问题：

支持下列参数：

• -q --quiet 仅报告 error 级别的问题
• -o --output-report 输出扫描出的规范问题日志
• -i --include <dirpath> 指定要进行规范扫描的目录
• --no-ignore 忽略 eslint 的 ignore 配置文件和 ignore 规则

注 1：事实上，你可以在任意目录执行 re-lint-soso scan re-lint-soso 会根据文件类型、JSON 等特征嗅探项目类型。但我们还是推荐在执行过 re-lint-soso init 的项目根目录执行 re-lint-soso scan，以得到最准确的扫描结果。

注 2: re-lint-soso 会根据项目内有无 eslint 和 stylelint 配置文件判断使用项目的配置文件还是 re-lint-soso 默认配置进行扫描。若使用项目的，在未安装依赖时会帮其安装（执行 npm i）。若使用项目配置扫描失败，则使用默认配置扫描

re-lint-soso fix：一键修复

在项目的根目录执行命令，即可修复部分规范问题：

支持下列参数：

• -i --include <dirpath> 指定要进行修复扫描的目录
• --no-ignore 忽略 eslint 的 ignore 配置文件和 ignore 规则

注意请 review 下修复前后的代码，以免工具误修的情况。

re-lint-soso commit-file-scan 提交文件扫描

在 git commit 时对提交文件进行规范问题扫描，需配合 git 的 pre-commit 钩子使用。

支持下列参数：

• -s --strict 严格模式，对 warn 和 error 问题都卡口，默认仅对 error 问题卡口

re-lint-soso commit-msg-scan 提交信息扫描

git commit 时对 commit message 的格式进行扫描（使用 commitlint），需配合 husky 的 commit-msg 钩子使用。

Node.js API 使用

安装

npm install re-lint-soso --save

API

init：初始化

• reLintSoso.init(options)：将项目一键接入规范，效果等同于 re-lint-soso init

示例：

const reLintSoso = require('re-lint-soso');

await reLintSoso.init({
  cwd: '/path/to/project',
  checkVersionUpdate: false,
  eslintType: 'react',
  enableESLint: true,
  enableStylelint: true,
  enableMarkdownlint: true,
  enablePrettier: true,
  disableNpmInstall: false,
});

options 参数与 InitOptions 接口完全对应：

| 参数 | 类型 | 默认值 | 说明 | | ------------------- | ---------- | ------ | ------------------------------------------------------------------------------------------------------------- | | cwd | string | - | 项目绝对路径，必填（CLI 入口在执行目录时已自动传入） | | checkVersionUpdate | boolean | false | 是否在初始化前检查 re-lint-soso 的最新版并提示/升级；CLI init 传 true，Node API 默认 false | | rewriteConfig | boolean | - | 当目标项目已存在规范配置时，是否不询问直接覆盖；undefined 会触发交互确认 | | eslintType | ESLintType | - | 语言和框架类型，传值后跳过控制台交互；详见下方枚举 | | enableESLint | boolean | true | 是否启用 ESLint（默认开启） | | enableStylelint | boolean | - | 是否启用 stylelint（缺省时按 eslintType 是否含 node 自动推断） | | enableMarkdownlint | boolean | - | 是否启用 markdownlint（缺省时控制台询问） | | enablePrettier | boolean | - | 是否启用 Prettier（缺省时控制台询问） | | disableNpmInstall | boolean | false | 是否禁用初始化完成后自动执行包管理器安装 |

ESLintType

枚举值与 src/utils/constants.ts#PROJECT_TYPES.value 一一对应；其中 language（JS/TS）由项目内是否存在 *.ts/tsx 文件推断，dsl（React/Vue/Node/Rax）由文件与依赖共同嗅探，结果映射到 eslint-config-re/<language>/<dsl> 入口。

| 取值 | 含义 | 生成的 ESLint extends | | --------------------- | --------------------------------- | ------------------------------------ | | index | 未使用 React / Vue / Node 的 JS | eslint-config-re | | typescript | 未使用 React / Vue / Node 的 TS | eslint-config-re/typescript | | react | JS + React | eslint-config-re/react | | typescript/react | TS + React | eslint-config-re/typescript/react | | vue | JS + Vue | eslint-config-re/vue | | typescript/vue | TS + Vue | eslint-config-re/typescript/vue | | node | JS (Node.js) | eslint-config-re/node | | typescript/node | TS (Node.js) | eslint-config-re/typescript/node | | es5 | ES5 及以前版本 JS 老项目 | eslint-config-re/es5 |

注 1：rax / typescript/rax 选项已不在 [email protected] 提供对应入口，初始化器会忽略并回落到 index；如果你正在维护 Rax 项目，请使用 react 入口并在项目里自行安装 eslint-plugin-react 兼容。

注 2：希望所有风格错误降级为 warning，可在生成 .eslintrc.js 后追加 extends: ['<上述入口>/essential']（例如 eslint-config-re/typescript/react/essential）。

配置

re-lint-soso 基于一份配置进行扫描（但你也可以零配置使用），支持的配置参数对应 src/types.ts#Config：

| 参数 | 类型 | 默认值 | 说明 | | ------------------- | ------------------------- | ------ | ------------------------------------------------------------------------------------------ | | enableESLint | boolean | true | 是否启用 ESLint（scan 默认开启；init 若用户未传值则设为 true） | | enableStylelint | boolean | true | 是否启用 stylelint | | enableMarkdownlint | boolean | true | 是否启用 markdownlint | | enablePrettier | boolean | false | 是否启用 Prettier | | eslintOptions | ESLint.Options | - | 直接传入 ESLint 引擎；缺省时使用项目 .eslintrc 或内置默认 eslint-config-re/<lang>/<dsl> | | stylelintOptions | stylelint.LinterOptions | - | 缺省时使用项目配置或内置默认 stylelint-config-re | | markdownlintOptions | markdownlint.Options | - | 缺省时使用项目配置或内置默认 markdownlint-config-re |

re-lint-soso 会读取执行目录下的 re-lint-soso.config.js 作为配置文件。re-lint-soso init 会在执行目录下新增如下的 re-lint-soso.config.js 文件：

module.exports = {
  enableESLint: true,
  enableStylelint: true,
  enableMarkdownlint: true,
  enablePrettier: true,
};

兼容性与版本对照（1.1.0 末班车）

⚠️ 1.1.0 是 re-lint-soso 的最终发布版本（末班车）。后续不会再有新功能或升级兼容。 推荐仅用于仍在使用 Node 14-18 / npm 6-10 / 旧版 husky 3-4 的存量项目，新项目请直接 fork 或迁移到上游 eslint-config-re 等独立包。

[email protected] 锁定的依赖与 2021 年前后发布的 Linter 生态严格对齐。请确认你的项目处于下表兼容范围内，否则会出现解析失败、CLI crash 或 hooks 失效。

| 关键节点 | re-lint-soso 锁定 | 兼容范围 | 超出范围的现象 | | --- | --- | --- | --- | | Node.js | >=14 | 14 ~ 22（推荐 16 / 18） | Node 26+ 上 chalk@4 / inquirer@7 偶发 warning，CLI 可正常完成 | | 包管理器 | npm 6/7 | npm 6 / 7 / 8 / 9 / 10 | npm 11 默认 allow-scripts 不再自动跑 husky 3 postinstall | | husky | ^3.1.0 | 3 / 4 / 5 / 6 / 7 | v8+ 完全不在 package.json 读 husky.hooks，需手动迁移 .husky/<hook>（见 init 章节注 3） | | eslint | ^8.7.0 | 8.x | v9+ 强制 flat config、v10+ 移除部分规则；规则包 [email protected] 对应的就是 v8 | | stylelint | ^14.3.0 | 14.x | v15+ / v16+ API 变化，stylelint-scss@4 不可用 | | prettier | ^2.2.1 | 2.x | v3+ 默认引号风格、API 行为变化 | | @commitlint/cli | ^17.0.0 | 17.x | v18+ / v19+ 改用 ESM only，老 CJS 入口不存在 | | markdownlint | ^0.28.1 | 0.28.x | v0.29+ 改为 ESM only | | commitlint-config-re | ^1.0.10 | 1.0.10（registry 唯一已发布版本） | 无新版本可升 | | inquirer | ^7.3.3 | 7 / 8 / 9 | v10+ 改为 ESM only，CI 下交互会直接 hang | | chalk | ^4.1.0 | 4.x | v5+ ESM only | | commander | ^6.2.1 | 6 / 7 / 8 / 9 | v10+ 改用 ESM export 写法 | | ora | 5.0.0（精确锁） | 5.0.0 | 5.1.0+ 引入 bl 依赖链路，在 Node 14 + npm 6 上 [email protected] 装包时文件会损坏成 0 bytes；v6+ 改用 ESM export | | postcss | 8.4.49（精确锁） | 8.4.x | 8.5+ 移除 Container 主 export，[email protected] 全部失效 | | postcss-scss | 4.0.0（精确锁） | 4.0.0 | 4.0.6+ 加入 exports 字段 + 依赖 postcss@^7.0.32，会拉出 postcss@7 死链 |

新装包到 Node 18+ / npm 9+ 项目时，额外的两步兜底：

1. 在 npm 配置中通过 npm config set allow-scripts husky 允许 husky 的 postinstall，或运行 npm approve-scripts 手动批准 husky 的安装脚本，让 husky 3 能在 postinstall 设置 hooks。
2. re-lint-soso init 完成后，git commit 一次触发 husky 初始化；之后再执行 git commit 才会触发 re-lint-soso commit-file-scan / commit-msg-scan。

旧项目（Node 14-16 / npm 6-7）无需上述步骤。

老项目 peer 冲突处理：

• [email protected] 自带的 [email protected] 期望 eslint ^8.0.0；老项目若仍锁 eslint ^7.x，会 ERESOLVE 失败。请加 --legacy-peer-deps：npm install re-lint-soso -D --legacy-peer-deps（npm 7+ / pnpm 6+ 都支持）。
• 若使用 yarn classic（无 legacy-peer-deps 概念），直接装即可，yarn 默认容忍 peer 冲突。

CLI init 必须交互：

• re-lint-soso init 走的 inquirer 交互（语言/框架/stylelint/Prettier）没有非交互 flag。CI / docker / 自动化脚本里 init 必然 hang。
• 替代方案：用 Node API 传 eslintType 等参数跳过交互（详见"安装"章节示例）。

老项目装机自检 (重要)：

npm 在 Node 14 + npm 6 / Node 18 + npm 10 解包 tarball 偶发会让部分包文件被写成 0 bytes（已知 npm 装包 bug，与 re-lint-soso 无关）。装包后请运行：

find node_modules -type f -size 0 -name "*.js" | wc -l
find node_modules -type f -size 0 -name "*.js" | head -20

若非 0 / 出现 stylelint/lib/*.js / postcss-scss/lib/*.js / readable-stream/lib/internal/streams/*.js 等关键文件 0 bytes，请：

rm -rf node_modules package-lock.json
npm install --legacy-peer-deps

或换 npm ci（需先 commit package-lock.json）。在 Node 22 + npm 10 / Node 26 + npm 11 的干净环境上，0 个 0 bytes 文件，全流程跑通。

常见问题

与 re-spec 配套包的对齐

| 依赖 | npm 上当前发布版本 | re-spec package.json#peerDependencies 要求 | | ----------------- | ------------------ | --------------------------------------------- | | eslint-config-re | 1.1.0 | eslint ^8.0.0 | | stylelint-config-re | 1.1.0 | stylelint ^14.0.0 + stylelint-scss ^4.0.0 | | markdownlint-config-re | 1.1.0 | markdownlint ^0.28.1 | | commitlint-config-re | 1.0.10 | @commitlint/cli ^17.0.0 |

如果你的项目依旧使用旧版本，请主动 npm i -D eslint-config-re@^1.1.0 等再执行 re-lint-soso init。

TypeScript 项目扫描性能问题

如果你的 TS 项目 commit 卡口和 re-lint-soso scan 运行时间很长，可以通过如下在 .eslintrc.js 中增加以下配置提升性能：

module.exports = {
  parserOptions: {
    project: [], // for lint performance
    createDefaultProgram: false, // for lint performance
  },
  rules: {
    '@typescript-eslint/dot-notation': 0, // for lint performance
    '@typescript-eslint/restrict-plus-operands': 0, // for lint performance
  },
};