# @achingbrain/semantic-release-github 中文文档

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

版本：0\.0\.2
npm 元数据更新时间：2023-05-03T10:43:34.339Z
中文译文更新时间：2026-11-05T17:50:28.220Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：63.9 kB，24 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>=14\.17
- 运行依赖：16 个
- peer 依赖：semantic-release \>=18\.0\.0-beta\.1
- 首次发布：2022-04-08T11:59:33.810Z
- 最新版本发布：2023-05-03T10:43:34.219Z
- 近 30 天下载量：132899（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 0 个）

## 中文简介

语义- 释放插件以发布 GitHub 发布并评论已发布的 Pull 请求/ 问题

## 安装

```sh
npm install @achingbrain/semantic-release-github
```

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

## README

# @semantic-release/ github (英语)

[**语义释放**](https://github.com/semantic-release/semantic-release) 发布一个插件 [GitHub 发布](https://help.github.com/articles/about-releases) 并评论发布的"拉出请求"/"问题".

[![Build Status](https://github.com/semantic-release/github/workflows/Test/badge.svg)](https://github.com/semantic-release/github/actions?query=workflow%3ATest+branch%3Amaster)

[![npm latest version](https://img.shields.io/npm/v/@semantic-release/github/latest.svg)](https://www.npmjs.com/package/@semantic-release/github) [![npm next version](https://img.shields.io/npm/v/@semantic-release/github/next.svg)](https://www.npmjs.com/package/@semantic-release/github) [![npm beta version](https://img.shields.io/npm/v/@semantic-release/github/beta.svg)](https://www.npmjs.com/package/@semantic-release/github)

| 步骤 | 说明 |
| --- | --- |
| `verifyConditions` | 验证认证的存在和有效性(通过 [环境变量](https://npmcn.com/package/%40achingbrain/semantic-release-github/#readme-environment-variables))和 [资产](https://npmcn.com/package/%40achingbrain/semantic-release-github/#readme-assets) 选项配置. |
| `publish` | 发布a [GitHub 发布](https://help.github.com/articles/about-releases),可选择上传文件资产. |
| `addChannel` | 更新a [GitHub 发布](https://help.github.com/articles/about-releases)是因为 `pre-release` 字段. |
| `success` | 在每个注释中添加注释 [GitHub 问题](https://help.github.com/articles/about-issues) 或者说 [拉请求](https://help.github.com/articles/about-pull-requests) 解决了释放问题和以前尚未解决的问题 `fail` 步骤. |
| `fail` | 打开或更新 a [GitHub 问题](https://help.github.com/articles/about-issues) 以及导致发行失败的错误信息. |

## 安装

```bash
$ npm install @semantic-release/github -D
```

## 使用量

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

```json
{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    ["@semantic-release/github", {
      "assets": [
        {"path": "dist/asset.min.css", "label": "CSS distribution"},
        {"path": "dist/asset.min.js", "label": "JS distribution"}
      ]
    }],
  ]
}
```

以此为例 [GitHub 发布](https://help.github.com/articles/about-releases) 将随文件一起发布 `dist/asset.min.css` 财务报告和审定财务报表 `dist/asset.min.js`。 。 。 .

## 配置

### GitHub 认证

GitHub 认证配置为 **所需经费** 并可以通过 [环境变量](https://npmcn.com/package/%40achingbrain/semantic-release-github/#readme-environment-variables)。 。 。 .

跟着 [为命令行创建个人访问符](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line) 文档以获取认证符。 必须在您的 CI 环境中通过 `GH_TOKEN` 环境变量。 与该令牌相关的用户必须具有向寄存器推出权限.

当创建符号时 **最低要求范围** 它们是:

-   [`repo`](https://github.com/settings/tokens/new?scopes=repo) 用于私人仓库
-   [`public_repo`](https://github.com/settings/tokens/new?scopes=public_repo) 公共存储器

_关于 GitHub 行动的说明:_ 您可以使用密件中提供的默认符号 _(原始内容存档于2018-10-21). GITHUB TOKEN_然而,使用此符号完成的发布不会触发启动其他工作流程的发布事件. 如果您有触发新创建的释放的动作, 请为此使用生成的代号, 并将其存储在您的存储库的秘密中( GITHUB TOKEN 以外的任何名称都很好) .

使用时 _(原始内容存档于2018-10-21). GITHUB TOKEN_,则 **最低许可** 它们是:

-   `contents: write` 能够发布 GitHub 发布
-   `issues: write` \* 能够就已公布的问题发表意见
-   `pull-requests: write` 能够对已发布的拉动请求进行评论

### 环境变量

| 变量 | 说明 |
| --- | --- |
| `GH_TOKEN` 或者说 `GITHUB_TOKEN` | **要求.** 用于认证与 GitHub 的标志 . |
| `GITHUB_API_URL` 或者说 `GH_URL` 或者说 `GITHUB_URL` | GitHub企业端点. |
| `GH_PREFIX` 或者说 `GITHUB_PREFIX` | GitHub Entertainment API前缀. |

### 选项

| 选项 | 说明 | 默认 |
| --- | --- | --- |
| `githubUrl` | GitHub企业端点. | `GH_URL` 或者说 `GITHUB_URL` 环境变量. |
| `githubApiPathPrefix` | GitHub Entertainment API前缀. | `GH_PREFIX` 或者说 `GITHUB_PREFIX` 环境变量. |
| `proxy` | 用于访问 GitHub API 的代理 。 设定为 `false` 以禁用代理服务器。 见 [代理服务器](https://npmcn.com/package/%40achingbrain/semantic-release-github/#readme-proxy)。 。 。 . | `HTTP_PROXY` 环境变量. |
| `assets` | 要上传到发布的文件阵列 。 见 [资产](https://npmcn.com/package/%40achingbrain/semantic-release-github/#readme-assets)。 。 。 . | \- 说吧 |
| `successComment` | 评论要加入每个问题,拉出请求通过发行解决. 设定为 `false` 以禁用对问题的评论并拉动请求。 见 [成功Comment](https://npmcn.com/package/%40achingbrain/semantic-release-github/#readme-successcomment)。 。 。 . | `:tada: This issue has been resolved in version ${nextRelease.version} :tada:\n\nThe release is available on [GitHub release](<github_release_url>)` |
| `failComment` | 发行失败时创建的问题内容 。 设定为 `false` 无法在发布失败时打开问题。 见 [失败Comment](https://npmcn.com/package/%40achingbrain/semantic-release-github/#readme-failcomment)。 。 。 . | 有链接的友好消息 **语义释放** 文档和支持,并列出导致发布失败的错误清单. |
| `failTitle` | 发行失败时创建的问题标题 。 设定为 `false` 无法在发布失败时打开问题. | `The automated release is failing 🚨` |
| `labels` | 这个 [标签](https://help.github.com/articles/about-labels) 以添加在发布失败时创建的问题。 设定为 `false` 不添加任何标签. | `['semantic-release']` |
| `assignees` | 这个 [受让人](https://help.github.com/articles/assigning-issues-and-pull-requests-to-other-github-users) 以添加在发布失败时创建的问题. | \- 说吧 |
| `releasedLabels` | 这个 [标签](https://help.github.com/articles/about-labels) 以添加每个问题,并拉动通过发行解决的请求。 设定为 `false` 不添加任何标签。 见 [已放出的标签](https://npmcn.com/package/%40achingbrain/semantic-release-github/#readme-releasedlabels)。 。 。 . | `['released<%= nextRelease.channel ? \` 在@${nextrelease. channel}#####$#nextRelease.channel####:"("""%>")- |
| `addReleases` | 将添加释放链接到 GitHub 释放 。 可能会 `false`, (中文(简体) ), `"bottom"` 或者说 `"top"`。见 [添加释放](https://npmcn.com/package/%40achingbrain/semantic-release-github/#readme-addReleases)。 。 。 . | `false` |

#### 代理服务器

可能会 `false`,一个代理 URL 或一个 `Object` 具有下列属性:

| 财产 | 说明 | 默认 |
| --- | --- | --- |
| `host` | **要求.** 要连接到的代理主机 . | \- 说吧 |
| `port` | **要求.** 要连接的代理端口 . | 从中提取的文件名 `path`。 。 。 . |
| `secureProxy` | 若为 `true`,然后使用 TLS 连接到代理服务器. | `false` |
| `headers` | 在HTTP CONNECT方法下发送额外的HTTP头. | \- 说吧 |

见 [节点- https- 代理代理](https://github.com/TooTallNate/node-https-proxy-agent#new-httpsproxyagentobject-options) 财务报告和审定财务报表 [节点- http- 代理代理](https://github.com/TooTallNate/node-http-proxy-agent) 其他细节.

##### 代理示例

`'http://168.63.76.32:3128'`: 使用运行在主机上的代理 `168.63.76.32` 和端口 `3128` 每个 GitHub API 请求. `{host: '168.63.76.32', port: 3128, headers: {Foo: 'bar'}}`: 使用运行在主机上的代理 `168.63.76.32` 和端口 `3128` 每个 GitHub API 请求,设置 `Foo` 页眉值为 `bar`。 。 。 .

#### 资产

可能是一个 [阴影](https://github.com/isaacs/node-glob#glob-primer) 或和 `Array` 联 合 国 [缩写](https://github.com/isaacs/node-glob#glob-primer) 财务报告和审定财务报表 `Object`s 有下列属性:

| 财产 | 说明 | 默认 |
| --- | --- | --- |
| `path` | **要求.** A 类 [阴影](https://github.com/isaacs/node-glob#glob-primer) 以识别要上传的文件. | \- 说吧 |
| `name` | GitHub 发行的可下载文件名称. | 从中提取的文件名 `path`。 。 。 . |
| `label` | GitHub 发布时显示的文件的简短描述 . | \- 说吧 |

表格中的每个条目 `assets` `Array` 被逐个地颂扬。 A 类 [阴影](https://github.com/isaacs/node-glob#glob-primer) 可能是一个 `String` (单位:千美元)`"dist/**/*.js"` 或者说 `"dist/mylib.js"`或一个 `Array` 联 合 国 `String`s,将一起被颂扬 (单位:千美元)`["dist/**", "!**/*.css"]`) (中文(简体) ).

如果配置了目录,将包含该目录下的所有文件及其子项.

这个 `name` 财务报告和审定财务报表 `label` 每笔资产都是通过 [Lodash 模板](https://lodash.com/docs#template)。有下列变量:

| 参数 | 说明 |
| --- | --- |
| `branch` | 释出所从之分支. |
| `lastRelease` | `Object` 与 `version`, (中文(简体) ), `gitTag` 财务报告和审定财务报表 `gitHead` 最后的释放. |
| `nextRelease` | `Object` 与 `version`, (中文(简体) ), `gitTag`, (中文(简体) ), `gitHead` 财务报告和审定财务报表 `notes` 正在完成的释放. |
| `commits` | `Array` 承诺 `Object`编号与 `hash`, (中文(简体) ), `subject`, (中文(简体) ), `body` `message` 财务报告和审定财务报表 `author`。 。 。 . |

**说明**: 如果一个文件在 `assets` 即便它也有匹配点,它也会被包含在内 `.gitignore`。 。 。 .

##### 资产实例

`'dist/*.js'`:包括所有 `js` 文档中 `dist` 目录,但不在其子目录中.

`[['dist', '!**/*.css']]`: 包含全部文件 `dist` 目录及其分目录不包括 `css` 文档.

`[{path: 'dist/MyLibrary.js', label: 'MyLibrary JS distribution'}, {path: 'dist/MyLibrary.css', label: 'MyLibrary CSS distribution'}]`:包括 `dist/MyLibrary.js` 财务报告和审定财务报表 `dist/MyLibrary.css` 文件,并标签 `MyLibrary JS distribution` 财务报告和审定财务报表 `MyLibrary CSS distribution` 在 GitHub 发布中.

`[['dist/**/*.{js,css}', '!**/*.min.*'], {path: 'build/MyLibrary.zip', label: 'MyLibrary'}]`:包括所有 `js` 财务报告和审定财务报表 `css` 文档中 `dist` 目录及其子目录,不包括已修改的版本,加 `build/MyLibrary.zip` 文件并标签 `MyLibrary` 在 GitHub 发布中.

`[{path: 'dist/MyLibrary.js', name: 'MyLibrary-${nextRelease.gitTag}.js', label: 'MyLibrary JS (${nextRelease.gitTag}) distribution'}]`: 包含文件 `dist/MyLibrary.js` 并上传到 GitHub 发布中 `MyLibrary-v1.0.0.js` 和标签 `MyLibrary JS (v1.0.0) distribution` 这将生成链接 :

> `[MyLibrary JS (v1.0.0) distribution](MyLibrary-v1.0.0.js)`

#### 成功Comment

问题评论的讯息是用 [Lodash 模板](https://lodash.com/docs#template)。有下列变量:

| 参数 | 说明 |
| --- | --- |
| `branch` | `Object` 与 `name`, (中文(简体) ), `type`, (中文(简体) ), `channel`, (中文(简体) ), `range` 财务报告和审定财务报表 `prerelease` 用于释放的分支的属性. |
| `lastRelease` | `Object` 与 `version`, (中文(简体) ), `channel`, (中文(简体) ), `gitTag` 财务报告和审定财务报表 `gitHead` 最后的释放. |
| `nextRelease` | `Object` 与 `version`, (中文(简体) ), `channel`, (中文(简体) ), `gitTag`, (中文(简体) ), `gitHead` 财务报告和审定财务报表 `notes` 正在完成的释放. |
| `commits` | `Array` 承诺 `Object`编号与 `hash`, (中文(简体) ), `subject`, (中文(简体) ), `body` `message` 财务报告和审定财务报表 `author`。 。 。 . |
| `releases` | `Array` 释放 `Object`s 用于发布的每一版,可选发布数据,例如: `name` 财务报告和审定财务报表 `url`。 。 。 . |
| `issue` | A 类 [GitHub API 拖取请求对象](https://developer.github.com/v3/search/#search-issues) 与犯罪或 `Object` 与 `number` 财产,通过 [关键词](https://help.github.com/articles/closing-issues-using-keywords) |

##### 成功Comment 示例

这个 `successComment` `This ${issue.pull_request ? 'pull request' : 'issue'} is included in version ${nextRelease.version}` 生成注释 :

> 此拉力请求包含在1.0.0版本中

#### 失败Comment

用于问题内容的信息由 [Lodash 模板](https://lodash.com/docs#template)。有下列变量:

| 参数 | 说明 |
| --- | --- |
| `branch` | 释放失败的分支. |
| `errors` | 一个 `Array` 联 合 国 [语义释放错误](https://github.com/semantic-release/error)。每个错误都有 `message`, (中文(简体) ), `code`, (中文(简体) ), `pluginName` 财务报告和审定财务报表 `details` 属性.  
`pluginName` 包含丢出错误的插件的软件包名称.  
`details` 包含关于降标格式错误的信息. |

##### 失败Comment 示例

这个 `failComment` `This release from branch ${branch.name} had failed due to the following errors:\n- ${errors.map(err => err.message).join('\\n- ')}` 生成注释 :

> 分支主机的这一释放由于以下错误而失败 :
> 
> -   错误消息 1
> -   错误消息 2

#### 已放出的标签

每个标签名称都是用 [Lodash 模板](https://lodash.com/docs#template)。有下列变量:

| 参数 | 说明 |
| --- | --- |
| `branch` | `Object` 与 `name`, (中文(简体) ), `type`, (中文(简体) ), `channel`, (中文(简体) ), `range` 财务报告和审定财务报表 `prerelease` 用于释放的分支的属性. |
| `lastRelease` | `Object` 与 `version`, (中文(简体) ), `channel`, (中文(简体) ), `gitTag` 财务报告和审定财务报表 `gitHead` 最后的释放. |
| `nextRelease` | `Object` 与 `version`, (中文(简体) ), `channel`, (中文(简体) ), `gitTag`, (中文(简体) ), `gitHead` 财务报告和审定财务报表 `notes` 正在完成的释放. |
| `commits` | `Array` 承诺 `Object`编号与 `hash`, (中文(简体) ), `subject`, (中文(简体) ), `body` `message` 财务报告和审定财务报表 `author`。 。 。 . |
| `releases` | `Array` 释放 `Object`s 用于发布的每一版,可选发布数据,例如: `name` 财务报告和审定财务报表 `url`。 。 。 . |
| `issue` | A 类 [GitHub API 拖取请求对象](https://developer.github.com/v3/search/#search-issues) 与犯罪或 `Object` 与 `number` 财产,通过 [关键词](https://help.github.com/articles/closing-issues-using-keywords) |

##### 已放出的标签示例

这个 `releasedLabels` ``['released<%= nextRelease.channel ? ` on @\${nextRelease.channel}` : "" %> from <%= branch.name %>']`` 生成标签 :

> 发布于 @ next 从分支下一个

#### 添加释放

向 GitHub 发布机构添加其它发布内容的链接.

此选项的有效值为 `false`, (中文(简体) ), `"top"` 或者说 `"bottom"`。 。 。 .

##### 添加释放实例

见 [引入公关](https://github.com/semantic-release/github/pull/282) 举个例子说明它会是什么样子.

## 常见问题

### @achingbrain/semantic-release-github 是什么？

语义- 释放插件以发布 GitHub 发布并评论已发布的 Pull 请求/ 问题

### 如何安装 @achingbrain/semantic-release-github？

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

### @achingbrain/semantic-release-github 支持 TypeScript 吗？

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

### @achingbrain/semantic-release-github 支持 ESM 还是 CommonJS？

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

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

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

### @achingbrain/semantic-release-github 可以商用吗？

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

### @achingbrain/semantic-release-github 的下载量有多少？

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

### @achingbrain/semantic-release-github 还在维护吗？

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