Egg 项目 TypeScript 基础配置包 eggjs/tsconfig 完全指南从安装、配置项解析到版本演进【免费下载链接】egg Born to build better enterprise frameworks and apps with Node.js Koa. https://307.run/eggcode项目地址: https://gitcode.com/gh_mirrors/eg/eggeggjs/tsconfig 是 Egg 框架官方维护的 TypeScript 基础编译配置包旨在为 Egg 及 TeggEgg 的依赖注入增强方案相关项目提供一套开箱即用、与框架自身构建链路tsdown、vitest保持一致的编译器默认值。本文以仓库中 packages/tsconfig/CHANGELOG.md 的版本演进为脉络结合 packages/tsconfig/tsconfig.json、packages/tsconfig/package.json 及 packages/tsconfig/test/index.test.ts 的源码证据逐项讲解每个核心配置项的含义、默认值与适用场景帮助读者直接在自己的 Egg TypeScript 项目中落地使用并理解升级大版本时需要关注的破坏性变更。一、这个包是什么Egg 官方 TypeScript 基础配置的定位在 Egg 框架的 monorepo 中packages/tsconfig是一个极简但关键的基建包它的全部发布产物只有一份tsconfig.json见 packages/tsconfig/package.json 中files: [tsconfig.json]通过 npm 包名eggjs/tsconfig对外分发供各类 Egg TypeScript 项目通过extends继承。它的核心定位有两个统一编译基线将 strict 严格模式、装饰器支持、ESM/NodeNext 模块解析、Node.js 版本对应的 target 等最佳实践固化为默认值避免每个项目各自摸索与框架构建工具链对齐仓库内多个包如packages/core、packages/egg等的tsconfig.json均在此基础上衍生配合tsdown.config.ts、vitest.config.ts完成打包与测试。从源码看当前仓库中的版本为3.1.2-beta.25engines声明node 22.18.0且type: module表明该包已全面切换到 ESM 体系见 packages/tsconfig/package.json。二、安装与使用三步接入你的 Egg 项目官方 README见 packages/tsconfig/README.md给出了最直接的接入方式。1. 安装为开发依赖npm i --save-dev eggjs/tsconfig2. 在项目 tsconfig.json 中继承// tsconfig.json { extends: eggjs/tsconfig, // custom config compilerOptions: { // override eggjs/tsconfig options here } }extends的语义是先加载eggjs/tsconfig中的基础配置再合并当前文件中的自定义项当前文件中的compilerOptions会覆盖同名默认值未覆盖的键沿用基础配置。3. 验证测试 fixture 是现成的参考样例仓库测试夹具 packages/tsconfig/test/fixtures/apps/ts-proj/tsconfig.json 就是一个最小可用示例——它只额外设置了输出目录{ extends: eggjs/tsconfig, compilerOptions: { outDir: dist } }其配套源码 Foo.ts 与 FooDecorator.ts 刻意覆盖了三个典型能力点类装饰器验证experimentalDecoratorsemitDecoratorMetadata、带.ts扩展名的相对导入验证allowImportingTsExtensionsrewriteRelativeImportExtensions、try/catch中的instanceof类型收窄验证useUnknownInCatchVariables。跑通这个 fixture 即代表基础配置可用。三、核心配置项深度解析每一行默认值背后的原因下面逐组解析 packages/tsconfig/tsconfig.json 中的默认配置注释均取自该文件源码读者可直接对照。3.1 严格模式与代码质量约束strict: true, noImplicitAny: true, noUnusedLocals: true, noUnusedParameters: true, allowUnreachableCode: false, allowUnusedLabels: false, noFallthroughCasesInSwitch: truestrict: true是整套严格检查的总开关连带开启noImplicitAny等多项严格检查noUnusedLocals/noUnusedParameters会在编译期直接报错杜绝未使用变量与参数——在 Egg 的中间件、控制器这类按约定签名的代码里这能强制开发者显式声明未用参数通常以下划线开头保持代码整洁allowUnreachableCode: false与allowUnusedLabels: false禁止不可达代码与未使用标签noFallthroughCasesInSwitch防止switch分支意外贯穿。3.2 现代 ESM / NodeNext 模块体系3.x 的核心变更// https://node.green/#ES2024 target: ES2024, module: NodeNext, moduleResolution: NodeNext, esModuleInterop: true, verbatimModuleSyntax: false, rewriteRelativeImportExtensions: true, allowImportingTsExtensions: true, erasableSyntaxOnly: true这是 3.0.0 版本esm only方向的具体落地详见下文版本演进target: ES2024与 Node.js 22 的运行能力对齐允许使用最新 ECMAScript 语法源码注释指向 Node.js 兼容性表ES2024作为依据module: NodeNextmoduleResolution: NodeNext按 Node.js 原生 ESM 规则解析模块与决定输出格式这是 Egg 从 CommonJS 全面转向 ESM 的技术基础esModuleInterop: true源码注释明确说明其目的——为运行时兼容 Babel 生态输出__importStar/__importHelper并在类型系统层面启用--allowSyntheticDefaultImports例如可以放心import assert from assertallowImportingTsExtensionsrewriteRelativeImportExtensions允许源码中直接写import Foo from ./Foo.ts见测试夹具 Foo.ts并由rewriteRelativeImportExtensions在构建时把.ts扩展名重写为.js兼顾源码可执行性与产物正确性erasableSyntaxOnly: true只允许可擦除的 TypeScript 语法即编译后不产生运行时代码的类型语法源码注释引用 Node.js 官方 TypeScript 发布指南这对以类型注释为主、无需 enum/namespace 等保留语法的项目是更安全的约束verbatimModuleSyntax: false注释指出该选项只适合库、不适合应用Egg 作为应用框架默认关闭保证应用代码里的导入语法处理更宽容。3.3 装饰器与依赖注入支持Egg/Tegg 的关键依赖experimentalDecorators: true, emitDecoratorMetadata: true, strictPropertyInitialization: falseexperimentalDecoratorsemitDecoratorMetadata启用 ES7 阶段装饰器与类型元数据发射这是 Egg 中Controller、Inject、Provide等 Tegg 装饰器体系能够工作的前提emitDecoratorMetadata自 1.3.0 起默认开启见 CHANGELOG 对应条目此后 Egg 插件开发者无需再手动开启strictPropertyInitialization: false放宽非 undefined 类属性必须在构造函数中初始化的约束源码注释解释得非常清楚——使用 DI 时属性会被隐式初始化即依赖注入场景下属性由容器注入而非构造器赋值因此必须关闭该检查。3.4 输出、源码映射与构建行为compileOnSave: true, noEmitOnError: true, pretty: true, declaration: true, inlineSourceMap: true, incremental: false, allowJs: false, isolatedDeclarations: falsedeclaration: true同时生成.d.ts声明文件是发布 npm 包的必要条件inlineSourceMap: true将 source map 内联进产物便于开发期调试allowJs: false不允许编译 JS 文件注释给出关键原因——Egg 编译是原地in place进行的若允许 JS 会报无法覆盖同名 js 文件的错误这解释了 Egg 项目通常由编译产物目录承载运行文件的约束incremental: false1.2.0 曾默认开启增量编译1.3.2 又改为关闭详见版本演进避免产生.tsbuildinfo缓存文件的副作用noEmitOnError保证有编译错误时不产出文件pretty让终端报错更易读isolatedDeclarations: false关闭 TS 5.5 引入的孤立声明强制检查保留一定的声明生成灵活性。3.5 其他常用项skipLibCheck: true, skipDefaultLibCheck: true, resolveJsonModule: true, useUnknownInCatchVariables: trueskipLibCheck/skipDefaultLibCheck跳过依赖声明文件与默认库的类型检查显著提升大型 monorepo 的编译速度resolveJsonModule允许importJSON 文件如读取package.json版本号useUnknownInCatchVariablescatch (err)的变量类型默认为unknown而非any配合instanceof做类型收窄——这正是测试夹具 Foo.ts 验证的行为该选项自 1.1.0 起启用。四、版本演进主线从 1.0.0 到 3.x 的关键变更packages/tsconfig/CHANGELOG.md 完整记录了该包的发展脉络核心主线是跟随 Node.js 版本升级 target、逐步收紧模块体系、全面拥抱 ESM4.1 3.0.0当前仓库主线对应 3.1.2-beta.25破坏性变更不再支持 Node.js 22.18.0与 packages/tsconfig/package.json 的engines声明一致只支持 egg4是 Egg 4 时代的配套基础配置属于 eggjs/egg 问题 #5434 整体规划的一部分源码层面tsconfig.json已呈现该方向的完整形态target: ES2024、module/moduleResolution: NodeNext、allowImportingTsExtensions、rewriteRelativeImportExtensions、erasableSyntaxOnly等新选项全部到位。4.2 3.0.02025-07-30破坏性变更放弃 Node.js 22.17.1 的支持esm only包本身切换为纯 ESM对应 package.json 的type: module配置中的模块解析全面转向 NodeNextCI 工作流升级支持 Node.js 22 与 24测试框架从 Mocha 迁移到 Node.js 原生 test runnertarget 升级到 ES2024并新增 module 相关编译选项。4.3 2.0.02025-03-11破坏性变更放弃 Node.js 18.19.0 的支持默认target设为 ES2022moduleResolution设为 NodeNext——这是 ESM 化推进的第一步。4.4 1.x 系列2022-2023逐步打磨基础1.3.3移除charset选项1.3.2关闭incrementaltarget回退到 ES20201.3.1target回退到 ES2019短暂上调后的回调1.3.0默认开启emitDecoratorMetadata为装饰器与 DI 生态铺路1.2.0默认开启incrementaltarget设为 es20201.1.0启用useUnknownInCatchVariables1.0.02020-07-30首次实现并发布。纵向对比可见target经历了 ES2019 → ES2020 → ES2022 → ES2024 的逐步上移每次升级都与 Node.js LTS 版本线强绑定incremental经历了开启又关闭的反复最终以关闭收场装饰器、catch 变量类型等 Egg 场景专属配置则持续稳定保留。五、如何验证测试机制与可运行的保证仓库通过 packages/tsconfig/test/index.test.ts 保证配置的真实可编译性测试使用 vitest 启动真实typescript/bin/tsc以-p参数编译fixtures/apps/ts-proj夹具项目断言编译进程退出码为 0且产出dist目录存在夹具中故意混用了装饰器、.ts扩展名导入、unknown捕获变量等特性Foo.ts、FooDecorator.ts确保这些默认选项不是纸面配置而是能实际通过类型检查与转译的。这意味着任何extends: eggjs/tsconfig的项目只要 Node.js 版本满足要求理论上都能通过同样的编译链路值得作为自检的参考基准。六、升级与迁移建议基于 CHANGELOG 的破坏性变更综合 CHANGELOG 中三次破坏性变更升级时需重点核对Node.js 版本3.x 要求 22.18.02.x 要求 18.19.0低于要求的运行环境必须先升级运行时Egg 大版本3.x 仅支持 egg4若仍停留在 egg3 需先完成框架升级模块体系3.x 全面 ESM 化module/moduleResolution: NodeNextCommonJS 风格项目需评估导入导出写法、__dirname替代方案import.meta.dirname等的改造成本target 上移ES2024 意味着编译器会按新语法基线输出需确认目标部署环境Node 22与之匹配。七、小结eggjs/tsconfig 用一份tsconfig.json把 Egg 4 Node.js 22 时代的最佳 TypeScript 实践固化下来严格类型检查、NodeNext ESM 解析、装饰器与 DI 支持、可擦除语法约束以及经过真实tsc编译测试验证的可靠性。无论是开发 Egg 应用还是发布 Egg 插件extends: eggjs/tsconfig都是当前仓库推荐的基础配置起点阅读其 tsconfig.json 源码注释与 CHANGELOG.md 演进历史也能帮助开发者理解每个编译选项在 Egg 生态中的真实用途与取舍。【免费下载链接】egg Born to build better enterprise frameworks and apps with Node.js Koa. https://307.run/eggcode项目地址: https://gitcode.com/gh_mirrors/eg/egg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考