# @droidsolutions-oss/semantic-release-nuget 中文文档 规范地址：https://npmcn.com/package/%40droidsolutions-oss/semantic-release-nuget/ 版本：2\.1\.2 npm 元数据更新时间：2026-10-27T09:36:35.354Z 中文译文更新时间：2026-11-12T20:28:50.924Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40droidsolutions-oss/semantic-release-nuget 原文对照：https://npmcn.com/package/%40droidsolutions-oss/semantic-release-nuget/?lang=original 项目主页：https://github.com/droidsolutions/semantic-release-nuget#readme 源码仓库：https://github.com/droidsolutions/semantic-release-nuget ## 关键信息（来自 npm 元数据） - 包体积（解压后）：54.9 kB，12 个文件 - 模块格式：ES Module - TypeScript 类型：未声明 - Node.js 要求：\>=22 - 运行依赖：1 个 - 首次发布：2022-01-20T14:38:14.583Z - 最新版本发布：2026-10-27T09:36:34.804Z - 近 30 天下载量：9386（2026-10-13 至 2026-11-11，npm 官方下载统计） - 已发布版本数：29（近 12 个月 10 个） ## 中文简介 语义放出插件以创建并发布 NuGet 包. ## 安装 ```sh npm install @droidsolutions-oss/semantic-release-nuget ``` 也可以使用：`pnpm add @droidsolutions-oss/semantic-release-nuget`、`yarn add @droidsolutions-oss/semantic-release-nuget`、`bun add @droidsolutions-oss/semantic-release-nuget` ## README # 语义 -- -- 释放 -- -- 核 [**语义释放**](https://github.com/semantic-release/semantic-release) 创建和发布插件 [新建](https://www.nuget.org/) 软件包. ![NPM Version](https://img.shields.io/npm/v/%40droidsolutions-oss%2Fsemantic-release-nuget?style=flat) | 步骤 | 说明 | | --- | --- | | `verifyConditions` | 验证所提供的插件配置的正确性 . | | `prepare` | 创建 NuGet 软件包. | | `publish` | 发布创建的 [NuGet 软件包](https://docs.microsoft.com/en-us/nuget/what-is-nuget) 登记. | ## 安装 将插件安装为开发依赖 ```bash npm i -D @droidsolutions-oss/semantic-release-nuget ``` ## 使用量 插件可以在 [**语义释放** 配置文件](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/changelog", "@droidsolutions-oss/semantic-release-update-file", "@semantic-release/npm", "@droidsolutions-oss/semantic-release-nuget", [ "@semantic-release/git", { "assets": ["package.json", "package-lock.json", "CHANGELOG.md", "Directory.Build.props"], "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}" } ], "@semantic-release/gitlab" ] } ``` **提示**: 您可以使用 [@droidsolutions-oss/ semantic-release-update-file 互联网档案馆的存檔,存档日期2013-12-02](https://github.com/droidsolutions/semantic-release-update-file) 在工程中更新版本编号的插件或 `Directory.Build.props` 在创建 NuGet 软件包之前的文件. ## 配置 ### NuGet 服务器认证 NuGet 服务器认证为 **所需经费** 并可以通过 [环境变量](https://npmcn.com/package/%40droidsolutions-oss/semantic-release-nuget/#readme-environment-variables)。 。 。 . ### 环境变量 | 变量 | 说明 | | --- | --- | | `NUGET_TOKEN` | 您想要发布的 NuGet 服务器的 NuGet 令牌, 创建于 [NuGet API 密钥页面](https://www.nuget.org/account/apikeys)。 。 。 . | | `CI_SERVER_URL` | 如果您想要向您的 GitLab 服务器发布, 需要将此设定为您使用的 GitLab 实例的主 URL 。 在 GitLab CI 运行时, 这已经由 GitLab 设置 . | | `CI_PROJECT_ID` | 如果您要向您的 GitLab 服务器发布, 这需要设置为您想要发布的工程的 Id 。 在 GitLab CI 中运行时, 这已经设置到项目上 由 GitLab 运行的 pipleine . | | `CI_JOB_TOKEN` | 如果您想向您的 GitLab 服务器发布, 需要设置此选项 。 在 GitLab CI 运行时, 这已经由 GitLab 设置, 但是它只有在发布给同一项目时才有效. | ### 选项 | 选项 | 说明 | 默认 | | --- | --- | --- | | `nugetRegistries` | 要公布的 NuGet 注册配置列表 . | 见下文 | | `nugetRegistries[].type` | NuGet 注册类型 。 可能值为 `nuget`, (中文(简体) ), `gitlab_private`, (中文(简体) ), `github`。 。 。 . | `nuget` | | `nugetRegistries[].name` | 用于记录和从核子识别的来源名称。 相会. | `nuget` | | `nugetRegistries[].url` | NuGet 注册的 URL . | `https://api.nuget.org/v3/index.json` | | `nugetRegistries[].user` | 要登录 NuGet 注册的用户 . | | | `nugetRegistries[].tokenEnvVar` | 包含密码或令牌以对 NuGet 注册进行认证的环境变量的名称 . | `NUGET_TOKEN` 或者说 `CI_JOB_TOKEN` 为吉特拉布. | | `projectPath` | 要打包的项目文件的相对路径 。 也可以是一个包括多个工程的阵列. | | | `nugetServer` | **折旧**,使用核子登记 \[\].url代替。 NuGet 服务器的URL可以将软件包推向. | `https://api.nuget.org/v3/index.json` | | `includeSymbols` | 如果选中的话, 将会创建一个带有调试符号的额外包 . | `false` | | `includeSource` | 如果真的源代码将包含在软件包中, 当消费者需要调试您的库时会有所帮助 . | `false` | | `dotnet` | 如果不是在 PATH 中可执行的 dotnet 路径 . | `dotnet` | | `publishToGitLab` | **折旧**,取而代之的是核子登记。 如果选中的话, 软件包也将发布到 GitLab 注册 . | `false` | | `usePackageVersion` | 如果真实, 从语义发布的新版本将直接交给 `dotnet pack` 命令,否则则在 `csproj` 或者说 `Directory.Build.props` 用于 NuGet 软件包. | `false` | | `skipPublishToNuget` | **折旧**,取而代之的是核子登记。 如果选中的话, NuGet 软件包将不会发布到 `nugetServer`。您可以一起使用这个 `publishToGitLab` 改为 **仅限** 将您的软件包发布到 GitLab 注册. | `false` | | `gitlabRegistryProjectId` | 可设定将软件包发布到不同的 GitLab 项目 。 仅在 `publishToGitLab` 被设定为真实. | `CI_PROJECT_ID` | | `gitlabUser` | 向单独的GitLab项目出版时需要。 如果使用部署令牌,必须给出令牌名称,在使用个人访问令牌时,必须给出用户名. | `gitlab-ci-token` | | `dotnetVerbosity` | 可选字符串传递到多特网包命令作为动词参数. 见 [动词参数](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-pack) 用于有效值. | | 随着2.1.0配置方法的改变. 现在一个 `nugetRegistries` 可以给出数组来配置每个应公布的软件包. 空配置将导致此默认配置 : ```json { "nugetRegistries": [ { "name": "nuget", "url": "https://api.nuget.org/v3/index.json", "tokenEnvVar": "NUGET_TOKEN", "type": "nuget" } ] } ``` **说明**: 如果 `publishToGitLab` 设置环境变量 `CI_SERVER_URL`, (中文(简体) ), `CI_PROJECT_ID` 财务报告和审定财务报表 `CI_JOB_TOKEN` 必须设定。 如果您在 GitLab CI 中运行, 由 GitLab 自动设定 。 核子注册处的配置将附带如下: ```json { "name": "gitlab", "url": "${CI_SERVER_URL}/api/v4/projects/${CI_PROJECT_ID}/packages/nuget/index.json", "tokenEnvVar": "CI_JOB_TOKEN", "type": "gitlab_private" } ``` **说明**: 如果 `skipPublishToNuget` 设置此软件包将不会发布到正式的 Nuget 服务器。 这只有结合 `publishToGitLab`。现在已贬值,您应该通过 `nugetRegistries` 相会. **说明**: 当添加时 [国家预防机制插件](https://raw.githubusercontent.com/semantic-release/npm) 更新您的 `package.json` 设置 `npmPublish` 改为 `false` 防止语义释放试图发布国家预防机制的套件. **说明**: 当您想要将您的软件包发布到不同的 GitLab 项目时 `gitlabRegistryProjectId` 确保NUGET TOKEN是一个可以访问它和它的标志 `gitlabUser` 必须设置给属于该符号的用户. 更多信息见下面的配置示例. ## 版本 在创建的 NuGet 软件包中,版本的设置有两种方式. 最简单的方式(例如不需要任何额外的配置)是设置 `usePackageVersion` 真实的。 这将使语义释放被计算为下一个版本成为直接作为论据的版本 `dotnet pack` 命令(通过 `-p:PackageVersion=` 参数)。 然而, 您的版本的缺点并没有在您的仓库文件中持续 . 将您的软件包版本化的建议方式是将该版本写入您的项目文件中 。 你可以使用一个 [目录. 构建.道具](https://docs.microsoft.com/en-us/visualstudio/msbuild/customize-your-build) 用于为您仓库中的所有工程设置同一版本的文件。 添加一个 `VersionPrefix` (或 `Version`标记并使用 [语义发布更新文件插件](https://github.com/droidsolutions/semantic-release-update-file) 在创建软件包之前更新版本。 确保 `update-file` 插件位于 `git` 插件在单元格中 `plugins` 列表并添加项目文件或 `Directory.Build.props` 到资产清单。 见 [实例配置](https://npmcn.com/package/%40droidsolutions-oss/semantic-release-nuget/#readme-example-config) 见下文. ## 配置示例 ### 简单发布到 nuget.org 你不需要任何配置 只要确保 `NUGET_TOKEN` 环境变量包含一个发布到nuget.org的有效符号. 如果您想要使用另一个环境变量或只是明确配置它,您可以使用: ```json { "nugetRegistries": [ { "name": "nuget", "url": "https://api.nuget.org/v3/index.json", "tokenEnvVar": "NUGET_TOKEN", "type": "nuget" } ] } ``` ### 发布到当前 GitLab 项目 如果您想要不经特殊许可向当前 GitLab 项目发布, 您可以使用以下最小示例 : ```json { "nugetRegistries": [ { "type": "gitlab_private" } ] } ``` 这将从 GitLab CI 设置的变量中解决 GitLab 注册 URL : `${CI_SERVER_URL}/api/v4/projects/${CI_PROJECT_ID}/packages/nuget/index.json`它将设定 `tokenEnvVar` 改为 `CI_JOB_TOKEN` 足以向当前项目发布软件包. ### 发布到不同的 GitLab 项目 如果您想要发布到不同的 GitLab 项目中, 您可能需要一个 GitLab 标记, 并有正确的权利 。 将工程 ID 添加到普通配置中 : ```json { "gitlabRegistryProjectId": 123, "nugetRegistries": [ { "type": "gitlab_private" } ] } ``` 这将从 GitLab CI 设置的变量中解决 GitLab 注册 URL : `${CI_SERVER_URL}/api/v4/projects/123/packages/nuget/index.json`它将设定 `tokenEnvVar` 改为 `NUGET_TOKEN` 足以向当前项目发布软件包。 您也可以设置 `tokenEnvVar` 如果您想要使用不同的环境变量,您也可以使用. ### 发布到 GitHub 软件包 要发布到 GitHub 软件包, 您可以使用 `github` 类型. ```json { "nugetRegistries": [ { "type": "github" } ] } ``` 这将自动解决注册 URL 到 `https://nuget.pkg.github.com/${GITHUB_REPOSITORY_OWNER}/index.json`。 。 。 . 它会用 `GITHUB_TOKEN` 用于认证和 `GITHUB_ACTOR` 作为用户名. 确保你的工作流程 `packages: write` 允许. ### 向多个登记处公布 如果您想向不同的注册点发布, 您应该为每个注册点设定符号 EnvVar : ```json { "nugetRegistries": [ { "name": "nuget", "tokenEnvVar": "NUGET_TOKEN", "type": "nuget" }, { "name": "gitlab_private", "tokenEnvVar": "CI_JOB_TOKEN", "type": "gitlab_private" } ] } ``` ### 持久版在目录中的更改. 盖起. 道具 以下是如何使用这个插件构建语义化的NuGet版本包并坚持项目文件中的版本的例子. 添加一个 `Directory.Build.props` 到您的工程, 取决于您是否想要在同一寄存器的多个工程中共享值, 它可以从工程根到您的 csproj 文件相邻的任何地方 。 此文件可以并且应该包含一些关于您的 NuGet 软件包的元数据 . **说明**: 代替此特殊文件, 您也可以直接在您的 csproj 文件中添加这些属性 。 如果您这样做, 请确保您相应更改更新文件插件的路径 . ```xml Stefan Ißmer Library for working with jobs that may be recurring in distributed systems and microservices. DroidSolutions GmbH LICENSE README.md https://github.com/droidsolutions/job-service/blob/main/CHANGELOG.md snupkg https://github.com/droidsolutions/job-service.git true git main 209982581960ec4e7361ec556e51be4ebbee2052 3.0.1 ``` 现在配置语义发布并使用更新文件插件来更新文件中的值. 除了版本,你还可以更新承诺散列等. 参见 [更新文件插件文档](https://github.com/droidsolutions/semantic-release-update-file#configuration-options) 对于您可以使用的数值列表. ```jsonc { // order of plugins is important, because it is the execution order "plugins": [ "@semantic-release/commit-analyzer", "@semantic-release/release-notes-generator", "@semantic-release/changelog", "@droidsolutions-oss/semantic-release-update-file", // update version in Directory.Build.props "@semantic-release/npm", // update package.json "@droidsolutions-oss/semantic-release-nuget", // create nuget package [ "@semantic-release/git", { "assets": [ "package.json", "package-lock.json", "CHANGELOG.md", "Directory.Build.props", // add updated file to the Semantic Release commit ], "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}", }, ], "@semantic-release/gitlab", ], "npmPublish": false, // prevent creating NPM package "nugetRegistries": [ { "name": "custom-nuget", "url": "https://nuget.mycomapny.com/v3/index.json", // custom (private) NuGet server, uses NUGET_TOKEN for auth "type": "nuget", }, ], "projectPath": [ "src/DroidSolutions.Oss.JobService/DroidSolutions.Oss.JobService.csproj", // path to the project files ], "includeSymbols": true, // include Debug symbols for easier debugging "files": [ { "path": ["Directory.Build.props"], // configure update-file plugin to update fields in Directory.Build.props "type": "xml", "replacements": [ { "key": "Version", "value": "${nextRelease.version}", }, { "key": "RepositoryCommit", "value": "${CI_COMMIT_SHA}", }, ], }, ], } ``` ### 多个软件包 您可以从一个寄存器构建多个 NuGet 软件包 。 要做到这一点,请指定项目的相关路径。 改为 ```json { "projectPath": "src/DroidSolutions.SemanticVersion/DroidSolutions.SemanticVersion.csproj" } ``` 你也可以用这样的东西: ```json { "projectPath": [ "src/DroidSolutions.Oss.JobService/DroidSolutions.Oss.JobService.csproj", "src/DroidSolutions.Oss.JobService.EFCore/DroidSolutions.Oss.JobService.EFCore.csproj", "src/DroidSolutions.Oss.JobService.Postgres/DroidSolutions.Oss.JobService.Postgres.csproj" ] } ``` ## 常见问题 ### @droidsolutions-oss/semantic-release-nuget 是什么？ 语义放出插件以创建并发布 NuGet 包\. ### 如何安装 @droidsolutions-oss/semantic-release-nuget？ 在项目目录运行 npm install @droidsolutions-oss/semantic-release-nuget，或使用 pnpm add / yarn add / bun add。 ### @droidsolutions-oss/semantic-release-nuget 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/droidsolutions-oss\_\_semantic-release-nuget 是否存在。 ### @droidsolutions-oss/semantic-release-nuget 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @droidsolutions-oss/semantic-release-nuget 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @droidsolutions-oss/semantic-release-nuget 可以商用吗？ @droidsolutions-oss/semantic-release-nuget 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @droidsolutions-oss/semantic-release-nuget 的下载量有多少？ 根据 npm 官方下载统计，@droidsolutions-oss/semantic-release-nuget 在 2026/10/13 – 2026/11/11 这 30 天内被下载 9,386 次，日均约 313 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @droidsolutions-oss/semantic-release-nuget 还在维护吗？ 最新版本 2\.1\.2 发布于 2026/10/27（17 天前）；至今共发布 29 个版本，其中过去 12 个月发布了 10 个；首次发布于 2022/01/20。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。