Vite 与 TypeScript

TypeScript 能给 JavaScript 加上类型，提前拦住大量低级错误。Vite 对 TS 的支持是开箱即用的，这一篇我们讲怎么在 Vite 项目里高效使用它。

Vite 对 TS 的原生支持

Vite 不需要你装 tsc 来转译代码就能跑 TS。开发时它用 esbuild 把 TS 快速转成 JS（只去类型，不做类型检查），所以启动依然很快。类型检查可以放到编辑器或专门的构建步骤里做，不拖慢开发。

创建项目时直接选带 -ts 的模板最省事：

npm create vite@latest my-app -- --template vue-ts

tsconfig.json 关键配置

TS 项目需要一个 tsconfig.json。Vite 模板给出的配置里，几个字段值得你理解：

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "isolatedModules": true,
    "noEmit": true
  },
  "include": ["src"]
}

• moduleResolution: "bundler" 让 TS 按打包器的方式解析模块，和 Vite 行为一致。
• isolatedModules: true 要求每个文件都能独立编译，符合 esbuild 的处理模型。
• noEmit: true 表示 TS 只做检查、不产出文件，产出交给 Vite。

strict: true 开启严格模式，初期可能报错多，但长期收益很大，建议保持开启。

vite-env.d.ts 的作用

模板里通常有一个 src/vite-env.d.ts，内容很简单：

/// <reference types="vite/client" />

它给 TS 提供了 Vite 特有的类型，比如 import.meta.env、各类静态资源 import 的类型声明。没有它，TS 就不认识 import logo from './logo.png' 这种写法。一般不用改，保留即可。

在组件里使用 TS

以 Vue 为例，单文件组件里用 <script setup lang="ts"> 即可开启类型：

<script setup lang="ts">
import { ref } from 'vue'

const count = ref<number>(0)
</script>

React 项目则用 .tsx 文件，并安装 @vitejs/plugin-react，Vite 会自动处理 JSX 转换。

配置路径别名 @

项目大了之后，深层目录互相引用写 ../../ 很烦。约定用 @ 指向 src 是常见做法。Vite 侧配置 resolve.alias：

// vite.config.ts
import { defineConfig } from 'vite'
import { fileURLToPath, URL } from 'node:url'

export default defineConfig({
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url))
    }
  }
})

但 TS 自己也要知道 @ 代表什么，否则编辑器报错。在 tsconfig.json 里加上 paths：

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

两边都配好，你就能在任意文件写：

import { format } from '@/utils/format'

Vite 负责运行时解析，TS 负责类型检查，二者缺一不可。

本篇小结

• Vite 用 esbuild 转 TS，开发快、类型检查可独立进行。
• vite-env.d.ts 提供 Vite 特有类型，务必保留。
• 路径别名 @ 要同时在 Vite 和 tsconfig 配置。
• moduleResolution: bundler 让 TS 与 Vite 行为对齐。

下一篇我们聊性能优化，让 Vite 项目跑得更快。