Vite + TypeScript：快速開發現代前端應用的最佳組合

簡介

在前端開發的生態系統中，Vite 以其極速的開發伺服器與零配置的建構體驗，已成為許多專案的首選。而 TypeScript 則提供靜態類型檢查、智慧型補完與更好的程式碼可維護性，讓大型專案的開發品質大幅提升。把兩者結合起來，就能同時享有 開發即時回饋 與 型別安全，大幅縮短開發迭代時間。

本篇文章將從環境安裝、專案初始化、常見設定到實務範例，完整說明如何在 Vite 中整合 TypeScript，並提供 最佳實踐 與 常見陷阱，讓你可以快速上手、建立可擴充的前端程式碼基礎。

---

核心概念

1. 為什麼選擇 Vite？

• 即時模組熱更新（HMR）：Vite 透過原生 ES 模組在瀏覽器中直接載入，修改檔案後只重新載入變更的模組，回饋時間通常在 毫秒等級。
• 快速建構：使用 Rollup 作為生產環境的打包工具，結合 Tree‑shaking、代碼分割等最佳化手段，建構速度遠快於傳統的 Webpack。
• 零配置：只要有 index.html 與 src/main.ts，Vite 就能自動偵測並啟動開發伺服器，省去繁雜的設定檔。

2. TypeScript 與 Vite 的結合點

Vite 內建支援 .ts、.tsx 檔案，會自動使用 esbuild 進行 TypeScript 轉譯（只做語法轉換，不進行型別檢查），因此開發階段的速度非常快。
型別檢查則交給 tsc 或 vite-plugin-checker 這類插件完成，兩者可以同時運行，互不衝突。

3. 初始化 Vite + TypeScript 專案

# 1. 使用官方模板建立專案
npm create vite@latest my-vite-ts-app -- --template vue-ts   # Vue 3 + TS
# 或
npm create vite@latest my-vite-ts-app -- --template react-ts # React + TS

# 2. 進入目錄並安裝相依套件
cd my-vite-ts-app
npm install

# 3. 啟動開發伺服器
npm run dev

若只想要純粹的 Vite + TS（不綁定框架），可以使用 vanilla-ts 模板：
npm create vite@latest my-vite-ts-app -- --template vanilla-ts

4. tsconfig.json 的關鍵設定

設定項目	說明	推薦值
target	編譯後的 JavaScript 目標版本	"esnext"（讓瀏覽器直接執行原生 ES 模組）
module	模組系統	"esnext"（配合 Vite 的 ES 模組）
strict	啟用所有嚴格類型檢查	true
esModuleInterop	允許 import 兼容 CommonJS	true
skipLibCheck	跳過庫檔案的型別檢查，提高編譯速度	true
sourceMap	產生對應的 source map，方便除錯	true

{
  "compilerOptions": {
    "target": "esnext",
    "module": "esnext",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "sourceMap": true,
    "jsx": "preserve",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true   // 交給 Vite 處理，避免重複輸出
  },
  "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.vue"]
}

noEmit: true 告訴 tsc 只做型別檢查，實際的編譯交給 Vite（esbuild）完成，這樣可以避免兩次編譯造成的效能浪費。

5. 常用 Vite 插件

插件	功能	安裝指令
@vitejs/plugin-vue / @vitejs/plugin-react	框架特定支援（Vue、React）	npm i -D @vitejs/plugin-vue
vite-plugin-checker	同時執行 tsc、eslint、vue-tsc 等檢查，顯示在瀏覽器 console	npm i -D vite-plugin-checker
vite-plugin-env-compatible	讓 Vite 支援傳統的 .env 變數寫法	npm i -D vite-plugin-env-compatible

範例：在 vite.config.ts 中加入型別檢查插件

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import checker from 'vite-plugin-checker'

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    vue(),
    // 同步跑 tsc，錯誤會顯示在瀏覽器的 console
    checker({ typescript: true })
  ],
  // 若需要自訂別名，可在此設定
  resolve: {
    alias: {
      '@': '/src'
    }
  }
})

6. 程式碼範例

以下提供 5 個常見且實用的範例，展示在 Vite + TypeScript 環境中如何撰寫、使用以及最佳化程式碼。

6.1. 基本的型別宣告與函式

// src/utils/math.ts
/** 計算兩個數字的和 */
export function add(a: number, b: number): number {
  return a + b
}

/** 透過泛型實作陣列的第一項回傳 */
export function first<T>(arr: T[]): T | undefined {
  return arr[0]
}

使用方式：

import { add, first } from '@/utils/math'

const sum = add(3, 7)           // sum: number = 10
const firstName = first(['Tom', 'Jane']) // firstName: string | undefined

6.2. Vue 3 + TypeScript 單檔元件（SFC）

<!-- src/components/Counter.vue -->
<template>
  <button @click="count++">Clicked {{ count }} 次</button>
</template>

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

/** 計數器的狀態 */
const count = ref<number>(0)
</script>

<style scoped>
button {
  padding: 0.5rem 1rem;
  font-size: 1rem;
}
</style>

使用 lang="ts" 後，Vite 會自動透過 vue-tsc 進行型別檢查，確保 ref<number> 的型別正確。

6.3. React + TypeScript 的函式型元件

// src/components/Hello.tsx
import React from 'react'

interface HelloProps {
  /** 使用者名稱 */
  name: string
}

/** 透過泛型取得子元素的型別 */
export const Hello: React.FC<HelloProps> = ({ name, children }) => {
  return (
    <div>
      <h1>Hello, {name}!</h1>
      {children}
    </div>
  )
}

使用方式：

import { Hello } from '@/components/Hello'

function App() {
  return (
    <Hello name="Alice">
      <p>歡迎使用 Vite + TypeScript！</p>
    </Hello>
  )
}

6.4. 使用環境變數（.env）並在 TypeScript 中取得類型

# .env
VITE_API_URL=https://api.example.com
VITE_FEATURE_FLAG=true

// src/config.ts
/** 取得 Vite 注入的環境變數 */
export const API_URL = import.meta.env.VITE_API_URL as string
export const FEATURE_FLAG = import.meta.env.VITE_FEATURE_FLAG === 'true'

注意：Vite 只會把以 VITE_ 為前綴的變數注入前端程式碼，確保不會意外洩漏機密資訊。

6.5. 建構自訂的 Vite 插件（簡易範例）

// vite-plugin-log.ts
import { Plugin } from 'vite'

export default function logPlugin(): Plugin {
  return {
    name: 'vite-plugin-log',
    // 伺服器啟動時顯示訊息
    configureServer(server) {
      console.log('🚀 Vite dev server 已啟動')
    },
    // 每次重新整理頁面時印出檔案名稱
    transformIndexHtml(html) {
      console.log('🔄 正在重新載入 index.html')
      return html
    }
  }
}

在 vite.config.ts 中加入：

import logPlugin from './vite-plugin-log'

export default defineConfig({
  plugins: [vue(), checker({ typescript: true }), logPlugin()]
})

這個範例說明 自訂插件 的基本結構，讓你在專案需要時可以快速加入自動化流程（如代碼統計、日誌等）。

---

常見陷阱與最佳實踐

陷阱	可能的結果	解決方案或最佳實踐
忘記在 tsconfig.json 加入 include	tsc 無法正確檢查 src 目錄下的檔案	把 src/**/*.ts*、src/**/*.vue 加入 include
在 vite.config.ts 中使用 import 而非 require（Node <14）	會拋出語法錯誤	確保 Node 版本 ≥14，或在 package.json 加入 "type": "module"
將 noEmit 設為 false	Vite 與 tsc 會同時產生 dist，導致檔案衝突	設為 true，交由 Vite 完成編譯與打包
在程式碼中直接使用 process.env	Vite 不會將其注入，導致 undefined	改用 import.meta.env，且變數名稱必須以 VITE_ 開頭
使用 any 過度	失去 TypeScript 帶來的型別安全	盡量使用 泛型、映射型別 或 unknown，必要時才轉 any 並加上註解說明原因

進階最佳實踐

1. 開啟型別檢查插件：在開發期間同時跑 vite-plugin-checker，即時看到型別錯誤，避免在 build 時才發現問題。
2. 使用 path 別名：在 vite.config.ts 中設定 @ 為 /src，配合 tsconfig.json 的 paths，讓 import 更簡潔。
3. 分層建構：將 類型定義、業務邏輯、UI 元件 分別放在 types/、services/、components/，保持目錄結構清晰。
4. 自動化測試：結合 vitest（Vite 官方測試框架）與 TypeScript，確保型別與行為一致。
5. CI/CD 整合：在 GitHub Actions 或 GitLab CI 中加入 npm run lint && tsc --noEmit && npm run build，保證每次提交都通過型別檢查與建構。

---

實際應用場景

場景	為什麼選擇 Vite + TypeScript	實作要點
單頁應用（SPA）	快速的 HMR 與 TypeScript 提供的型別安全，使開發者能即時看到 UI 變化且不易產生 runtime 錯誤。	使用 react-ts 或 vue-ts 模板，結合 react-router / vue-router，在 vite.config.ts 加入路由懶載入設定。
微前端子應用	Vite 支援 Multiple Entry，可為每個子應用產生獨立的入口檔，且 TypeScript 能確保跨子應用的公用介面一致。	在 vite.config.ts 使用 build.rollupOptions.input 設定多入口，並在 types/ 中定義共享介面。
靜態網站生成（SSG）	Vite + Vue/React 可搭配 vite-plugin-ssg 或 vite-ssr，在編譯階段產生靜態 HTML，配合 TypeScript 確保資料模型正確。	使用 vite-plugin-ssg，在 src/pages 中撰寫頁面組件，並在 src/types 定義 API 回傳型別。
開發工具或 UI Library	Vite 的 esbuild 轉譯速度非常快，適合頻繁編譯的 library 專案；TypeScript 能輸出 .d.ts 宣告檔，方便使用者引用。	在 package.json 中設定 build 為 vite build && tsc --emitDeclarationOnly，產出 dist 與 types。
Electron 前端	Vite 可作為 Electron 的渲染程序（renderer）開發伺服器，提供即時重載；TypeScript 讓主/渲染進程的 IPC 型別安全。	在 vite.config.ts 設定 base: './'，並在 electron/main.ts 中使用 ipcRenderer.invoke 時搭配介面定義。

---

總結

• Vite 為開發者提供 即時回饋、零配置與高速建構 的體驗，是現代前端開發的首選工具。
• TypeScript 為程式碼加入 靜態型別、IDE 智慧補完與可維護性，在大型專案中尤為重要。
• 兩者的結合只需要 簡單的初始化指令、 少量的 tsconfig 設定，即可在 毫秒級的 HMR 與 嚴謹的型別檢查 之間取得平衡。
• 透過 vite-plugin-checker、別名設定、自訂插件 等技巧，能進一步提升開發效率與程式碼品質。
• 在實務上，從 SPA、微前端、SSG 到 Electron，Vite + TypeScript 都能提供穩定、可擴充的解決方案。

掌握上述概念與最佳實踐後，你就能在 開發速度 與 程式安全性 之間取得最佳平衡，讓前端專案更快上線、更易維護。祝你玩得開心，寫出乾淨、可讀、且具備型別保護的程理碼！ 🚀