配置智能提示与类型支持

配置智能提示与类型支持

Vite.js 项目中的智能提示与类型支持能极大提升开发效率。通过合理配置，可以让编辑器在编写代码时提供准确的类型推断、自动补全和错误检查。这主要依赖于 TypeScript 或 JSDoc 的类型系统，结合 Vite 的特定配置实现。

npm install -D typescript @types/node

安装 TypeScript 和 Node 类型定义后，在项目根目录创建 tsconfig.json 文件。这个文件控制 TypeScript 编译器的行为，也影响编辑器的智能提示。

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "node",
    "strict": true,
    "jsx": "preserve",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  },
  "include": ["src/**/*.ts", "src/**/*.d.ts", "src/**/*.tsx", "src/**/*.vue"],
  "exclude": ["node_modules"]
}

配置路径别名

路径别名能简化模块导入，同时让智能提示正常工作。在 Vite 中需要同时在 tsconfig.json 和 vite.config.ts 中配置：

// vite.config.ts
import { defineConfig } from 'vite'
import path from 'path'

export default defineConfig({
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src')
    }
  }
})

配置后，编辑器能正确解析类似 @/components/Button 的导入路径，并提供组件属性的智能提示。

类型定义文件

对于非 TypeScript 编写的库或自定义类型，需要创建 .d.ts 声明文件。例如为环境变量添加类型：

// src/env.d.ts
interface ImportMetaEnv {
  readonly VITE_API_BASE_URL: string
  readonly VITE_APP_TITLE: string
}

interface ImportMeta {
  readonly env: ImportMetaEnv
}

这样在使用 import.meta.env 时就能获得智能提示，避免拼写错误。

配置 Vue 项目的智能提示

在 Vue 项目中，需要额外配置以获得模板内的智能提示：

// vite.config.ts
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          // 配置模板编译器选项
        }
      }
    })
  ]
})

同时创建 src/shims-vue.d.ts 文件：

declare module '*.vue' {
  import { DefineComponent } from 'vue'
  const component: DefineComponent<{}, {}, any>
  export default component
}

配置 JSX/TSX 支持

要在 Vite 中使用 JSX/TSX，需要安装相应插件并配置：

npm install @vitejs/plugin-vue-jsx -D

然后在配置中启用：

import vueJsx from '@vitejs/plugin-vue-jsx'

export default defineConfig({
  plugins: [
    vueJsx({
      // 配置选项
    })
  ]
})

自定义类型扩展

可以扩展全局类型定义来增强智能提示。例如为 window 对象添加自定义属性：

// src/types/global.d.ts
export {}

declare global {
  interface Window {
    __APP_VERSION__: string
    __DEV__: boolean
  }
}

配置 CSS 模块类型

对于 CSS Modules，可以添加类型支持以获得类名的智能提示：

// src/styles.d.ts
declare module '*.module.css' {
  const classes: { readonly [key: string]: string }
  export default classes
}

declare module '*.module.scss' {
  const classes: { readonly [key: string]: string }
  export default classes
}

配置 JSON 导入类型

默认情况下，JSON 导入会被视为 any 类型。可以创建类型声明来改善：

// src/json.d.ts
declare module '*.json' {
  const value: {
    [key: string]: any
  }
  export default value
}

配置 SVG 组件导入

处理 SVG 作为组件导入时，需要添加类型支持：

// src/svg.d.ts
declare module '*.svg' {
  import { FunctionalComponent, SVGAttributes } from 'vue'
  const src: FunctionalComponent<SVGAttributes>
  export default src
}

配置环境变量类型

在 .env 文件中定义的环境变量默认都是字符串类型。可以通过类型声明增强：

// src/env.d.ts
interface ImportMetaEnv {
  readonly VITE_API_TIMEOUT: number
  readonly VITE_ENABLE_ANALYTICS: boolean
  readonly VITE_DEFAULT_LOCALE: 'en' | 'zh' | 'ja'
}

配置第三方库类型

对于没有类型定义的第三方库，可以创建声明文件：

// src/modules/legacy-lib.d.ts
declare module 'legacy-lib' {
  export function deprecatedMethod(): void
  export const legacyConstant: number
}

配置 Vite 插件类型

开发 Vite 插件时，可以定义插件选项的类型：

// plugins/my-plugin/types.d.ts
interface MyPluginOptions {
  /**
   * 是否启用调试模式
   * @default false
   */
  debug?: boolean
  /**
   * 要排除的文件模式
   */
  exclude?: RegExp | RegExp[]
}

配置多项目类型共享

在 monorepo 项目中，可以共享类型定义：

// packages/shared/tsconfig.json
{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "declarationMap": true,
    "rootDir": "src",
    "outDir": "dist/types"
  },
  "include": ["src"]
}

然后在其他项目中引用：

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

配置测试类型

为测试文件配置专门的类型规则：

// tsconfig.test.json
{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "types": ["jest", "node"]
  },
  "include": ["**/*.test.ts", "**/*.spec.ts", "tests/**/*.ts"]
}

配置 Worker 类型

在使用 Web Worker 时，需要添加类型支持：

// src/worker.d.ts
declare module '*?worker' {
  const workerConstructor: new () => Worker
  export default workerConstructor
}

这样在导入 Worker 时能获得类型安全：

import Worker from './worker?worker'

const worker = new Worker()

配置全局组件类型

在 Vue 项目中注册全局组件时，可以添加类型支持：

// src/components.d.ts
import { App } from 'vue'

declare module 'vue' {
  interface GlobalComponents {
    BaseButton: typeof import('./components/BaseButton.vue')['default']
    BaseIcon: typeof import('./components/BaseIcon.vue')['default']
  }
}

export const install: (app: App) => void

配置自定义指令类型

为 Vue 自定义指令添加类型支持：

// src/directives.d.ts
import { App } from 'vue'

declare module 'vue' {
  interface ComponentCustomProperties {
    vFocus: typeof import('./directives/focus')['default']
    vTooltip: typeof import('./directives/tooltip')['default']
  }
}

export const install: (app: App) => void

配置 Composition API 类型

在使用 Composition API 时，可以定义响应式数据的类型：

import { ref } from 'vue'

interface User {
  id: number
  name: string
  email: string
}

const user = ref<User>({
  id: 1,
  name: '',
  email: ''
})

配置 Pinia 存储类型

在使用 Pinia 状态管理时，可以定义存储的类型：

// stores/user.ts
import { defineStore } from 'pinia'

interface UserState {
  id: number | null
  token: string | null
  preferences: {
    theme: 'light' | 'dark'
    locale: string
  }
}

export const useUserStore = defineStore('user', {
  state: (): UserState => ({
    id: null,
    token: null,
    preferences: {
      theme: 'light',
      locale: 'en'
    }
  })
})

配置路由元字段类型

在使用 Vue Router 时，可以定义路由元字段的类型：

// src/router/types.d.ts
import 'vue-router'

declare module 'vue-router' {
  interface RouteMeta {
    requiresAuth?: boolean
    roles?: string[]
    title?: string
    transition?: string
  }
}

配置国际化类型

在使用国际化库时，可以定义消息类型：

// src/i18n/types.d.ts
declare module 'vue-i18n' {
  interface DefineLocaleMessage {
    welcome: string
    buttons: {
      submit: string
      cancel: string
    }
    validation: {
      email: string
      required: string
    }
  }
}

配置 API 响应类型

定义 API 响应数据的类型：

// src/api/types.d.ts
interface ApiResponse<T = any> {
  code: number
  data: T
  message: string
  timestamp: number
}

interface PaginatedData<T> {
  items: T[]
  total: number
  page: number
  pageSize: number
}

配置工具函数类型

为工具函数添加详细的类型定义：

// src/utils/types.d.ts
type Nullable<T> = T | null
type Maybe<T> = T | undefined

interface DebounceOptions {
  leading?: boolean
  trailing?: boolean
  maxWait?: number
}

declare function debounce<T extends (...args: any[]) => any>(
  func: T,
  wait?: number,
  options?: DebounceOptions
): (...args: Parameters<T>) => ReturnType<T>

配置主题类型

定义主题相关的类型：

// src/styles/theme.d.ts
interface ThemeColors {
  primary: string
  secondary: string
  success: string
  warning: string
  error: string
  background: string
  text: string
}

interface Theme {
  colors: ThemeColors
  spacing: {
    small: string
    medium: string
    large: string
  }
  borderRadius: string
}

declare module '@emotion/react' {
  export interface Theme extends Theme {}
}

配置表单验证类型

定义表单验证规则的类型：

// src/utils/validation.d.ts
type ValidationRule =
  | { required: true; message: string }
  | { min: number; message: string }
  | { max: number; message: string }
  | { pattern: RegExp; message: string }
  | { validator: (value: any) => boolean; message: string }

interface ValidationSchema {
  [field: string]: ValidationRule[]
}

配置图表数据类型

定义图表数据结构的类型：

// src/components/charts/types.d.ts
interface ChartDataPoint {
  x: number | string | Date
  y: number
  meta?: any
}

interface ChartSeries {
  name: string
  data: ChartDataPoint[]
  color?: string
  type?: 'line' | 'bar' | 'area'
}

配置表格列类型

定义表格列配置的类型：

// src/components/table/types.d.ts
interface TableColumn<T = any> {
  key: string
  title: string
  width?: number | string
  align?: 'left' | 'center' | 'right'
  render?: (value: any, row: T, index: number) => VNode
  sortable?: boolean
  filterable?: boolean
}