👁 114 次阅读

问题来源：https://github.com/vitejs/vite/issues/5370

pnpm monorepo 中 vite.config.ts 通过 symlink 导入 TS 文件报错 “defaultLoader is not a function” 的根因与可行解决方案？

现象与背景

在 pnpm workspace 管理的 monorepo 项目中，vite.config.ts 位于某个子包内，而该配置需要引用另一个 workspace 包中的 TypeScript 文件。这类共享文件可能是公共配置片段、构建辅助函数或类型常量。开发者通常在 vite.config.ts 中直接写出类似 import sharedConfig from '@my-monorepo/shared' 的语句。由于 pnpm 的 node_modules 目录会为 workspace 内部包创建 symlink（软链接），该导入最终落到真实目录中另一个包内的 .ts 源文件上。

执行 vite dev 或 vite build 时，Vite 需要先加载并执行 vite.config.ts，此时会报出两类关键信息：

failed to load config from .../vite.config.ts
error when starting dev server: TypeError: defaultLoader is not a function

该报错发生在 Vite 2.x 时代，典型环境为 Node 14.17.0、pnpm 包管理器，时间上对应 2021 年 10 月。报错虽然指向 defaultLoader 不是函数，但问题并不在 Vite 的配置文件本身，而在于 Vite 加载配置文件的底层机制与 pnpm symlink 结构之间的相互作用。

核心原因分析

Vite 加载 vite.config.ts 时，并不直接交给 Node.js 执行，而是先调用 esbuild 对配置文件进行打包和转译。esbuild 是一款基于 Go 编写的高速打包工具，它能将 TypeScript 编译成 JavaScript，并处理模块间的导入关系。Vite 在 config 加载阶段使用 esbuild 生成一个临时的 bundle，然后让 Node.js 去加载这个 bundle。

问题出在外部依赖（external）的处理上。当 esbuild 打包 vite.config.ts 时，它会将来自 node_modules 或识别为外部依赖的导入标记为“external”，意思是这些模块不需要被打入 bundle，留给运行时由 Node.js 直接加载。Vite 官方维护者 haoqunjiang（GitHub 用户名 sodatea）在 Issue #5370 中确认了根因：来自外部包的导入被 esbuild 排除后，不会经过任何转译。于是 Node.js 在运行时直接加载了外部包内的原始 .ts 文件。Node.js 本身无法直接解析 TypeScript 语法，加载过程随即失败，最终在配置加载环节抛出 TypeError: defaultLoader is not a function 这类异常。

需要说明的是，defaultLoader 这个错误名称本身是 Vite 内部加载流程中暴露出的一个 TypeError，它并非 Node.js 对 TypeScript 的语法错误提示，而是配置加载流程被打断后出现的连锁反应。真正的原因始终是：外部 TS 文件被 Node.js 原生加载，但没有经过任何转译步骤。

monorepo 与 pnpm 在这里扮演了关键角色。monorepo 将多个子包放在同一个仓库中，pnpm 则通过 hard link 加 symlink 的方式管理依赖。一个 workspace 包被另一个 workspace 包导入时，pnpm 会在 node_modules 中创建一个指向真实目录的软链接。这个软链接指向的往往是一个包含 src/index.ts 的源文件目录。普通项目中的第三方依赖通常已经提供编译后的 .js 文件，而 monorepo 内部包常常直接暴露源码，于是问题被触发。

Vite 维护者评估后认为，该场景比较罕见，配置逻辑通常不比业务代码复杂，因此不准备将其作为内置功能支持，避免为此引入额外的配置项。Issue 中的讨论因此主要落在社区方案上。

详细机制与影响面

下表概括了问题链条中每个环节的作用与后果。

环节	机制	后果
vite.config.ts	使用 TypeScript 编写	需要转译后才能被 Node.js 加载
esbuild 打包配置	Vite 用 esbuild 将配置文件打包为临时 JS	内联配置文件的源码，完成 TS 语法转译
外部依赖标记	esbuild 将来自外部的导入视为 external	不打包、不转译，保留原始导入语句
pnpm symlink	workspace 包之间通过软链接互连	让 Node.js 运行时解析到源码目录
Node.js 加载 TS	Node 原生不支持 TS 语法	加载失败，抛出 TypeError
Vite 启动流程	配置加载失败后无法继续	报出 failed to load config 与 defaultLoader 错误

该问题影响范围集中在小范围场景：只有 vite.config.ts 的依赖项中包含未被编译的 TS 文件，同时这些依赖通过 pnpm symlink 暴露时才必然触发。Vite 2.x 中该问题较为稳定地复现，Vite 4 及之后版本对配置文件加载流程做了更多健壮性改进，直接加载配置时路径解析错误已大幅减少，但外部包内 TS 文件的转译问题并未被官方纳入支持轨道。

解决方案与操作步骤

Issue #5370 的讨论中出现了多种行之有效的解法，分别适用于不同的工程约束。下面逐一拆解。

方案一：将共享 TS 配置包预编译为 JS

zheeeng 在 Issue 中采用的思路是先用 tsc 将共享 TS 配置编译成 JS，再让 vite.config.ts 导入编译产物。该方法把转译步骤提前到 Vite 启动之前，规避了运行时加载 TS 的问题。

假设 monorepo 中存在一个名为 @repo/config 的包，其入口为 src/index.ts。在 @repo/config/package.json 中设置构建命令：

{
  "name": "@repo/config",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "scripts": {
    "build": "tsc -p tsconfig.json"
  }
}

开发流程调整为：

pnpm --filter @repo/config build

然后 vite.config.ts 按照常规方式导入：

import { defineConfig } from "vite";
import { sharedServerConfig } from "@repo/config";

export default defineConfig(sharedServerConfig);

该方案的优点是侵入性最小，不改变 Vite 的加载机制，也不要求 Vite 识别 symlink。代价是配置文件变更后需要重新运行 tsc。在 monorepo 根目录使用 pnpm -r build 可一次构建全部子包。

方案二：使用真实文件路径导入，绕过 symlink

Issue 正文中提到的 workspace 方案是：将导入目标的路径从包名改为其在仓库中的真实文件路径，避开 pnpm 生成的 symlink。例如原本通过包名导入：

import { baseConfig } from "@my-repo/shared";

改为直接指向真实文件目录：

import { baseConfig } from "../../packages/shared/src/index";

这里使用的是相对路径，完全绕过了 node_modules 与软链接机制。esbuild 在打包 vite.config.ts 时，该相对导入会被视为普通源码模块并纳入打包范围，因此其中的 TypeScript 语法会被正常转译。

该方案适合共享配置只在少量配置文件中使用、且仓库结构相对稳定的场景。缺点是路径依赖仓库目录布局，一旦移动包位置，需要同步修改导入路径。

方案三：公共配置写成纯 JS，TS 侧用 mergeConfig 合并

julianklumpers 在 5 个微前端组成的 monorepo 实践中使用了该方案。其核心思路是：公共配置完全用 JavaScript 编写，以 module.exports 导出一个工厂函数，而每个子应用的 vite.config.ts 通过 mergeConfig 与这份 JS 配置合并。

公共配置文件命名为 vite.apps.base.js，内容示例如下：

module.exports = function createBaseConfig(options) {
  return {
    root: options.root,
    server: {
      host: "0.0.0.0",
      port: options.port,
    },
    resolve: {
      alias: {
        "@": options.root + "/src",
      },
    },
  };
};

子应用中的 vite.config.ts 导入该 JS 文件，并与自身配置合并：

import { defineConfig, mergeConfig } from "vite";
import createBaseConfig from "./vite.apps.base.js";
import createAppConfig from "./vite.app.config";

export default defineConfig(
  mergeConfig(createBaseConfig({ root: __dirname, port: 3000 }), createAppConfig)
);

纯 JS 文件始终可以被 Node.js 原生加载，因此该方案完全不依赖 esbuild 的外部依赖处理行为。TS 侧只负责编写当前应用的个性化配置，并通过 mergeConfig 与 JS 基础配置合并。对于配置项数量较多、需要函数式生成的场景，这种工厂函数模式比静态对象更灵活。

方案四：使用 esbuild-register 加载器或 preconstruct 生成入口桩

维护者在 2021 年 11 月的评论中提出一个未来方向：在 config 加载阶段注册 TypeScript 转译器，例如通过 esbuild-register 让 Node.js 具备运行时加载 TS 文件的能力。esbuild-register 利用 esbuild 对 Node.js 的 require.extensions 进行扩展，使 require 加载 .ts 文件时自动转译。操作方式是在 Vite 配置加载前先注册转译器。

一种实现思路是在使用 Vite 命令前通过 Node 预加载模块注册，例如：

node -r esbuild-register node_modules/vite/bin/vite.js

也可以将注册逻辑放到单独的入口文件中，再执行 Vite 的 CLI。需要注意，这种方法要求 esbuild-register 能匹配到目标 TS 文件的扩展名，并且 Vite 的加载流程在 require 该文件时经过 Node 的模块解析。由于 Vite 2.x 对配置文件使用 esbuild bundle 后可能直接加载生成结果，注册加载器的方式并非在所有版本中都百分之百生效，但它是社区中可行且经过验证的方向。

airtonix 则提出了另一种思路：使用 preconstruct 为 workspace 包生成 .mjs 和 .cjs 入口桩（stub）。preconstruct 是面向 JavaScript 库和 monorepo 的构建工具，它可以生成一个小的入口文件，在开发模式下将导入重定向到包的源码入口，在构建模式下重定向到产物入口。这个入口桩本身是合法的 JavaScript，因此 Vite 加载配置文件时不会遇到未编译的 TS 源码。该方案适合已经接入 preconstruct 的 monorepo 项目，能够统一处理所有子包的入口暴露方式，而不是单独为 Vite 编写加载逻辑。

方案五：使用社区配置构建器或 tsconfig extends

black7375 在 Issue 中分享了自己的 vite-config-builder 与 ts-monorepo 方案。这类方案的核心思想是，不直接让 Vite 动态加载外部 TS 文件，而是通过一个独立的构建步骤，将 Vite 配置本身打包成可执行的 JS 文件，再交给 Vite 使用。这种模式实际上是把“配置文件”当作“应用程序”来构建，彻底避开 Node.js 直接加载 TS 的问题。

另一种轻量做法是利用 TypeScript 自身的 tsconfig 继承机制。配置共享的内容如果主要是编译选项、路径别名、include/exclude 之类的 TypeScript 配置，可以直接通过 extends 复用，而不是在 vite.config.ts 中导入外部 TS 文件：

{
  "extends": "@repo/config/tsconfig.base.json",
  "compilerOptions": {
    "baseUrl": "."
  }
}

这种方案不涉及运行时模块加载，因此不会触发 defaultLoader 错误，但它只适用于配置类型的共享，无法共享 Vite 的 plugin 实例或完整配置对象。对于大量插件配置的共享，仍需要回到上述其他方案。

注意事项与常见误区

第一，不要在 vite.config.ts 中尝试通过 Vite 插件或 resolve.alias 强行将外部 TS 导入指向编译产物。Vite 的 resolve.alias 服务于应用代码的模块解析，而配置文件加载发生在 Vite 应用配置生效之前，此时别名机制尚未初始化。

第二，不要认为给 vite.config.ts 加上 // @ts-ignore 或修改 TypeScript 类型声明能绕过该问题。错误发生在转译与加载阶段，与类型检查无关。

第三，pnpm 的 node-linker 设置会影响问题是否出现。如果项目改用传统的 hoisted 布局，依赖会被扁平化，外部包路径不再通过 symlink 暴露，该问题可能不再触发。但修改 linker 会影响整个 monorepo 的依赖管理行为，不应仅仅为了修复配置文件加载而调整。

第四，Vite 4 及以上版本对配置文件加载的健壮性有所提升，部分路径解析问题会以错误的形式更早暴露，但官方仍然没有为“外部包中的 TS 文件被 vite.config 导入并转译”这一能力提供内建支持。升级 Vite 不等于该场景自动修复。

第五，如果共享 TS 文件中只有类型定义，而没有实际运行逻辑，应使用 import type 或 tsconfig 的类型引用。类型会在编译期被擦除，不会出现在运行时加载的 JavaScript 中，因此可以从根源上避免 Node.js 加载 TS 的问题。

总结

pnpm monorepo 中 vite.config.ts 通过 symlink 导入外部 TS 文件导致的 TypeError: defaultLoader is not a function，其本质是 Vite 的配置加载机制、pnpm 的软链接结构以及 Node.js 对 TypeScript 的原生不兼容三者叠加的结果。Vite 依赖 esbuild 转译配置文件，但将外部依赖排除在转译范围之外；pnpm 又将 workspace 包暴露为源码目录；Node.js 加载该目录下的 .ts 文件时便发生崩溃。

解决该问题的有效路径只有两条：要么让 Node.js 最终加载的文件是合法 JavaScript，要么让外部 TS 文件被纳入 esbuild 的打包范围。方案一通过 tsc 预编译做到前者，方案二通过真实路径导入做到后者，方案三把公共配置整体下沉到 JS 层，方案四则借助加载器或预生成入口桩实现等价效果。选择哪一种，取决于 monorepo 的构建设施、子包数量以及团队对构建时机的容忍度。对于配置逻辑复杂的项目，方案三的工厂函数模式最为稳妥；对于已有构建体系的项目，方案一更贴合现有习惯；对于希望完全消除 symlink 影响的项目，方案二的路径改写最为直接。

常见问题 FAQ

问题	答案
为什么这个报错只在 pnpm monorepo 中出现？	pnpm 使用 symlink 链接 workspace 包，`vite.config.ts` 导入的包名会解析到源码目录中的 `.ts` 文件。使用 npm 的扁平化 `node_modules` 时，workspace 包往往直接暴露文件路径或已编译产物，触发的概率较低。
esbuild 为什么没有转译外部 TS 文件？	Vite 加载配置文件时，esbuild 只负责打包 `vite.config.ts` 自身的源码，外部导入会被标记为 external，不进入打包与转译流程。
升级 Vite 到 4 或 5 能彻底解决吗？	不能彻底解决。Vite 4 之后对配置加载的健壮性有所提升，解析与报错更为明确，但外部包内 TS 文件的运行时转译依然不是受官方支持的能力。
官方是否计划添加专门的配置项？	截至 Issue #5370 的讨论，维护者认为该场景罕见，不打算内置支持，也未提供额外配置项。社区方案是唯一可行的路径。
最有普适性的方案是哪一个？	对于大多数项目，将共享配置写成纯 JS 文件并通过 `mergeConfig` 合并，是最简单且不依赖额外构建步骤的方案；已经具备编译流程的项目可优先考虑用 `tsc` 预编译共享 TS 包。