# @droidsolutions-oss/semantic-release-update-file 中文文档 规范地址：https://npmcn.com/package/%40droidsolutions-oss/semantic-release-update-file/ 版本：2\.0\.0 npm 元数据更新时间：2026-09-30T09:43:52.806Z 中文译文更新时间：2026-11-12T20:38:12.704Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40droidsolutions-oss/semantic-release-update-file 原文对照：https://npmcn.com/package/%40droidsolutions-oss/semantic-release-update-file/?lang=original 项目主页：https://github.com/droidsolutions/semantic-release-update-file#readme 源码仓库：https://github.com/droidsolutions/semantic-release-update-file ## 关键信息（来自 npm 元数据） - 包体积（解压后）：29.6 kB，9 个文件 - 模块格式：ES Module - TypeScript 类型：未声明 - Node.js 要求：^22\.14\.0 \|\| \>= 24\.10\.0 - 运行依赖：1 个 - 首次发布：2021-05-18T09:38:17.251Z - 最新版本发布：2026-09-30T09:43:52.409Z - 近 30 天下载量：6014（2026-10-13 至 2026-11-11，npm 官方下载统计） - 已发布版本数：10（近 12 个月 1 个） ## 中文简介 语义放行插件,帮助在放行时更新文件. ## 安装 ```sh npm install @droidsolutions-oss/semantic-release-update-file ``` 也可以使用：`pnpm add @droidsolutions-oss/semantic-release-update-file`、`yarn add @droidsolutions-oss/semantic-release-update-file`、`bun add @droidsolutions-oss/semantic-release-update-file` ## README # 语义学-释放-更新-文件 [**语义释放**](https://github.com/semantic-release/semantic-release) 在发布时帮助更新文件的插件 . [![main](https://github.com/droidsolutions/semantic-release-update-file/actions/workflows/main.yml/badge.svg)](https://github.com/droidsolutions/semantic-release-update-file/actions/workflows/main.yml) [![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) [![npm (scoped)](https://img.shields.io/npm/v/@droidsolutions-oss/semantic-release-update-file)](https://www.npmjs.com/package/@droidsolutions-oss/semantic-release-update-file) 此插件有助于您在发布时更新文件, 该文件主要有助于更新 Kubernetes 显示或使用 Semantic Release 用于非节点, 如 Dotnet 或 Flustter 等其它语言的项目 . | 步骤 | 说明 | | --- | --- | | `verifyConditions` | 验证插件的配置是否正确,以及所提供的文件是否可写. | | `prepare` | 通过每个配置的文件更新它 . | ## 安装 ```bash npm install -D @droidsolutions-oss/semantic-release-update-file ``` ## 使用量 插件可以在 [**语义释放** 配置文件](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/configuration.md#configuration)数字 : ```json { "release": { "plugins": [ "@semantic-release/commit-analyzer", "@semantic-release/changelog", "@semantic-release/release-notes-generator", "@semantic-release/npm", [ "@droidsolutions-oss/semantic-release-update-file", { "files": [ { "path": ["k8s/prod/deployment.yaml"], "type": "k8s", "image": ["my.registry.com/some/image"], "branches": "main" }, { "path": ["k8s/test/deployment.yaml"], "type": "k8s", "image": ["my.registry.com/some/image"], "branches": ["main", "develop"] }, { "path": ["Directory.Build.props"], "type": "xml", "replacements": [{ "key": "Version", "value": "${nextRelease.version}" }] }, { "path": ["Dockerfile"], "type": "containerfile", "label": "version" } ] } ], [ "@semantic-release/git", { "assets": [ "package.json", "package-lock.json", "k8s/prod/deployment.yaml", "k8s/test/deployment.yaml", "CHANGELOG.md", "Directory.Build.props", "Dockerfile" ], "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}" } ] ] } } ``` 通过这个例子,将更新4个文件: - 在文件中 `k8s/prod/deployment.yaml` 图像的版本 `my.registry.com/some/image` 将更新为新版本的语义版。 此文件仅在发布运行的分支名称时更新 `main`。 。 。 . - 这同样适用于文件 `k8s/test/deployment.yaml` 但它也会在发布运行的分支名称时更新 `develop`。 。 。 . - 在 XML 文件内 `Directory.Build.props` 标记的值 `Version` 将设定为新版语义版. - 在那个 `Dockerfile` 标签的值 `version` 将设定为新版本. 另外,git插件配置被更新,将已修改的文件包含在承诺中(这样它们可以稍后成为用户). 您可以在插件的文件属性中指定每个要更新的文件 。 现将备选方案说明如下. ### 配置选项 #### 路径 这是需要的字段, 您指定要更新的文件的路径( 相对于根工程目录) 。 这可以是一个字符串或一系列字符串,从而导致所有文件以同样的方式被更新. #### 类型 支持的文件类型之一 。 目前这些是 `k8s` 对于雅姆尔文件, `flutter` 用于达特 `pubspec.yaml` 文档, `xml` 用于像 Dotnet 项目文件和 XML 文件 `containerfile` 对于多克文件. #### 分支 一个过滤器,允许根据运行中的分支更改文件。 例如,您可能想要从不同的分支测试活度。 在这种情况下,您可以设置这样的文件配置 : ```json { "files": [ { "path": ["k8s/prod/deployment.yaml"], "type": "k8s", "image": ["my.registry.com/some/image"], "branches": "main" }, { "path": ["k8s/test/deployment.yaml"], "type": "k8s", "image": ["my.registry.com/some/image"], "branches": ["develop"] } ] } ``` 分支可以是字符串或分支的数组,如果需要更新多个分支中的文件(例如,用于从α/β/develop分支中预释). #### 图像 只有当类型是 `k8s`。指定要替换哪个版本的容器图像。 比如说,如果你 `deployment.yaml` 看起来像这样: ```yaml apiVersion: apps/v1 kind: Deployment spec: template: spec: containers: - image: my.registry.com/some/image:v2.8.2 name: my-deployment ``` 需要说明 `my.registry.com/some/image` 作为配置中的图像。 在语义放行完成后,图像的版本将成为新版本. 如果将容器图像作为另一个语义释放插件的一部分来构建和发布,并且你想将其部署在CI管道的后期步骤中,这非常有帮助. **说明:** 该插件将更新给定的 Yaml 文件内图像的所有出错 . #### 准确匹配 只有当类型是 `k8s`。这个插件将图像标记完全替换为新版本。 如果你在标签上有一个后缀 可能会有问题 `-alpine`为此 `exactMatch` 选项。 如果您指定 `exactMatch: true` 只有旧版本字符串被新版本所取代. 例如,如果您的最后一个标记是 `v1.0.0` 的版本(没有领导 v)被新版本所取代. 这样,任何标记后缀都应该保留. 举个例子 `my.registry.com/some/image:v1.0.0-alpine` 将会变成 `my.registry.com/some/image:v1.1.0-alpine`。 。 。 . **警告:** 要做到这一点,Yaml文件中的版本必须与确定为旧版本的Semantic Release相匹配,即Git标签,除非它是第一次发布. #### 替换 只有在类型是 `xml`。您可以指定 XML 文件需要更新的密钥/值对数组。 您可以以此为例, 更新版本, 并在 C# 项目文件中为 NuGet 软件包承诺标签 。 例如,考虑以下.csproj文件: ```xml 1.0.0 Stefan Ißmer DroidSolutions GmbH Awesome description of awesome NuGet package. git@example.git main 2e5a8557392548f0c7463a102efdb0add0ee5aab ``` 使用以下配置语义发布会更新版本Prefix和 Repository Commit字段: ```json { "files": [ { "path": ["path/to/my.csproj"], "type": "xml", "replacements": [ { "key": "VersionPrefix", "value": "${nextRelease.version}" }, { "key": "RepositoryCommit", "value": "${nextRelease.gitHead}" } ] } ] } ``` 现在版本Prefix更新了(您可以在后期的Semantic Release步骤中创建一个带有版本在文件中的NuGet软件包),Repository Commit会指向触发发布的承诺. 密钥必须是您给出文件中有效的 XML 标记 。 如果不存在错误,则会记录到错误,但语义释放的执行会继续下去. 值既可以是固定值,也可以是通过模板函数提取的语义放出上下文中的任何对象. 包括上一期和新版的信息,以及你自己设定的环境变量。 更多信息见 [文件](https://semantic-release.gitbook.io/semantic-release/developer-guide/plugin#context)。 。 。 . #### 标签 当指定容器文件( 如 Dockerfiles) 时, 您可以在文件内指定一个标签, 在语义发布时应该随程序更新 。 例如,如果您在您的容器文件上添加一个标签,那么您可以用这个插件来更新应用程序版本. ## 发展 要开始阅读 [捐款准则](https://npmcn.com/package/%40droidsolutions-oss/semantic-release-update-file/CONTRIBUTING.md) 首先,确保您设置了先决条件,然后遵循以下步骤来设置您的环境. ### 先决条件 这个项目需要 [节点JS](https://nodejs.org/) 安装在您的机器上. ### 建立开发环境 - 使用 git 复制此重播 - 运行 `npm install` 以获取所有依赖 - 运行 `npx husky install` 来搭起钩子 ### 转写 由于这个项目是写在 [类型脚本](https://www.typescriptlang.org/) 您需要将其移植到 JavaScript 文件 。 这个可以用 `npm run build` 命令. ### 测试 测试也用 TypeScript 写入和使用 [摩诃迦叶](https://mochajs.org/) 作为试跑者和 [Chai 断言图书馆](https://www.chaijs.com/)。如果您添加了新功能,请同时添加单元测试,以确保该功能正常工作. ## 常见问题 ### @droidsolutions-oss/semantic-release-update-file 是什么？ 语义放行插件,帮助在放行时更新文件\. ### 如何安装 @droidsolutions-oss/semantic-release-update-file？ 在项目目录运行 npm install @droidsolutions-oss/semantic-release-update-file，或使用 pnpm add / yarn add / bun add。 ### @droidsolutions-oss/semantic-release-update-file 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/droidsolutions-oss\_\_semantic-release-update-file 是否存在。 ### @droidsolutions-oss/semantic-release-update-file 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @droidsolutions-oss/semantic-release-update-file 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js ^22\.14\.0 \|\| \>= 24\.10\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @droidsolutions-oss/semantic-release-update-file 可以商用吗？ @droidsolutions-oss/semantic-release-update-file 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @droidsolutions-oss/semantic-release-update-file 的下载量有多少？ 根据 npm 官方下载统计，@droidsolutions-oss/semantic-release-update-file 在 2026/10/13 – 2026/11/11 这 30 天内被下载 6,014 次，日均约 200 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @droidsolutions-oss/semantic-release-update-file 还在维护吗？ 最新版本 2\.0\.0 发布于 2026/09/30（1 个月前）；至今共发布 10 个版本，其中过去 12 个月发布了 1 个；首次发布于 2021/05/18。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。