一、前言

想用 TypeScript 寫(xiě)代碼，但卡在了“怎么跑起來(lái)”？
你是否遇到過(guò)這些問(wèn)題：

• 安裝了 TypeScript，卻不知道如何編譯 .ts 文件？
• 每次改代碼都要手動(dòng)執(zhí)行 tsc，效率低下？
• 斷點(diǎn)調(diào)試時(shí)無(wú)法命中斷點(diǎn)？
• 項(xiàng)目結(jié)構(gòu)混亂，不知道該把文件放哪？

別擔(dān)心！本文將帶你從零開(kāi)始，一步步搭建一個(gè)：

• ? 支持自動(dòng)編譯
• ? 支持?jǐn)帱c(diǎn)調(diào)試
• ? 結(jié)構(gòu)清晰
• ? 工具鏈完整

的 TypeScript 開(kāi)發(fā)環(huán)境。

無(wú)論你是寫(xiě) Node.js 后端、前端工具庫(kù)，還是學(xué)習(xí) TS 基礎(chǔ)，這套配置都適用！

二、準(zhǔn)備工作：安裝必要工具

1. 安裝 Node.js（推薦 LTS 版）

TypeScript 依賴(lài) Node.js 運(yùn)行。

前往 https://nodejs.org 下載并安裝。

驗(yàn)證安裝：

node -v  # 如 v20.15.0
npm -v   # 如 10.7.0

2. 安裝 TypeScript（全局 or 本地？）

? 推薦：本地安裝（項(xiàng)目級(jí)）

npm init -y
npm install --save-dev typescript

為什么不用全局安裝？

• 避免不同項(xiàng)目 TS 版本沖突
• 團(tuán)隊(duì)協(xié)作時(shí)版本一致
• 可通過(guò) npx tsc 調(diào)用本地版本

全局安裝（僅用于快速測(cè)試）：

npm install -g typescript

驗(yàn)證安裝：

npx tsc --version  # 顯示版本號(hào)，如 Version 5.6.2

三、初始化項(xiàng)目結(jié)構(gòu)

創(chuàng)建一個(gè)清晰的目錄結(jié)構(gòu)是專(zhuān)業(yè)開(kāi)發(fā)的第一步：

my-ts-project/
├── src/              # 源代碼目錄
│   └── index.ts
├── dist/             # 編譯輸出目錄（自動(dòng)生成）
├── tsconfig.json     # TS 配置文件
└── package.json

創(chuàng)建文件：

mkdir my-ts-project && cd my-ts-project
mkdir src dist
echo 'console.log("Hello, TypeScript!");' > src/index.ts

四、生成并配置tsconfig.json

這是 TypeScript 項(xiàng)目的“心臟”。

1. 自動(dòng)生成配置

npx tsc --init

這會(huì)生成一個(gè)帶大量注釋的 tsconfig.json，包含所有選項(xiàng)說(shuō)明。

2. 精簡(jiǎn)核心配置（推薦初學(xué)者使用）

編輯 tsconfig.json，保留關(guān)鍵字段：

{
  "compilerOptions": {
    "target": "ES2020",          // 編譯目標(biāo) JS 版本
    "module": "commonjs",        // 模塊系統(tǒng)（Node.js 用 commonjs，瀏覽器用 ESNext）
    "outDir": "./dist",          // 輸出目錄
    "rootDir": "./src",          // 源碼目錄
    "strict": true,              // 啟用所有嚴(yán)格類(lèi)型檢查
    "esModuleInterop": true,     // 兼容 CommonJS 和 ES Module
    "skipLibCheck": true,        // 跳過(guò) .d.ts 類(lèi)型檢查（加快編譯）
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],       // 包含哪些文件
  "exclude": ["node_modules"]    // 排除哪些文件
}

關(guān)鍵解釋：

• "strict": true → 強(qiáng)烈建議開(kāi)啟，避免隱式 any
• "outDir" / "rootDir" → 明確輸入輸出路徑
• "include" → 只編譯 src 下的 .ts 文件

五、配置自動(dòng)編譯（告別手動(dòng)tsc）

每次改代碼都手動(dòng)編譯？太低效！

方法 1：使用--watch模式（最簡(jiǎn)單）

在 package.json 中添加腳本：

{
  "scripts": {
    "build": "tsc",
    "dev": "t tsc --watch"
  }
}

運(yùn)行開(kāi)發(fā)模式：

npm run dev

效果：

? 監(jiān)聽(tīng) src 目錄變化

? 自動(dòng)重新編譯到 dist

? 終端實(shí)時(shí)顯示錯(cuò)誤

方法 2：結(jié)合nodemon（適用于 Node.js 項(xiàng)目）

如果你寫(xiě)的是后端服務(wù)，希望自動(dòng)重啟 Node 進(jìn)程：

npm install --save-dev nodemon

修改 package.json：

{
  "scripts": {
    "build": "tsc",
    "dev": "concurrently \"tsc --watch\" \"nodemon dist/index.js\""
  }
}

需要先安裝 concurrently：

npm install --save-dev concurrently

這樣就能實(shí)現(xiàn)：

TS 修改 → 自動(dòng)編譯 → Node 自動(dòng)重啟 → 立即看到效果！

六、配置 VS Code：獲得最佳開(kāi)發(fā)體驗(yàn)

VS Code 是 TypeScript 的“親兒子”，原生深度集成。

1. 安裝推薦插件（可選但強(qiáng)烈建議）

• ESLint（配合 TS 做代碼規(guī)范）
• Prettier（代碼格式化）
• Auto Rename Tag（HTML 標(biāo)簽重命名）

TypeScript 本身無(wú)需插件，VS Code 內(nèi)置支持！

2. 啟用 TS 語(yǔ)言服務(wù)

打開(kāi) .ts 文件，右下角應(yīng)顯示 TS 版本（如 TS 5.6.2）。

點(diǎn)擊可切換使用本地或全局版本 → 選擇本地（Workspace）版本。

3. 配置自動(dòng)保存 & 格式化（可選）

在 VS Code 設(shè)置中 (Ctrl+,) 搜索：

• ? Files: Auto Save → onFocusChange 或 afterDelay
• ? Editor: Format On Save → 勾選

七、配置調(diào)試（Debug）：直接在 VS Code 中打斷點(diǎn)

無(wú)需 console.log，直接調(diào)試 TS 源碼！

步驟 1：生成.vscode/launch.json

在 VS Code 中：

1. 打開(kāi)左側(cè)“運(yùn)行和調(diào)試”面板
2. 點(diǎn)擊“創(chuàng)建 launch.json 文件”
3. 選擇 Node.js

步驟 2：配置launch.json

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug TS",
      "program": "${workspaceFolder}/src/index.ts",
      "preLaunchTask": "tsc: build - tsconfig.json",
      "outFiles": ["${workspaceFolder}/dist/**/*.js"],
      "sourceMaps": true
    }
  ]
}

步驟 3：在tsconfig.json中啟用 sourceMap

確保 compilerOptions 包含：

"sourceMap": true

效果：

• 在 src/index.ts 中打上斷點(diǎn)
• 按 F5 啟動(dòng)調(diào)試
• 程序停在 TS 源碼斷點(diǎn)處（而非編譯后的 JS）

? 實(shí)現(xiàn) “寫(xiě) TS，調(diào) TS” 的無(wú)縫體驗(yàn)！

八、驗(yàn)證環(huán)境是否成功

在 src/index.ts 中寫(xiě)一段帶類(lèi)型的代碼：

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

console.log(greet("TypeScript"));

運(yùn)行開(kāi)發(fā)模式：

npm run dev

• 查看 dist/index.js 是否生成
• （可選）按 F5 調(diào)試，看是否能命中斷點(diǎn)

? 如果一切正常，恭喜你！開(kāi)發(fā)環(huán)境已就緒！

九、常見(jiàn)問(wèn)題與解決方案

? 問(wèn)題 1：tsc : 無(wú)法加載文件... 因?yàn)樵诖讼到y(tǒng)上禁止運(yùn)行腳本

原因：Windows PowerShell 執(zhí)行策略限制

解決（以管理員身份運(yùn)行 PowerShell）：

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

? 問(wèn)題 2：修改 TS 文件后，dist 沒(méi)更新

檢查：

• 是否運(yùn)行了 npm run dev（--watch 模式）？
• tsconfig.json 的 include 是否包含該文件？
• 文件擴(kuò)展名是否為 .ts（不是 .js）？

? 問(wèn)題 3：調(diào)試時(shí)斷點(diǎn)變成空心（未綁定）

原因：sourceMap 未生效

解決：

• 確保 tsconfig.json 有 "sourceMap": true
• 確保 launch.json 的 outFiles 路徑正確
• 重新編譯一次再調(diào)試

十、總結(jié)

以上為個(gè)人經(jīng)驗(yàn)，希望能給大家一個(gè)參考，也希望大家多多支持腳本之家。

最新評(píng)論