# @2digits/oxlint-plugin 中文文档

规范地址：https://npmcn.com/package/%402digits/oxlint-plugin/

版本：0\.5\.0
npm 元数据更新时间：2026-11-05T16:53:33.052Z
中文译文更新时间：2026-11-06T03:45:31.158Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%402digits/oxlint-plugin
原文对照：https://npmcn.com/package/%402digits/oxlint-plugin/?lang=original
源码仓库：https://github.com/2digits-agency/configs

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

- 包体积（解压后）：114 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2026-09-03T13:23:31.594Z
- 最新版本发布：2026-11-05T16:53:32.666Z
- 近 30 天下载量：5390（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：27（近 12 个月 27 个）

## 中文简介

2位数项目的自定义 Oxlint 规则 .

## 安装

```sh
npm install @2digits/oxlint-plugin
```

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

## README

# @ 2 数字/ xlint- 插件

自定义 [Oxlint JavaScript 插件](https://oxc.rs/docs/guide/usage/linter/writing-js-plugins.html) 规则 `@2digits/oxlint-config`。 。 。 .

默认启用建议集 `@2digits/oxlint-config`选择进入 `prefer-effect-filesystem` 财务报告和审定财务报表 `prefer-effect-path` 规则被排除,因为配置 `@effect/tsgo/nodeBuiltinImport` 诊断已经 更广泛地执行这些进口。 要直接注册插件 :

```ts
import { defineConfig } from 'oxlint';

import { recommendedRules } from '@2digits/oxlint-plugin';

export default defineConfig({
  jsPlugins: [{ name: '2digits', specifier: import.meta.resolve('@2digits/oxlint-plugin') }],
  rules: recommendedRules,
});
```

## 规则

包输出所有规则为 `rules`名称为 `RuleName`,默认错误级别配置为 `recommendedRules`。 。 。 .

-   复制和调整效果做法: `avoid-data-tagged-error`, (中文(简体) ), `ban-error-string`, (中文(简体) ), `effect-promise-vs-trypromise`, (中文(简体) ), `no-logging-in-catch`,以及 `throw-in-effect-gen`。 。 。 .
-   开放式建议的效果诊断 `Effect-TS/tsgo` 问题: `cors-*`, (中文(简体) ), `dual-*`, (中文(简体) ), `no-*`, (中文(简体) ), `prefer-*`, (中文(简体) ), `preserve-*`,以及 `require-*` 效果规则.
-   效果 v4 API 用于矩阵、 日期时间、 持续时间、 编码、 文件系统、 过滤器、 信头、 匹配、 路径和 Url, 加可中断 `Effect.tryPromise` th.
-   效果和炼金术进口政策:从PascalCase子模块的入站点、罐头效应别名、, 并且不导入根管模块. `@effect/vitest` 并且小写不稳定的桶被故意豁免.
-   炼金术 v2 实践: 所有其他 `alchemy-*` 规则.
-   数学领域模拟规则 `@alchemy.run/domain` 代理技能: `alchemy-domain-*` 规则。 见 [炼金术域模型](https://npmcn.com/package/%402digits/oxlint-plugin/#readme-alchemy-domain-models)。 。 。 .
-   从 t3code 跳出 Schema 编译器 : `no-inline-schema-compile` 报告 `Schema.decode*`, (中文(简体) ), `Schema.encode*`, (中文(简体) ), `Schema.is`,以及 `Schema.asserts` 在函数体内构建和引用的编译器,当其计划时 可升入模块范围.
-   日志结果 : `no-effect-as-on-log` 报告 `Effect.as`, (中文(简体) ), `Effect.asSome` 财务报告和审定财务报表 `Effect.asVoid` 适用于 `Effect.log*` 或者说 `Console.*` 日志效果 (e)`.pipe(Effect.as(x))`, (中文(简体) ), `pipe(log, Effect.as(x))` 或数据先行)。 写入 `Effect.gen` 那个 `yield*`s 日志并返回数值.
-   Schema 链样式 : `consistent-schema-pipe` 应用 Schema 修改器和数据最后步骤 `.pipe(...)` (单位:千美元)`Schema.String.pipe(Schema.optionalKey)`)并称为Schema 包装纸,例如: `Schema.Array(...)` 直接说 见 [ADR 0001 (韩语)](https://npmcn.com/package/docs/adr/0001-schema-modifiers-pipe-wrappers-call.md)。 。 。 .

看每个规则 `meta.docs.url` (c) 其上游规则、问题或框架文件。 复制代码归属于 [`NOTICE`](https://npmcn.com/package/%402digits/oxlint-plugin/NOTICE)。 。 。 .

## 炼金术域模型

这个 `alchemy-domain-*` 规则检查保留 [`@alchemy.run/domain`](https://alchemy.run/domain) 模式正确。 他们只看电话 `@alchemy.run/domain` 导入,所以其他代码不受影响.

-   `alchemy-domain-pure-decide` 报告时间(`Date()`, (中文(简体) ), `Date.now()`, (中文(简体) ), `new Date()`, (中文(简体) ), `Clock.*`, (中文(简体) ), `DateTime.now`, (中文(简体) ), `Jwt.verify`),随机性(`Math.random()`, (中文(简体) ), `crypto.randomUUID()`, (中文(简体) ), `Random.*`, (中文(简体) ), `SecureRandom.*`,则 `effect/crypto` 财务报告和审定财务报表 `effect/jose` 生成密钥、 非密钥或签名的 API, 如 `Aead.Aead`, (中文(简体) ), `Jwk.generateKeyPair` 财务报告和审定财务报表 `Jws.sign`)和一/一/一(`fetch`, (中文(简体) ), `Effect.promise`, (中文(简体) ), `Effect.tryPromise`, (中文(简体) ), `Jwks.Jwks`在聚合物中 `decide` 管理者。 决定密码( T)`Digest`, (中文(简体) ), `Mac`, (中文(简体) ), `Kdf`, (中文(简体) ), `KeyFormat`, (中文(简体) ), `Jws.verify`)被允许. 阅读时间从 `decide`是因为 `now` 参数和调用外部系统.
-   `alchemy-domain-total-handlers` 报告 `throw` 财务报告和审定财务报表 `Option`编号 :`Result` `getOrThrow*` 在一个集合中 `evolve` 财务报告和审定财务报表 `reply` 或风景 `evolve`保持任何无法遵循的状态 单位 `decide` 它也报告他们:返回 a 而不是拒绝.
-   `alchemy-domain-require-view-version` 需求 `version` 每页 `Domain.View`,所以改变视图的计算 坐在部署重建时必须碰倒的数字旁边. `version: 0` 保留当前默认值.
-   `alchemy-domain-block-file-name` 需要每个文件一个块, 以它的类型命名( n)`Account.aggregate.ts`, (中文(简体) ), `WithdrawMoney.command.ts`, (中文(简体) ), `FraudCheck.external.ts`, (中文(简体) ), `CurrentActor.context.ts`) (中文(简体) ). 事件和拒绝可以分享 命令、外部系统或使用它们的流的文件 `.event.ts` 或者说 `.rejection.ts` 文件,每个文件一个。 测试和故事文件被跳过 .
-   `alchemy-domain-pure-imports` 限制块文件( e)`*.aggregate.ts`, (中文(简体) ), `*.command.ts`, (中文(简体) ), `*.middleware.ts`,(...) 那个 导入 `@alchemy.run/domain` 相对进口, `effect` 财务报告和审定财务报表 `@alchemy.run/domain`。 。 。 .

没有自动修补的 规则只使用语法,所以一个助手从 `decide` 或者说 `evolve` 未遵循.

## 端点头图案

`no-uppercase-http-api-header` 在直接效果 v4 端点中报告每个静态 ASCII- oppercase 密钥 `headers` 字段对象。 来信头是小写, 和 chema 解码 完全向上 键 :

```ts
import * as Schema from 'effect/Schema';
import { HttpApiEndpoint } from 'effect/unstable/httpapi';

// Diagnosed: the required header is missing to the decoder even when it arrived.
HttpApiEndpoint.get('me', '/me', { headers: { 'X-Api-Key': Schema.String } });
// Valid: the schema matches the lowercase incoming key.
HttpApiEndpoint.get('me', '/me', { headers: { 'x-api-key': Schema.String } });
```

规则检查参数 2 的选项 `get`, (中文(简体) ), `post`, (中文(简体) ), `put`, (中文(简体) ), `patch`, (中文(简体) ), `delete`, (中文(简体) ), `head`,以及 `options`。 。 。 . 它解决了从 `effect/unstable/httpapi` 联 合 国 `HttpApiEndpoint` 子模块,包括 并忽略阴影绑定。 参考计划,计算密钥,分布, 复制密钥、访问器和模糊的选项对象在此初始切片之外。 已关闭 `make(method)`, (中文(简体) ), 页:1 `setHeaders`、本地请求/答复/牵引信头、外出设置和本地 `Headers.get`编号 :`has` 未检查. 只有ASCII大写字母被诊断出;该规则不使非ASCII名称正常化.

有一个 **无自定义**:重命名一个标题的 schema 密钥会更改打入的合同,并可能与小写密钥相撞. 一同检讨计划及其消费者. 运行时控制使用工作空间的效果版本 `@effect/vitest`。 。 。 . 这是预防指南: 历史机构扫描发现 **零坏站点和七个有效的终点计划**, (中文(简体) ), 不是7个缺陷 也不是时间短了.

### 测试

使用 `@effect/vitest` 用于测试效果代码。 运行效果 `it.effect` (或 `it.live` 实时运行时 服务需要),而非人工操作 `Effect.run*` 打电话 规则测试器和同步CLI测试定期使用 `it`。 。 。 .

### 持续时间常数

`prefer-effect-duration` 将数字字面和数字算术包装为 `Duration.Input` 生效 v4 APIs (单位:千美元)`Effect.sleep`, (中文(简体) ), `Effect.timeout`, (中文(简体) ), `Schedule.spaced`, (中文(简体) ), `Schedule.exponential`, (中文(简体) ), `Stream.debounce`, (中文(简体) ), `TestClock.adjust`,则 `duration` 选项 `Effect.timeoutOrElse`,以及其它)与 `Duration.millis`。 。 。 .

`prefer-effect-duration-constants` 报告 `const` 在文档中以简单数字表示持续时间的 导入效果 :

```ts
import * as Effect from 'effect/Effect';

const TIMEOUT_MS = 30_000; // Declare it as Duration.seconds(30)
const CACHE_TTL_SECONDS = 3600; // Declare it as Duration.hours(1)
const ONE_DAY = 24 * 60 * 60 * 1000; // Declare it as Duration.days(1)
const wait = 250; // Declare it as Duration.millis(250)

Effect.sleep(wait);
```

当一个常数名称以复数或缩略单位结尾时,即为报告(`_MS`, (中文(简体) ), `Seconds`, (中文(简体) ), `_MINS`, (中文(简体) ), `_DAYS`或一个 持续时间字(`TIMEOUT`, (中文(简体) ), `DELAY`, (中文(简体) ), `INTERVAL`, (中文(简体) ), `TTL`, (中文(简体) ), `ONE_DAY`, (中文(简体) ), `maxAge`, (中文(简体) ), `expiresIn`当它是手写的时间 算术,或当它传递到效果持续时间 API。 只有名字的最后一句话才算数 所以 `RETRY_DELAY_FACTOR` 不是一个持续时间。 包含名称 `per`, (中文(简体) ), `at`, (中文(简体) ), `epoch`,或 `timestamp` (单位:千美元)`MS_PER_SECOND`, (中文(简体) ), `REQUESTS_PER_SECOND`, (中文(简体) ), `CREATED_AT_MS`),零或负的恒星,和以a作注释的常数 `Duration` 类型是 跳过,除非它们被传递到一个持续时间 API 。 建议的构造器使用名称中的单元; Effect's millisecond 解释仅适用于持续时间的常数。 没有已知的单位,消息就保持通俗.

有一个 **无自定义**: 从 `number` 改为 `Duration`在非有效边界下转换 `Duration.toMillis` 或者说 `Duration.toSeconds`,读作可配置的持续时间 `Config.Duration`,并使用 `Schema.DurationFromMillis` 用于计划田地.

### 函数值配置默认值

`no-function-config-default` 将零参数函数传递给Effect的渴望 `Config.withDefault` API, (英语), 除非接收到的配置被当地证明具有函数:

```ts
import * as Config from 'effect/Config';

Config.withDefault(
  Config.succeed(() => 1),
  () => 2,
);
const config = Config.succeed(() => {
  return 1;
});

config.pipe(Config.withDefault(() => 2));
```

证据跟同案一样 `const` 接收者别名,不进行调用,并承认运行时间 `effect` 财务报告和审定财务报表 `effect/Config`包括别名和语法影子。 这个 `succeed` 参数必须是函数字元; 含有某个函数的无效对象不合格。 单位 `.pipe(...)`,只有第一个操作可以使用证明. 进口的、可变的或以其他方式构成的配置仍然未知,并保留诊断。 这是语法证明,不是 一般推论 `Config<A>`。参数化函数默认值仍然排除在外。 没有自动修正: 急于评估 或解开th可以改变副作用或有意的函数值.

## 反斜坡效果规则

适应自 [`dmmulroy/anti-slop`](https://github.com/dmmulroy/anti-slop/tree/main/src/effect/rules)数字 :

-   `no-manual-effect-error-tag`: 更喜欢贴有标签的处理器 `_tag` 大效果渔获量的比较/抽取.
-   `no-manual-tag-comparison`: 偏好匹配/预选字面 `_tag` 在渔获量之外进行比较和交换.
-   `no-manual-tagged-construction`: 偏好现有的构造器而不是字串 `_tag` 对象; 直接 `Match.when`编号 :`Match.not` 模式对象被豁免.
-   `no-service-constructor-imports`: 拒绝相对名称 `make[A-Z]` 外部进口 `.test`编号 :`.spec` 文档.
-   `prefer-effect-match`: 也报告连锁字三角比较同一源表达式,同时保留 现有的效果文件开关诊断.

全部列入 `recommendedRules`,没有自定义。 与上游一样,这些是协同政策: 要求进口效果,推断标记类型,或证明存在构造器。 确认渔获量和模式豁免 字义 `Effect`编号 :`Match` 标识符,而不是别名或阴影。 建构器导入匹配导入名称 (包括别名),不是返回类型;包/绝对进口不包括在内. 开关规则可以与 现有 `prefer-effect-match` 诊断.

## 自动修正

### 语句间隔( 选入)

`padding-line-between-statements` 适应了反斯洛普的销售商ESLint Stylistic规则. 不包括在 `recommendedRules`: 以明确政策使之生效。 后续匹配条目覆盖先前条目 .

```ts
export default {
  rules: {
    '2digits/padding-line-between-statements': [
      'error',
      { blankLine: 'always', prev: '*', next: 'return' },
      { blankLine: 'always', prev: ['const', 'let'], next: '*' },
      { blankLine: 'any', prev: ['const', 'let'], next: ['const', 'let'] },
    ],
  },
};
```

接受选项 `always`, (中文(简体) ), `never`,或 `any`,语句名称(包括类型脚本声明和 `singleline-*`编号 :`multiline-*` 变体、数组或 `{ selector: 'ExpressionStatement', lineMode: 'multiline' }` AST选取者. 选择者必须匹配语句节点( 例如) `ExpressionStatement[expression.type="CallExpression"]`而不是他们的 筑巢表达. 见 [上游语句名称](https://eslint.style/rules/padding-line-between-statements)。 。 。 . 自动修补保存了后缀的注释并避免被注释分隔出多个空白行间隙倒塌. 导出 `PaddingLineOption` 类型描述每个配置条目。 没有选择就意味着没有诊断.

### 其他修正

运行 `vpr lint:oxlint:fix` 从寄存器根到应用修正 `consistent-schema-pipe`, (中文(简体) ), `prefer-effect-duration`, (中文(简体) ), `no-empty-effect-callback`, (中文(简体) ), `no-effect-alchemy-barrel-imports`, (中文(简体) ), `prefer-effect-alchemy-namespace-imports`, (中文(简体) ), `alchemy-no-v1-worker-properties`,以及 `alchemy-no-deprecated-docker-constraints`。 。 。 . 修补会跳过模棱两可的绑定,相互冲突的属性,以及不支持的导入引用.

## 添加规则

Oxlint的JavaScript插件API目前为α,不出出类型信息. 保持语法安全 离开 语义效果检查到 `@effect/tsgo` 编号 : `@effect/language-service`。 。 。 .

Oxfmt 格式导入,但不执行包的特定导入架构. 效果语言服务 `namespaceImportPackages` 财务报告和审定财务报表 `importAliases` 设置指南只生成自动导入, 所以插件执行相同 手写导入政策.

1.  在下面添加一个规则文件 `src/rules/alchemy` 或者说 `src/rules/effect` 与 `defineRule` 结束 `defineSyntaxRule` 或者说 `defineEffectRule`。 。 。 .
2.  登记在册 `src/rules/index.ts`。 。 。 . `src/index.ts` 自动包含在 `recommendedRules`。 。 。 .
3.  在下面添加匹配的测试文件 `test/rules` 有效且无效 `RuleTester` 案例.
4.  运行 `vpr test` 财务报告和审定财务报表 `vpr build` 在此软件包中 `vpr check` 从寄存器根.

`defineEffectRule` 解决命名空间和命名导入 `effect`, (中文(简体) ), `@effect/*`,以及 `alchemy/*` 进入点,所以规则 应当匹配条形API路径,而不是硬编码本地导入名称.

## 常见问题

### @2digits/oxlint-plugin 是什么？

2位数项目的自定义 Oxlint 规则 \.

### 如何安装 @2digits/oxlint-plugin？

在项目目录运行 npm install @2digits/oxlint-plugin，或使用 pnpm add / yarn add / bun add。

### @2digits/oxlint-plugin 支持 TypeScript 吗？

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

### @2digits/oxlint-plugin 支持 ESM 还是 CommonJS？

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

### @2digits/oxlint-plugin 可以商用吗？

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

### @2digits/oxlint-plugin 的下载量有多少？

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

### @2digits/oxlint-plugin 还在维护吗？

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