# @codedependant/semantic-release-docker 中文文档

规范地址：https://npmcn.com/package/%40codedependant/semantic-release-docker/

版本：8\.0\.0
npm 元数据更新时间：2026-08-29T02:45:37.637Z
中文译文更新时间：2026-11-10T06:31:07.199Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40codedependant/semantic-release-docker
原文对照：https://npmcn.com/package/%40codedependant/semantic-release-docker/?lang=original
项目主页：https://github.com/esatterwhite/semantic-release-docker#readme
源码仓库：https://github.com/esatterwhite/semantic-release-docker

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

- 包体积（解压后）：66.4 kB，40 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>=20
- 运行依赖：7 个
- 首次发布：2020-07-24T18:30:42.273Z
- 最新版本发布：2026-08-29T02:45:37.322Z
- 近 30 天下载量：48984（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：31（近 12 个月 5 个）

## 中文简介

嵌入套件

## 安装

```sh
npm install @codedependant/semantic-release-docker
```

也可以使用：`pnpm add @codedependant/semantic-release-docker`、`yarn add @codedependant/semantic-release-docker`、`bun add @codedependant/semantic-release-docker`

## README

# @ codedependant/ semantic- release- docker (英语)

[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release) [![MIT license](https://img.shields.io/npm/l/@codedependant/semantic-release-docker.svg)](https://www.npmjs.com/package/@codedependant/semantic-release-docker)

A 类 [语义释放](https://github.com/semantic-release/semantic-release) 对嵌入器图像使用语义化版本的插件 .

## 支持的步骤

### 校验条件

验证通过用户名和密码进行认证的环境变量. 它使用一个通过配置或环境变量(首选)提供的注册服务器,或者默认在不给出的情况下使用嵌入器中枢. 它还通过登录到特定登记册核实证书正确无误.

### 准备

使用指定的嵌入器文件和上下文构建图像。 此图像将在后期步骤中用于创建标记

### 发布

将带有指定标记的图像推到注册处. 标记支持简单的导出 [手柄栏](https://handlebarsjs.com/). 括号中的数值 `{{}}` 将替换为发布上下文信息

## 安装

运行 `npm i --save-dev @codedependant/semantic-release-docker` 安装此语义释放插件.

## 配置

### Docker 注册认证

认证到 a `docker registry` 通过环境变量设置。 不需要,如果 中,它被假定在目标注册处已经认证了 docker 守护进程 .

### 环境变量

| 变量 | 说明 |
| --- | --- |
| 登记时间: | 在登记处进行认证的用户名. |
| 密码: | 用于登记册认证的密码. |

### 选项

| 选项 | 说明 | 类型 | 默认 |
| --- | --- | --- | --- |
| `dockerTags` | _可选_。可以指定用于图像的额外标记的字符串。 支持调制 | [阵列](https://mdn.io/array)<[字符串](https://mdn.io/string)\> 翻译: | \[`latest`, (中文(简体) ), `{{major}}-latest`, (中文(简体) ), `{{version}}`\[ . \] |
| `dockerImage` | _可选_。要释放的图像名称. | [字符串](https://mdn.io/string) | 从 package.json 解析 `name` 属性 |
| `dockerRegistry` | _可选_。登记册格式中所使用的主机名和端口 `hostname[:port]`如果注册使用默认端口,则关闭端口 | [字符串](https://mdn.io/string) | `null` (鸟叫声) |
| `dockerProject` | _可选_。将图像发布到 | [字符串](https://mdn.io/string) | 对于范围包,将使用范围,否则 `null` |
| `dockerPlatform` | _可选_。列出要建造的目标平板电脑。 如果指定, [构建x](https://docs.docker.com/reference/cli/docker/buildx/build) 用于生成最终图像 | [阵列](https://mdn.io/array)<[字符串](https://mdn.io/string)\> 翻译: | `null` (默认嵌入器构建行为) |
| `dockerFile` | _可选_路径,相对于 `$PWD` 创建目标图像 | [字符串](https://mdn.io/string) | `Dockerfile` |
| `dockerContext` | _可选_路径,相对于 `$PWD` 用作建构上下文A | [字符串](https://mdn.io/string) | `.` |
| `dockerLogin` | _可选_。如果点球守护进程已经获得授权,则设定通过点球登录来伪造它 | [字符串](https://mdn.io/string) | `true` |
| `dockerArgs` | _可选_中包含嵌入器的额外值 `build-arg`。支持调温 | [对象](https://mdn.io/object) |  |
| `dockerPublish` | _可选_。在发布阶段自动推动图像标记. | [布尔](https://mdn.io/boolean) | `true` |
| `dockerVerifyCmd` | _可选_如果指定,在验证阶段,指定的命令将在构建图像的容器中执行。 如果命令出错,则发布失败. | [字符串](https://mdn.io/string) | `false` |
| `dockerNetwork` | _可选_。指定图像构建时要使用的多克网络。 设置此值为 `null` 明确从构建命令中删除网络旗 | [字符串](https://mdn.io/string) | `default` |
| `dockerAutoClean` | _可选_。如果设置为真 | [布尔](https://mdn.io/boolean) | `true` |
| `dockerBuildFlags` | _可选_中添加标记的对象 `docker build` 命令。 值可以是字符串或一系列字符串 | [对象](https://mdn.io/object) | `{}` |
| `dockerBuildCacheFrom` | _可选_。外部缓存来源列表。 见 [\--cache - from (从)](https://docs.docker.com/engine/reference/commandline/build/#cache-from) | [字符串](https://mdn.io/string) | [阵列](https://mdn.io/array)<[字符串](https://mdn.io/string)\> 翻译: |  |

### 构建X 支持

5.X版本包括通过该版本对多平台图像的初步和实验支持 [构建x](https://docs.docker.com/reference/cli/docker/buildx/build) 插件 . 此插件假设已正确设置了 Docker 守护进程和 builtx . 必须为此插件设置和选择平台特定构建器以使用 [构建x](https://docs.docker.com/reference/cli/docker/buildx/build)

> \[尖叫声\]
> 
> 在通过多克Platform 选项使用 builtx 时, 图像不保存在本地 而针对这些图像的普通道克命令不会成功. 这个 `dockerVerifyCmd` 行为只触发构建, 无法执行本地命令

#### 证明书

当推进注册时, [构建x](https://docs.docker.com/reference/cli/docker/buildx/build) 附上a [来源证明](https://docs.docker.com/build/metadata/attestations/slsa-provenance/#create-provenance-attestations) (单位:千美元)`mode=min`改为: 默认图像索引。 这额外 `unknown/unknown` 显示在指数上,有些 登记册和集装箱运行时间完全拒绝----特别是AWS Lambda集装箱图像.

证明(和SBOM)的证明可以通过 `dockerBuildFlags`数字 :

```javascript
{
  dockerBuildFlags: {
    provenance: false
  , sbom: false
  }
}
```

或者设置 `BUILDX_NO_DEFAULT_ATTESTATIONS=true` 在环境中,释放会进入.

### 构建参数

默认情况下,在建起嵌入器图像时会包含几个构建参数 . 构建参数可以和道克标记一样被模板. 如果一个值 构建参数是明确的 `true`中,该值将被省略,该值来自 将取而代之的是相应的环境变量。 这在试图纳入时可能有用 机密和其他敏感信息

| 参数名称 | 说明 | 默认 |
| --- | --- | --- |
| `SRC_DIRECTORY` | 该构建的目录是从 | CWD 的目录名称 |
| `TARGET_PATH` | 相对于执行根的路径 。 用于在单重机中共享单个嵌入器文件 |  |
| `NPM_PACKAGE_NAME` | 这个 `name` 从 `package.json` - 如果有的话 |  |
| `NPM_PACKAGE_SCOPE` | 从 `name` 属性从 `package.json` - 萨斯 `@` |  |
| `CONFIG_NAME` | 嵌入器图像的已配置名称 . | 解析的软件包名称 |
| `CONFIG_PROJECT` | 配置的 Docker Repo 工程名称 | 如果有包范围 |
| `GIT_SHA` | 当前发行的 SHA 承诺 |  |
| `GIT_TAG` | 当前发行的 git 标签 |  |

### 模板变量

字符串模板将会通过这些

| 可变名称 | 说明 | 类型 |
| --- | --- | --- |
| `git_sha` | 当前发行的 SHA 承诺 | [字符串](https://mdn.io/string) |
| `git_tag` | 当前发行的 git 标签 | [字符串](https://mdn.io/string) |
| `release_type` | 当前建筑的重度类型(`major`, (中文(简体) ), `minor`, (中文(简体) ), `patch`(中文(简体) ) | [字符串](https://mdn.io/string) |
| `release_notes` | 发行笔记与发行相关的blob | [字符串](https://mdn.io/string) |
| `next` | 代表下次发行的 semver 对象 | [对象](https://mdn.io/object) |
| `previous` | 代表上次发行的 semver 对象 | [对象](https://mdn.io/object) |
| `major` | 下次发行的主要版本 | [数目](https://mdn.io/number) |
| `minor` | 下次发行的小版本 | [数目](https://mdn.io/number) |
| `patch` | 下次发行的补丁版本 | [数目](https://mdn.io/number) |
| `prerelease` | 下一次发行的预发版本 | [阵列](https://mdn.io/array)<[数目](https://mdn.io/number)\> 翻译: |
| `env` | 构建时设定的环境变量 | [对象](https://mdn.io/object) |
| `pkg` | 从 `package.json` | [对象](https://mdn.io/object) |
| `build` | 代表当前执行背景的随机构建散列 | [字符串](https://mdn.io/string) |
| `now` | 当前的时间戳是 ISO 8601 格式 | [字符串](https://mdn.io/string) |

### 模板帮助

以下手柄栏模板帮助器已预先安装

| 帮助者名称 | 说明 | 返回类型 | 示例 |
| --- | --- | --- | --- |
| `endswith` | 如果字符串以另一个结尾, 返回正则 | [布尔](https://mdn.io/boolean) | 
{{#if (endswith myvar 'ing')}}{{ othervar }}{{/if}}

 |
| `eq` | 如果两个值严格对等,则返回为真 | [布尔](https://mdn.io/boolean) | 

{{#if (eq var\_one var\_two)}}{{ var\_three }}{{/if}}

 |
| `gt` | 如果第一个值大于第二个值,则返回正数 | [布尔](https://mdn.io/boolean) | 

{{#if (gt var\_one var\_two)}}{{ var\_three }}{{/if}}

 |
| `gte` | 如果第一个值大于或等于第二个值,则返回正数 | [布尔](https://mdn.io/boolean) | 

{{#if (gte var\_one var\_two)}}{{ var\_three }}{{/if}}

 |
| `includes` | 如果输入(字符串qq阵列)包含第二个值,则返回正数 | [布尔](https://mdn.io/boolean) | 

{{#if (includes some\_array 'one')}}{{ var\_one }}{{/if}}

 |
| `lower` | 返回输入字符串的下大小写变量 | [字符串](https://mdn.io/string) | 

{{ lower my\_var }}

 |
| `lt` | 如果第一个值小于第二个,则返回正数 | [布尔](https://mdn.io/boolean) | 

{{#if (lt var\_one var\_two)}}{{ var\_three }}{{/if}}

 |
| `lte` | 如果第一个值小于或等于第二个值,则返回正数 | [布尔](https://mdn.io/boolean) | 

{{#if (lte var\_one var\_two)}}{{ var\_three }}{{/if}}

 |
| `neq` | 如果两个值不相等则返回为正 | [布尔](https://mdn.io/boolean) | 

{{#if (neq var\_one var\_two)}}{{ var\_three }}{{/if}}

 |
| `pick` | 返回第一个非无效值。 会请客的 `false` 作为值 | `any` | 

{{#with (pick var\_one, var\_two) as | value |}}{{ value }}{{/with}}

 |
| `split` | 将 csv 值分割为 javascript 数组 | [阵列](https://mdn.io/array) | 

{{#each (split csv\_value)}}{{ this }}{{/each}}

 |
| `startswith` | 如果字符串从另一个开始, 返回正则 | [布尔](https://mdn.io/boolean) | 

{{#if (starts myvar 'foo')}}{{ othervar }}{{/if}}

 |
| `upper` | 返回输入字符串的上大小写变量 | [字符串](https://mdn.io/string) | 

{{upper my\_var}}

 |

### 构建旗帜

使用 `dockerBuildFlags` 选项允许您向构建命令传递任意的旗帜. 如果标准选项不够, `dockerBuildFlags` 是一个完美的工作 直到可以添加头等舱支持。 这是考虑和先进的功能,你应该 在使用之前,你知道你打算做什么。 没有验证,也没有配置 需要的多克守护进程预计将在手前完成 .

在其中找到密钥 `dockerBuildFlags` 以下列方式作为命令行旗正常化:

-   如果密钥不是以一个开头 `-` 准备就绪
-   所有意外情况 `_` 将重写为 `-`
-   单字母密钥被认为是简指如. `p` 变成 `-p`
-   多字母键被认为是长形式,例如. `foo_bar` 变成 `--foo-bar`
-   如果值是数组,则每次发生时会重现旗子
-   A 类 `null` 值可能用于省略值并仅注入旗帜本身

#### 示例

```javascript
{
  plugins: [
    ['@codedependant/semantic-release-docker', {
      dockerImage: 'my-image',
      dockerRegistry: 'quay.io',
      dockerProject: 'codedependant',
      dockerCacheFrom: 'myname/myapp'
      dockerBuildFlags: {
        pull: null
      , target: 'release'
      },
      dockerArgs: {
        GITHUB_TOKEN: null
      }
    }]
  ]
}
```

此配置将生成以下构建命令

```bash
> docker build --network=default --quiet --tag quay.io/codedependant/my-image:abc123 --cache-from myname/myapp --build-arg GITHUB_TOKEN --pull --target release -f path/to/repo/Dockerfile /path/to/repo
```

## 使用量

**完整配置**数字 :

```javascript
// release.config.js

module.exports = {
  branches: ['main']
  plugins: [
    ['@codedependant/semantic-release-docker', {
      dockerTags: ['latest', '{{version}}', '{{major}}-latest', '{{major}}.{{minor}}'],
      dockerImage: 'my-image',
      dockerFile: 'Dockerfile',
      dockerRegistry: 'quay.io',
      dockerProject: 'codedependant',
      dockerPlatform: ['linux/amd64', 'linux/arm64']
      dockerBuildFlags: {
        pull: null
      , target: 'release'
      },
      dockerArgs: {
        API_TOKEN: null
      , RELEASE_DATE: new Date().toISOString()
      , RELEASE_VERSION: '{{next.version}}'
      }
    }]
  ]
}
```

结果 `quay.io/codedependant/my-image` 带有标签 `latest`, (中文(简体) ), `1.0.0`, (中文(简体) ), `1-latest` 编辑 `1.0` 由 `semantic-release`。 。 。 .

或者,使用全局选项 w/ 根配置

```json5
// package.json
{
  "name": "@codedependant/test-project"
  "version": "1.0.0"
  "release": {
    "extends": "@internal/release-config-docker",
    "dockerTags": ["latest", "{{version}}", "{{major}}-latest", "{{major}}.{{minor}}"],
    "dockerImage": "my-image",
    "dockerFile": "Dockerfile",
    "dockerRegistry": "quay.io",
    "dockerArgs": {
      "GITHUB_TOKEN": null
    , "SOME_VALUE": '{{git_sha}}'
    }
  }
}
```

这将产生以下结果: `1.2.0` 构建

```shell
$ docker build -t quay.io/codedependant/my-image --build-arg GITHUB_TOKEN --build-arg SOME_VALUE=6eada70 -f Dockerfile .
$ docker tag <SHA1> latest
$ docker tag <SHA1> 1.2.0
$ docker tag <SHA1> 1.2
$ docker tag <SHA1> 1-latest
$ docker push quay.io/codedependant/my-image
```

**最小配置**数字 :

```json
{
  "release": {
    "plugins": [
      "@codedependant/semantic-release-docker"
    ]
  }
}
```

-   一个软件包名称 `@codedependant/test-project` 居克项目名称的结果`codedependant` 图像名称 `test-project`
-   一个软件包名称 `test-project` 生成一个嵌入器图像名称 `test-project`

用于 1. 0.0 释放的默认嵌入器图像标记为 `1.0.0`, (中文(简体) ), `1-latest`, (中文(简体) ), `latest`

**示例预释配置**数字 :

```json
{
  "release": {
    "dockerTags": [
      "{{#if prerelease.[0]}}{{prerelease.[0]}}{{else}}latest{{/if}}",
      "{{major}}-{{#if prerelease.[0]}}{{prerelease.[0]}}{{else}}latest{{/if}}",
      "{{major}}.{{minor}}-{{#if prerelease.[0]}}{{prerelease.[0]}}{{else}}latest{{/if}}",
      "{{version}}"
    ]
  }
}
```

版本的嵌入标记 `1.2.3` 将会是 `1.2.3`, (中文(简体) ), `1.2-latest`, (中文(简体) ), `1-latest` 财务报告和审定财务报表 `latest` 版本的嵌入标记 `2.3.4-beta.6` 将会是 `2.3.4-beta.6`, (中文(简体) ), `2.3-beta`, (中文(简体) ), `2-beta` 财务报告和审定财务报表 `beta`

## GitHub 动作

通过曝光多个输出和环境变量,该插件对 github 动作有一些基本支持 在出版阶段

> \[尖叫声\]
> 
> 当使用builtx图像 shas时,每个平台都不同,因此直接使用 shas 不支持,并可能导致出乎意料的结果.

### 产出

| 名称 | 说明 | 实例 |
| --- | --- | --- |
| `docker_image` | 包括注册在内的嵌入器图像的全名,提供任何标签信息 | quay.io/编码依赖者/我的图像 |
| `docker_image_build_id` | 发布时用于初始构建图像的独特构建 ID |  |
| `docker_image_sha_short` | 适合引用图像的图像 sha 值的短版本 | `b94d27b9934d3e0` |
| `docker_image_sha_long` | 指向发布时所建图像的全sha256值 | `b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9` |

### 环境变量

| 名称 | 说明 | 实例 |
| --- | --- | --- |
| `SEMANTIC_RELEASE_DOCKER_IMAGE` | 包括注册在内的嵌入器图像的全名,提供任何标签信息 | quay.io/编码依赖者/我的图像 |
| `SEMANTIC_RELEASE_DOCKER_IMAGE_BUILD_ID` | 发布时用于初始构建图像的独特构建 ID |  |
| `SEMANTIC_RELEASE_DOCKER_IMAGE_SHA_SHORT` | 适合引用图像的图像 sha 值的短版本 | `b94d27b9934d3e0` |
| `SEMANTIC_RELEASE_DOCKER_IMAGE_SHA_LONG` | 指向发布时所建图像的全sha256值 | `b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9` |

## 发展

### Docker 书记官处

为了能够将认证证书推入本地登记册,需要sl证书. 此项目使用自签名的证书 。 重新生成证书运行如下:

```bash
$ openssl req -new -newkey rsa:2048 -days 365 -nodes -x509 -keyout server.key -out server.crt
```

**页:1**:当要求国防军时,必须是 `registry:5000` **页:1**: 当地登记册的全权证书为: **用户 :** `iamweasel`, (中文(简体) ), **过:** `secretsquirrel`

## 常见问题

### @codedependant/semantic-release-docker 是什么？

嵌入套件

### 如何安装 @codedependant/semantic-release-docker？

在项目目录运行 npm install @codedependant/semantic-release-docker，或使用 pnpm add / yarn add / bun add。

### @codedependant/semantic-release-docker 支持 TypeScript 吗？

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

### @codedependant/semantic-release-docker 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @codedependant/semantic-release-docker 需要什么版本的 Node\.js？

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

### @codedependant/semantic-release-docker 可以商用吗？

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

### @codedependant/semantic-release-docker 的下载量有多少？

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

### @codedependant/semantic-release-docker 还在维护吗？

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