# @aurelienbbn/oxlint-plugin-xstate 中文文档

规范地址：https://npmcn.com/package/%40aurelienbbn/oxlint-plugin-xstate/

版本：0\.2\.0
npm 元数据更新时间：2026-10-14T14:33:48.818Z
中文译文更新时间：2026-11-07T05:30:01.634Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40aurelienbbn/oxlint-plugin-xstate
原文对照：https://npmcn.com/package/%40aurelienbbn/oxlint-plugin-xstate/?lang=original
项目主页：https://github.com/aurelienbobenrieth/harness/tree/main/packages/oxlint-plugin-xstate#readme
源码仓库：https://github.com/aurelienbobenrieth/harness

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

- 包体积（解压后）：282 kB，7 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^22\.19\.0 \|\| ^24\.11\.0
- 运行依赖：1 个
- peer 依赖：oxlint \>=1\.82\.0 \<2\.0\.0
- 首次发布：2026-09-25T09:46:38.423Z
- 最新版本发布：2026-10-14T14:33:48.465Z
- 近 30 天下载量：2417（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

X国产机器和演员的自定义克克林特规则.

## 安装

```sh
npm install @aurelienbbn/oxlint-plugin-xstate
```

也可以使用：`pnpm add @aurelienbbn/oxlint-plugin-xstate`、`yarn add @aurelienbbn/oxlint-plugin-xstate`、`bun add @aurelienbbn/oxlint-plugin-xstate`

## README

# @aurelienbn/克林特-插文-xstate

[![npm](https://img.shields.io/npm/v/@aurelienbbn/oxlint-plugin-xstate)](https://www.npmjs.com/package/@aurelienbbn/oxlint-plugin-xstate) [![downloads](https://img.shields.io/npm/dm/@aurelienbbn/oxlint-plugin-xstate)](https://www.npmjs.com/package/@aurelienbbn/oxlint-plugin-xstate) [![CI](https://github.com/aurelienbobenrieth/harness/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/aurelienbobenrieth/harness/actions/workflows/ci.yml) [![license](https://img.shields.io/npm/l/@aurelienbbn/oxlint-plugin-xstate)](https://github.com/aurelienbobenrieth/harness/blob/main/packages/oxlint-plugin-xstate/LICENSE) [![node](https://img.shields.io/node/v/@aurelienbbn/oxlint-plugin-xstate)](https://github.com/aurelienbobenrieth/harness/blob/main/packages/oxlint-plugin-xstate/package.json)

**17个xState v5 和 v6 alpha 机器的克林特规则(使用 `@xstate/effect`),与 `setup().createMachine()`,形状 `eslint-plugin-xstate` 看不见.**

> v6 支持被选中 `xstate@6.0.0-alpha.64`, (中文(简体) ), `@xstate/effect@0.1.0-alpha.6` 财务报告和审定财务报表 `@xstate/react@7.0.0-alpha.4`;α APIs可以在发行间移动.

|  | `eslint-plugin-xstate` | 此插件 |
| --- | --- | --- |
| `setup().createMachine()` 机器 | 裸着 `createMachine` 仅被调用 | qq 设置意识 |
| XState v6 alpha + 状态 `@xstate/effect` | ❌ | v5和v6拼写 |
| 维持 | QQ 上次发布 2023- 12, ESLint 8 同行 | 牛林 >= 1.82.0 < 2.0.0 |

```sh
pnpm add -D @aurelienbbn/oxlint-plugin-xstate oxlint
```

```json
{
  "jsPlugins": ["@aurelienbbn/oxlint-plugin-xstate"],
  "rules": {
    "xstate/require-setup-create-machine": "error",
    "xstate/no-context-mutation": "error",
    "xstate/require-effect-actor": "error",
    "xstate/no-deferred-enqueue": "error"
  }
}
```

无预设,无自定义:按名称启用每个规则.

## 13个固体、2个MayBE、2个已贬值

```text
solid       █████████████  13   error
MAYBE       ██              2   off or warn: no-unreachable-transition · promise-actor-abort-signal
deprecated  ██              2   v5 only: no-imperative-action-creator · prefer-send-to
```

**`no-imperative-action-creator` 财务报告和审定财务报表 `prefer-send-to` 自0.2.0起贬值.** XState v6 移除动作创建器并 `sendParent` (导入一个是类型错误);两种规则在迁移前仍然在v5上工作.

`no-direct-named-action` 与显示直接的上游 v6 文档相矛盾 `actions.x(...)` 打电话 无论如何,它都报告他们:在α.64中,一个直通电话两次跑一次 `send`在纯度期间运行 `transition()` 财务报告和审定财务报表 `snapshot.can()`。 。 。 .

## 什么火吗

```ts
setup({ types: {} }).createMachine({
  entry: ({ context }) => {
    assign({ count: context.count + 1 });
  }, // ❌ no-imperative-action-creator: builds an action, runs nothing
});
setup({ types: {} }).createMachine({
  entry: assign({ count: ({ context }) => context.count + 1 }), // ✅
});

actorRef.send({ type: "ADD_ITEM", id: "x" }); // ❌ require-event-satisfies
actorRef.send({ type: "ADD_ITEM" } satisfies CartEvent); // ✅

setup({}).createMachine({ id: "app.cart" });
// ❌ require-setup-create-machine: neither `types` (v5) nor `schemas` (v6)

// v6 alpha / @xstate/effect
createActor(setupEffect({ actors }).createMachine(config)); // ❌ require-effect-actor: status 'error', use createEffectActor
on: { SAVE: (_, enq) => { setTimeout(() => enq.raise({ type: "SAVED" }), 100); } } // ❌ no-deferred-enqueue
on: { SAVE: (_, enq) => { enq.raise({ type: "SAVED" }, { delay: 100 }); } } // ✅
after: { "5m": { target: "expired" } } // ❌ valid-duration: write "PT5M" or 300000
```

## `require-event-satisfies` 类型被删除的事项

```text
setup({ types }) machine  ──▶  TypeScript already checks the payload  → rule redundant
sendTo / sendParent targets,
AnyActorRef, untyped refs ──▶  event type erased                      → rule is the only check
```

**完全输入代码库? 缩小 `sendCalleeNames` 给被抹去的发件人.** `satisfies unknown` 编号 : `any` 规则是执行语法,而不是预期的事件结合.

选项和默认

| 规则 | 选项 | 默认 |
| --- | --- | --- |
| `machine-naming` | `pattern` | `^[a-z][a-z0-9-]*\.[a-z][a-z0-9-]*$` (基因活性克巴布(kebab-case)取名空间,不特指io) |
| `named-actor-src` | v5 文件 : `invoke.src` 或第一个参数: `spawnChild` 编号 : `enqueue.spawnChild` 是一个调用,一个函数,或者一个不绑定于字符串常数的标识符; v6: 第一个参数 `enq.spawn` 这是一个呼吁, `new`,或函数 | `false`· ; `true` 还检查 `spawn(...)` 从一个 `assign` 参数或 v6 上下文厂。 xqq v6 文件( 没有只导入 v5 文件, 没有) `types`: `invoke.src`,标识符 |
|  | `guards` | `false`· ; `true` 还报告内在函数 `guard` 数值 |
| `no-context-mutation` | `allowCollectionMethods` | `false`· ; `true` 豁免地图/设置 `set` 编号 : `add` 编号 : `delete` 编号 : `clear`; v6 类型 `createLogic` 编号 : `createAsyncLogic` 编号 : `<setup>.createInvoke` 编号 : `createStateConfig(path, config)`, (中文(简体) ), `setupEffect` (单位:千美元)`@xstate/effect`, (中文(简体) ), `.provide` 编号 : `.extend` |
| `require-event-satisfies` | `sendCalleeNames` | `["send", "raise", "sendTo", "sendParent", "emit", "sendBack"]`; v6 类型 `enq.raise` 编号 : `sendTo` 编号 : `emit` 编号 : `sendBack` 处理器的第二个参数; `@xstate/effect` `send(actor, ev)` 编号 : `send(ev)`· ; `.send` 打开 `<system>.createActor` 财务报告和审定财务报表 `yield* createEffectActor` 参考 |

每项规则的确切触发因素和范围

| 规则 | \* 开火 | 匹配/ QQ 跳过 |
| --- | --- | --- |
| `no-imperative-action-creator` | qq已贬值(只有v5). `assign` 编号 : `raise` 编号 : `sendTo` 编号 : `sendParent` 编号 : `forwardTo` 编号 : `emit` 编号 : `cancel` 编号 : `stopChild` 编号 : `stop` 编号 : `spawnChild` 编号 : `log` 编号 : `enqueueActions` 作为被丢弃的语句(亦包括 `void` 编号 : `await`,或用简洁的箭头返回 `entry` 编号 : `exit` 编号 : `actions` 或者说 `setup({ actions })` | 从 `xstate`或调用 `setup()` 结果 |
| `no-context-mutation` | 任务, `++` 编号 : `--`, (中文(简体) ), `delete`,或根植于 `context` 或者说 `snapshot.context` 编号 : `getSnapshot().context` | `context` 由内部执行功能解构 `setup` 编号 : `createMachine` 编号 : `createStateConfig` 编号 : `createAction` 编号 : `assign` 编号 : `enqueueActions`方法: `push`, (中文(简体) ), `pop`, (中文(简体) ), `shift`, (中文(简体) ), `unshift`, (中文(简体) ), `splice`, (中文(简体) ), `sort`, (中文(简体) ), `reverse`, (中文(简体) ), `fill`, (中文(简体) ), `copyWithin`, (中文(简体) ), `set`, (中文(简体) ), `add`, (中文(简体) ), `delete`, (中文(简体) ), `clear`地图/地图 `allowCollectionMethods: true` |
| `no-machine-in-render` | `createMachine`, (中文(简体) ), `<setup>.createMachine` (包括:. `setupEffect`, (中文(简体) ), `system.setup`, (中文(简体) ), `createActor`, (中文(简体) ), `<system>.createActor`, (中文(简体) ), `interpret`, (中文(简体) ), `createActorAtoms` 直接在部件或钩体中 | 最近的附加函数是一个组件( q)`/^[A-Z]/`)或钩(`/^use[A-Z]/`, (中文(简体) ), `memo` 编号 : `forwardRef` 包含, 在导入的文件中 `react` 或者说 `@xstate/react`. . . . . . `useMemo`, (中文(简体) ), `useEffect`处理者, `machine.provide(...)` |
| `named-actor-src` | `invoke.src` 或第一个参数: `spawnChild` 编号 : `enqueue.spawnChild` 那是一个调用,一个函数,或者一个不绑定于字符串常数的标识符 | `invoke.src` 内 `createMachine` 编号 : `<setup>.createMachine` 编号 : `<setup>.createStateConfig` 相会. 成员表达式 |
| `stable-selector-result` | 内入 `useSelector` 或者说 `actor.select` 选择器返回新的对象/阵列,没有参照参数 | `useSelector` 从 `@xstate/react`, (中文(简体) ), `@xstate/store-react`遗产 `@xstate/store/react`, (中文(简体) ), `<ActorContext>.useSelector`。新鲜=对象/阵列正文, `.map` 编号 : `.filter` 编号 : `.flatMap` 编号 : `.toSorted`, (中文(简体) ), `Object.keys` 编号 : `values` 编号 : `entries`· ; `.select` 打开 `createActor` 编号 : `<system>.createActor` 编号 : `useActorRef` 裁判员。 原子数 `.select` |
| `require-setup-create-machine` | `createMachine`, (中文(简体) ), `setup`, (中文(简体) ), `setupEffect` 或者说 `<system>.setup` 他们的字面特征没有 `types` 也没有 `schemas`,除非每个 `.createMachine` 编号 : `.extend` 在文件的设置上声明 | 命名和命名空间导入,别名,词典阴影。 ⏭️ `setup(...)` 无法静态读取的参数( 识别符、 扩展符) |
| `require-event-satisfies` | 发送到不包含的对象升字事件 `satisfies` | `send`, (中文(简体) ), `raise`, (中文(简体) ), `sendTo`, (中文(简体) ), `sendParent`, (中文(简体) ), `emit` 从 `xstate`· ; `enqueue.raise` 编号 : `sendTo` 编号 : `sendParent` 编号 : `emit` 打开 `enqueueActions`' `enqueue`· ; `.send` 参考书目 `createActor`, (中文(简体) ), `useActorRef`, (中文(简体) ), `<ActorContext>.useActorRef()`,则 `useMachine` 编号 : `useActor` 二联( t)`send` 和演员-后备插槽)。 无关 `.send` 方法 |
| `machine-naming` | 当前静态机器 id 失败 `pattern` | \* 缺少身份证; `createStateConfig` (状态-节点标识,而不是机器标识) |
| `no-unreachable-transition` | 未加保护的分支不持续于 `always`, (中文(简体) ), `on.<EVENT>`, (中文(简体) ), `after.<DELAY>`, (中文(简体) ), `onDone`, (中文(简体) ), `onError` 数组( v5); 无目标无条件 `always` 与 `actions` 或者说 `context`,或者一个 v6 `always` 函数返回无目标 `{ context }` 在每个路径上补丁( 无限循环) | 有分数或计算键的分枝 |
| `prefer-send-to` | qq已贬值(只有v5). `sendParent` 进口自 `xstate`,以及 `<object>.sendParent(...)` 例如 `enqueue.sendParent` |  |
| `promise-actor-abort-signal` | 内入 `fromPromise`, (中文(简体) ), `createAsyncLogic({ run })` 或者说 `<setup>.createInvoke({ src })` 全球逻辑 `fetch` 读作(无正文或正文) `GET` 编号 : `HEAD`从未引用 `signal` | 被包裹的HTTP客户端是隐形的 |
| `require-effect-actor` | `createActor` 编号 : `useMachine` 编号 : `useActor` 编号 : `useActorRef` 编号 : `createActorContext` 给定 `fromEffect*` 逻辑或a `setupEffect` 机器(内含,通过 `const`, (中文(简体) ), `.provide`, (中文(简体) ), `.extend`(中文(简体) ) | ⏭️ `createEffectActor`, (中文(简体) ), `createActorAtoms` |
| `no-discarded-effect` | `enq(() => Effect.…)`,或从 `entry` 编号 : `exit` / 过渡 | `Effect` 进口自 `effect`。 。 。 `Effect.run*` 编号 : `Effect.is*`, (中文(简体) ), `enq(actions.x, params)` |
| `no-deferred-enqueue` | `enq` 编号 : `enq.*` 在计时器内,承诺,听众或排队效应回调,或之后 `await`,在v6处理器中 | qq 同步回调(`forEach`, (中文(简体) ), `createAsyncLogic` `run` |
| `no-direct-named-action` | `actions.x(...)` 在 v6 处理器中直接调用 | `{ actions }` 编号 : `{ actions: a }` 编号 : `args.actions`内部 `enq(() => …)`,行动实施,上下文厂 |
| `valid-duration` | 时间类似 `after` 键, `timeout`,或 `createAsyncLogic` 超时字符串 X状态无法解析和否 `delays` 条目名称 | 接受ms数字, `<n>ms`, (中文(简体) ), `<n>s`,ISO 8601 (中文(简体) )`PT5M`) (中文(简体) ). 仅报告 |
| `no-persist-live-snapshot` | `JSON.stringify` 联 合 国 `getSnapshot()`页:1 `useMachine` 快照,或者说 `subscribe` 听众快照 | ⏭️ `getPersistedSnapshot()`, (中文(简体) ), `getSnapshot().context`,接收者不能证明是行为者 |

配置规则处理 `<setup>.createStateConfig(...)` (v6):第二个论点是: `createStateConfig(path, config)`作为机器配置。 v6 规则确认处理器为 `entry` 编号 : `exit` 编号 : `always` 编号 : `on` 编号 : `after` 编号 : `onDone` 编号 : `onError` 编号 : `onSnapshot` 编号 : `onTimeout` 编号 : `to` 插槽,与 `enq` 作为他们的第二个参数.

**未运出 : `no-deprecated-xstate-api`。 。 。 .** 类型意识 `typescript/no-deprecated` 已报告 `interpret`, (中文(简体) ), `stop`, (中文(简体) ), `getNextSnapshot` 以及其它问题 `@deprecated` 出口.

**资信:** `no-imperative-action-creator` 财务报告和审定财务报表 `no-unreachable-transition` 重新执行 `eslint-plugin-xstate`是因为 `no-imperative-action` 财务报告和审定财务报表 `no-infinite-loop` 思想(理查德·拉弗斯); `no-discarded-effect` 重新实施州/州的想法 `no-inline-effect` (麻省理工学院). 没有复制代码 .

## 登记的合同库存

从软件包导出 `pnpm catalog`. 规则特定选项和限制在上文和源测试中都有描述.

| 规则/检查 | 触发或审查范围 |
| --- | --- |
| `machine-naming` | 要求 X State 机器ID 遵循配置的命名公约 . |
| `named-actor-src` | 要求引用.src和产卵儿童() (X State v5)和enq.spawn () (X State v6) 引用按键而不是内置演员逻辑在设置({ 演员})中声明的演员. |
| `no-context-mutation` | XState 语境中被禁的就地变异(在上下文或shapt.context上指定、删除和变异数组/Map/Set方法). |
| `no-deferred-enqueue` | 禁止从计时器中调用 v6 处理器的 enq, 许诺, 倾听, 或 等效回调, 或等待之后 . |
| `no-direct-named-action` | 禁用在 v6 处理器中直接调用命名动作, 而不是 enq( actions. name, params) . |
| `no-discarded-effect` | 在 inline enq( () QQ.) 效应内所建的或从机器处理器返回的禁用效果, X State 丢弃它们未运行 . |
| `no-imperative-action-creator` | Forbid X State 动作创建者( 指定, 提升, send To, ...) 调用为已丢弃的语句或从内置动作函数返回, 在那里他们默默无声 . |
| `no-machine-in-render` | Forbid 创建 Machine, setup (. create Machine), create Actor, system.create Actor, 解释并创建 ActorAtoms 直接在一个 React 组件或钩身中调用. |
| `no-persist-live-snapshot` | Forbid JSON.stringify of a actor's live快照(GetSnapshot (),使用Machine快照,订阅者听众快照),而不是取PersistedSnapshot (). |
| `no-unreachable-transition` | 强制将一个无保护的过渡放置在同一过渡阵列(XState v5)的其他分支上,并且无目标过渡总是会重新运行其动作或上下文永远更新. |
| `prefer-send-to` | Prefer sendTo () 由演员参考器通过输入通过 sendParrent () and enqueue. sendParrent (). |
| `promise-actor-abort-signal` | 需要内置的同声演员逻辑(来自Promise, CreateAsyncLogic run, CreateInvoke src),该逻辑要求获取一个读取以转发演员的中止信号. |
| `require-effect-actor` | 要求以创建效果Actor开始@xstate/effect逻辑(从effect \*,设置效果机),而不是创建Actor或@xstate/ react hooks. |
| `require-event-satisfies` | 要求发送到机器上的物体读取事件符合. |
| `require-setup-create-machine` | 要求 X State 机器在创建 Machine (), 设置 (), 设置效果 () 或 system. setup () 上声明类型 (XState v5) 或 schemas (XState v6) . |
| `stable-selector-result` | 禁入内行使用Selector 和 actor. 选择当没有通过参照参数时返回新对象或数组的选择器. |
| `valid-duration` | 要求在按键后, 状态超时, 并创建 AsyncLogic 超时, 作为持续时间字符串写入以使用格式 X State 剖析, 除非它们指定一个已声明的延迟 . |

### 信用概念

-   由Sandro Maglione(启发、独立重新执行)自动操作
-   由Richard Laffers(概念)撰写
-   由理查德·拉弗斯所著 (概念)
-   statelyai/xstate no-inline-effect(麻省理工学院;概念,独立执行)

## 常见问题

### @aurelienbbn/oxlint-plugin-xstate 是什么？

X国产机器和演员的自定义克克林特规则\.

### 如何安装 @aurelienbbn/oxlint-plugin-xstate？

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

### @aurelienbbn/oxlint-plugin-xstate 支持 TypeScript 吗？

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

### @aurelienbbn/oxlint-plugin-xstate 支持 ESM 还是 CommonJS？

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

### @aurelienbbn/oxlint-plugin-xstate 需要什么版本的 Node\.js？

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

### @aurelienbbn/oxlint-plugin-xstate 可以商用吗？

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

### @aurelienbbn/oxlint-plugin-xstate 的下载量有多少？

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

### @aurelienbbn/oxlint-plugin-xstate 还在维护吗？

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