# @aleph-alpha/tsconfig-frontend 中文文档

规范地址：https://npmcn.com/package/%40aleph-alpha/tsconfig-frontend/

版本：0\.7\.3
npm 元数据更新时间：2026-10-28T11:38:18.218Z
中文译文更新时间：2026-11-05T22:04:06.137Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40aleph-alpha/tsconfig-frontend
原文对照：https://npmcn.com/package/%40aleph-alpha/tsconfig-frontend/?lang=original
项目主页：https://docs.aleph-alpha.com/

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

- 包体积（解压后）：134 kB，14 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：2 个
- 首次发布：2025-03-10T15:00:33.363Z
- 最新版本发布：2026-08-11T14:15:19.486Z
- 近 30 天下载量：14119（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：129（近 12 个月 86 个）

## 中文简介

共享严格的类型Script预设( 基础, vue- app, lib, 节点) , 用于 Aleph Alph Alph 前端工程

## 安装

```sh
npm install @aleph-alpha/tsconfig-frontend
```

也可以使用：`pnpm add @aleph-alpha/tsconfig-frontend`、`yarn add @aleph-alpha/tsconfig-frontend`、`bun add @aleph-alpha/tsconfig-frontend`

## README

# @ aleph- alpha/ tsconfig- 前端

共享, **严格默认** Aleph Alpha 前端工程的TypeScript配置.

它载着一小批 **可堆叠预设**. 想法:所有真正 _可分享_ (语言目标,模块分辨率,严格的家庭,通用质量旗帜) 住在一个被审查过的地方,一切 _具体项目_ (单位:千美元)`paths`, (中文(简体) ), `include`编号 :`exclude`, (中文(简体) ), 发射布局、环境 `types`留在消费项目中。 每个 `compilerOption` (单位:千美元) 预设套装可以被本地覆盖——预设是基线而不是紧身衣.

```bash
pnpm add -D @aleph-alpha/tsconfig-frontend
```

## 为何四个预设而不是一个?

`base` **实值** 单一可扩展的核心。 其他三个之所以存在是因为 TypeScript 编译 不同,相互排斥 _语境_ 一个配置不能同时服务——以及 每个前端工程已经分开(a) `tsconfig.app.json` 浏览器代码 + a `tsconfig.node.json` 工具是事实上的标准:

-   浏览器/ Vue 代码需求 `DOM` libs + JSX; 节点工具必须 **没有** 有他们.
-   节点工具需求 `types: ["node"]`; 浏览器代码必须 **没有** 污染其全球范围.
-   发射的软件包 `.d.ts` 需求 `declaration`编号 :`composite`不发射的应用软件会出错.

折叠到一个配置中不会移除这个配置——它只会复制到 每个项目(并像太低那样引起错误) `lib`) (中文(简体) ). 预设器将其移入一地.

## 一览预设

| 预设 | 扩展 | 用它来 | 爱慕? |
| --- | --- | --- | --- |
| [`/base`](https://npmcn.com/package/%40aleph-alpha/tsconfig-frontend/#readme-base) | —— 说 | 框架不可知 TS: 共享 libs, utils, 纯逻辑 | 没有 |
| [`/vue-app`](https://npmcn.com/package/%40aleph-alpha/tsconfig-frontend/#readme-vue-app) | ——(镜像) `@vue/tsconfig`(中文(简体) ) | Vue SFCs 浏览器代码( 应用程序和 Vue 组件 libs) | 无( Vite/ dts 插件出局) |
| [`/lib`](https://npmcn.com/package/%40aleph-alpha/tsconfig-frontend/#readme-lib) | `./base` | 可新建的放出库 `.d.ts` 通过 `tsc` | 对 |
| [`/node`](https://npmcn.com/package/%40aleph-alpha/tsconfig-frontend/#readme-node) | ——(镜像) `@tsconfig/node24`(中文(简体) ) | 节点工具 : `vite.config`, (中文(简体) ), `vitest.config`, (中文(简体) ), `eslint.config`脚本 | 没有 |

> 赤裸裸的 `@aleph-alpha/tsconfig-frontend` 条目仍然解决(它映射到遗产平面 配置)用于后向相容性. **新代码应扩展上面四个预设之一.**

* * *

## `/base`

**什麽** ——框架不可知的严格基准. 没有DOM,没有节点,没有JSX的假设.

**设定** (所有其它预设的可共享核心基于概念):

```jsonc
{
  "target": "es2022",
  "module": "esnext",
  "moduleResolution": "bundler",
  "lib": ["es2022"],

  // strict family
  "strict": true,                     // implies noImplicitAny, strictNullChecks, ...
  "noUncheckedIndexedAccess": true,   // arr[i] / obj[key] is T | undefined
  "verbatimModuleSyntax": true,       // type-only imports must use `import type`
  "useDefineForClassFields": true,

  // safe bug-catchers (no emit impact, catch real bugs)
  "noImplicitOverride": true,         // overrides must be marked `override`
  "noFallthroughCasesInSwitch": true,
  "noImplicitReturns": true,

  // ergonomics
  "isolatedModules": true,
  "esModuleInterop": true,
  "forceConsistentCasingInFileNames": true,
  "importHelpers": true,
  "resolveJsonModule": true,
  "skipLibCheck": true,
  "sourceMap": true
}
```

**为什么** ——这是整个矿石的严格性合同. `noUncheckedIndexedAccess` 编辑 捕虫者发现真正的缺陷; `verbatimModuleSyntax` 为捆绑者保持进口的明确性.

**何时使用** ——纯类型脚本,没有浏览器或节点假设(例如a) `utils` 软件包).

**如何使用**

```jsonc
{
  "extends": "@aleph-alpha/tsconfig-frontend/base",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": { "@/*": ["src/*"] }
  },
  "include": ["src/**/*.ts"]
}
```

* * *

## `/vue-app`

**什麽** ——为Vue Single-File组件和浏览器代码配置. 镜像 Vue 团队的官方 `@vue/tsconfig/tsconfig.dom.json`缩写(见 [为什么预设是自成一体的](https://npmcn.com/package/%40aleph-alpha/tsconfig-frontend/#readme-why-the-presets-are-self-contained)) (中文(简体) ).

**设定** (内线上) `@vue/tsconfig` 基线,已经提供 `strict`, (中文(简体) ), `verbatimModuleSyntax`, (中文(简体) ), `useDefineForClassFields`, (中文(简体) ), `jsx: "preserve"`, (中文(简体) ), `jsxImportSource: "vue"`, (中文(简体) ), `noEmit`:

```jsonc
{
  "lib": ["ES2022", "DOM", "DOM.Iterable"],
  "types": ["vite/client"],
  "noImplicitOverride": true,
  "noFallthroughCasesInSwitch": true,
  "noImplicitReturns": true
}
```

**为什么** —— 说 `.vue` 文件需要 JSX + DOM libs + Vue 的 `jsxImportSource`。镜像 `@vue/tsconfig` (而不是重新开发它) 给了我们Vue团队的战斗测试默认值; 重现上游 碰上时用手打印.

**何时使用** - 包含下列内容的任何应用程序或组件库: `.vue` 文档。 实际联合来文/`.d.ts` 输出为 生产 **视频 / `vite-plugin-dts`**没有 `tsc` 这样啊 `noEmit: true` (从内线基线)是 这里正确.

**如何使用**

```jsonc
{
  "extends": "@aleph-alpha/tsconfig-frontend/vue-app",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": { "@/*": ["src/*"] }
  },
  "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.vue"]
}
```

* * *

## `/lib`

**什麽** 用于可建库软件包,通过该软件包发送声明类型 `tsc`。 。 。 .

**设定** (续) `./base`:

```jsonc
{
  "declaration": true,
  "composite": true,
  "lib": ["es2022", "dom", "dom.iterable"]
}
```

**为什么** - 排放图书馆需要 `declaration` (至船舶) `.d.ts`和 `composite` (项目 参考文献/增量构建)。 这对应用来说是错误的,所以它们生活在自己的预设中.

**何时** - 一个非Vue包,其 `.d.ts` 由 `tsc` (非由维特. 通常配对 a 当地 `outDir`编号 :`rootDir`。 。 。 .

**怎么样**

```jsonc
{
  "extends": "@aleph-alpha/tsconfig-frontend/lib",
  "compilerOptions": {
    "outDir": "dist",
    "rootDir": "src",
    "paths": { "@/*": ["src/*"] }
  },
  "include": ["src/**/*.ts"]
}
```

> **说明:** `composite` 实值 **不兼容 `outFile`**。如果包件捆绑其声明 输入单个文件通过 `outFile`,扩展 `/base` 改为添加 `declaration` + 键 `emitDeclarationOnly` 当地(见 `outFile` (原始内容存档于2018-09-21). gotcha between.

* * *

## `/node`

**什麽** ——为节点执行的工具文件配置,不是运出浏览器代码.

**设定** (内线上) `@tsconfig/node24` 基线:

```jsonc
{
  "noEmit": true,
  "module": "esnext",
  "moduleResolution": "bundler",
  "types": ["node"],
  "noImplicitOverride": true,
  "noFallthroughCasesInSwitch": true,
  "noImplicitReturns": true
}
```

**为什么** —— 说 `vite.config.ts`, (中文(简体) ), `vitest.config.ts`, (中文(简体) ), `eslint.config.ts`,构建脚本等 节点和需要节点全球/类型, **没有** dOM(英语:DOM). 把它们保存在一个单独的配置中意味着浏览器 代码从不意外地在节点类型和反之.

**何时使用** - 那个 `tsconfig.node.json` 该类型检查您的配置/ 工具文件 .

**如何使用**

```jsonc
{
  "extends": "@aleph-alpha/tsconfig-frontend/node",
  "include": ["vite.config.ts", "vitest.config.ts", "eslint.config.ts"]
}
```

* * *

## 软件包拥有的对项目拥有的

**在预设中( 可共享) :** `target`, (中文(简体) ), `module`编号 :`moduleResolution`基线 `lib`严格 家庭,捕虫者, 和发射形状 `/lib`。仅通过更改软件包更改这些软件包 (所以每个消费者都一起行动).

**在项目中( 总是本地的和压倒性的):** `paths` + 键 `baseUrl`, (中文(简体) ), `include`编号 :`exclude`, (中文(简体) ), `rootDir`编号 :`outDir`编号 :`tsBuildInfoFile`环境 `types`, (中文(简体) ), `references`, (中文(简体) ), `experimentalDecorators`编号 :`emitDecoratorMetadata`,以及任何每个项目严格选择退出/选择进入.

## 为什么预设是自成一体的

这里没有扩展配置的预设 **另一个软件包** —— 说 `/vue-app` 财务报告和审定财务报表 `/node` 内含 上游基线`@vue/tsconfig`, (中文(简体) ), `@tsconfig/node24`)而不是延长.

TypeScript 解析软件包样式 `extends` 节点解决导入的方式,走起 `node_modules` 并跟随符号链接。 其他读取工具 `tsconfig.json` 别 剧作家,用于 一个,只看里面 `<the extending file>/node_modules/…` - 所以用pnpm, 里面一个包自己的 依赖性在商店而不是软件包文件夹内存在,无法遵循 `node.json → @tsconfig/node24` 无法完全装入配置 :

```
Failed to load tsconfig file at …/apps/<app>-e2e/tsconfig.json:
Failed to resolve "extends" path "@tsconfig/node24/tsconfig.json"
referenced from …/node_modules/@aleph-alpha/tsconfig-frontend/node.json
```

保持每一个预先设定的自成一体可以消除整个失败的类别——对于Playwright和任何 其他工具 一个天真的解析器。 其代价是,必须用手重新出现上游起伏 原出地(包装+准确版本)记录在 `"//"` 键位于每个受影响的预设的顶端.

相对 `extends` **在内部** 此软件包( e)`/lib → ./base`)是好的——每个工具都处理这个.

`@vue/tsconfig` 财务报告和审定财务报表 `@tsconfig/node24` 保留在本包中 `dependencies` 即使没有预设 继续扩展 这是故意的: 扔掉它们会打破任何消费者 `extends` 任意一个软件包 _直接_ 并依靠它过境抵达。 它们被保存在后方 兼容性并预定在今后的主要项目中清除——如果直接延长其中之一,则宣布 在你身边 `package.json`。 。 。 .

## 常见的覆盖( G)

这些是真正的移民,都是合法的 **当地** 覆盖 :

-   **需要一个新的JS内置** (单位:千美元)`Array.prototype.toSorted` =ES2023等吗?)? `@vue/tsconfig` 我们 预设目标为保守 `lib`。从本地跳出: `"lib": ["ES2023", "DOM", "DOM.Iterable"]`。这只影响类型检查 真实浏览器目标 .
-   **代码使用 `window`/DOM 但扩展 `/base`? 吗?** 添加 DOM 到 `lib` 当地: `"lib": ["ES2022", "DOM"]`。 。 。 . (或使用 `/vue-app`,包括DOM.)
-   **`outFile` 对于一个捆绑的 `.d.ts`? 吗?** `outFile` 两者均不相容 `composite` 财务报告和审定财务报表 `verbatimModuleSyntax`扩展 `/base`设置 `declaration` + 键 `emitDeclarationOnly` + 键 `outFile`,以及 覆盖 `"verbatimModuleSyntax": false` 当地.
-   **非配置文件的节点工具** (例如节点目标图书馆)? 扩展 `/base` 添加 `"types": ["node"]` 而不是说 `/node` (这迫使 `noEmit`) (中文(简体) ).
-   **移动一个日期之前的代码库 `noImplicitAny`? 吗?** 如果打开它 表面大量积压, 您可以临时设置 `"noImplicitAny": false` 本地并点出错误 打开 `base` 所以,新的/干净的代码保持严格的.

> **公约:** 文档 _原因_ 严格选择退出 **公关说明**,而不是作为一个 注释 `tsconfig` ——所以在后期取消重置后不会腐烂.

## 常见问题

### @aleph-alpha/tsconfig-frontend 是什么？

共享严格的类型Script预设\( 基础, vue- app, lib, 节点\) , 用于 Aleph Alph Alph 前端工程

### 如何安装 @aleph-alpha/tsconfig-frontend？

在项目目录运行 npm install @aleph-alpha/tsconfig-frontend，或使用 pnpm add / yarn add / bun add。

### @aleph-alpha/tsconfig-frontend 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/aleph-alpha\_\_tsconfig-frontend 是否存在。

### @aleph-alpha/tsconfig-frontend 支持 ESM 还是 CommonJS？

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

### @aleph-alpha/tsconfig-frontend 可以商用吗？

@aleph-alpha/tsconfig-frontend 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @aleph-alpha/tsconfig-frontend 的下载量有多少？

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

### @aleph-alpha/tsconfig-frontend 还在维护吗？

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