企业官网建设流程全解析

• 后端

MikroORM 的 CLI（如schema:update、migration:create、entity-generator等命令）在启动时需要import()你的 TypeScript 文件——既包括 ORM 配置文件，也包括从配置中发现并加载的实体。Node.js 原生虽然已能运行 TypeScript，但只做「剥离类型」处理，遇到 enum、装饰器这类需要语义信息的语法仍会解析失败。而装饰器定义实体恰恰是 MikroORM 最常见的用法，因此 CLI 在加载配置前会先注册一个受支持的 TypeScript loader。本篇指南以 v7.2 版本文档（docs/versioned_docs/version-7.2/typescript-loaders.md）为主线，结合 packages/cli 的源码实现，完整讲解 loader 的检测逻辑、支持的 loader 清单、选型与配置方式，以及 Nub 等特殊 loader 的约束，帮助你排查「CLI 读不到 TS 配置 / 装饰器实体解析失败」一类问题。

为什么 CLI 需要 TypeScript Loader

MikroORM CLI 的工作流大致是：读取配置 → 发现实体 → 基于元数据执行命令。整个过程发生在 Node 进程内，因此 CLI 必须先能把.ts文件真正「跑起来」。

Node.js 22.6+ 及后续版本内置了对 TypeScript 的实验性支持，但它只负责剥离类型注解（type stripping），不会做完整的类型检查与转换。对于普通接口、类型别名等纯类型语法没问题，可一旦文件中出现：

• enum 声明：Node 原生剥离无法将enum转换为其运行时可用的对象形态；
• 装饰器：@Entity()、@Property()这类 MikroORM 核心语法依赖experimentalDecorators编译产物，剥离型执行直接失败。

装饰器定义实体是 MikroORM 的主流用法，所以 CLI 必须借助第三方 loader。若任何 loader 都不可用，CLI 只能回退到编译后的 JavaScript 配置（如dist/mikro-orm.config.js），并忽略 TypeScript 配置。

从源码看，这一注册动作发生在 CLI 解析命令之前：CLIConfigurator.ts 中，只要settings.preferTs !== false，就会调用CLIHelper.registerTypeScriptSupport()注册 loader；注册失败时会把MIKRO_ORM_CLI_PREFER_TS置为'0'，从而在后续配置路径搜索中跳过 TS 文件。

自动检测：TypeScript 支持是如何被发现的

preferTs未显式配置时，CLI 通过Utils.detectTypeScriptSupport()自动判断当前环境是否「在跑 TypeScript」。其实现位于 packages/core/src/utils/Utils.ts，检测条件包括：

也就是说，测试框架、运行器、已注册的 loader、入口文件扩展名都会影响检测结果，这也是文档所说的「基于配置文件扩展名、process.execArgv中的 TS loader、或所用测试运行器」的完整来源。

检测结果直接影响配置搜索路径：CLIHelper.getConfigPaths()（CLIHelper.ts）在检测到 TS 支持时，会额外把./src/mikro-orm.config.ts与./mikro-orm.config.ts加入候选；同时根据dist/build/src目录的存在情况，依次尝试./dist|build|src/mikro-orm.config.js与./mikro-orm.config.js。非 TS 后缀的.ts配置路径会被过滤掉，这正是「找不到 loader 就回退到编译后 JS 配置」的实现细节。

手动强制：preferTs

检测是启发式的，偶尔需要强制干预。在package.json中声明mikro-orm配置块：

"mikro-orm": { "preferTs": true }

等价的环境变量写法：

export MIKRO_ORM_CLI_PREFER_TS=true

从CLIHelper.getSettings()（CLIHelper.ts）可以看出环境变量的优先级高于package.json设置；另外，当MIKRO_ORM_CLI_CONFIG指向的配置文件以.ts结尾时，preferTs会被隐式置为 true。mikro-orm debug命令会如实输出该标志的实际取值（见 DebugCommand.ts），当它被显式设置为true时还会提示「在运行编译后代码时应将其设为false」。

支持的 Loader 清单

v7.2 文档列出的 loader 按自动尝试顺序如下：

这里的「元数据反射」指 loader 是否尊重emitDecoratorMetadata编译选项——该选项是ReflectMetadataProvider与 legacy 装饰器配合工作的前提。其他元数据提供者（如TsMorphMetadataProvider、ReflectionMetadataProvider等）不依赖反射元数据，因此对 loader 没有此要求。这也是oxc、swc、nub三个 loader 在文档中被单独标注「supports metadata reflection」的原因。

对应源码映射位于registerTypeScriptSupport的loaders表（CLIHelper.ts），每种 loader 都区分了 ESM 与 CJS 两个注册入口，例如 swc 在 ESM 下用@swc-node/register/esm-register、CJS 下用@swc-node/register；tsx 则通过tsx.register({ tsconfig: configPath })回调注入。jiti与tsimp还会设置dynamicImportProvider，以兼容 CJS 项目中的动态导入。

选型：auto 与显式指定

默认值为auto：CLI 按照上表顺序依次尝试Utils.tryImport()，取第一个在当前项目依赖中存在的 loader。若某 loader 已安装但加载抛错，auto 模式不会立刻失败，而是把错误记录下来继续尝试下一个；如果最终一个都没装上，会输出一条警告并返回false（此时 CLI 回退到 JS 配置）。警告文本还附带了安装提示：用oxc需安装@oxc-node/core，用swc需同时安装@swc-node/register与@swc/core（CLIHelper.ts）。

显式指定 loader 用package.json的tsLoader设置：

"mikro-orm": { "tsLoader": "jiti" }

或环境变量：

export MIKRO_ORM_CLI_TS_LOADER=jiti

关键差异：显式指定时没有任何回退机制。若指定 loader 未安装或加载失败，CLI 会直接抛出Failed to load TypeScript loader ...错误，而不是尝试下一个（CLIHelper.ts）。因此请确保所选 loader 已加入项目devDependencies。

验证当前生效的 loader 有两种方式：运行npx mikro-orm debug，输出中的TypeScript support enabled (<loader>)即注册成功的 loader（DebugCommand.ts）；在auto模式下，registerTypeScriptSupport成功后还会把选中的 loader 名写回MIKRO_ORM_CLI_TS_LOADER环境变量，供后续逻辑查询。

tsconfig.json 的指向

oxc、swc、tsx、jiti、tsimp这些 loader 都依赖你的tsconfig.json来决定编译选项（装饰器开关、emitDecoratorMetadata等），默认指向当前工作目录下的tsconfig.json。如需指向其他文件，用tsConfigPath设置：

"mikro-orm": { "tsConfigPath": "./tsconfig.cli.json" }

或环境变量：

export MIKRO_ORM_CLI_TS_CONFIG_PATH=./tsconfig.cli.json

注意：cli 的tsConfigPath是 CLI 层概念，与discovery.tsConfigPath（已废弃，见 upgrading-v3-to-v4.md 中的说明）不是一回事。源码中该路径还会通过SWC_NODE_PROJECT、TSIMP_PROJECT环境变量传递给对应 loader（CLIHelper.ts）。

Nub：特殊约束需注意

nub（@nubjs/loader）在 v7.2 加入，行为与其余 loader 有显著差异：

1. tsconfig 自主解析：它总是自行查找「每个被导入文件最近的tsconfig.json」，无法被指向自定义路径。因此：
   • 显式选择tsLoader: "nub"且同时配置了tsConfigPath时，CLI 直接抛错；
   • auto模式下，只要配置了自定义 tsconfig 路径，自动选型会跳过 nub（源码见 CLIHelper.ts 与 L380-L382 的continue逻辑）。
2. 仅支持 legacy 装饰器：需要tsconfig.json中开启"experimentalDecorators": true；使用 ES 装饰器（标准装饰器语法）的文件会被 nub 拒绝。若你的实体使用 ES 装饰器，请换用其他 loader。

显式使用 nub 的配置：

"mikro-orm": { "tsLoader": "nub" }

提前编译：另一种路径

以上 loader 全部面向「直接运行 TypeScript」的场景。如果你的项目是用tsc、Babel 或 SWC预先编译成 JS 后再交给 CLI，那么不需要（也不建议）在 CLI 中启用这些 loader，而是要为编译流程配置正确的装饰器选项——详见 usage-with-transpilers.md（其中涵盖experimentalDecorators、emitDecoratorMetadata、useDefineForClassFields等与 MikroORM 强相关的编译选项）。此时应把preferTs设为false，让 CLI 直接使用entities数组与编译产物。

配置优先级速查

综合文档与 CLIHelper.ts 的getSettings()实现，三个 CLI 专属设置的优先级从高到低均为：环境变量 > package.json 的mikro-orm配置块 > 默认值：

其中preferTs与tsLoader为布尔/枚举值（'true'/'t'/'1'视为真），环境变量值会直接覆盖配置文件中的值。

故障排查建议

遇到「CLI 找不到 TS 配置」或「装饰器实体加载报错」时，按此顺序排查：

1. 运行npx mikro-orm debug，确认TypeScript support enabled (<loader>)一行是否存在、用的是哪个 loader；
2. 确认项目依赖中确实安装了对应 loader（auto模式下缺装只会降级到 JS 配置并打警告，容易误判）；
3. 若使用ReflectMetadataProvider+ legacy 装饰器，确认所选 loader 支持元数据反射（oxc/swc/nub），且tsconfig.json开启了experimentalDecorators与emitDecoratorMetadata；
4. 检查是否误配了tsLoader与tsConfigPath的组合（nub 与自定义 tsconfig 互斥）；
5. 确认package.json中mikro-orm配置块与相关环境变量没有互相冲突（环境变量优先）。

相关源码与文档可继续深入：CLIHelper.ts（loader 注册与设置读取）、Utils.ts（TS 支持检测）、DebugCommand.ts（debug 输出）、configuration.md（CLI 环境变量总表）。

• 后端