# js-lean 中文文档

规范地址：https://npmcn.com/package/js-lean/

版本：0\.1\.0
npm 元数据更新时间：2026-11-03T19:56:43.766Z
中文译文更新时间：2026-11-04T00:57:44.084Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/js-lean
原文对照：https://npmcn.com/package/js-lean/?lang=original
项目主页：https://github.com/lean-packages/js-lean#readme
源码仓库：https://github.com/lean-packages/js-lean

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：81.4 kB，6 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：2 个
- 首次发布：2026-11-03T19:55:06.923Z
- 最新版本发布：2026-11-03T19:56:43.512Z
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

用于验证和优化JavaScript包分发归档的CLI工具。

## 安装

```sh
npm install js-lean
```

也可以使用：`pnpm add js-lean`、`yarn add js-lean`、`bun add js-lean`

## README

# js-lean

验证和管理npm包发布卫生，以保持发布包精简。

`js-lean` 是JavaScript/TypeScript对应的 [cargo-lean](https://github.com/lean-packages/cargo-lean) 和 [py-lean](https://github.com/lean-packages/py-lean)． 中的发布配置进行审计 `package.json` ( `files` Allowlist)和一个可选的 `.npmignore` 帮助防止仅存储库文件不必要地以 已发布的包档案。

## 为什么?

一个发布的npm包可以包含比消费者在运行时需要的文件更多的文件。没有刻意发表 配置、存储库工件（如IDE设置、测试、构建配置、文档和CI工作流） 可能会在包存档中结束。

这些不必要的文件会增加包的大小，为下游用户增加噪音，并暴露程序的详细信息 不需要成为发布包一部分的开发存储库。

`js-lean` 帮助保持 `package.json` `files` Allowlist关注运行时文件，并检查现有的 `.npmignore` 对于应该排除的存储库构件。

您的工作库保持完整： `js-lean` 更改发布配置，而不是更改项目中的文件。 它不会删除存储库文件。

## 特性

-   **线头** 中检测非运行时条目 `files`中引用的不必要的存储库构件 `.npmignore`, 散乱的可发布文件。
-   **创建** -构建一个默认值 `files` Allowlist和一个填充的 `.npmignore`。
-   **更新** -非破坏性互补 `files` 和 `.npmignore` 基于存储库内容。

## 安装

### 从源

```bash
git clone https://github.com/lean-packages/js-lean.git && cd js-lean
npm install
npm run build
```

### 从npm

```bash
npm install js-lean
```

### 在开发期间运行

```bash
# Run from source (no build needed; uses tsx)
npm run dev -- lint

# Run the built CLI
npm start -- lint
```

或者，使用npx直接运行它，而不需要在本地安装：

```bash
npx js-lean lint
```

## 用法

```bash
js-lean <command>
```

### 命令

| 命令 | 描述 |
| --- | --- |
| `lint` | 检查的发布卫生状况 `package.json` `files` 和 `.npmignore`。 |
| `create` | 构建默认值 `files` Allowlist和一个填充的 `.npmignore`。 |
| `update` | 补充 `files` 和 `.npmignore` 以反映存储库内容。 |

### `lint` -检查发布状况

检查 `package.json` `files` Allowlist包含运行时文件，并且该文件已存在 `.npmignore` 不 包含点文件和存储库构件的不必要条目。

```bash
# Check the current directory
js-lean lint

# Check a specific manifest
js-lean lint --manifest-path /path/to/package.json

# Show a diff of the entries that should be removed
js-lean lint --diff

# JSON output for scripting
js-lean lint --format json

# Enable the stray publishable file check
js-lean lint --enforce-no-strays
```

#### 散乱的可发布文件检查

控件未考虑其发布状态的顶级文件标记为可选的偏离文件检查 `package.json` `files` allowlist或 `.npmignore`． 对于每个标记的文件，确定它是否属于已发布文件 包：添加到 `files` 是否应该发表，或者通过 `.npmignore` 如果它应该保留 repository-only。

npm总是包含的文件(比如 `README`， `LICENSE`, `package.json`)、lockfiles和dotfiles则不是 由这张支票报告。缺省情况下，检查是关闭的。使用 `--enforce-no-strays`;启用后，每个 Stray被报告为错误和原因 `lint` 使用代码退出 `1`。

### `create` -脚手架发布配置

添加默认值 `files` allowlist来 `package.json` 当字段不存在时，创建一个填充的 `.npmignore` 与 当文件不存在时，生成公共存储库。保留现有配置。

```bash
# Preview what would be created
js-lean create --dry-run

# Apply changes
js-lean create

# JSON output
js-lean create --format json
```

### `update` —反映存储库的内容

非破坏性补充 `package.json` `files` 字段和现有的 `.npmignore` 运行时文件和 实际存在于磁盘上的存储库构件。保留现有的分录； `update` 不删除表项。

```bash
# Preview what would change
js-lean update --dry-run

# Apply changes
js-lean update

# JSON output
js-lean update --format json
```

### 选项和标志

这些命令共享以下选项和标志，并与同级命令对齐 `cargo-lean` 工具：

| 选项/标志 | 描述 |
| --- | --- |
| `-m, --manifest-path <path>` | 路径 `package.json` (默认值: `package.json`）. |
| `--format <format>` | 输出格式: `text` 或 `json` (默认值: `text`）. |
| `--dry-run` | 无需修改文件即可预览更改(`create`， `update`）. |
| `--diff` | 以不同的方式预览违规条目(`lint`）. |
| `--enforce-no-strays` | 启用流浪可发布文件检查；走失的人不会掉线(`lint`）. |

当 `--manifest-path` ，则工作目录是从指定的父目录派生的 `package.json`． 例如, `--manifest-path /path/to/package.json` 检查存储库构件和 `.npmignore` 相对于 `/path/to/`。

### 帮助和版本

```bash
js-lean --help      # Show help
js-lean --version   # Print version
```

## CI集成

运行 `js-lean lint` 在CI管道中检查发布配置是否保持整洁：

```yaml
# Example GitHub Actions step
- name: Check package publishing hygiene
  run: npx js-lean lint
```

失败检查有助于在包发布之前捕获存储库构件。

要查看npm将包含的文件的最终视图，还可以使用 `npm pack --dry-run`。 `js-lean` 审核和管理发布配置；Npm的包输出是包的权威预览 生成的包内容。

## AI免责声明

该软件包是在人工智能（AI）的帮助下开发的。人工智能工具在整个过程中使用 开发过程，包括代码生成、文档、测试和维护。

虽然审查和验证人工智能生成的贡献是合理的，但人工智能生成的代码并不是固有的 正确的，安全的或没有缺陷的所有的贡献仍然受制于人工审查和项目质量标准。

与任何软件一样，使用此软件包的风险由您自己承担。不保证其适合于某一特定 维修人员对因使用而造成的损害不承担任何责任。

## 发展

看到 [CONTRIBUTING.md](https://npmcn.com/package/js-lean/CONTRIBUTING.md) 用于开发说明。

## 许可证

本项目使用MIT许可协议。请参阅 [LICENSE.md](https://npmcn.com/package/js-lean/LICENSE.md) 了解更多详情。

## 相关项目

-   [lean-package-validator](https://github.com/lean-packages/lean-package-validator) - - - `PHP` 同行。
-   [cargo-lean](https://github.com/lean-packages/cargo-lean) - - - `Rust` 同行。
-   [py-lean](https://github.com/lean-packages/py-lean) - - - `Python` 同行。

## 常见问题

### js-lean 是什么？

用于验证和优化JavaScript包分发归档的CLI工具。

### 如何安装 js-lean？

在项目目录运行 npm install js-lean，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 js-lean，可以用 npx js-lean 直接运行。

### js-lean 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### js-lean 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### js-lean 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### js-lean 可以商用吗？

js-lean 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### js-lean 还在维护吗？

最新版本 0\.1\.0 发布于 2026/11/04（1 天前）；至今共发布 2 个版本，其中过去 12 个月发布了 2 个；首次发布于 2026/11/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。