# @dwmkerr/standard-version 中文文档

规范地址：https://npmcn.com/package/%40dwmkerr/standard-version/

版本：8\.3\.0
npm 元数据更新时间：2022-04-05T06:11:51.531Z
中文译文更新时间：2026-11-13T04:27:46.713Z
软件包许可：ISC

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

原始 npm 页面：https://www.npmjs.com/package/%40dwmkerr/standard-version
原文对照：https://npmcn.com/package/%40dwmkerr/standard-version/?lang=original
项目主页：https://github.com/conventional-changelog/standard-version#readme
源码仓库：https://github.com/conventional-changelog/standard-version

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

- 包体积（解压后）：132 kB，44 个文件
- TypeScript 类型：未声明
- Node.js 要求：\>=8\.0
- 运行依赖：15 个
- 首次发布：2020-05-19T06:31:03.973Z
- 最新版本发布：2020-05-20T03:50:08.507Z
- 近 30 天下载量：2322（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 0 个）

## 中文简介

替换为 `npm version` 自动生成变换组

## 安装

```sh
npm install @dwmkerr/standard-version
```

也可以使用：`pnpm add @dwmkerr/standard-version`、`yarn add @dwmkerr/standard-version`、`bun add @dwmkerr/standard-version`

## README

# 标准版本

用于使用版本的工具 [铸造](https://semver.org/) 和变换组发电 [常规武器委员会](https://conventionalcommits.org/)。 。 。 .

[![Build Status](https://travis-ci.org/conventional-changelog/standard-version.svg?branch=master)](https://travis-ci.org/conventional-changelog/standard-version) [![NPM version](https://img.shields.io/npm/v/standard-version.svg)](https://www.npmjs.com/package/standard-version) [![Coverage Status](https://coveralls.io/repos/conventional-changelog/standard-version/badge.svg?branch=)](https://coveralls.io/r/conventional-changelog/standard-version?branch=master) [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org/) [![Community slack](http://devtoolscommunity.herokuapp.com/badge.svg)](http://devtoolscommunity.herokuapp.com/)

_有问题吗? 想贡献吗? 加入我们的行列 [节点工具社区](http://devtoolscommunity.herokuapp.com/)_。 。 。 .

_如何运作:_

1.  跟着 [常规提交规格](https://conventionalcommits.org/) 在您的仓库.
2.  当你准备好释放,跑 `standard-version`。 。 。 .

`standard-version` 然后将采取下列行动:

1.  通过查看获取当前版本的仓库 `bumpFiles`[\[1\] (中文(简体) )](https://npmcn.com/package/%40dwmkerr/standard-version/#readme-bumpfiles-packagefiles-and-updaters),倒回最后一个 `git tag`。 。 。 .
2.  `bump` 该版本在 `bumpFiles`[\[1\] (中文(简体) )](https://npmcn.com/package/%40dwmkerr/standard-version/#readme-bumpfiles-packagefiles-and-updaters) 基于你的承诺.
3.  生成 a `changelog` 基于您的承诺(使用) [常规变化日志](https://github.com/conventional-changelog/conventional-changelog) 盖下.
4.  创建新 `commit` 包括你 `bumpFiles`[\[1\] (中文(简体) )](https://npmcn.com/package/%40dwmkerr/standard-version/#readme-bumpfiles-packagefiles-and-updaters) 并更新了变换组.
5.  创建新 `tag` 带有新版本编号.

### `bumpFiles`, (中文(简体) ), `packageFiles` 财务报告和审定财务报表 `updaters`

`standard-version` 使用一些关键概念处理您的工程中出现的版本.

-   **`packageFiles`** - 用户定义的文件,可从其中读取版本 _财务报告和审定财务报表_ 被"弹出".
    -   实例: `package.json`, (中文(简体) ), `manifest.json`
    -   在大多数情况下(包括违约), `packageFiles` 属于 `bumpFiles`。 。 。 .
-   **`bumpFiles`** – 用户定义的文件,其中版本应当"跳出",但没有明确读取.
    -   实例: `package-lock.json`, (中文(简体) ), `npm-shrinkwrap.json`
-   **`updaters`** - 用于阅读的简单模块 `packageFiles` 并写信给 `bumpFiles`。 。 。 .

默认, `standard-version` 假设你在基于节点JS的项目中工作... 因为这, 对于大多数的项目 你可能不需要与这些选项互动.

这么说,如果你发现自己问 [我如何使用标准版本来获取更多元数据文件,语言或版本文件?](https://npmcn.com/package/%40dwmkerr/standard-version/#readme-can-i-use-standard-version-for-additional-metadata-files-languages-or-version-files) - 这些配置选项会有所帮助!

### Java 支持

从盒子里出来, `standard-version` 支持 Maven 工程, 只要提供路径到您 `pom.xml` 作为软件包和凸起文件:

```sh
standard-version --packageFiles pom.xml --bumpFiles pom.xml
```

如果你使用"格拉德",那就指向 `build.gradle` 档案!

```sh
standard-version --packageFiles build.gradle --bumpFiles build.gradle
```

## 安装 `standard-version`

### 作为当地人 `npm run` 脚本

安装并添加到 `devDependencies`数字 :

```
npm i --save-dev standard-version
```

添加一个 [`npm run` 脚本](https://docs.npmjs.com/cli/run-script) 给您的 `package.json`数字 :

```json
{
  "scripts": {
    "release": "standard-version"
  }
}
```

现在你可以用 `npm run release` 替换 `npm version`。 。 。 .

这有利于使您的再集/包装更加便携,使其他开发者可以不需全球安装而剪切发布 `standard-version` 在他们的机器上.

### 作为全球 `bin`

全局安装( 添加到您的 `PATH`:

```
npm i -g standard-version
```

现在你可以用 `standard-version` 替换 `npm version`。 。 。 .

这可以让你使用 `standard-version` 在任何还原/包装上,不增加每件的依赖性.

### 使用 `npx`

截止 `npm@5.2.0`, (中文(简体) ), `npx` 安装在旁边 `npm`。使用 `npx` 您可以使用 `standard-version` 无需保留 `package.json` 运行时的文件 : `npx standard-version`。 。 。 .

这种方法在使用时特别有用 `standard-version` 在非贾瓦脚本项目中.

## 配置

您可以配置 `standard-version` 方法之一:

1.  设置 a `standard-version` 在你身边 `package.json` (假定 您的项目是 JavaScript .
2.  创建一个 `.versionrc`, (中文(简体) ), `.versionrc.json` 或者说 `.versionrc.js`。 。 。 .

-   如果你正在使用一个 `.versionrc.js` 您的默认导出必须是配置对象,或者函数返回配置对象.

任意命令行参数 `standard-version` 可改为 通过配置提供。 请参看 [常规变换log-配置- spec](https://github.com/conventional-changelog/conventional-changelog-config-spec/) 以获取关于可用配置选项的详情.

### 自定义变换组

默认(截至 `6.0.0`, (中文(简体) ), `standard-version` 使用该 [常规承诺预设](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-conventionalcommits)。 。 。 .

此预设 :

-   紧紧跟随 [常规承诺.org](https://www.conventionalcommits.org/) 规格.
-   高度可配置, 遵循配置规格 [在这儿维持](https://github.com/conventional-changelog/conventional-changelog-config-spec)。 。 。 .
    -   _我们记录了这些配置设置,作为给其他工具制造者的建议._

有多种拨号和取号,可以转接与ChangGELOG生成相关.

例如,假设您使用GitLab,而不是GitHub,您可能会修改以下变量:

-   `commitUrlFormat`: 承诺消息中检测到的SHAs的URL格式.
-   `compareUrlFormat`:用于比较两个标记的URL格式.
-   `issueUrlFormat`: 用于链接问题的URL格式.

使这些URL符合GitLab的格式,而不是GitHub的格式.

## CLI 使用量

> **注:** 将嵌入式配置传递给 CLI 而不在 `package.json` 使用标记作为参数 `e.g. --skip.changelog`。 。 。 .

### 第一版发布

要生成您第一次发行的更改日志, 只需做:

```sh
# npm run script
npm run release -- --first-release
# global bin
standard-version --first-release
# npx
npx standard-version --first-release
```

这将标记释放 **在不撞倒版本的情况下 `bumpFiles`1个**。 。 。 .

等你准备好了,按下标记 `npm publish` 你的第一个释放。 \\o/ (% 1)

### 剪接释放

如果您通常使用 `npm version` 切换到新版本,请这样做:

```sh
# npm run script
npm run release
# or global bin
standard-version
```

只要您的 git 承诺消息是常规的和准确的, 你不再需要指定 semver 类型 - 并且免费获得 ChangGELOG 生成 ! \\o/ (% 1)

剪辑后,你可以推出新的git标签和 `npm publish` (或 `npm publish --tag next`当你准备好了.

### 作为释放前释放

使用旗帜 `--prerelease` 生成预放:

假设您的代码的最后版本是 `1.0.0`,而要执行的代码则补丁了修改。 运行 :

```bash
# npm run script
npm run release -- --prerelease
```

这将标记您的版本为: `1.0.1-0`。 。 。 .

如果您想要指定发行前的名称,请通过 `--prerelease <name>`。 。 。 .

例如,假设你的预释应该包含 `alpha` 前缀 :

```bash
# npm run script
npm run release -- --prerelease alpha
```

这将标记该版本为: `1.0.1-alpha.0`

### 作为目标类型的释放`npm version`\- 喜欢)

放弃自动版本的凸起使用 `--release-as` 与论据 `major`, (中文(简体) ), `minor` 或者说 `patch`。 。 。 .

假设您的代码的最后版本是 `1.0.0`你只着陆了 `fix:` 承诺,但 你希望你的下次释放成为 `minor`。简单运行如下:

```bash
# npm run script
npm run release -- --release-as minor
# Or
npm run release -- --release-as 1.1.0
```

你会得到版本 `1.1.0` 而不是自动生成的版本 `1.0.1`。 。 。 .

> **注:** 你可以结合 `--release-as` 财务报告和审定财务报表 `--prerelease` 生成释放。 这在发布实验特性时是有用的.

### 防止金钩

如果像承诺前一样使用"git"钩子,在承诺前测试你的代码,可以防止在承诺步骤中通过"通过"来验证"钩子 `--no-verify` 选项 :

```sh
# npm run script
npm run release -- --no-verify
# or global bin
standard-version --no-verify
```

### 签名提交和标记

如果您设置了 GPG 密钥, 请添加 `--sign` 或者说 `-s` 标记为您的 `standard-version` 命令.

### 生命周期脚本

`standard-version` 支持生命周期脚本。 这些可以让你执行 拥有发布期间的补充命令。 以下内容: 钩子可用并按文件顺序执行:

-   `prerelease`: 在事发前被处决. 如果 `prerelease` 脚本返回 a 非零退出代码,版本将中止,但不会对 进程.
-   `prebump`编号 :`postbump`: 版本被撞出前后执行. 如果 `prebump` 脚本返回一个版本 #, 它将被使用而不是 以 `standard-version`。 。 。 .
-   `prechangelog`编号 :`postchangelog`: 生成 ChangeGELOG 前后执行.
-   `precommit`编号 :`postcommit`:在承诺步骤前后呼叫.
-   `pretag`编号 :`posttag`:在标记步骤前后调用.

简单地在您的软件包中添加以下内容. json 来配置生命周期脚本 :

```json
{
  "standard-version": {
    "scripts": {
      "prebump": "echo 9.9.9"
    }
  }
}
```

作为从使用 GitHub 跟踪您的项目到使用您的项目的一个实例 Jira 使用 a `postchangelog` 替换包含'https://github.com/'的url碎片的脚本`myproject`/问题/' 与您的 Jira 链接 - 假设您已经安装 [替换](https://www.npmjs.com/package/replace)

```json
{
  "standard-version": {
    "scripts": {
      "postchangelog": "replace 'https://github.com/myproject/issues/' 'https://myjira/browse/' CHANGELOG.md"
    }
  }
}
```

### 跳过生命周期步骤

你可以跳过任何生命周期步骤(`bump`, (中文(简体) ), `changelog`, (中文(简体) ), `commit`, (中文(简体) ), `tag`, (中文(简体) ), 在您的软件包中添加以下内容

```json
{
  "standard-version": {
    "skip": {
      "changelog": true
    }
  }
}
```

### 在释放命令中提交生成的艺术

如果您想在释放中承诺生成的文物(例如:. [96号](https://github.com/conventional-changelog/standard-version/issues/96)),可以使用 `--commit-all` 或者说 `-a` 旗帜。 你将需要展示你想要的艺术品,所以你 `release` 命令可能像这样 :

```json
"prerelease": "webpack -p --bail",
"release": "git add <file(s) to commit> && standard-version -a"
```

### 干运行模式

运行 `standard-version` 与旗帜 `--dry-run` 让你看到什么 命令将运行,而不承诺对文件进行配置或更新.

```sh
# npm run script
npm run release -- --dry-run
# or global bin
standard-version --dry-run
```

### 前缀标记

标记前缀为 `v` 默认。 如果你想用别的东西前缀标签,你可以用 `-t` 旗帜.

```sh
standard-version -t @scope/package\@
```

这将在标记前加个前缀, 以看起来像 `@scope/package@2.0.0`

如果您不想有任何标记前缀, 您可以使用 `-t` 无值的旗帜.

### CLI 帮助

```sh
# npm run script
npm run release -- --help
# or global bin
standard-version --help
```

## 代码使用

```js
const standardVersion = require('standard-version')

// Options are the same as command line, except camelCase
// standardVersion returns a Promise
standardVersion({
  noVerify: true,
  infile: 'docs/CHANGELOG.md',
  silent: true
}).then(() => {
  // standard-version is done
}).catch(err => {
    console.error(`standard-version failed with message: ${err.message}`)
})
```

_TIP: 使用 `silent` 选项 `standard-version` 从打印到打印 `console`。 。 。 ._

## 财务问题

### 怎么样 `standard-version` 与 `semantic-release`? 吗?

[`semantic-release`](https://github.com/semantic-release/semantic-release) 描述为:

> 语义-放出将整个包放出工作流程自动化,包括:确定下个版本号,生成放出注释并发布包.

虽然两者都基于结构化承诺信息的同一基础, `standard-version` 通过处理版本、更改日志生成和为您指定标签, 采取了不同的方法 **无** 自动推( to GitHub) 或发布( to a npm register). 使用 `standard-version` 只影响您的本地 git repo - 它根本不影响远程资源。 跑完你再说 `standard-version`,你可以审查你的释放状态,纠正错误并遵循对你的代码库最有意义的释放策略.

我们鼓励人们使用 `semantic-release` 改为 `standard-version` 如果用起来合理的话.

### 公关合并时,我是否应该总是犯错?

当合并拉力请求时,壁球的指示假定: **一个公关最多等于一个特性或固定**。 。 。 .

如果您拥有多个特性或固定在单个PR中着陆,并且每个承诺使用结构化消息,那么在接受PR时就可以进行标准合并. 这将保存承诺历史 从您的分支合并后.

尽管这将使每个承诺作为单独的条目列入您的变换组,但条目将 **没有** 能够引用调取更改的PR,因为保存的承诺信息不包括PR号码.

为此,我们建议将每项公关的范围保持在一个一般特征或固定。 在实践中,这允许您在每次小改动时使用无结构化的传输消息,然后在经过审查和接受后,用结构化的信息(参考PR号码)将其压入一个单一的承诺中.

### 我可以用吗 `standard-version` 用于额外的元数据文件、语言或版本文件?

截至版本 `7.1.0` 您可以配置多个 `bumpFiles` 财务报告和审定财务报表 `packageFiles`。 。 。 .

1.  指定自定义 `bumpFile` " (中文(简体) )`filename`",这是路径到文件 你想"跳"
    
2.  指定 `bumpFile` " (中文(简体) )`updater`",这是 _怎么样_ 文件会被撞倒.
    
    (单位:千美元) 如果使用普通类型,您可以使用其中的一种 `standard-version`内置 `updaters` 通过指定一个 `type`。 。 。 .
    
    b. 如果您使用不太常用的版本文件, 您可以创建自己的文件 `updater`。 。 。 .
    

```js
// .versionrc
{
  "bumpFiles": [
    {
      "filename": "MY_VERSION_TRACKER.txt",
      // The `plain-text` updater assumes the file contents represents the version.
      "type": "plain-text"
    },
    {
      "filename": "a/deep/package/dot/json/file/package.json",
      // The `json` updater assumes the version is available under a `version` key in the provided JSON document.
      "type": "json"
    },
    {
      "filename": "VERSION_TRACKER.json",
      //  See "Custom `updater`s" for more details.
      "updater": "standard-version-updater.js"
    }
  ]
}
```

#### 自定义 `updater`编号

一个 `updater` 的 Javascript 模块中 _起码_ 两种方法曝光: `readVersion` 财务报告和审定财务报表 `writeVersion`。 。 。 .

##### `readVersion(contents = string): string`

这种方法用于从提供的文件内容读取版本.

返回值预计为语义版本字符串.

##### `writeVersion(contents = string, version: string): string`

这种方法用于将版本写入提供的内容.

返回值将直接写入(覆盖)提供的文件 .

* * *

假设我们 `VERSION_TRACKER.json` 有下列内容:

```json
{
  "tracker": {
    "package": {
      "version": "1.0.0"
    }
  }
}

```

一个可以接受的 `standard-version-updater.js` 将:

```js
// standard-version-updater.js
const stringifyPackage = require('stringify-package')
const detectIndent = require('detect-indent')
const detectNewline = require('detect-newline')

module.exports.readVersion = function (contents) {
  return JSON.parse(contents).tracker.package.version;
}

module.exports.writeVersion = function (contents, version) {
  const json = JSON.parse(contents)
  let indent = detectIndent(contents).indent
  let newline = detectNewline(contents)
  json.tracker.package.version = version
  return stringifyPackage(json, indent, newline)
}
```

## 许可证

公务员制度委员会

## 常见问题

### @dwmkerr/standard-version 是什么？

替换为 npm version 自动生成变换组

### 如何安装 @dwmkerr/standard-version？

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

### @dwmkerr/standard-version 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/dwmkerr\_\_standard-version 是否存在。

### @dwmkerr/standard-version 需要什么版本的 Node\.js？

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

### @dwmkerr/standard-version 可以商用吗？

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

### @dwmkerr/standard-version 的下载量有多少？

根据 npm 官方下载统计，@dwmkerr/standard-version 在 2026/10/13 – 2026/11/11 这 30 天内被下载 2,322 次，日均约 77 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @dwmkerr/standard-version 还在维护吗？

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