# @effected/tsconfig-json 中文文档

规范地址：https://npmcn.com/package/%40effected/tsconfig-json/

版本：0\.22\.0
npm 元数据更新时间：2026-11-12T19:03:42.282Z
中文译文更新时间：2026-11-13T09:25:46.130Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：163 kB，17 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.11\.0
- 运行依赖：0 个
- peer 依赖：effect ~4\.1\.0，@effected/glob ^0\.22\.0，@effected/jsonc ^0\.25\.0，@effected/walker ^0\.29\.0
- 首次发布：2026-07-16T17:31:59.708Z
- 最新版本发布：2026-11-12T19:03:41.935Z
- 近 30 天下载量：6189（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：50（近 12 个月 50 个）

## 中文简介

Compossible tsconfig.json handling for Effect: schemas,扩展链分辨率和配置发现.

## 安装

```sh
npm install @effected/tsconfig-json
```

也可以使用：`pnpm add @effected/tsconfig-json`、`yarn add @effected/tsconfig-json`、`bun add @effected/tsconfig-json`

## README

# @ effect/ tsconfig-json (英语)

[![npm](https://img.shields.io/npm/v/@effected%2Ftsconfig-json?label=npm&color=cb3837)](https://www.npmjs.com/package/@effected/tsconfig-json) [![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/)

可编译 tsconfig.json 处理效果: 文档和编译器- 选项计划, `extends`\- 有 tsc 自身合并语义的链解析度,最近的配置发现和用于虚拟类型Script环境的可移植配置过滤器. 每个剖面都是JSONC——评论和后继逗号在任何地方都是合法的,完全像 tsc 对待它们一样——以及各种选择,这些计划不知道通过解码和编码,而不是被丢弃.

> **预`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/tsconfig-json

读取 tsconfig.json 正确的意思是复制 tsc 所做的, Tsc 所做的不仅仅是 `JSON.parse` 加号 `Object.assign`。一个 `extends` 目标解像模块: 赤光光光光光光的行走祖先 `node_modules` 目录, 一个软件包 `exports` 映射可以重定向或屏蔽它,并且 a `tsconfig` 字段可以完全指向别的地方。 合并链条是每个字段的,路径选项与宣布它们而不是你装入的配置相对应 `${configDir}` 在顶端配置目录中替换一次。 这些规则取自TypeScript编译器的源头,并在这里编码为由数据驱动的测试,所以你得到的分辨率是分辨率tsc计算.

包在不导入的情况下完成全部任务 `typescript`,甚至不是一个类型。 它在字符串级别工作—— `"target": "es2023"` 通过计划、合并和发现保留一个字符串——而版本相接的数值表映射在 `TsEnumCodec` 作为普通数据表格,将真正的编译器所期望的数字形状转换为明确的最后一步,而不是随处携带的依赖。 输入错误总是通过打出错误通道失败, 递归 `extends` 行走带有循环和深度守护,因为一个配置文件是不可信的输入.

## 安装

```bash
npm install @effected/tsconfig-json @effected/jsonc @effected/walker effect
```

```bash
pnpm add @effected/tsconfig-json @effected/jsonc @effected/walker effect
```

需要节点.js~~24.11.0. `effect` v4, (英语), `@effected/jsonc` 财务报告和审定财务报表 `@effected/walker` 是同行的依赖关系;没有自己的运行时间依赖关系.

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

所有IO通过 `FileSystem` 财务报告和审定财务报表 `Path` 从 `effect` 核心,不是平台包,所以消费者一次在边缘提供它们(`@effect/platform-node` 在节点上, `@effect/platform-bun` 测试提供了核心 `Path.layer` 外加来自 `@effected/memfs` ——未安装平台软件包.

## 快开始

解决一个配置及其全部 `extends` 链条 :

```ts
import { TsconfigLoader } from "@effected/tsconfig-json";
import * as NodeFileSystem from "@effect/platform-node/NodeFileSystem";
import * as NodePath from "@effect/platform-node/NodePath";
import { Effect, Layer } from "effect";

const PlatformLive = Layer.mergeAll(NodeFileSystem.layer, NodePath.layer);

const resolved = await Effect.runPromise(TsconfigLoader.resolve("./tsconfig.json").pipe(Effect.provide(PlatformLive)));

console.log(resolved.extendedPaths);
// every config on the extends chain as normalized absolute paths, base-most first and your own config last
console.log(resolved.compilerOptions);
// the merged options after folding the whole chain — later configs win per field, paths replaced wholesale
```

`TsconfigLoader.compilerOptions("./tsconfig.json")` 是相同的管道 预测到合并的选项, 因为当有效选项是你想要的.

在您只有起始目录时先查找最近的配置 :

```ts
import { TsconfigDiscovery } from "@effected/tsconfig-json";
import { Effect, Option } from "effect";

const nearest = TsconfigDiscovery.findNearest(process.cwd());
// Effect<Option<string>, never, FileSystem | Path> — absence is Option.none(), never an error
```

将结果交给一个真实的编译器,将enum家族编码为它们的数值形式,或者将其缩小为可移植子集,一个虚拟的TypeScript环境可以安全地再利用:

```ts
import { PortableTsconfig, TsEnumCodec } from "@effected/tsconfig-json";

console.log(TsEnumCodec.encodeCompilerOptions({ target: "es2023", strict: true, lib: ["esnext"] }));
// { target: 10, strict: true, lib: [ 'lib.esnext.d.ts' ] }

console.log(PortableTsconfig.make(resolved).compilerOptions.noEmit);
// true — always forced, whatever the source config declared

console.log(PortableTsconfig.make(resolved, { includeTypes: true }).compilerOptions.types);
// carries the source config's `types` package names when it declares them, omitted when absent
```

`includeTypes` 选择进入,默认为 `false` 因为排放 `types` 让科技部要求这些 `@types` 软件包解析 — 虚拟环境中的硬错误, 无 `node_modules`。当环境实现时通过它 `@types` 本身; 在 TypeScript 自动包含所找到的任何内容的允许默认情况下离开 .

## 同步装入

邦德勒插件钩和配置工厂往往无法等待. `TsconfigLoaderSync` 在您提供的文件和路径操作上同步运行未变的加载器管道——软件包仍然导入没有 `node:*` 模块,而节点的内置直接满足操作:

```ts
import { existsSync, readFileSync } from "node:fs";
import * as path from "node:path";
import { TsconfigLoaderSync } from "@effected/tsconfig-json";

const options = {
  fileSystem: { exists: existsSync, readFile: (p: string) => readFileSync(p, "utf8") },
  path, // node:path satisfies SyncPath verbatim; path.win32 / path.posix force a convention
};

const compilerOptions = TsconfigLoaderSync.compilerOptions("./tsconfig.json", options);
// the merged options for the full extends chain — the same result TsconfigLoader.resolve computes
```

`load` 财务报告和审定财务报表 `resolve` 具有相同的同步形式。 失败是Aync管道自己打出来的错误 `TsconfigParseError`, (中文(简体) ), `TsconfigExtendsError` 或一个 `PlatformError` 包着任何你 `readFile` 扔了... 从来没有纤维失效的包裹.

## TypeScript 7 和经典编译器 API

类型脚本 7 的本地 `tsc` 仅作为版本分贝的船舶 `.` export ——后面没有JS编译器API. 作为库驱动打字器的软件包( Name`@typescript/vfs`,语言服务,程序 API)既不能对 TypeScript 7 安装进行键入,也不能运行时装入 TypeScript 7 `typescript` 6岁时丧失了本地人 `tsc` 并打开工具链端点 `^7` 未达到。 保持两者的食谱都从这里开始,因为这个软件包是去除所依赖的编译时间的一半.

1.  键入到 tsconfig JSON 表格中,而不是编译器中。 公共选项类型 `CompilerOptions.Type` —— 说 `{ target: "es2022" }`绳子一直向下,所以没有 `src` 或试验进口 `typescript`,甚至不是一个类型。 德夫尔 `typescript` 留在7号线上,本地 `tsc --noEmit` 仍然运行类型检查和工具链 `^7` 同行保持满意.
2.  在一个运行时间接合时转换 . `TsEnumCodec.encodeCompilerOptions` 将字符串窗体映射到一个真正的编译器所期望的和返回的数值 `ProgrammaticCompilerOptions`,形状 a `ts.CompilerOptions`\- 型号的API没有铸币。 只有一个呼叫网站知道一个编译器存在. 入境方向是 `CompilerOptionsFromProgrammatic`一个计划,而不是一个功能: 把它当活的 `ts.CompilerOptions`,数字化的正文或输出 `encodeCompilerOptions` 已验证 `CompilerOptions.Type` 回来时,有一个不可操作的数字失败解码而不是漏出.
3.  作为测试运行时间的经典安装, 其中 JS API 是真正需要的: 一个 dev- only `"typescript-classic": "npm:typescript@^6.0.3"` 外加维特 `resolve.alias` 绘图 `typescript` 对它。 面对消费者的同龄人可以选择 `^6` ——只运行时间,适用于编译器-触控模块的调用者.
4.  过 `tsLibDirectory` 驾驶时明确 `@typescript/vfs`它会定位 `lib.*.d.ts` 结束 `require.resolve("typescript")`,在此设置下解决 TypeScript 7 安装,而该安装没有 lib 目录: 地图返回 **空**,沉默地,没有错误可循. 从您实际装入的模块中获取目录 .

```json
{
  "devDependencies": {
    "typescript-classic": "npm:typescript@^6.0.3"
  }
}
```

```ts
import { defineConfig } from "vitest/config";

export default defineConfig({
  resolve: { alias: { typescript: "typescript-classic" } },
});
```

```ts
import { dirname } from "node:path";
import { TsEnumCodec } from "@effected/tsconfig-json";
import { createDefaultMapFromNodeModules } from "@typescript/vfs";
import ts from "typescript";

const fsMap = createDefaultMapFromNodeModules(
  TsEnumCodec.encodeCompilerOptions({ target: "es2023", lib: ["esnext"] }),
  ts,
  dirname(ts.sys.getExecutingFilePath()),
);

console.log(fsMap.size);
// the lib files the loaded compiler ships; drop the third argument and this is 0
```

## 特征

-   `TsconfigJson` 编号 : `TsconfigJsonFromString` ——文档 schema及其JSONC字符串编码. 评论和后序逗号在每一段都是合法的;没有JSON限制路径.
-   `CompilerOptions` - 用于 `compilerOptions`:enum值对大小写不敏感地解码并编码为犬科小写,未知或被删除的选项在通过时能幸存回程.
-   `TsconfigLoader.load` 编号 : `TsconfigLoader.resolve` 编号 : `TsconfigLoader.compilerOptions` ——读出并解码一个配置,全部解决 `extends` 链式深度先与每个分支的循环堆栈(diamond 链是合法的),对于相对的,有根的和赤色的标靶来说,是深度守护和tsc的目标分辨率 `exports` 地图,或将解开的链条直下投影到其合并的选项.
-   `TsconfigLoaderSync` —— 只同步主机的同步外观 : `load`, (中文(简体) ), `resolve` 财务报告和审定财务报表 `compilerOptions` 超过消费供应 `{ fileSystem, path }` 操作,运行同一管线并投掷相同的打字错误.
-   `ResolvedTsconfig` - 后面的纯合并引擎 `resolve`: 每字段合并语义, 路径选项解析到声明配置目录, 最终 `${configDir}` 替换和 `pathsBase` 出处,完全没有文件系统访问.
-   `TsconfigDiscovery.findNearest` - 离这里最近的 `tsconfig.json` (或任何文件名通过) `options.filename`在起始目录上方或以上 `@effected/walker`; 一个无法读取的祖先无法在它上方隐藏一个配置.
-   `TsEnumCodec` ——字符串qq 数字表作为零的平方数据 `typescript` 进口. `encodeCompilerOptions` 返回导出的 `ProgrammaticCompilerOptions` 类型 - 数字形状 `ts.CompilerOptions` 期待,所以你把它交给一个 `ts.CompilerOptions`\- 成型的API没有铸件 - 与 `lib` 文件名格式中的条目,编译器将逐字解决; `decodeCompilerOptions` 倒车.
-   `CompilerOptionsFromProgrammatic` ——与验证代码相同的表格,用于持有TypeScript程序拼音的呼叫者. 解码器接受数字化的enums,cononical的字符串,大小写变化的字符串,任何三和三的混合 `lib` ; 编码返回数字形式。 没有表格条目的数值失败解码为打入的策略问题,而不是通过,这是检查 `TsEnumCodec.decodeCompilerOptions` 故意不做.
-   `PortableTsconfig.make` ——允许列表投影到机器独立的类型语义选项,带有 `composite: false` 财务报告和审定财务报表 `noEmit: true` 强制:一个虚拟 TypeScript 环境(Twoslash, API Creator, 内存语言服务)的切片可以安全地继承. 可选 `{ includeTypes }` 参数带有源配置 `types` 包名也放在便携式形状上,用于一个虚拟环境可以解决的呼叫者 `@types` 软件包本身; `typeRoots` 无论是哪种方式, 都保留, 因为它命名了机器专用、 配置位置依赖目录 .
-   `JsxConfig.fromCompilerOptions` ——JSX转换捆绑器可以配置,从解码选项投射: `react-jsx` 编号 : `react-jsxdev` 选择带有导入源的自动运行时间( 默认为 `react`,tsc本身的默认), `react` 选择经典,和 `preserve`, (中文(简体) ), `react-native` 或缺席 `jsx` 产量 `Option.none()`。 。 。 .
-   在所有地方打入失败: 文件格式错误是一个 `TsconfigParseError` 一条断链就是一条 `TsconfigExtendsError` 带有 `not-found` 编号 : `cycle` 编号 : `depth` 编号 : `empty` 理性和全解析链, IO 错误流经 `PlatformError`没有什么是失败的缺陷.

## 许可证

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

## 常见问题

### @effected/tsconfig-json 是什么？

Compossible tsconfig\.json handling for Effect: schemas,扩展链分辨率和配置发现\.

### 如何安装 @effected/tsconfig-json？

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

### @effected/tsconfig-json 支持 TypeScript 吗？

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

### @effected/tsconfig-json 支持 ESM 还是 CommonJS？

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

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

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

### @effected/tsconfig-json 可以商用吗？

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

### @effected/tsconfig-json 的下载量有多少？

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

### @effected/tsconfig-json 还在维护吗？

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