@kinngyo/np

轻量级 npm 包发布助手，支持单包和 monorepo workspace 多包发布。

自动检测远程版本 → 交互选择升级策略 → 确认变更 → 发布，全程处理版本管理、git 操作和发布流程。

功能特性

• 🔍 自动检测远程版本，智能推荐版本号
• 🎯 交互式版本选择，支持 alpha / beta / rc / patch / minor / major
• 🏷️ 根据升级策略自动推断 npm tag（prerelease → next，stable → latest）
• 🔒 发布前 Git 工作区检查 + npm 登录状态检测
• 📦 支持 scoped / 非 scoped 包，自动推断 access
• 🏢 支持 npm workspaces 多包发布（changed / select / unified / individual）
• 🔄 workspace: 协议自动替换与恢复
• 🛡️ 发布失败自动回滚版本号
• 🔕 静默模式，适用于 CI/CD 环境
• 🧪 dry-run 预演模式，验证发布可行性

安装使用

免安装使用：

npx @kinngyo/np            # 交互式发布
npx @kinngyo/np publish    # 直接发布当前版本
npx @kinngyo/np diff       # 查看本地与远程版本差异

安装后使用：

# yarn
yarn add @kinngyo/np -D

# npm
npm i @kinngyo/np --save-dev

np            # 交互式发布
np publish    # 直接发布当前版本
np diff       # 查看版本差异

命令

| 命令 | 说明 | | ------------ | -------------------------------------------------- | | np | 交互式发布：选择升级策略 → 确认 → 发布 | | np publish | 直接发布当前版本，不修改版本号（仍执行预检和确认） | | np diff | 查看本地与远程版本差异 |

参数

| 参数 | 说明 | | ------------------------ | -------------------------------------------- | | -r, --root <path> | 项目根目录（默认 process.cwd()） | | --no-remote | 跳过远程版本查询 | | --tag <tag> | npm publish tag（如 latest、next），自动推断 | | --access <type> | 包访问级别：public / restricted，自动推断 | | --registry <url> | npm registry 地址 | | --skip-git-check | 跳过 git 工作区检查 | | --skip-auth-check | 跳过 npm 登录检查 | | --any-branch | 允许非默认分支发布 | | --no-confirm | 跳过发布确认 | | --dry-run | 预演模式，展示变更 + dry-run 验证 | | --ignore-scripts | 跳过 npm 生命周期脚本 | | --commit-message <msg> | 自定义 git commit message | | --log-level <level> | 日志级别：silent / normal / verbose | | -v, --version | 显示版本号 |

升级策略与 tag 自动推断

交互发布时选择升级策略，npm tag 根据策略自动推断：

| 策略 | tag | 示例（从 1.0.1 升级） | 示例（从 1.0.1-alpha.0 升级） | | ----- | ------ | --------------------- | ----------------------------- | | alpha | next | 1.0.2-alpha.0 | 1.0.1-alpha.1 | | beta | next | 1.0.2-beta.0 | 1.0.1-beta.0 | | rc | next | 1.0.2-rc.0 | 1.0.1-rc.0 | | patch | latest | 1.0.2 | 1.0.1 | | minor | latest | 1.1.0 | 1.1.0 | | major | latest | 2.0.0 | 2.0.0 |

可通过 --tag 或 publishConfig.tag 覆盖推断结果。

publishConfig 配置

在 package.json 中配置默认值：

{
    "publishConfig": {
        "registry": "https://registry.npmjs.org/",
        "access": "public",
        "tag": "beta"
    }
}

配置优先级

CLI 参数 > publishConfig > 默认值

| 配置项 | CLI 参数 | publishConfig 字段 | 默认值 | | ------------- | ------------ | ------------------ | --------------------------------------------- | | npm tag | --tag | tag | 由升级策略自动推断 | | 包访问级别 | --access | access | scoped 包 restricted，非 scoped 包 public | | registry 地址 | --registry | registry | undefined（npm 默认源） |

registry 优先级：CLI --registry > 子包 publishConfig.registry > 根包 publishConfig.registry > undefined（npm 默认源）

发布流程

单包项目

环境预检
  ├─ 检查是否在 git 仓库内
  ├─ 检查工作区是否存在未提交变更
  ├─ 检查 npm 登录状态（仅警告，不终止）
  └─ 检查当前分支是否为默认分支（仅警告）
  │
  ▼
版本决策
  ├─ 查询远程最新版本
  ├─ 比对本地/远程版本，确定基准版本
  └─ 选择升级策略 → 计算目标版本 + 自动推断 tag
  │
  ▼
变更确认
  ├─ 展示变更清单（包名、版本、tag、access）
  ├─ --dry-run: npm publish --dry-run 验证
  └─ 交互确认（--no-confirm 跳过）
  │
  ▼
执行发布
  ├─ 更新 package.json 版本号
  ├─ git add + commit + tag
  └─ npm publish
  │
  ▼
结果报告
  ├─ 发布结果汇总（成功/失败/跳过）
  ├─ npm 包链接
  └─ git push 提示

workspaces 项目

在 workspaces 项目根目录执行 np 时，会自动检测并列出可发布的包，支持以下策略：

| 策略 | 说明 | | ---------- | ------------------------ | | changed | 仅发布有变更的包（默认） | | select | 交互式多选要发布的包 | | unified | 统一升级策略 | | individual | 逐包独立选择 |

环境预检（根目录，仅一次）
  │
  ▼
选择 workspace 发布策略
  │
  ▼
逐包：查询远程版本 → 比对 → 选择版本号 → 更新 package.json（不提交）
  │
  ▼
替换 workspace: 协议为实际版本号
  │
  ▼
逐包 npm publish（按拓扑排序，被依赖者优先）
  │
  ▼
恢复 workspace: 协议
  │
  ▼
统一提交 (chore(release): [email protected], [email protected])
  │
  ▼
结果报告

注意事项

1. 登录状态：默认会检查 npm 登录状态（npm whoami），未登录时警告但不终止，最终认证以 npm publish 结果为准
2. Git 检查：默认会检查 Git 工作区是否干净，有未提交更改时会报错终止
3. 跳过检查：--skip-git-check 跳过 Git 检查，--skip-auth-check 跳过登录检查
4. 分支检查：非默认分支发布时警告，--any-branch 可抑制
5. workspaces 自动检测：通过 package.json 中的 workspaces 字段扫描文件系统检测（支持 npm/yarn，不支持 pnpm-workspaces.yaml 和 lerna.json）
6. workspace 协议：发布前自动将 workspace: 和裸 * 依赖替换为实际版本号，发布后恢复为原始协议；失败时立即恢复
7. 失败回滚：发布失败时自动回滚 package.json 版本号至发布前状态
8. 中断恢复：重试时版本已发布的包自动跳过（检测 npm publish 的 "already published" 错误），避免重复发布

License

MIT