sindresorhus/eslint-package-json
GitHub: sindresorhus/eslint-package-json
一款 ESLint 插件，用于对 package.json 进行语义级别的 lint 检查与自动修复，帮助开发者捕获无效名称、错误版本范围、损坏 exports 等包元数据问题。
Stars: 16 | Forks: 1
# eslint-package-json
使用 ESLint 对你的 `package.json` 文件进行 lint 和自动修复，由 [`@eslint/json`](https://github.com/eslint/json) 提供支持。
该插件能够捕获真实的 `package.json` 错误（如无效的名称、错误的版本范围、损坏的 `exports`、位置错误的 `@types/*`、多余的 `files` 条目等），并自动修复其中的许多错误。
## 安装
```
npm install --save-dev eslint eslint-package-json
```
**要求 ESLint `>=10.4`、[flat config](https://eslint.org/docs/latest/use/configure/configuration-files) 以及 [ESM](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c#how-can-i-make-my-typescript-project-output-esm)。**
## 用法
将推荐的配置添加到你的 `eslint.config.js` 中：
```
import {defineConfig} from 'eslint/config';
import packageJson from 'eslint-package-json';
export default defineConfig({
files: ['**/package.json'],
plugins: {
'package-json': packageJson
},
extends: [
'package-json/recommended'
]
});
```
这会对你的项目中每个 `package.json` 进行 lint。要调整单个规则，请将它们添加到同一个配置对象中：
```
import {defineConfig} from 'eslint/config';
import packageJson from 'eslint-package-json';
export default defineConfig({
files: ['**/package.json'],
plugins: {
'package-json': packageJson
},
extends: [
'package-json/recommended'
],
rules: {
'package-json/dependency-version-range': [
'error',
{
range: 'caret'
}
]
}
});
```
如果你更喜欢手动配置而不是使用预设：
```
import json from '@eslint/json';
import {defineConfig} from 'eslint/config';
import packageJson from 'eslint-package-json';
export default defineConfig({
files: ['**/package.json'],
language: 'json/json',
plugins: {
json,
'package-json': packageJson
},
rules: {
'package-json/valid-fields': 'error'
}
});
```
## 配置
- `recommended` — 启用能够捕获真实且毫无争议错误的规则。
- `all` — 启用所有规则。适合用于发现规则；不建议日常使用。
## 规则
💼 启用的[配置](https://github.com/sindresorhus/eslint-package-json#configs)。\
✅ 在 `recommended` [配置](https://github.com/sindresorhus/eslint-package-json#configs)中设置。\
🔧 可通过 [`--fix` CLI 选项](https://eslint.org/docs/user-guide/command-line-interface#--fix)自动修复。\
💡 可通过[编辑器建议](https://eslint.org/docs/latest/use/core-concepts#rule-suggestions)手动修复。
| Name | Description | 💼 | 🔧 | 💡 |
| :----------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------- | :- | :- | :- |
| [consistent-name-casing](docs/rules/consistent-name-casing.md) | 强制 `scripts` 和 `bin` 对象中的键使用 kebab-case。 | | | |
| [consistent-path-prefix](docs/rules/consistent-path-prefix.md) | 强制本地路径字段使用一致的 `./` 前缀。 | ✅ | 🔧 | |
| [dependency-version-range](docs/rules/dependency-version-range.md) | 强制依赖项使用一致的版本范围风格。 | ✅ | | 💡 |
| [description-format](docs/rules/description-format.md) | 强制 `description` 字段的格式。 | | 🔧 | |
| [no-absolute-paths](docs/rules/no-absolute-paths.md) | 禁止在路径字段中使用绝对路径。 | ✅ | | |
| [no-backslash-paths](docs/rules/no-backslash-paths.md) | 强制在路径字段中使用正斜杠。 | ✅ | 🔧 | |
| [no-core-module-dependencies](docs/rules/no-core-module-dependencies.md) | 禁止会遮蔽 Node.js 内置模块的依赖项。 | ✅ | | 💡 |
| [no-deprecated-fields](docs/rules/no-deprecated-fields.md) | 禁止 npm 已弃用的字段和脚本。 | ✅ | | |
| [no-dist-tag-dependencies](docs/rules/no-dist-tag-dependencies.md) | 禁止将 dist-tags 用作依赖指定符。 | ✅ | | |
| [no-duplicate-dependencies](docs/rules/no-duplicate-dependencies.md) | 禁止在多个依赖组中列出同一个依赖。 | ✅ | 🔧 | |
| [no-empty-fields](docs/rules/no-empty-fields.md) | 禁止空字段。 | ✅ | | 💡 |
| [no-exact-peer-dependencies](docs/rules/no-exact-peer-dependencies.md) | 禁止 peer dependencies 使用精确版本。 | | | 💡 |
| [no-exports-trailing-slash](docs/rules/no-exports-trailing-slash.md) | 禁止在 `exports`/`imports` 中使用已弃用的带尾斜杠文件夹映射。 | ✅ | 🔧 | |
| [no-fallback-export-arrays](docs/rules/no-fallback-export-arrays.md) | 不建议在 `exports`/`imports` 中使用字符串目标的回退数组。 | ✅ | | |
| [no-git-dependencies](docs/rules/no-git-dependencies.md) | 禁止将 git URLs 用作依赖指定符。 | | | |
| [no-http-dependencies](docs/rules/no-http-dependencies.md) | 禁止将 HTTP URLs 用作依赖指定符。 | ✅ | | |
| [no-install-scripts](docs/rules/no-install-scripts.md) | 禁止 `install` 生命周期脚本。 | ✅ | | 💡 |
| [no-invalid-direct-overrides](docs/rules/no-invalid-direct-overrides.md) | 禁止与直接依赖项冲突的 npm overrides。 | ✅ | 🔧 | |
| [no-local-dependencies](docs/rules/no-local-dependencies.md) | 禁止将本地文件系统路径用作依赖指定符。 | | | |
| [no-manual-maintainers](docs/rules/no-manual-maintainers.md) | 禁止手动设置 `maintainers` 字段。 | ✅ | | 💡 |
| [no-missing-files](docs/rules/no-missing-files.md) | 禁止包元数据引用丢失的文件。 | | | |
| [no-nested-exports](docs/rules/no-nested-exports.md) | 禁止在嵌套的 `package.json` 文件中使用 `exports` 和 `imports`。 | ✅ | | 💡 |
| [no-orphan-script-hooks](docs/rules/no-orphan-script-hooks.md) | 禁止没有对应脚本的 `pre`/`post` 脚本钩子。 | ✅ | | |
| [no-orphan-types](docs/rules/no-orphan-types.md) | 禁止没有对应依赖的 `@types/*` 包。 | ✅ | | 💡 |
| [no-overrides-in-published-package](docs/rules/no-overrides-in-published-package.md) | 禁止在可发布的包中使用 `overrides`。 | ✅ | | 💡 |
| [no-package-manager-engines](docs/rules/no-package-manager-engines.md) | 禁止在 `engines` 字段中包含包管理器版本。 | ✅ | | 💡 |
| [no-pre-release-dependencies](docs/rules/no-pre-release-dependencies.md) | 禁止将预发布版本用作依赖指定符。 | | | |
| [no-redundant-files](docs/rules/no-redundant-files.md) | 禁止 `files` 字段中的冗余条目。 | ✅ | 🔧 | |
| [no-redundant-repository-fields](docs/rules/no-redundant-repository-fields.md) | 禁止 `bugs`/`homepage` 的值与 npm 从 `repository` 推断出的内容重复。 | | 🔧 | |
| [no-restricted-dependencies](docs/rules/no-restricted-dependencies.md) | 禁止特定的依赖项。 | | | |
| [no-restricted-fields](docs/rules/no-restricted-fields.md) | 禁止特定字段。 | | | 💡 |
| [no-self-dependency](docs/rules/no-self-dependency.md) | 禁止包依赖自身。 | ✅ | | 💡 |
| [no-typo-fields](docs/rules/no-typo-fields.md) | 禁止拼写错误的 package.json 字段名。 | ✅ | 🔧 | |
| [no-wildcard-dependencies](docs/rules/no-wildcard-dependencies.md) | 禁止依赖项使用通配符版本范围。 | ✅ | | |
| [no-workspace-protocol-in-published-package](docs/rules/no-workspace-protocol-in-published-package.md) | 禁止在可发布的包中使用 `workspace:` 依赖指定符。 | ✅ | | |
| [peer-dependencies-as-dev-dependencies](docs/rules/peer-dependencies-as-dev-dependencies.md) | 强制 peer dependencies 也以兼容版本列在 `devDependencies` 中。 | ✅ | | 💡 |
| [prefer-engines-range](docs/rules/prefer-engines-range.md) | 倾向于在 `engines` 字段中使用开放式 `>=` 范围。 | ✅ | | 💡 |
| [prefer-exports](docs/rules/prefer-exports.md) | 倾向于 `exports` 优先的包接口。 | ✅ | | |
| [prefer-files-field](docs/rules/prefer-files-field.md) | 要求 `files` 白名单覆盖已发布的入口点。 | ✅ | | |
| [prefer-https-urls](docs/rules/prefer-https-urls.md) | 倾向于在元数据字段中使用 `https://` URL。 | ✅ | 🔧 | |
| [prefer-provenance](docs/rules/prefer-provenance.md) | 通过 `publishConfig.provenance` 强制执行 npm provenance。 | | | 💡 |
| [prefer-shorthand](docs/rules/prefer-shorthand.md) | 尽可能倾向使用字段的简写字符串形式。 | ✅ | 🔧 | |
| [prefer-side-effects-field](docs/rules/prefer-side-effects-field.md) | 建议为包声明 `sideEffects` 字段。 | ✅ | | 💡 |
| [prefer-type-module](docs/rules/prefer-type-module.md) | 倾向于将 `type` 字段设为 `module`。 | ✅ | | 💡 |
| [require-bin-shebang](docs/rules/require-bin-shebang.md) | 要求 `bin` 文件以精确的 `#!/usr/bin/env node` shebang 开头。 | ✅ | | |
| [require-default-condition](docs/rules/require-default-condition.md) | 要求在 `exports`/`imports` 条件对象中包含最后的 `default` 条目。 | ✅ | | |
| [require-engines](docs/rules/require-engines.md) | 要求包含 `engines.node` 字段。 | ✅ | | |
| [require-entry-point](docs/rules/require-entry-point.md) | 要求包含入口点字段。 | ✅ | | |
| [require-exports-root](docs/rules/require-exports-root.md) | 要求 `exports` 字段中包含可用的 `.` 根条目。 | | | |
| [require-fields](docs/rules/require-fields.md) | 要求特定字段必须存在，始终如此或仅针对已发布的包。 | ✅ | | |
| [require-private-when-workspaces](docs/rules/require-private-when-workspaces.md) | 设置 `workspaces` 时要求 `private`。 | ✅ | | 💡 |
| [require-types-in-exports](docs/rules/require-types-in-exports.md) | 要求 `exports` 中的类型顺序正确且与模块兼容。 | ✅ | | |
| [restrict-fields-when-private](docs/rules/restrict-fields-when-private.md) | 禁止在包为私有时无效的字段。 | | | 💡 |
| [sort-dependencies](docs/rules/sort-dependencies.md) | 强制依赖项按字母顺序排序。 | ✅ | 🔧 | |
| [sort-files](docs/rules/sort-files.md) | 强制 `files` 字段中的条目按标准顺序排列。 | ✅ | 🔧 | |
| [sort-properties](docs/rules/sort-properties.md) | 强制顶级 package.json 字段按标准顺序排列。 | ✅ | 🔧 | |
| [sort-scripts](docs/rules/sort-scripts.md) | 强制脚本按字母顺序排序。 | | 🔧 | |
| [types-in-dev-dependencies](docs/rules/types-in-dev-dependencies.md) | 强制 `@types/*` 包位于 `devDependencies` 中。 | | | 💡 |
| [valid-fields](docs/rules/valid-fields.md) | 强制 package.json 字段的值有效。 | ✅ | 🔧 | 💡 |
## 常见问题
### 这与 [`eslint-plugin-package-json`](https://github.com/michaelfaith/eslint-plugin-package-json) 有什么不同？
两者都通过 ESLint 对 `package.json` 进行 lint，并且 `eslint-plugin-package-json` 是一个很棒的项目。我开发这个插件是因为我想要不同的设计：
- **更少、更强大的规则。** 我使用了少量带有选项的规则，而不是几十个几乎相同的规则（每个字段一个，每个依赖组一个）。例如，一个带有 `dependencyTypes` 选项的 `dependency-version-range` 规则就取代了整个 `no-caret-*` / `prefer-tilde-*` 规则族。学习和配置的成本更低。
- **原生支持 [`@eslint/json`](https://github.com/eslint/json)。** 我直接使用 ESLint 官方的 JSON 语言，不需要 parser 兼容层。
- **自动修复优先。** 每个能够安全修复或建议修复的规则都会这样做。
### 为什么不用 [`npm-package-json-lint`](https://github.com/tclindner/npm-package-json-lint)它是一个独立的 CLI，具有自己的配置格式，且不支持自动修复。这个插件存在于 ESLint 内部，因此它可以共享你的编辑器集成、`--fix` 和 flat config。
### 如何为 `package.json` 禁用某个规则？
`package.json` 必须是有效的 JSON，因此它不能包含注释。
请改为在 `eslint.config.js` 中禁用该规则：
```
import {defineConfig} from 'eslint/config';
import packageJson from 'eslint-package-json';
export default defineConfig({
files: ['**/package.json'],
plugins: {
'package-json': packageJson
},
extends: [
'package-json/recommended'
],
rules: {
'package-json/no-orphan-types': 'off',
},
});
```
如果只想为某一个包禁用该规则，请使用更具体的 `files` 匹配模式。
## 相关资源
- [eslint-plugin-unicorn](https://github.com/sindresorhus/eslint-plugin-unicorn) — 大量实用的 ESLint 规则。
- [eslint-node-test](https://github.com/sindresorhus/eslint-node-test) — 用于 Node.js 内置测试运行器的 ESLint 规则。
标签：ESLint, GNU通用公共许可证, JSON, MITM代理, Node.js, SOC Prime, 代码规范, 开发工具, 数据可视化, 自定义脚本, 错误基检测, 静态代码分析