vue-tsc：把类型检查跑起来

学习目标

类型写在编辑器里不等于项目是类型安全的——构建工具不做类型检查。这一节掌握 vue-tsc 的配置、把类型检查接进 npm scripts 与 CI、以及处理第三方库缺类型和 .vue 文件的类型声明。

问题场景

项目全是 .vue + TS，编辑器里偶尔飘红但能跑。某天改了一个 props 的类型，忘了改父组件的用法，构建照样成功，上线后运行时才炸。原因：Vite 的 esbuild 只做「类型擦除」，不做类型检查；tsc 默认也不认识 .vue 文件。

核心解释

vue-tsc 是 Vue 官方的类型检查器：包装 tsc，先让 TypeScript 理解 .vue 文件（通过 Volar 的语言服务），再执行标准类型检查。

安装与脚本：

先安装：npm install -D vue-tsc typescript。

{
  "scripts": {
    "dev": "vite",
    "build": "vue-tsc -b && vite build",
    "typecheck": "vue-tsc --noEmit"
  }
}

vue-tsc -b 使用项目引用（tsconfig.json + tsconfig.app.json + tsconfig.node.json），create-vue 生成的模板就是这个结构。单独跑 --noEmit 适合 CI 里快速检查。

tsconfig 的关键项：

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "strict": true,
    "jsx": "preserve",
    "types": ["vite/client"]
  },
  "include": ["src/**/*.ts", "src/**/*.vue"]
}

strict: true 是底线；moduleResolution: "Bundler" 匹配 Vite 的解析规则；types: ["vite/client"] 提供 import.meta.env 的类型。

环境变量的类型：vite/client 只给内置变量类型，自定义变量要扩声明：

// src/env.d.ts
/// <reference types="vite/client" />

interface ImportMetaEnv {
  readonly VITE_API_BASE: string;
  readonly VITE_APP_TITLE?: string;
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

这样 import.meta.env.VITE_API_BASE 有类型，拼错变量名会报错——这是最常见的生产事故来源之一（本地有、线上没配）。

第三方库缺类型：先找 @types/xxx；没有就自己写声明文件，例如 declare module "untyped-lib" { export function parse(input: string): { ok: boolean; value: unknown } }，放在 src/types/ 下由 tsconfig 的 include 覆盖。

.vue 文件的类型声明：vue-tsc 不需要 shims-vue.d.ts（Volar 已处理），但如果你用普通 tsc + 其他工具，可能需要 declare module "*.vue" 的兜底声明。统一用 vue-tsc 可以省掉。

示例拆解

把类型检查接进 CI，并处理一个真实的「构建通过但类型错误」案例：

# .github/workflows/ci.yml（片段）
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm run typecheck
      - run: npm run build

制造一个错误验证检查有效：把 Props 里的 title: string 改成 title: number，父组件仍传字符串。npm run dev 照常运行（esbuild 擦除类型），npm run typecheck 立即报错。这个实验说明为什么 CI 里必须有独立的一步。

修第三方库缺类型的实战顺序：npm i -D @types/xxx → 检查 tsconfig 的 types 是否包含 → 仍报错就写 .d.ts → 最后才考虑 // @ts-expect-error（并且要写原因注释，方便以后删）。

动手任务

1. 给一个 Vue + TS 项目加上 typecheck 脚本，制造并修复一个 props 类型错误。
2. 写 env.d.ts 声明自定义环境变量，验证 import.meta.env.VITE_XXX 拼错时报错。
3. 给一个没有类型的库写最小 .d.ts，并用 // @ts-expect-error 临时绕过一处无法修复的第三方类型问题（带注释说明）。

常见错误

• 以为 vite build 会做类型检查：它只打包。必须有独立的 vue-tsc 步骤。
• include 漏掉 .vue：src/**/*.vue 没写进 include，组件里的错误全被跳过。
• skipLibCheck 当万能药：它只跳过 .d.ts 的检查，不会救你自己的代码错误。
• 自定义环境变量不声明类型：拼错变量名静默变成 undefined，线上才暴露。

检查与复盘

• 能解释为什么 Vite 构建通过不代表类型正确
• 能配置 vue-tsc 并接入 npm scripts 与 CI
• 能写出环境变量与第三方库的类型声明

参考资料

• Vue 官方文档「TypeScript 总览」：vue-tsc 与项目配置
• Vite 官方文档：环境变量与类型声明