npmpreflight

npmpreflight

在运行 npm publish 之前审查软件包目录，趁发布出问题还容易撤回时及时发现。

npmpreflight 会解析软件包实际会包含的文件集，扫描这些文件中的机密信息模式，统计总大小，并检查 package.json 中发布所需的字段和入口点。它能回答一些发布后才发现会让人尴尬的问题：随包发布的文件中是否包含凭据，bin 目标文件是否存在于 tarball 中，是否设置了许可证字段，以及带作用域的软件包是否即将以受限权限发布。

安装

无需安装即可运行：

npx @reneturcios/npmpreflight check .

或全局安装：

npm install -g @reneturcios/npmpreflight
npmpreflight check .

需要 Node 20 或更高版本。

CLI 用法

npmpreflight check [path] [--json]
npmpreflight mcp
npmpreflight --version

• check [path] 审查 path 处的软件包目录（默认为当前目录），并输出易读的报告。添加 --json 可输出机器可读的报告。
• mcp 通过 stdio 启动 MCP 服务（见下文）。
• --version 输出版本号。

退出码：判定为 READY 时返回 0，其他判定返回 1，用法错误或 package.json 无法读取或无效时返回 2，读取端提前关闭输出管道时返回 141。

输出示例：

npmpreflight check .: FIX-FIRST
  files: 4, bytes: 603, findings: 2 (high: 2, medium: 0, low: 0, info: 0)
  summary: 4 shipped file(s), 603 byte(s), 2 finding(s) (2 high, 0 medium, 0 low, 0 info). High-severity findings must be fixed before publishing.
  [HIGH] SECRET-LEAK src/index.js:2 Shipped file matches the secret pattern private-key-block. Remove the credential from the package and rotate it if it was ever real. (evidence: private-key-block)
  [HIGH] SECRET-LEAK src/index.js:3 Shipped file matches the secret pattern github-pat-classic. Remove the credential from the package and rotate it if it was ever real. (evidence: github-pat-classic)
FIX-FIRST: resolve the high-severity findings before publishing.

发现项中不会包含匹配到的机密文本。机密发现项的证据仅包含模式 ID，以及文件和行号，因此可以放心将报告粘贴到问题单或 CI 日志中。

MCP

同一项审查也可通过 stdio 作为 MCP 工具使用：

• 工具：preflight_package
• 输入：path，要检查的软件包目录
• 输出：JSON 报告，与 check --json 的输出完全相同

运行 npmpreflight mcp 启动服务，或配置 MCP 客户端运行 npx @reneturcios/npmpreflight mcp。该服务也以 OCI 镜像形式发布，并以 io.github.CloudCorpRecords/npmpreflight 为名称列在 server.json 中。

检查项

规则	严重性	检查内容
MISSING-FIELD	高	package.json 缺少 name、version、license 或 description 之一（每个缺失字段对应一条发现项）。
BIN-MISSING	高	package.json 中的 bin 路径不在随包发布的文件集中。
MAIN-MISSING	高	main 入口点不在随包发布的文件集中。
SECRET-LEAK	高	随包发布的文本文件匹配机密信息模式：私钥块头、AWS 访问密钥 ID 格式（AKIA 加 16 个字符）、经典 GitHub 令牌格式（ghp_ 加至少 36 个字符）、细粒度 GitHub 令牌格式（github_pat_ 前缀）、sk- API 密钥格式，或值较长且带引号的通用 api_key 风格赋值。证据仅包含模式 ID。
OVERSIZE	中	随包发布的文件总大小超过 10 MiB，或任一随包发布的文件超过 1 MiB（每个超大文件对应一条发现项）。
SCOPED-NO-PUBLISHCONFIG	中	软件包名称带作用域（以 @ 开头），且 publishConfig.access 不是 public。
NO-README	低	随包发布的文件集中没有 README 文件。
NO-ENGINES	信息	package.json 未声明 engines 范围。

每份报告都会统计随包发布的文件数及其总字节数，并按严重性统计发现项数量。

判定

• 没有高严重性发现项时判定为 READY。中、低和信息级发现项会显示在报告中，但不会影响判定结果。
• 存在至少一条高严重性发现项时判定为 FIX-FIRST。

已发布文件集的解析方式

• 如果 package.json 中有 files 数组，则会包含其中列出的路径： 文件会直接添加，目录则会递归遍历。 只要存在，package.json、README 和 LICENSE 始终会被包含， 无论是否列在其中；这与 npm 的行为一致。
• 如果没有 files 数组，则会包含目录中的所有内容， 但 node_modules、.git 以及 .npmignore（如果存在）中匹配的路径除外。 即使忽略规则匹配到上述始终包含的文件，这些文件仍会被包含。
• 遍历最多处理 5000 个已发布文件。达到上限时， 报告会在计数中记录该情况（truncated: 1，并包含 filesSeen 和 maxFiles），渲染结果也会注明其余文件未被扫描。

限制

在相信检查结果为干净之前，请先阅读以下内容：

• 文件集是静态解析的，并非与字节完全一致的 npm pack 结果。 npm 还会应用更多规则（其自身始终排除的文件、生命周期生成的文件以及发布时间行为）， 静态检查不会复现这些规则。请将 npmpreflight 作为预检，然后使用 npm pack --dry-run 确认发布内容。
• .npmignore 仅支持简单子集：空行、# 注释、 普通行（任意层级的文件名或精确相对路径） 以及以 / 结尾的目录模式。不支持 .npmignore 中的 glob、否定规则和 字符类，此类行的匹配方式与 npm 不同。
• files 条目支持字面文件、字面目录、简单的 * 和 ** glob，以及对这些模式使用 ! 否定。 其他更复杂的模式会按字面解析，因此结果可能与 npm 不同。
• 密钥扫描仅会读取文本文件。如果文件被扫描的开头部分 含有 NUL 字节，则会被视为二进制文件并跳过。每个文件仅扫描前 512 KiB， 因此大型文件中超过该偏移位置的密钥不会被发现。模式描述的是特征，而非确证：匹配结果 可能来自测试样例或示例，而形状无法识别的真实凭据则不会匹配。
• 不会跟随符号链接，也不会发布符号链接。
• 输出具有确定性：发现项经过排序，计数保持稳定， 且不会输出时间戳。

开发

npm install
npm run build
npm test

许可证

MIT