# @effected/semver 中文文档

规范地址：https://npmcn.com/package/%40effected/semver/

版本：0\.24\.0
npm 元数据更新时间：2026-11-10T15:09:44.216Z
中文译文更新时间：2026-11-13T08:31:46.804Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40effected/semver
原文对照：https://npmcn.com/package/%40effected/semver/?lang=original
项目主页：https://github.com/spencerbeggs/effected/tree/main/packages/semver#readme
源码仓库：https://github.com/spencerbeggs/effected

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

- 包体积（解压后）：148 kB，17 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.11\.0
- 运行依赖：0 个
- peer 依赖：effect ~4\.1\.0
- 首次发布：2026-07-16T17:30:53.280Z
- 最新版本发布：2026-11-10T15:09:43.777Z
- 近 30 天下载量：23088（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：32（近 12 个月 32 个）

## 中文简介

严格SemVer 2.0.0版本,幅度和比较器作为Effect schemas.

## 安装

```sh
npm install @effected/semver
```

也可以使用：`pnpm add @effected/semver`、`yarn add @effected/semver`、`bun add @effected/semver`

## README

# @ 受影响/ 爆炸

[![npm](https://img.shields.io/npm/v/@effected%2Fsemver?label=npm&color=cb3837)](https://www.npmjs.com/package/@effected/semver) [![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT) [![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/) [![TypeScript 7.0](https://img.shields.io/badge/TypeScript-7.0-3178c6.svg)](https://www.typescriptlang.org/)

严格SemVer 2.0.0版本,幅度和比较器作为Effect schemas. `SemVer`, (中文(简体) ), `Comparator` 财务报告和审定财务报表 `Range` 为: `Schema.Class`因此,一个版本是一个有效的值 上面有方法,而不是一个字符串 你在每一个呼叫站点重排 `FromString` 解码器 解码器 并编码回它。 解析很严格:没有 `v` 前缀,无 `=` 前缀,在数字标识符上没有前缀,没有部分被消耗的输入。 每一次失败都是带有违法字符串和文法放弃的字符位置的标记错误. 零运行时间依赖,没有IO.

> **预`1.0.0`。 。 。 .** 此软件包是 `@effected/*` 在稳定基础上建造的工具包 效应v4(`effect` `~4.1.0`) 并仍在 `0.x` 发展。 稳定效果 制作一个工具箱 `1.0.0` 可能,不是自动的。 为了保持你的 `effect` 财务报告和审定财务报表 `@effect/*` 该工具包在线上构建和测试、安装 [`@effected/pnpm-plugin-effected`](https://www.npmjs.com/package/@effected/pnpm-plugin-effected)。 。 。 .
> 
> **稳定:不稳定.** 此软件包的 API 表面尚未考虑 完成并可能改变 `0.x` 释放 定一个确切的版本——甚至 标记软件包 _稳定_ 在此之前 `1.0.0` 可以引入突破性更改 和精确的针 变成一个类型检查错误 而不是一个 跑步时间惊喜。 完全政策: [释放策略](https://github.com/spencerbeggs/effected#release-strategy)。 。 。 .

## 为什么 @ effect/ semver

解析大多数工程的版本默认是宽大。 他们胁迫我 `v1.2.3` 财务报告和审定财务报表 `=1.2.3` 变成一个版本,然后手拿回来 `null` 当他们最终决定什么是错的时,或扔出什么,让你去重建失败的和在哪里。 解析后,结果将会是您为存储和再解析以比较而拼接的一包数字 。 这个包裹倒置。 班级 _实值_ 因此,一个版本的字段 在您自己的计划 解码为真实 `SemVer` 并重新编码到其无胶合码的光圈字符串,您想要的操作以您已有的值进行活化.

失败的是 `Schema.TaggedError` 您路径的值 `Effect.catchTag`,每个结构而不是字符串: `InvalidVersionError` 携带 `input` 财务报告和审定财务报表 `position`, (中文(简体) ), `UnsatisfiedRangeError` 携带范围 _财务报告和审定财务报表_ 每一个版本的可用 匹配它。 严相是想. 强制是一个关于您数据的决定 在一个你没有写到的库里, 它是版本错误隐藏的地方. `Range.intersect` 持有同一条线:相交 `^1.0.0` 与 `^2.0.0` 不悄悄地将一个与无相匹配的范围交回, 它失败了 `UnsatisfiableConstraintError` 有两个限制。 这里没有什么能修复你背后的输入.

## 安装

```bash
npm install @effected/semver effect
```

```bash
pnpm add @effected/semver effect
```

需要节点.js~~24.11.0.

全体 `@effected/*` 软件包仅为无害环境管理:只公布出口地图 `import` 条件,所以 `require()` 包括解析 CJS 模式的工具 —— 与节点失败 `ERR_PACKAGE_PATH_NOT_EXPORTED` 而不是装入不存在的 CJS 建筑。 从ES模块导入.

`effect` v4是唯一的对等依赖,它是任何种类的唯一依赖——没有剖析器,没有多填充器,没有平台包在它的后方搭载. 这里没有IO,所以边缘也没有东西可以提供: 整个地表都在下方 `Effect.runSync`,除 `VersionCache`,它带来了自己的层.

## 快开始

剖析、凸起、比较和测试一个版本,对照一个范围:

```ts
import { Range, SemVer } from "@effected/semver";
import { Effect } from "effect";

const program = Effect.gen(function* () {
  const version = yield* SemVer.parse("1.2.3");
  const next = version.bump.minor();
  const range = yield* Range.parse("^1.0.0");
  return [next.toString(), range.test(version), version.gt(next)] as const;
});

console.log(Effect.runSync(program));
// => ["1.3.0", true, false]
```

实例方法为犬科API:与 `a.gt(b)`, (中文(简体) ), `a.compare(b)`, (中文(简体) ), `range.filter(versions)`没有实例对应的操作是自有类上的双重静态,所以 `Range.satisfies(version, range)` 财务报告和审定财务报表 `version.pipe(Range.satisfies(range))` 都一样 为了进行最后的数据比较,从下列来源得出: `SemVer.Order`数字 : `Arr.filter(versions, Order.isGreaterThan(SemVer.Order)(floor))`。 。 。 .

## 版本数

`SemVer`其字段在schema中被验证——组件的非负式安全整数,造型良好的预放和构建标识符——所以 `SemVer.make` 无法生成无效的版本。 使用 `SemVer.parse` 用于字符串和 `SemVer.of(1, 2, 3)` 对位置表.

```ts
import { SemVer } from "@effected/semver";
import { Effect } from "effect";

const program = Effect.gen(function* () {
  const stable = yield* SemVer.parse("1.0.0");
  const rc = yield* SemVer.parse("2.0.0-rc.1");
  return [
    stable.bump.prerelease("beta").toString(),
    rc.bump.prerelease().toString(),
    rc.isPrerelease,
    SemVer.truncate(rc, "prerelease").toString(),
  ] as const;
});

console.log(Effect.runSync(program));
// => ["1.0.1-beta.0", "2.0.0-rc.2", true, "2.0.0"]
```

跳出是节点-闪出兼容性:稳定的版本开始预放 _下一个_ 补丁,切换标识符重置计数器,以及所坐位置最右侧的标识符递增(`1.0.0-1.beta` 变成 `1.0.0-2.beta`),与 `0` 只有在没有的情况下才予以补充。 构建元数据永远无法幸存.

平等遵循的是谱而不是弦. `Equal.equals` 忽略构建元数据(§10)并包括预释标识符(§11) `SemVer` 覆盖 `[Hash.symbol]` 因此,仅在构建元数据方面不同的两个版本是: `HashSet` 和一个插槽 `VersionCache`。 。 。 . `SemVer.Order` 按先后顺序排列; `SemVer.OrderWithBuild` 在构建元数据上添加一个词典连接断, 当您需要一个相对于不同版本字符串的总顺序时.

收集操作为静态: `sort`, (中文(简体) ), `rsort`, (中文(简体) ), `max`, (中文(简体) ), `min`, (中文(简体) ), `groupBy` (按主要、次要或补丁), `latestByMajor` 财务报告和审定财务报表 `latestByMinor`。 。 。 .

## 范围和比较国

A 类 `Range` 是比较器组合(AND)的联盟。 解析法接受节点-分解方言——连字符范围,X行距,平板,celt和 `||` ——去除它成为原始的参照物,使结果正常化. A 类 `Comparator` 一个操作员被应用在一个完整的版本上,没有通配符和糖;该词汇属于 `Range`。 。 。 .

```ts
import { Range, SemVer } from "@effected/semver";
import { Effect } from "effect";

const program = Effect.gen(function* () {
  const caret = yield* Range.parse("^1.0.0");
  const floor = yield* Range.parse(">=1.5.0");
  const both = yield* Range.intersect(caret, floor);
  const versions = [SemVer.of(1, 2, 0), SemVer.of(1, 6, 0), SemVer.of(2, 0, 0)];
  return [both.test(SemVer.of(1, 6, 0)), caret.filter(versions).map((v) => v.toString())] as const;
});

console.log(Effect.runSync(program));
// => [true, ["1.2.0", "1.6.0"]]
```

匹配执行节点-semver的预放出限制:只有当一个预放出版本在同一套上带有预放出时,才满足一个集 `major.minor.patch` tu. 这就是保持 `^1.2.3` 从意外匹配 `1.2.4-alpha`。通过 `Range.parse(input, { includePrerelease: true })` (亦为 `Range.parseResult` 财务报告和审定财务报表 `VersionCache.resolveString`取消该规则:将通配符地板降为第一次预放(`^1.2` 变成 `>=1.2.0-0 <2.0.0-0`和解析 `Range` 记录其中的选择 `includePrerelease` 所以每个配对者都以此为荣. `Range.FromString` 无法挂上旗帜; 结构形成回转.

范围代数是 `union`, (中文(简体) ), `intersect`, (中文(简体) ), `isSubset`, (中文(简体) ), `equivalent` 财务报告和审定财务报表 `simplify`。 。 。 . `isSubset` 是一个故意的保守近似:它可以报告 `false` 用于一个在技术上属于子集的范围,当子相距跨越了上行相距的参照国设定的边界。 假阴性是安全的,因为他们所做的只是拒绝简化.

## 比较两个版本

`VersionDiff.between(a, b)` 分类更改并带有已签名的组件三角洲。 这是一个 `Schema.TaggedClass`,所以diff序列化 如它计算干净.

```ts
import { SemVer, VersionDiff } from "@effected/semver";
import { Effect } from "effect";

const program = Effect.gen(function* () {
  const from = yield* SemVer.parse("1.2.3");
  const to = yield* SemVer.parse("2.0.0");
  const diff = VersionDiff.between(from, to);
  return [diff.type, diff.major, diff.toString()] as const;
});

console.log(Effect.runSync(program));
// => ["major", 1, "major (1.2.3 → 2.0.0)"]
```

`type` 名称 : `"major"`, (中文(简体) ), `"minor"`, (中文(简体) ), `"patch"`, (中文(简体) ), `"prerelease"`, (中文(简体) ), `"build"` 或者说 `"none"`。 。 。 .

## 版本缓存

`VersionCache` 是一个 `Context.Service` 超过一组分类的、被复制的版本——纯正状态 `Ref`没有IO。 当你持有一份已出版的版本清单和解决范围时,请联系它.

```ts
import { SemVer, VersionCache } from "@effected/semver";
import { Effect } from "effect";

const program = Effect.gen(function* () {
  const cache = yield* VersionCache;
  yield* cache.load([SemVer.of(1, 0, 0), SemVer.of(1, 4, 2), SemVer.of(2, 0, 0)]);
  const latest = yield* cache.latest();
  const resolved = yield* cache.resolveString("^1.0.0");
  return [latest.toString(), resolved.toString()] as const;
}).pipe(Effect.provide(VersionCache.layer));

console.log(Effect.runSync(program));
// => ["2.0.0", "1.4.2"]
```

二种出离相相别相. `next` 财务报告和审定财务报表 `prev` 失败 `VersionNotFoundError` 当关键版本不在缓存中时,并成功使用 `Option.none()` 当支柱坐落在一个边界上。 查询整个缓存( E)`versions`, (中文(简体) ), `filter`永不失败并返回 `[]`。 。 。 .

## 错误

每一次失败都是 `Schema.TaggedError` 路由为 `Effect.catchTag`,带有结构化字段. 这个 `message` 盖特就是从那些田地中衍生出来的,从未被储存过.

| 标记 | 升为 | 卡莉丝 |
| --- | --- | --- |
| `InvalidVersionError` | `SemVer.parse` | `input`,则 `position` 语法失败的地方 |
| `InvalidComparatorError` | `Comparator.parse` | `input`, (中文(简体) ), `position` |
| `InvalidRangeError` | `Range.parse`, (中文(简体) ), `VersionCache.resolveString` | `input`, (中文(简体) ), `position` |
| `UnsatisfiableConstraintError` | `Range.intersect` | `constraints`,其相交点为空的区域 |
| `EmptyCacheError` | `VersionCache.latest`, (中文(简体) ), `VersionCache.oldest` | 无; 缓存为空 |
| `VersionNotFoundError` | `VersionCache.diff`, (中文(简体) ), `next`, (中文(简体) ), `prev` | `version`,未缓存的关键 |
| `UnsatisfiedRangeError` | `VersionCache.resolve`, (中文(简体) ), `resolveString` | `range`附加时 `available`,用于匹配的版本 |

这个 `FromString` 解码器通过通用程序报告相同的失败 `Schema` 解析带有相同信件的错误, 所以要解码和解码 `parse` 静态对于什么是有效的,从不持异议.

```ts
import { SemVer } from "@effected/semver";
import { Effect } from "effect";

// A leading `v` is not a version, and nothing here coerces it into one.
const program = SemVer.parse("v1.2.3").pipe(Effect.catch((error) => Effect.succeed(`${error._tag}: ${error.input}`)));

console.log(Effect.runSync(program));
// => "InvalidVersionError: v1.2.3"
```

## 特征

-   `SemVer` ——版本模型:有计划验证的字段, `parse` 编号 : `of` 编号 : `make` 施工,撞穿 `version.bump`,比较作为实例方法和双重静态,光谱正确 `Equal` 财务报告和审定财务报表 `Hash`,以及收集的静态(`sort`, (中文(简体) ), `max`, (中文(简体) ), `groupBy`, (中文(简体) ), `latestByMajor`(中文(简体) ).
-   `Comparator` ——单一操作者-+-版本的制约,以及将糖分解剂放入的原始.
-   `Range` ——节点-同域方言解为已归正的比较方言集,并配对(`test`, (中文(简体) ), `filter`, (中文(简体) ), `maxSatisfying`, (中文(简体) ), `minSatisfying`)和代数(`union`, (中文(简体) ), `intersect`, (中文(简体) ), `isSubset`, (中文(简体) ), `equivalent`, (中文(简体) ), `simplify`) (中文(简体) ).
-   `VersionDiff` ——两个版本的有签名组件deltas的分类差异,可被连为标记类.
-   `VersionCache` ——一个排序的有射程分辨率和相邻导航的元版,由 `VersionCache.layer`。 。 。 .
-   `SemVer.FromString`, (中文(简体) ), `Comparator.FromString`, (中文(简体) ), `Range.FromString` ——相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相相接相接相接相相接相相接相相相接相接相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相.
-   7个标记错误,每个携带结构化有效载荷的呼叫者需要报告实际出错的情况.

## 许可证

[麻省理工学院](https://npmcn.com/package/%40effected/semver/LICENSE)

## 常见问题

### @effected/semver 是什么？

严格SemVer 2\.0\.0版本,幅度和比较器作为Effect schemas\.

### 如何安装 @effected/semver？

在项目目录运行 npm install @effected/semver，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：effect（~4\.1\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @effected/semver 支持 TypeScript 吗？

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

### @effected/semver 支持 ESM 还是 CommonJS？

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

### @effected/semver 需要什么版本的 Node\.js？

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

### @effected/semver 可以商用吗？

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

### @effected/semver 的下载量有多少？

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

### @effected/semver 还在维护吗？

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