TypeScript 开发环境搭建

一、前言

想用 TypeScript 写代码，但卡在了"怎么跑起来"？

你是否遇到过这些问题：

• 安装了 TypeScript，却不知道如何编译 .ts 文件？
• 每次改代码都要手动执行 tsc，效率低下？
• 断点调试时无法命中断点？
• 项目结构混乱，不知道该把文件放哪？

别担心！本文将带你从零开始 ，一步步搭建一个： ✅ 支持自动编译

✅ 支持断点调试

✅ 结构清晰

✅ 工具链完整

的 TypeScript 开发环境。

无论你是写 Node.js 后端、前端工具库，还是学习 TS 基础，这套配置都适用！

---

二、准备工作：安装必要工具

1. 安装 Node.js（推荐 LTS 版）

TypeScript 依赖 Node.js 运行。

前往 https://nodejs.org 下载并安装。

验证安装：

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

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

✅ 推荐：本地安装（项目级）

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

为什么不用全局安装？

• 避免不同项目 TS 版本冲突
• 团队协作时版本一致
• 可通过 npx tsc 调用本地版本

💡 全局安装（仅用于快速测试）：

npm install -g typescript

验证安装：

npx tsc --version  # 显示版本号，如 Version 5.6.2

---

三、初始化项目结构

创建一个清晰的目录结构是专业开发的第一步：

my-ts-project/
├── src/              # 源代码目录
│   └── index.ts
├── dist/             # 编译输出目录（自动生成）
├── tsconfig.json     # TS 配置文件
└── package.json

创建文件：

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

---

四、生成并配置 tsconfig.json

这是 TypeScript 项目的"心脏"。

1. 自动生成配置

npx tsc --init

这会生成一个带大量注释的 tsconfig.json，包含所有选项说明。

2. 精简核心配置（推荐初学者使用）

编辑 tsconfig.json，保留关键字段：

{
  "compilerOptions": {
    "target": "ES2020",          // 编译目标 JS 版本
    "module": "commonjs",        // 模块系统（Node.js 用 commonjs，浏览器用 ESNext）
    "outDir": "./dist",          // 输出目录
    "rootDir": "./src",          // 源码目录
    "strict": true,              // 启用所有严格类型检查
    "esModuleInterop": true,     // 兼容 CommonJS 和 ES Module
    "skipLibCheck": true,        // 跳过 .d.ts 类型检查（加快编译）
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],       // 包含哪些文件
  "exclude": ["node_modules"]    // 排除哪些文件
}

📌 关键解释：

• "strict": true → 强烈建议开启，避免隐式 any
• "outDir" / "rootDir" → 明确输入输出路径
• "include" → 只编译 src 下的 .ts 文件

---

五、配置自动编译（告别手动 tsc）

每次改代码都手动编译？太低效！

方法 1：使用 --watch 模式（最简单）

在 package.json 中添加脚本：

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

运行开发模式：

npm run dev

效果：

✅ 监听 src 目录变化

✅ 自动重新编译到 dist

✅ 终端实时显示错误

---

方法 2：结合 nodemon（适用于 Node.js 项目）

如果你写的是后端服务，希望自动重启 Node 进程：

npm install --save-dev nodemon

修改 package.json：

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

⚠️ 需要先安装 concurrently：

npm install --save-dev concurrently

这样就能实现：

TS 修改 → 自动编译 → Node 自动重启 → 立即看到效果！

---

六、配置 VS Code：获得最佳开发体验

VS Code 是 TypeScript 的"亲儿子"，原生深度集成。

1. 安装推荐插件（可选但强烈建议）

• ESLint（配合 TS 做代码规范）
• Prettier（代码格式化）
• Auto Rename Tag（HTML 标签重命名）

💡 TypeScript 本身无需插件，VS Code 内置支持！

2. 启用 TS 语言服务

打开 .ts 文件，右下角应显示 TS 版本（如 TS 5.6.2）。

点击可切换使用本地或全局版本 → 选择本地（Workspace）版本。

3. 配置自动保存 & 格式化（可选）

在 VS Code 设置中 (Ctrl+,) 搜索：

• ✅ Files: Auto Save → onFocusChange 或 afterDelay
• ✅ Editor: Format On Save → 勾选

---

七、配置调试（Debug）：直接在 VS Code 中打断点

无需 console.log，直接调试 TS 源码！

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

在 VS Code 中：

1. 打开左侧"运行和调试"面板
2. 点击"创建 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 中打上断点
• 按 F5 启动调试
• 程序停在 TS 源码断点处（而非编译后的 JS）

✅ 实现 "写 TS，调 TS" 的无缝体验！

---

八、验证环境是否成功

1. 在 src/index.ts 中写一段带类型的代码：

   function greet(name: string): string {
     return `Hello, ${name}!`;
   }
   
   console.log(greet("TypeScript"));

2. 运行开发模式：

   npm run dev

3. 查看 dist/index.js 是否生成

4. （可选）按 F5 调试，看是否能命中断点

✅ 如果一切正常，恭喜你！开发环境已就绪！

---

九、常见问题与解决方案

❌ 问题 1：tsc : 无法加载文件... 因为在此系统上禁止运行脚本

原因 ：Windows PowerShell 执行策略限制
解决（以管理员身份运行 PowerShell）：

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

---

❌ 问题 2：修改 TS 文件后，dist 没更新

检查：

• 是否运行了 npm run dev（--watch 模式）？
• tsconfig.json 的 include 是否包含该文件？
• 文件扩展名是否为 .ts（不是 .js）？

---

❌ 问题 3：调试时断点变成空心（未绑定）

原因 ：sourceMap 未生效
解决：

• 确保 tsconfig.json 有 "sourceMap": true
• 确保 launch.json 的 outFiles 路径正确
• 重新编译一次再调试

---

十、结语

感谢您的阅读！如果你有任何疑问或想要分享的经验，请在评论区留言交流！