zudit

English | 简体中文

面向 npm、pnpm、Yarn 的依赖审计流水线：可对本地路径、远程 Git 仓库（GitHub、GitLab、Gogs、Bitbucket、Azure DevOps 等）或 registry 上的 npm 包执行审计。默认在 .zudit/ 下生成原始 audit.json、规范化 standard.json 以及 HTML 报告。

npm 包名： z-audit · 命令行： zudit

功能概览

• 支持本地单体仓库与单包；在可行时尽量沿用已有 lockfile
• 远程 Git URL，可选分支/标签、托管方提示，必要时 git clone（shallow/full）
• 通过 npm:包@版本 或 --npm-name / --npm-version 审计 registry 包
• 统一流水线：工作区 → 分析 → lockfile → npm audit / pnpm audit / yarn 审计 JSON → 报告
• 可选 zudit.config.json（从当前工作目录向上查找）；可用 zudit init 生成模板。CLI 参数覆盖配置文件。
• 配置文件可写 "$schema" 指向随包发布的 zudit.config.schema.json，便于编辑器补全与校验
• 库接口：runAuditPipeline 及更底层模块（见 package exports）

环境要求

• Node.js ≥ 18
• PATH 上可用的包管理器（按需：npm、pnpm、yarn）

安装

npm install -g z-audit

或不全局安装，用 npx（需显式指定包名与 CLI 名）：

npx -p z-audit zudit --help

（若使用作用域包名，请将 z-audit 换成实际发布名，例如 @scope/z-audit。）

快速开始

# 审计当前目录（与 `zudit .` 相同）
zudit

# 显式指定本地路径
zudit .

# 在当前目录生成可选的 zudit.config.json
zudit init

# 远程仓库
zudit --project https://github.com/org/repo.git --branch main

# 私有仓库 / 依赖 API：建议用环境变量传 token
export ZUDIT_TOKEN=…
zudit --project https://github.com/org/private.git

# 审计 npm registry 上的包
zudit --npm-name axios --npm-version 1.4.0

命令行

zudit init [选项]
zudit [选项] [<项目>]
zudit audit [选项] [<项目>]

| 选项 | 说明 | |------|------| | -h, --help | 显示帮助 | | -c, --config <path> | zudit.config.json 路径 | | -p, --project <path> | 本地路径、Git URL 或 npm:包@版本 | | --npm-name, --npm-version | 从 registry 审计包（与普通 project 路径互斥） | | --provider <id> | github | gitlab | gogs | bitbucket | azure-devops | unknown | | --branch, --tag | 远程引用（解析 package.json / 锁文件） | | --token | API 令牌（优先使用 ZUDIT_TOKEN） | | --locale | 报告语言，如 zh-CN、en | | --package-manager | npm | pnpm | yarn-berry | yarn-classic | | --report-root, --report-file | 报告目录与 audit.json 文件名 | | --git-clone | shallow | full（远程 Git 克隆分析） |

优先级： CLI 覆盖 zudit.config.json。令牌：--token > ZUDIT_TOKEN > 配置文件。

配置

可在项目目录树中放置可选的 zudit.config.json（除非指定 --config，否则从 cwd 向上查找）。若不使用配置文件且未传 --project，单独执行 zudit 时默认审计当前目录（.）。

{
  "$schema": "./node_modules/z-audit/zudit.config.schema.json",
  "project": ".",
  "locale": "zh-CN",
  "packageManager": "npm",
  "analyzeOptions": {
    "packageJsonRef": { "source": "branch", "name": "main" }
  },
  "auditReport": {
    "reportRootDir": ".zudit",
    "reportFileName": "audit.json"
  }
}

勿将密钥提交进仓库；请使用 ZUDIT_TOKEN 等方式注入令牌。

环境变量

| 变量 | 作用 | |------|------| | ZUDIT_TOKEN | 私有远程 / API 鉴权（优先于写进配置） | | ZUDIT_LOCALE | 未指定 --locale 时的默认界面/报告语言 | | ZUDIT_STRICT_ENGINES | 设为 1 时在生成 lockfile 场景下严格校验 engines | | LANG | 语言解析的回退来源 |

在用到 HTTP 客户端的地方，会遵循常见代理变量（HTTPS_PROXY、HTTP_PROXY、ALL_PROXY 等）。

编程调用

import { runAuditPipeline } from 'z-audit';

const result = await runAuditPipeline({
  project: '.',
  locale: 'en',
});
console.log(result.reportPath, result.standardReportPath, result.htmlReportPath);

导入 runAuditPipeline 会加载内部 bootstrap（远程处理器等）。当前 exports 仅暴露主入口；请从包根路径按上例导入。

开发

git clone <你的仓库地址>
cd <目录>
npm install
npm run build
npm test

从源码运行 CLI：

npm run zudit -- --help

许可证

MIT