Vite 模式下的 TypeScript：从类型校验缺失到零运行时损耗的架构实践

Vite 原生支持 TypeScript，但这往往给开发者带来一种错觉：项目已经具备了完整的类型安全。实际上，Vite 为了追求极致的冷启动速度，在开发阶段并不会对 TS 文件进行原生的类型检查，而是直接利用 esbuild 进行剥离转译。这种机制在提升体验的同时，也埋下了隐患。

一、Vite 的转译陷阱：无类型校验的极速体验

esbuild 只负责移除 TS 类型注解并转换为 JavaScript，不会校验类型逻辑。这意味着明显的类型错误依然能在本地跑通，直到 CI/CD 阶段或线上才暴露。

反例：依赖 Vite 默认行为，开发期无报错

// user.ts
interface User {
  name: string;
  age: number;
}

// 错误：将 string 赋值给 number，Vite dev 下不报错，页面正常渲染
export const admin: User = {
  name: 'System',
  age: 'unknown' as any 
};

正例：引入 vite-plugin-checker 实时校验

在 Vite 配置中叠加类型检查，将语法转译与类型校验并行执行，既不拖慢 HMR，又能及时发现类型错误。

// vite.config.ts
import { defineConfig } from 'vite';
import checker from 'vite-plugin-checker';

export default defineConfig({
  plugins: [
    checker({
      typescript: true, // 开启 TypeScript 类型检查
      overlay: true // 在浏览器端展示类型错误
    })
  ]
});

二、隔离模块与 Tree-shaking：消除 TS 的运行时副作用

Vite 强制开启 isolatedModules，要求每个文件必须是可独立转译的模块。这直接影响了类型导出的方式，错误的写法会阻断 Rollup 的 Tree-shaking，导致产物体积膨胀。

反例：混合导入导致 Tree-shaking 失效

当仅需要类型时，如果使用普通 import，esbuild 无法在运行时判断该导入是类型还是值，只能保留引用，导致相关 JS 代码无法被摇树优化。

// api.ts
export interface UserType { id: number; }
export function fetchUser() { /* ... */ }

// app.ts
// UserType 是类型，但打包器会认为 fetchUser 被使用，从而保留其代码
import { UserType, fetchUser } from './api';
const user: UserType = { id: 1 };

正例：显式标记类型导入

使用 import type 或内联 type 修饰符，明确告知编译器该引用在编译后应被完全擦除。

// app.ts
// 方式 1：显式 type 导入
import type { UserType } from './api';
import { fetchUser } from './api';

// 方式 2：内联 type 修饰符 (TS 4.5+)
import { type UserType, fetchUser } from './api';

const user: UserType = { id: 1 };

三、静态资源与 JS 模块的类型收编

在 Vite 中引入图片、SVG 或纯 JS 模块时，TypeScript 默认无法识别，常常出现满屏红波浪线。滥用 // @ts-ignore 是下下策。

反例：粗暴忽略类型错误

// @ts-ignore
import logo from './logo.svg';

// @ts-ignore
const mod = require('./legacy.js');

正例：精准声明模块类型

利用 Vite 提供的 vite/client 类型定义，并在项目的 env.d.ts 中收编自定义资源。

// tsconfig.json
{
  "compilerOptions": {
    "types": ["vite/client"]
  }
}

// env.d.ts - 扩展静态资源声明
declare module '*.svg' {
  const src: string;
  export default src;
}

declare module './legacy.js' {
  const legacyModule: { init: () => void };
  export default legacyModule;
}

四、职责分离：让 esbuild 接管语法降级

很多项目在 tsconfig.json 中配置了 target: es5，试图让 TSC 处理语法降级。但在 Vite 体系下，这是极其低效的。Vite 的生产构建由 esbuild（开发）和 Rollup + Terser/esbuild（生产）负责语法降级与压缩。

反例：TSC 与 Vite 构建职责重叠

// tsconfig.json
{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs"
  }
}

上述配置会导致 Vite 预构建和产物输出时产生冗余的代码转换，甚至引发 CommonJS 与 ESM 兼容性问题。

正例：TS 专注类型，Vite 专注构建

将 tsconfig.json 的目标设为现代浏览器支持的语法，将降级工作完全交给 Vite 内部处理。

// tsconfig.json
{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "useDefineForClassFields": true
  }
}

结语

在 Vite 项目中写 TypeScript，不能再以 Webpack + TSC 的传统思维来配置。理解 Vite 的极速转译机制，通过 vite-plugin-checker 补齐类型校验，善用 import type 保障 Tree-shaking 效果，并明确构建工具与类型编译器的职责边界，才能真正实现类型安全与极致性能的双赢。