[TypeScript] 環境建置

寫過 JS 才有意義學 TS——它不是新語言，是給 JS 加了一層編譯期檢查。這篇把 Windows 上跑 TS 的最短路徑、tsconfig.json 的關鍵旋鈕、第一支程式怎麼跑一次串完，後面所有 TS 篇都假設這份 tsconfig 已經就位。

TypeScript 是什麼

TypeScript 是 JavaScript 的超集，在 JS 之上多一層靜態型別系統。寫好的 TS 要先用 tsc 編譯成純 JS——瀏覽器和 Node 不會直接執行 .ts 檔（除非搭配 runtime loader）。

不過實務上幾乎不會手動跑 tsc，多半交給這些工具：

安裝

全域 / 專案內

# 專案內（推薦，避免版本衝突）
npm install -D typescript @types/node
npx tsc --version

# 全域
npm install -g typescript
tsc --version

搭配 tsx（Node 環境直接跑 .ts）

npm install -D tsx
npx tsx src/index.ts

用 Bun

Bun 本身就是 JS / TS runtime，不需要額外裝 TS：

bun init                 # 互動式建立專案
bun run src/index.ts     # 直接執行

初始化 tsconfig.json

npx tsc --init

會產生一份預設 tsconfig.json，裡面註解很多。常用設定整理：

{
  "compilerOptions": {
    // 輸出
    "target": "ES2022",            // 編譯目標 JS 版本
    "module": "ESNext",            // 模組系統
    "moduleResolution": "bundler", // 解析方式（bundler / node / nodenext）
    "outDir": "./dist",
    "rootDir": "./src",

    // 嚴格性（強烈建議全開）
    "strict": true,                // 等於下列全部開啟
    // "noImplicitAny": true,
    // "strictNullChecks": true,
    // "strictFunctionTypes": true,
    // "strictBindCallApply": true,
    // "strictPropertyInitialization": true,
    // "noImplicitThis": true,
    // "alwaysStrict": true,

    // 額外建議開啟
    "noUncheckedIndexedAccess": true,  // arr[i] 結果一律帶 undefined
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,

    // 互通性
    "esModuleInterop": true,           // 允許 import x from 'cjs-module'
    "allowSyntheticDefaultImports": true,
    "forceConsistentCasingInFileNames": true,

    // 開發體驗
    "skipLibCheck": true,              // 跳過 node_modules 內 .d.ts 的檢查
    "resolveJsonModule": true,         // 允許 import xxx from './data.json'

    // 路徑別名
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

第一支程式

src/hello.ts：

function greet(name: string): string {
  return `Hello, ${name}`
}

console.log(greet('Jeremy'))

跑法（任一）：

# 1. tsc 編譯後執行
npx tsc && node dist/hello.js

# 2. tsx 直接跑
npx tsx src/hello.ts

# 3. Bun
bun run src/hello.ts

只做型別檢查不輸出

npx tsc --noEmit          # 只檢查不產生檔

CI 與 lint-staged 通常用這條，因為 build 是打包工具負責的，TS 只負責驗型別。

VS Code 設定

VS Code 內建 TS 支援。常用調整：

.vscode/settings.json：

{
  // 用專案的 TS 版本，避免和 VS Code 內建版本不一致
  "typescript.tsdk": "node_modules/typescript/lib",

  // 自動 import 用相對路徑或 alias
  "typescript.preferences.importModuleSpecifier": "non-relative",

  // 存檔時整理 import
  "editor.codeActionsOnSave": {
    "source.organizeImports": "explicit"
  }
}

兩種主流的專案類型範本

直接拷別人的 tsconfig 很常踩雷，先想清楚這份 TS 是要被誰執行的。

環境就緒、tsx/Bun 跑得起 .ts、tsconfig 開了 strict，下一篇進基本型別，把 TS 型別系統的入口磚塊鋪好。