# @effect/match 中文文档

规范地址：https://npmcn.com/package/%40effect/match/

版本：0\.40\.0
npm 元数据更新时间：2026-09-18T21:17:37.622Z
中文译文更新时间：2026-11-13T08:24:34.028Z
软件包许可：MIT

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

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

弃用说明：this package has been merged into the main effect package

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

- 包体积（解压后）：130 kB，43 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：effect 2\.0\.0-next\.47
- 首次发布：2023-01-30T04:24:32.874Z
- 最新版本发布：2023-10-08T11:14:13.596Z
- 近 30 天下载量：282913（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：86（近 12 个月 0 个）

## 中文简介

类型脚本的匹配模式

## 安装

```sh
npm install @effect/match
```

也可以使用：`pnpm add @effect/match`、`yarn add @effect/match`、`bun add @effect/match`

## README

### ![](https://raw.githubusercontent.com/Effect-TS/match/main/docs/example.png)

功能模式与Typescript的全部功率相匹配.

## 开始

从 npm 安装 :

```
npm install @effect/match
```

一旦安装了库,您可以从库中导入必要的类型和功能 `@effect/match` 模块.

```ts
import * as Match from "@effect/match"
```

## 定义匹配符

定义一个 `Matcher` 从给定类型,您可以使用 `type` 构造函数 .

然后,你可以使用 `when`, (中文(简体) ), `not` 打开 `tag` 组合符以指定匹配的模式.

例如:

```ts
import * as Match from "@effect/match"
import { pipe } from "@effect/data/Function"

const match = pipe(
  Match.type<{ a: number } | { b: string }>(),
  Match.when({ a: Match.number }, (_) => _.a),
  Match.when({ b: Match.string }, (_) => _.b),
  Match.exhaustive,
)

console.log(match({ a: 0 })) // 0
console.log(match({ b: "hello" })) // "hello"
```

您也可以创建 `Matcher` 从使用 `value` 构造函数 .

例如:

```ts
import * as Match from "@effect/match"
import { pipe } from "@effect/data/Function"

const result = pipe(
  Match.value({ name: "John", age: 30 }),
  Match.when(
    { name: "John" },
    (user) => `${user.name} is ${user.age} years old`,
  ),
  Match.orElse(() => "Oh, not John"),
)

console.log(result) // "John is 30 years old"
```

## 模式的类型

### 预测数

值可以通过任意函数测试.

```ts
import * as Match from "@effect/match"
import { pipe } from "@effect/data/Function"

const match = pipe(
  Match.type<{ age: number }>(),
  Match.when({ age: (age) => age >= 5 }, (user) => `Age: ${user.age}`),
  Match.orElse((user) => `${user.age} is too young`),
)

console.log(match({ age: 5 })) // "Age: 5"
console.log(match({ age: 4 })) // "4 is too young"
```

### `not` 模式

`not` 让你在每件事物上都匹配,但有一个特定的值.

```ts
import * as Match from "@effect/match"
import { pipe } from "@effect/data/Function"

const match = pipe(
  Match.type<string | number>(),
  Match.not("hi", (_) => "a"),
  Match.orElse(() => "b"),
)

console.log(match("hello")) // "a"
console.log(match("hi")) // "b"
```

### `tag` 模式

匹配标签在一个 [歧视联盟](https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes-func.html#discriminated-unions)

```ts
import * as Match from "@effect/match"
import * as E from "@effect/data/Either"
import { pipe } from "@effect/data/Function"

// type Either<L, R> = { _tag: "Right", right: R } | { _tag: "Left", left: L }
const match = pipe(
  Match.type<E.Either<string, number>>(),
  Match.tag("Right", (_) => _.right),
  Match.tag("Left", (_) => _.left),
  Match.exhaustive,
)

console.log(match(E.right(123))) // 123
```

## 评价a `Matcher`

### `option`

一个匹配者 _可能会_ 匹配一个值。 返回 a [选项](https://github.com/fp-ts/core/blob/main/guides/Option.md)。 。 。 .

```ts
import * as Match from "@effect/match"
import * as E from "@effect/data/Either"
import { pipe } from "@effect/data/Function"

// type Either<L, R> = { _tag: "Right", right: R } | { _tag: "Left", left: L }
// type Option<T> = { _tag: "Some", value: T } | { _tag: "None" }
const result = pipe(
  Match.value(E.right(0)),
  Match.when({ _tag: "Right" }, (_) => _.right),
  Match.option,
)

console.log(result) // { _tag: "Some", value: 0 }
```

### `exhaustive`

一个标记匹配过程结束的匹配器, 如果所有可能的匹配都完成了的话, 请检查 。 返回匹配( 对于 `Match.value`)或评价职能(用于 `Match.type`) (中文(简体) ).

```ts
import * as Match from "@effect/match"
import * as E from "@effect/data/Either"
import { pipe } from "@effect/data/Function"

// type Either<L, R> = { _tag: "Right", right: R } | { _tag: "Left", left: L }
const result = pipe(
  Match.value(E.right(0)),
  Match.when({ _tag: "Right" }, (_) => _.right),
  Match.exhaustive, // TypeError! { _tag: "left", left: never } is not assignable to never
)
```

### `orElse`

一个标出匹配者的尾端并允许在没有模式匹配的情况下提供倒数值的匹配者. 返回匹配( 对于 `Match.value`)或评价职能(用于 `Match.type`) (中文(简体) ).

```ts
import * as Match from "@effect/match"
import { pipe } from "@effect/data/Function"

const match = pipe(
  Match.type<string | number>(),
  Match.when("hi", (_) => "hello"),
  Match.orElse(() => "I literally do not understand"),
)

console.log(match("hello")) // "I literally do not understand"
console.log(match("hi")) // "hello"
```

### `either`

一个匹配者 _可能会_ 匹配一个值。 返回 a [无论是](https://github.com/fp-ts/core/blob/main/guides/Either.md) 形状 `Either<NoMatchResult, MatchResult>`。 。 。 .

```ts
import * as Match from "@effect/match"
import { pipe } from "@effect/data/Function"

const match = pipe(
  Match.type<string>(),
  Match.when("hi", (_) => "hello"),
  Match.either,
)

// type Either<L, R> = { _tag: "Right", right: R } | { _tag: "Left", left: L }
console.log(match("hi")) // { _tag: "Right", value: "hello" }
console.log(match("shigidigi")) // { _tag: "Left", value: "shigidigi" }
```

## 许可证

《麻省理工学院许可证》

## 常见问题

### @effect/match 是什么？

类型脚本的匹配模式注意：该包已被作者标记为弃用——this package has been merged into the main effect package

### 如何安装 @effect/match？

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

### @effect/match 支持 TypeScript 吗？

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

### @effect/match 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @effect/match 可以商用吗？

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

### @effect/match 的下载量有多少？

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

### @effect/match 还在维护吗？

最新版本 0\.40\.0 发布于 2023/10/08（3 年前）；至今共发布 86 个版本，其中过去 12 个月发布了 0 个；首次发布于 2023/01/30。作者已将其标记为弃用，新项目建议寻找替代方案。