# @cleyrop-org/semantic-release-backmerge 中文文档

规范地址：https://npmcn.com/package/%40cleyrop-org/semantic-release-backmerge/

版本：6\.2\.0
npm 元数据更新时间：2026-07-31T09:57:16.315Z
中文译文更新时间：2026-11-10T01:21:59.749Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40cleyrop-org/semantic-release-backmerge
原文对照：https://npmcn.com/package/%40cleyrop-org/semantic-release-backmerge/?lang=original
项目主页：https://gitlab.com/cleyrop-org/semantic-release-backmerge
源码仓库：https://gitlab.com/cleyrop-org/semantic-release-backmerge

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

- 包体积（解压后）：81.7 kB，30 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^22\.14\.0 \|\| \>=24\.10\.0
- 运行依赖：5 个
- peer 依赖：semantic-release \>=24
- 首次发布：2025-10-18T20:49:51.540Z
- 最新版本发布：2026-07-31T09:57:16.060Z
- 近 30 天下载量：49034（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 3 个）

## 中文简介

语义-放出插件以回放放入发展分支. @saithodev/ semantic-release-back 由马里奥·卢本卡(英语:Mario Lubenka)出道,由克莱罗普组织维护.

## 安装

```sh
npm install @cleyrop-org/semantic-release-backmerge
```

也可以使用：`pnpm add @cleyrop-org/semantic-release-backmerge`、`yarn add @cleyrop-org/semantic-release-backmerge`、`bun add @cleyrop-org/semantic-release-backmerge`

## README

# @cleyrop-org/semantic-release-back-communication (中文(简体) )

> **最初创建于 [马里奥·卢本卡 (@saithodev)](https://github.com/saitho/semantic-release-backmerge)** 由Jean Humman为种植业组织维护和加强

[**语义释放**](https://github.com/semantic-release/semantic-release) 插件以返回到您的开发分支中 [图形](https://git-scm.com/) 仓库.

[![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) [![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/) ![Gitlab Code Coverage](https://img.shields.io/gitlab/pipeline-coverage/cleyrop-org%2Fsemantic-release-backmerge?branch=main) ![NPM Version](https://img.shields.io/npm/v/%40cleyrop-org%2Fsemantic-release-backmerge) ![NPM Downloads](https://img.shields.io/npm/dw/%40cleyrop-org%2Fsemantic-release-backmerge)

## 这是什么插件?

这个插件可以自动从出产/放出分行(例如, `main`编号 :`master`发展部门(例如, `develop`编号 :`next`)作为你语义释放工作流程的一部分. 这对使用 **Git 流量** 或类似的分支策略.

### 何时使用此插件

-   你分别维持生产和开发分支
-   您想要自动同步释放回您的开发分支
-   您使用语义放出自动版本和发布
-   发布后需要保持开发分支的一致性

### 重要说明

**语义释放** 在其核心中不为具有稳定和不稳定分支的Git Flow工作流程所设计. 此插件允许这样的工作流程, 但是 **不保证** 所有情景中无缝操作.

⚠️ **热补版** 可能导致与需要人工解决的开发分支的合并冲突. 在这种情况下,发布工作流程会出故障,导致CI/CD管道故障.

| 步骤 | 说明 |
| --- | --- |
| `verifyConditions` | 验证远程 Git 仓库的访问权限并验证 `backmergeBranches` 配置 . |
| `done` | 如果发行成功, 则在配置的分支中创建后置 . |

## 安装

```bash
npm install @cleyrop-org/semantic-release-backmerge --save-dev
```

## 使用量

配置您的插件 [**语义释放** 配置文件](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/configuration.md#configuration)数字 :

**重要内容:** 此插件会重新建立或合并您的开发分支与您的生产分支 。 保证您在工作空间中没有未显示的文件,或者使用 [`clearWorkspace`](https://npmcn.com/package/%40cleyrop-org/semantic-release-backmerge/#readme-clearworkspace) 选择暂时隐藏它们.

### 基本配置

```json
{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    [
      "@cleyrop-org/semantic-release-backmerge",
      {
        "backmergeBranches": ["develop"],
        "backmergeStrategy": "rebase"
      }
    ]
  ]
}
```

### 刻录后置配置

创建多层次后置链( 例如 ), `main` → `staging` → `develop`:

```json
{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    [
      "@cleyrop-org/semantic-release-backmerge",
      {
        "backmergeBranches": [
          { "from": "main", "to": "staging" },
          { "from": "staging", "to": "develop" }
        ],
        "backmergeStrategy": "merge"
      }
    ]
  ]
}
```

当释放时 `main`,此配置将:

1.  备份 `main` → `staging`
2.  备份 `staging` → `develop` (从前一步起)

### 带有插件的高级配置

您可以在后置期间运行额外的插件来修改您的开发分支的文件 :

```json
{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    [
      "@cleyrop-org/semantic-release-backmerge",
      {
        "backmergeBranches": ["develop"],
        "plugins": [
          [
            "@semantic-release/exec",
            {
              "successCmd": "echo 'Version in main is ${nextRelease.version}' > VERSION.txt && git add VERSION.txt"
            }
          ]
        ]
      }
    ]
  ]
}
```

### CI/CD 平台实例

#### GitLab CI 语录

```yaml
release:
  stage: release
  image: node:24
  script:
    - npm ci
    - npx semantic-release
  only:
    - main
```

#### GitHub 动作

```yaml
- uses: actions/checkout@v4
  with:
    fetch-depth: 0
    persist-credentials: false # Required for backmerging into protected branches

- name: Setup Node.js
  uses: actions/setup-node@v4
  with:
    node-version: "24"

- name: Install dependencies
  run: npm ci

- name: Release
  env:
    GITHUB_TOKEN: ${{ secrets.GH_TOKEN }} # Use PAT with repo scope
  run: npx semantic-release
```

**GitHub 动作说明 :** 要回到受保护的树枝,你需要:

1.  禁用 `persist-credentials` 退出动作
2.  使用个人访问键 `repo` 范围 `GITHUB_TOKEN`
3.  确保令牌拥有者能够访问寄存器

#### 詹金斯(英语:

```groovy
withCredentials([usernamePassword(credentialsId: JENKINS_GIT_CREDENTIALS_ID,
                                  passwordVariable: 'GIT_PASSWORD',
                                  usernameVariable: 'GIT_USERNAME')]) {
    sh("git config credential.username ${GIT_USERNAME}")
    sh("git config credential.helper '!f() { echo password=$GIT_PASSWORD; }; f'")
}
withCredentials([usernameColonPassword(credentialsId: JENKINS_GIT_CREDENTIALS_ID,
                                        variable: 'GIT_CREDENTIALS')]) {
    nodejs(JENKINS_NODE_JS_INSTALLATION_LABEL) {
        sh("npx semantic-release")
    }
}
```

## 配置选项

### 核心选项

| 选项 | 说明 | 默认 |
| --- | --- | --- |
| `backmergeBranches` | 分支名称或源/目标路径以接收回流. 见 [细节](https://npmcn.com/package/%40cleyrop-org/semantic-release-backmerge/#readme-backmergeBranches)。 。 。 . | `['develop']` |
| `backmergeStrategy` | 如何进行后置: `rebase` 或者说 `merge`。见 [细节](https://npmcn.com/package/%40cleyrop-org/semantic-release-backmerge/#readme-backmergeStrategy)。 。 。 . | `rebase` |
| `message` | 提交后置信件( 如果文件已更改) 。 见 [细节](https://npmcn.com/package/%40cleyrop-org/semantic-release-backmerge/#readme-message)。 。 。 . | `chore(release): Preparations for next release [skip ci]` |
| `forcePush` | 强力推后起. 见 [细节](https://npmcn.com/package/%40cleyrop-org/semantic-release-backmerge/#readme-forcePush)。 。 。 . | `false` |
| `allowSameBranchMerge` | 允许与释放源重现为同一分支 . | `false` |
| `ignorePaths` | 每个目标分支的状态都有环球路径 每一条路都可以被推翻 见 [细节](https://npmcn.com/package/%40cleyrop-org/semantic-release-backmerge/#readme-ignorePaths)。 。 。 . | `[]` |

### 工作空间选项

| 选项 | 说明 | 默认 |
| --- | --- | --- |
| `clearWorkspace` | 在重新出现之前 做一些没有承诺的改变 见 [细节](https://npmcn.com/package/%40cleyrop-org/semantic-release-backmerge/#readme-clearWorkspace)。 。 。 . | `false` |
| `restoreWorkspace` | 返回后恢复已隐藏的更改 。 见 [细节](https://npmcn.com/package/%40cleyrop-org/semantic-release-backmerge/#readme-restoreWorkspace)。 。 。 . | `false` |

### 合并策略选项

| 选项 | 说明 | 默认 |
| --- | --- | --- |
| `mergeMode` | 使用时解决冲突 `merge` 战略。 见 [细节](https://npmcn.com/package/%40cleyrop-org/semantic-release-backmerge/#readme-mergeMode)。 。 。 . | `none` |
| `fastForwardMode` | 使用时快速前进选项 `merge` 战略。 见 [细节](https://npmcn.com/package/%40cleyrop-org/semantic-release-backmerge/#readme-fastForwardMode)。 。 。 . | `none` |

### 插件选项

| 选项 | 说明 | 默认 |
| --- | --- | --- |
| `plugins` | 返回时要运行的额外插件 。 见 [细节](https://npmcn.com/package/%40cleyrop-org/semantic-release-backmerge/#readme-plugins)。 。 。 . | `[]` |

### 性能选项

| 选项 | 说明 | 默认 |
| --- | --- | --- |
| `fetchDelay` | 获取后延迟( ms) 允许远程 git 提供者同步 。 见 [细节](https://npmcn.com/package/%40cleyrop-org/semantic-release-backmerge/#readme-fetchDelay)。 。 。 . | `3000` |

* * *

## 选项细节

### `backmergeBranches`

指定哪个分支应接收后置。 接受 :

-   **字符串阵列**: 简单的分支名称
-   **对象数组**: 有条件或连锁反应 `{from: "source", to: "target"}` 格式。 对象也可以定义 `ignorePaths` 只有这条路.

#### 实例

**简单的后置开发 :**

```json
{
  "backmergeBranches": ["develop"]
}
```

**多个分支 :**

```json
{
  "backmergeBranches": ["develop", "next"]
}
```

**有条件的后起:**

```json
{
  "backmergeBranches": [
    "develop",
    { "from": "main", "to": "staging" },
    { "from": "next", "to": "beta" }
  ]
}
```

在有条件的例子中:

-   全部释放回原地 `develop`
-   释放 `main` 重现为 `staging`
-   释放 `next` 重现为 `beta`

**连锁反应:**

```json
{
  "backmergeBranches": [
    { "from": "main", "to": "staging" },
    { "from": "staging", "to": "develop" }
  ]
}
```

在串连的例子中,当释放从 `main`数字 :

1.  首先, `main` 重现为 `staging`
2.  接下来, `staging` 重现为 `develop`

这就形成了一个级联: `main` → `staging` → `develop`

**串联方式:**

在当前发布工作流程中重新出现分支的插件跟踪 。 当它遇到一个 `{from: X, to: Y}` 配置 :

-   **有条件的后置**: 如果 `from` 等同尚未重现的释放分支 OR, 它只有在释放来源于该分支时才继续
-   **叠加回流**: 如果 `from` 已经是一个分支 `to` 目标在之前的后置中,它将会从该分支中合并,而不管释放来源如何

这允许您创建多层次后置链,同时保持与现有配置的后向兼容.

**混合配置示例 :**

```json
{
  "backmergeBranches": [
    "hotfix",
    { "from": "main", "to": "staging" },
    { "from": "staging", "to": "develop" }
  ]
}
```

当释放时 `main`数字 :

-   `main` → `hotfix` (简单反起)
-   `main` → `staging` (有条件反相)
-   `staging` → `develop` (cascing backcomming) (class independence) (笑声) (笑声)

#### 模板变量

你用得着 [Lodash 模板](https://lodash.com/docs#template) 分支名称中的语法 :

```json
{
  "backmergeBranches": ["${branch.name}-develop"]
}
```

可用变量 :

| 变量 | 说明 |
| --- | --- |
| `branch` | 释放分支对象 |
| `branch.name` | 分支名称 |
| `branch.type` | 分支类型(释放/提前释放/保养) |
| `branch.channel` | 分发渠道 |
| `branch.range` | 语义版本范围 |
| `branch.prerelease` | 预释标识符 |

### `backmergeStrategy`

确定开发分支如何从生产分支接收变化.

**选项 :**

-   `rebase` (默认):重放开发分支在生产上的承诺
-   `merge`: 创建从生产到发展的合并承诺

**示例**

```json
{
  "backmergeStrategy": "merge"
}
```

### `plugins`

在后置阶段运行额外的语义放出插件. 用于修改开发分支的文件(如更新版本文件,添加dev后缀).

**重要内容:** 插件必须将其更改级为 Git (`git add`(a) 列入后出现的承诺.

**示例**

```json
{
  "plugins": [
    [
      "@semantic-release/exec",
      {
        "successCmd": "npm version ${nextRelease.version}-dev --no-git-tag-version && git add package.json"
      }
    ]
  ]
}
```

### `message`

自定义用于后起后起的承诺信件 [Lodash 模板](https://lodash.com/docs#template) 语法.

**可用变量 :**

| 变量 | 说明 |
| --- | --- |
| `branch` | 释放分支对象(见上文结构) |
| `lastRelease` | 前一次释放( E)`version`, (中文(简体) ), `gitTag`, (中文(简体) ), `gitHead`(中文(简体) ) |
| `nextRelease` | 目前发布( O)`version`, (中文(简体) ), `gitTag`, (中文(简体) ), `gitHead`, (中文(简体) ), `notes`(中文(简体) ) |

**示例**

```json
{
  "message": "chore: merge v${nextRelease.version} into develop [skip ci]"
}
```

**提示 :** 包含 `[skip ci]` 防止触发另一个CI构建.

### `forcePush`

强制推后向开发分支.

⚠️ **警告:** 这将覆盖开发部门中 不生产的承诺。 用得非常谨慎!

```json
{
  "forcePush": true
}
```

### `clearWorkspace`

在尝试后退前 将未承诺的改变固定下来.

```json
{
  "clearWorkspace": true
}
```

### `restoreWorkspace`

返回完成后恢复隐藏的更改 。 只有有意义的 `clearWorkspace: true`。 。 。 .

```json
{
  "clearWorkspace": true,
  "restoreWorkspace": true
}
```

### `ignorePaths`

路径列表 **排除** 从后起而来。 合并/再基后,每个 列表路径恢复为 **目标分支** 后起后起状态,所以任何 源分支上的更改永远不会被结转。 两人的工作 `merge` 财务报告和审定财务报表 `rebase` 战略.

这对于每个分支必须相去甚远的文件有用,否则将是 被后起后起-典型的版本指针或放出矩阵所打碎 持有不同的值 `staging` 对 `develop`。 。 。 .

```json
{
  "backmergeBranches": [
    { "from": "main", "to": "staging" },
    {
      "from": "staging",
      "to": "develop",
      "ignorePaths": ["version-matrix.yaml.jinja"]
    }
  ],
  "backmergeStrategy": "merge"
}
```

在这个例子中, `version-matrix.yaml.jinja` 仅在 倒计时 `staging` 输入 `develop`;它仍然包括在 `main` 改为 `staging` 再来一次.

高层 `ignorePaths` 选项继续支持并适用于每个 再来一次 特定路线 `ignorePaths` 值优先 路线。 使用空路由特定数组禁用全局排除 一条路线:

```json
{
  "ignorePaths": ["version-matrix.yaml.jinja"],
  "backmergeBranches": [
    {
      "from": "main",
      "to": "staging",
      "ignorePaths": []
    },
    { "from": "staging", "to": "develop" }
  ]
}
```

**行为 :**

-   重置每个匹配的文件 **整体** 转到目标分支的版本(不是线下相接).
-   发布分支上存在的文件, 但是 **没有** 目标被删除,结果与目标完全吻合.
-   路径规格(包括光谱等). `"values/**"`) 匹配无一被跳出——它们从未中止后起.

### `mergeMode`

使用时 `backmergeStrategy: "merge"`,决定解决冲突的战略.

**选项 :**

-   `none` (默认):没有自动解决(冲突失败)
-   `ours`: 优先开发分支变化
-   `theirs`: 偏好生产分支变化

```json
{
  "backmergeStrategy": "merge",
  "mergeMode": "theirs"
}
```

### `fastForwardMode`

使用时 `backmergeStrategy: "merge"`控制快速前进的行为.

**选项 :**

-   `none` (默认):与 `ff`
-   `ff`: 尽可能快速前进, 合并另作承诺
-   `no-ff`: 总是创建合并承诺
-   `ff-only`:只有快前行,如果不可能,则失败

```json
{
  "backmergeStrategy": "merge",
  "fastForwardMode": "no-ff"
}
```

### `fetchDelay`

在抓取更新本地分支引用前, 推入远程寄存器后延迟( 毫秒) 。 这样可以让远程 git 提供者(GitHub, GitLab, Bitbucket)有更多的时间来充分处理并同步推力操作.

**为什么你可能需要这个:**

-   远程 git 提供者在按下完成后到这些更改可供后续抓取操作之间可能有一个小的延迟
-   这是 **对连锁反应至关重要** 其中一个后起之推力必须在下一个后起之取来之前完全可见到远程
-   网络延迟、CDN传播和API处理可造成时间问题
-   没有这一拖延,后起后起可能不包括所有预期的承付款

**默认 :** `3000` (3秒钟)

**实例:**

禁用本地寄存器的延迟或更快的 CI :

```json
{
  "fetchDelay": 0
}
```

增加较慢网络或远程提供者的延迟 :

```json
{
  "fetchDelay": 5000
}
```

**说明:** 默认的3秒延迟为大多数远程 git 提供者提供了合理的缓冲. 只有在遇到与时间相关的失败或想要优化本地寄存器的 CI 速度时才调整 .

## 保护部门

重现为受保护的分支 :

1.  使用有管理员/维护权限的证书
2.  提供适当的访问标志(例如:, `GITHUB_TOKEN`, (中文(简体) ), `GITLAB_TOKEN`(中文(简体) )
3.  对于 GitHub 动作, 禁用 `persist-credentials` 退出动作

## 解决问题

### 合并冲突

如果由于冲突而自动后置失败 :

1.  手动解决您的发展分支中的冲突
2.  下一次发布会再次尝试重现

### 工作空间问题

如果遇到"未实现的更改"错误:

-   设定 `clearWorkspace: true` 自动隐藏更改
-   设定 `restoreWorkspace: true` 如果您需要恢复这些更改

### CI/CD 管道循环

确保您的承诺消息包含 `[skip ci]` 或等同防止无限放出回路.

### 归来问题

若相克相克后起相克相克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克, `main` → `staging` → `develop`不包括所有预期承诺:

**症状:**

-   来自第一个分支(例如, `main`)不出现于最终分支(如, `develop`(中文(简体) )
-   合并信件引用正确的分支但历史不完整
-   综合测试显示级联链中缺少承诺

**解决方案 :**

1.  **增加获取**: 默认的3秒延迟可能不足以满足一些远程提供者的需要
    
    ```json
    {
      "fetchDelay": 5000
    }
    ```
    
2.  **用于当地测试**设置 `fetchDelay: 0` 由于本地 git 寄存器没有同步延迟
    
    ```json
    {
      "fetchDelay": 0
    }
    ```
    
3.  **检查远程配置**: 确保您的 git 遥控器被正确配置为 `origin`
    
    ```bash
    git remote -v
    ```
    

**技术说明:** 该插件使用 `git fetch origin` 用于更新远程跟踪分支。 如果您的远程程序名称不同, 您可能需要调整您的 git 配置或创建一个 `origin` 别名.

## 捐款

欢迎捐款! 请看 [捐款额](https://npmcn.com/package/%40cleyrop-org/semantic-release-backmerge/CONTRIBUTING.md) 准则.

## 许可证

麻省理工学院许可证 - 详情见LICENSE文件

## 承认

这个项目是原作的叉子和续作 [`@saithodev/semantic-release-backmerge`](https://github.com/saitho/semantic-release-backmerge) 创建于 [马里奥·卢本卡](https://github.com/saitho)感谢基础性的工作,并保持了这一分叉,以提供持续的支持和增强.

## 链接

-   [GitLab 仓库](https://gitlab.com/cleyrop-org/semantic-release-backmerge)
-   [国家防范机制一揽子计划](https://www.npmjs.com/package/@cleyrop-org/semantic-release-backmerge)
-   [语义释放文档](https://semantic-release.gitbook.io/)

## 常见问题

### @cleyrop-org/semantic-release-backmerge 是什么？

语义-放出插件以回放放入发展分支\. @saithodev/ semantic-release-back 由马里奥·卢本卡\(英语:Mario Lubenka\)出道,由克莱罗普组织维护\.

### 如何安装 @cleyrop-org/semantic-release-backmerge？

在项目目录运行 npm install @cleyrop-org/semantic-release-backmerge，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：semantic-release（\>=24）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @cleyrop-org/semantic-release-backmerge 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cleyrop-org/semantic-release-backmerge 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @cleyrop-org/semantic-release-backmerge 需要什么版本的 Node\.js？

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

### @cleyrop-org/semantic-release-backmerge 可以商用吗？

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

### @cleyrop-org/semantic-release-backmerge 的下载量有多少？

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

### @cleyrop-org/semantic-release-backmerge 还在维护吗？

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