@mznjs/qbump

v1.0.12

Published

4 months ago

版本号自动更新工具，支持 package.json 版本更新、CHANGELOG 生成、Git Tag 管理

0High
0Medium
0Low

supbose

version bump changelog git tag

版本号自动更新工具

功能介绍

自动化版本号管理工具，支持自动更新 package.json 版本号、提交代码、创建 Git Tag 并推送到远程仓库。

主要特性

✅ 支持多种版本类型（major/minor/patch/prerelease）
✅ 支持直接指定版本号
✅ 支持多 package.json 文件同步更新
✅ 自动检测未提交文件并询问是否一起提交
✅ 自动创建 Git Tag（可配置）
✅ 预览模式（--dry-run）
✅ 确认模式（--confirm）
✅ 不推送模式（--no-push）
✅ 不创建 Tag 模式（--no-tag）
✅ CHANGELOG.md 自动更新
✅ 配置文件支持
✅ 彩色输出

安装

无需额外安装，项目已集成该脚本。

基本用法

npm run bump [选项] [版本类型|版本号]

命令行选项

--help, -h

显示帮助信息并退出。

npm run bump --help

--dry-run, -d

预览模式，仅显示将要执行的操作，不实际修改文件或提交。

适用场景：确认版本更新计划是否符合预期。

npm run bump --dry-run
npm run bump -d minor

--confirm, -c

确认模式，在执行更新操作前显示确认提示。

适用场景：重要版本更新（如 major 版本），需要二次确认。

npm run bump --confirm major
npm run bump -c minor

--no-push, -n

不推送模式，更新版本并创建 tag，但不推送到远程仓库。

适用场景：本地测试或需要手动审核的场景。

npm run bump --no-push
npm run bump -n minor

--changelog, -l

更新 CHANGELOG.md 文件（如果存在），自动在文件顶部添加新版本记录。

npm run bump --changelog
npm run bump -l minor

--all, -a

更新所有 package.json 文件（递归查找），默认只更新根目录的 package.json。

适用场景：monorepo 项目或多 package.json 项目。

npm run bump --all
npm run bump -a minor

--files, -f

指定要更新的 package.json 文件列表（逗号分隔）。

适用场景：只需要更新特定的 package.json 文件。

npm run bump --files package.json,frontend/package.json
npm run bump -f "package.json,apps/*/package.json"

--no-tag, -t

不创建 Git Tag。默认会创建 tag（格式：v{版本号}）。

适用场景：不需要 tag 的场景，如内部版本更新。

npm run bump --no-tag
npm run bump -t minor

版本类型

major

主版本号递增，适用于不兼容的 API 变更。

格式: X.Y.Z → (X+1).0.0
示例: 1.2.3 → 2.0.0

npm run bump major

minor

次版本号递增，适用于向后兼容的功能新增。

格式: X.Y.Z → X.(Y+1).0
示例: 1.2.3 → 1.3.0

npm run bump minor

patch（默认）

补丁版本号递增，适用于向后兼容的问题修复。

格式: X.Y.Z → X.Y.(Z+1)
示例: 1.2.3 → 1.2.4

npm run bump
npm run bump patch

prerelease

创建预发布版本，适用于测试和预览版本。

格式: X.Y.Z → X.Y.(Z+1)-rc.N
示例: 1.2.3 → 1.2.4-rc.0 → 1.2.4-rc.1

npm run bump prerelease

直接指定版本号

支持直接传入版本号，无需使用版本类型。

格式: X.Y.Z 或 X.Y.Z-xxx.N
示例: npm run bump 2.0.0

npm run bump 2.0.0
npm run bump 1.5.0-rc.0

快捷命令

在 package.json 中已配置以下快捷命令：

npm run bump          # 补丁版本（默认，仅根目录）
npm run bump:patch    # 补丁版本（仅根目录）
npm run bump:minor    # 次版本（仅根目录）
npm run bump:major    # 主版本（仅根目录）

配置文件

可在 package.json 中添加 bump 配置，设置默认行为。配置后，运行 npm run bump 时会自动使用这些配置。

{
  "bump": {
    "commitMessage": "chore: bump version to {{version}}",
    "tagPrefix": "v",
    "tag": true,
    "changelog": true,
    "confirm": false,
    "files": ["package.json", "frontend/package.json"]
  }
}

配置项详细说明

commitMessage

类型: string
默认值: chore: 版本更新到 {{version}}
说明: Git 提交信息模板，支持模板变量替换。
模板变量: {{version}} - 会被替换为实际的新版本号。
示例:
- "chore: bump version to {{version}}" → 提交信息为 chore: bump version to 1.0.0
- "feat: release {{version}}" → 提交信息为 feat: release 1.0.0
建议: 遵循 Conventional Commits 规范，便于生成 CHANGELOG 和版本管理。

tagPrefix

类型: string
默认值: v
说明: Git Tag 的前缀。
示例:
- "v" → 创建的 tag 为 v1.0.0
- ""（空字符串）→ 创建的 tag 为 1.0.0
- "release-" → 创建的 tag 为 release-1.0.0
用途: 便于区分不同类型的版本标签，或符合团队的标签命名规范。

changelog

类型: boolean
默认值: false
说明: 是否自动更新 CHANGELOG.md 文件。
取值:
- true: 如果项目根目录存在 CHANGELOG.md，会自动在文件顶部添加新版本记录
- false: 不更新 CHANGELOG.md

更新格式: 自动在 CHANGELOG.md 顶部添加以下格式的内容：

## [1.0.0] - 2024-01-15

### Features

### Bug Fixes

### Breaking Changes

注意: 仅当 CHANGELOG.md 文件存在时才会更新。

confirm

类型: boolean
默认值: false
说明: 是否默认启用确认模式，在执行更新前提示用户确认。
取值:
- true: 每次运行时都会显示确认提示（相当于每次使用 --confirm 选项）
- false: 直接执行更新，不提示确认
适用场景:
- true: 重要版本更新（如 major 版本），需要二次确认
- false: 日常小更新，无需确认

files

类型: array
默认值: ["package.json"]
说明: 默认更新的 package.json 文件列表，支持相对路径。
示例:
- ["package.json"] → 仅更新根目录的 package.json
- ["package.json", "frontend/package.json"] → 更新根目录和 frontend 目录的 package.json
- ["package.json", "apps/mobile/package.json", "apps/desktop/package.json"] → 更新多个 package.json
用途: 适用于 monorepo 项目或包含多个 package.json 的项目，确保所有相关版本号同步更新。

配置优先级

配置项的优先级从高到低依次为：

命令行选项 - 最高优先级，会覆盖配置文件中的设置
package.json 中的 bump 配置 - 默认配置
脚本内置默认值 - 最低优先级

示例:

如果在 package.json 中设置 "confirm": true，但运行时使用 npm run bump --no-confirm，则不会显示确认提示（命令行选项优先）。
如果在 package.json 中设置 "tag": false，则每次运行时默认不创建 tag，除非使用 --tag 选项覆盖。

完整配置示例

{
  "name": "my-project",
  "version": "1.0.0",
  "scripts": {
    "bump": "node scripts/bump-version.js"
  },
  "bump": {
    "commitMessage": "chore(release): bump version to {{version}}",
    "tagPrefix": "v",
    "tag": true,
    "changelog": true,
    "confirm": true,
    "files": [
      "package.json",
      "frontend/package.json",
      "backend/package.json"
    ]
  }
}

配置说明:

提交信息格式为 chore(release): bump version to {{version}}
Tag 前缀为 v，生成的 tag 如 v1.0.1
自动创建 tag
自动更新 CHANGELOG.md
每次更新前需要确认
同时更新根目录、frontend 和 backend 目录的 package.json

多 package.json 文件更新

自动查找所有 package.json

使用 --all 选项，工具会递归查找项目中所有 package.json 文件（排除 node_modules）：

npm run bump --all
npm run bump -a minor

指定特定文件

使用 --files 选项，指定要更新的 package.json 文件：

npm run bump --files package.json,frontend/package.json
npm run bump -f "package.json,apps/mobile/package.json"

配置文件默认值

在 package.json 中配置默认文件列表：

{
  "bump": {
    "files": ["package.json", "frontend/package.json"]
  }
}

配置后，运行 npm run bump 会自动更新这些文件。

工作流程

读取当前 package.json 中的版本号
根据指定类型计算新版本号（或使用指定的版本号）
检测是否有未提交的文件（可选一起提交）
更新所有指定的 package.json 文件
更新 CHANGELOG.md（如果启用 --changelog 选项）
提交变更到 Git（提交信息格式：chore: 版本更新到 {版本号}）
创建版本 Tag（格式：v{版本号}）
推送 commits 和 tags 到远程仓库（除非使用 --no-push）

使用示例

# 基础用法
npm run bump                    # 更新补丁版本（仅根目录）
npm run bump minor              # 更新次版本号（仅根目录）

# 多文件更新
npm run bump --all              # 更新所有 package.json 文件的补丁版本
npm run bump --all minor        # 更新所有 package.json 文件的次版本号
npm run bump --files "package.json,frontend/package.json"  # 更新指定文件

# 带选项的用法
npm run bump --dry-run          # 预览补丁版本更新操作，不实际执行
npm run bump --confirm major    # 更新主版本号，执行前需要确认
npm run bump --no-push          # 更新版本但不推送
npm run bump --changelog patch  # 更新补丁版本并更新 CHANGELOG

# 组合使用
npm run bump -d -c prerelease   # 预览预发布版本并确认
npm run bump 2.0.0 --no-push    # 直接指定版本号，不推送
npm run bump --all --confirm    # 更新所有文件并确认

交互功能

未提交文件检测

当检测到有未提交的文件时，会列出文件列表并询问是否一起提交：

⚠️  检测到以下未提交的文件：
   [M] src/components/Example.vue
   [A] src/utils/new-file.js

是否将这些文件一起提交？(y/n, 默认y):

按回车或输入 y/yes：将所有未提交文件一起提交
输入 n/no：仅提交 package.json 版本变更

确认模式

使用 --confirm 选项时，执行前会显示确认提示：

确认执行以上操作？(y/n, 默认y):

输出示例

成功执行（单文件）

🚀 版本号自动更新工具

当前版本: 0.0.33
目标版本: 0.0.34
更新文件: package.json

开始执行更新...
✓ package.json 已更新
✓ 文件已暂存
✓ 提交成功
✓ 已创建 tag: v0.0.34
✓ 已推送 commits
✓ 已推送 tags

🎉 版本更新完成！
旧版本: 0.0.33
新版本: 0.0.34
更新文件: package.json

成功执行（多文件）

🚀 版本号自动更新工具

当前版本: 0.0.33
目标版本: 0.0.34
更新文件: frontend/package.json, package.json

开始执行更新...
✓ frontend/package.json 已更新
✓ package.json 已更新
✓ 文件已暂存
✓ 提交成功
✓ 已创建 tag: v0.0.34
✓ 已推送 commits
✓ 已推送 tags

🎉 版本更新完成！
旧版本: 0.0.33
新版本: 0.0.34
更新文件: frontend/package.json, package.json

预览模式

🚀 版本号自动更新工具

当前版本: 0.0.33
目标版本: 0.0.34
更新文件: frontend/package.json, package.json

💡 预览模式 - 不会执行实际操作

将执行的操作:
  1. 更新 frontend/package.json 版本: 0.0.33 → 0.0.34
  2. 更新 package.json 版本: 0.0.33 → 0.0.34
  3. 提交变更
  4. 创建 tag: v0.0.34
  5. 推送 commits 和 tags

CHANGELOG 更新

使用 --changelog 选项时，工具会自动从 Git 提交记录中提取变更内容并填充到 CHANGELOG.md 中。

Emoji 风格分类（类似 changelogen）

工具会自动分析自上一个 tag 以来的所有 Git 提交，并根据 Conventional Commits 规范分类，使用 emoji 标识类型：

| 类型 | Emoji | 分类标题 | |------|-------|----------| | feat/feature | 🚀 | 新增功能 | | fix/bugfix | 🩹 | 缺陷修复 | | perf/performance | 🔥 | 性能优化 | | refactor | ♻️ | 代码重构 | | docs | 📝 | 文档更新 | | style | 💄 | 代码格式 | | chore | 🔧 | 工具变更 | | build | 📦 | 构建变更 | | ci | 👷 | CI 变更 | | test | ✅ | 测试更新 | | revert | ⏪ | 回滚提交 | | break/breaking | 💥 | 破坏性变更 |

变更条目格式

每条变更按以下格式显示：

- 提交信息 (文件名1, 文件名2)

示例：

## [1.0.0] - 2024-01-15

🚀 新增功能

- feat(auth): 添加用户登录功能 (auth.js, login.vue)
- feat(i18n): 支持多语言切换 (i18n.js)

🩹 缺陷修复

- fix(login): 修复登录页面样式问题 (login.vue)
- fix(api): 修复数据加载缓慢的问题 (api.js)

🔧 工具变更

- chore: 更新依赖版本 (package.json)
- chore(build): 优化构建脚本 (webpack.config.js)

如果文件不存在

自动创建 CHANGELOG.md 文件，并填充提交记录：

# 更新日志 (Changelog)

本项目的所有重要变更都将记录在此文件中。

格式遵循 [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)，
本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。

## [1.0.0] - 2024-01-15

🚀 新增功能

- feat(auth): 添加用户登录功能 (auth.js)
- feat(i18n): 支持多语言切换 (i18n.js)

🩹 缺陷修复

- fix(login): 修复登录页面样式问题 (login.vue)

如果文件存在

在文件顶部添加新版本记录，并自动填充提交内容：

## [1.0.1] - 2024-01-16

🚀 新增功能

- feat(export): 添加导出功能 (export.js)

🩹 缺陷修复

- fix(export): 修复导出按钮点击无响应的问题 (export.vue)

... (原有内容)

智能格式检测

工具会自动检测现有 CHANGELOG.md 的格式：

标题格式：检测是使用 ## [version] 还是 ## version 格式
章节级别：检测是使用 ### 还是其他级别
自动适配：根据检测结果使用相同的格式添加新版本

提交信息格式支持

支持标准的 Conventional Commits 格式：

<type>(<scope>): <subject>

例如：

feat(auth): 添加用户登录功能
fix(login): 修复登录按钮样式
chore: 更新依赖版本
refactor(core): 重构核心模块

也支持非标准格式，会自动识别关键词：

包含 "fix", "bug" → 归类为修复
包含 "feat", "new" → 归类为新增
包含 "break", "major" → 归类为破坏性变更

执行效果

🚀 版本号自动更新工具

当前版本：0.0.44
目标版本：0.0.45

开始执行更新...
✓ package.json 已更新
✓ CHANGELOG.md 已更新
  📝 自动收录了 5 条提交记录
✓ 文件已暂存
✓ 提交成功

注意事项

如果没有提交记录（commits.length === 0），会显示"待补充"章节
如果没有使用规范的提交格式，所有提交会归类到"变更"章节
建议在提交时使用 Conventional Commits 规范，以获得更好的 CHANGELOG 生成效果

注意事项

确保当前工作目录是 Git 仓库
确保已配置正确的 Git 远程仓库地址
建议在执行重要版本更新前使用 --dry-run 预览
预发布版本不会自动升级为正式版本
Git 提交信息遵循约定式提交规范（Conventional Commits）
CHANGELOG.md 更新功能仅在文件存在时生效
使用 --all 选项时，会自动排除 node_modules 目录

版本历史

v1.3.0

CHANGELOG 生成优化，采用 emoji 风格分类（类似 changelogen）
变更条目显示关联的文件名
修复多提交记录解析问题，确保所有提交都能正确写入 CHANGELOG

v1.2.0

新增 --all, -a 选项，支持自动查找所有 package.json 文件
新增 --files, -f 选项，支持指定要更新的文件列表
支持在配置文件中设置默认文件列表

v1.1.0

新增 --no-push 选项，支持本地模式
新增 --changelog 选项，自动更新 CHANGELOG.md
支持直接指定版本号
新增配置文件支持（package.json 中的 bump 字段）

v1.0.0

支持 major/minor/patch/prerelease 版本类型
添加 --dry-run 预览模式
添加 --confirm 确认模式
添加彩色输出
支持未提交文件检测和批量提交
自动创建 Git Tag 并推送

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

版本号自动更新工具

功能介绍

主要特性

安装

基本用法

命令行选项

--help, -h

--dry-run, -d

--confirm, -c

--no-push, -n

--changelog, -l

--all, -a

--files, -f

--no-tag, -t

版本类型

major

minor

patch（默认）

prerelease

直接指定版本号

快捷命令

配置文件

配置项详细说明

commitMessage

tagPrefix

tag

changelog

confirm

files

配置优先级

完整配置示例

多 package.json 文件更新

自动查找所有 package.json

指定特定文件

配置文件默认值

工作流程

使用示例

交互功能

未提交文件检测

确认模式

输出示例

成功执行（单文件）

成功执行（多文件）

预览模式

CHANGELOG 更新

Emoji 风格分类（类似 changelogen）

变更条目格式

如果文件不存在

如果文件存在

智能格式检测

提交信息格式支持

执行效果

注意事项

注意事项

相关文件

版本历史

v1.3.0

v1.2.0

v1.1.0

v1.0.0