Vite识别tsconfig.json的机制及自定义配置路径方法

问题背景 #

我有一个基于 Vite 的自定义构建器项目，结构如下：

builder
  index.ts
  tsconfig.json
application
  src
    server.ts
    ...
  index.html
  tsconfig.json
  ...

builder/index.ts 核心配置代码：

const root = '../application';
const viteConfig: InlineConfig[] = [
  // 编译SPA获取资源
  {
    root,
    build: {
      outDir: `${root}/dist`,
      ssrManifest: true,
      emptyOutDir: true,
      rollupOptions: {
        input: `${root}/index.html`,
      },
    },
  },
  // 编译SSR转换为SSG
  {
    root,
    build: {
      outDir: `${root}/dist/server`,
      ssr: true,
      rollupOptions: {
        input: `${root}/src/entryServer.ts`,
      },
    },
  },
];

项目运行正常，但直接在 CLI 执行 node index.ts 时未配置 tsconfig.json 路径，想搞清楚几个问题：

1. Vite 是如何识别 tsconfig.json 的？是否通过 root 字段？
2. 移除 application/tsconfig.json 后项目仍能运行（仅 IDE 报错），想理解 Vite 与 TypeScript 的工作机制。
3. 如何手动指定 tsconfig 的直接路径？

解答 #

1. Vite 识别 tsconfig.json 的逻辑 #

没错，Vite 确实是通过你配置的 root 字段来定位 tsconfig.json 的。
当你在 Vite 配置中指定了 root，Vite 会自动从这个根目录开始，依次查找 tsconfig.json、jsconfig.json 文件。如果没找到，就会向上级目录继续查找，直到找到或者到达文件系统根目录。
你这里的 root 指向 ../application，所以 Vite 会优先读取 application/tsconfig.json，这也是为什么移除它之后项目还能跑——因为 Vite 在找不到的时候会使用默认的 TypeScript 编译配置，不会强制要求必须存在 tsconfig 文件。

2. Vite 与 TypeScript 的工作机制 #

Vite 对 TypeScript 的处理分为编译阶段和类型检查阶段，两者是完全分离的：

• 编译阶段：Vite 不会直接调用 tsc 编译，而是用 esbuild 快速转译 TypeScript 代码到 JavaScript（只做语法转换，不做类型检查）。这个过程不需要 tsconfig，esbuild 有默认的语法转换规则，所以哪怕没有 tsconfig，代码也能正常编译运行。
• 类型检查阶段：这一步是可选的，Vite 默认不会在构建过程中做类型检查（会拖慢构建速度）。通常是 IDE（比如 VS Code）会读取 tsconfig 来做实时类型提示和检查，所以移除 tsconfig 后只有 IDE 报错，不影响项目运行。如果需要在构建时做类型检查，可以手动添加 vite-plugin-checker 这类插件，它会调用 tsc 完成类型校验，这时候才会依赖 tsconfig。

3. 手动指定 tsconfig 的直接路径 #

如果不想让 Vite 自动查找，而是直接指定 tsconfig 文件路径，可以在 Vite 配置中添加 resolve.typescript.tsconfigPath 字段：

const viteConfig: InlineConfig[] = [
  {
    root,
    resolve: {
      typescript: {
        tsconfigPath: '../application/tsconfig.custom.json' // 替换为你的目标 tsconfig 路径
      }
    },
    build: {
      // ... 原有配置
    },
  },
  // SSR 配置同理
  {
    root,
    resolve: {
      typescript: {
        tsconfigPath: '../application/tsconfig.custom.json'
      }
    },
    build: {
      // ... 原有配置
    },
  },
];

注意路径是相对于当前执行脚本（builder/index.ts）的位置，也可以使用绝对路径来避免歧义。

内容的提问来源于stack exchange，提问作者FLighter