Node.js 和 TypeScript 编译器必须本地安装，VSCode 不自带；需通过 node -v 和 tsc -v 验证是否成功加入 PATH，Windows 安装时须勾选“Add to PATH”，macOS/Linux 使用 nvm 时需确保 shell 已加载并激活对应版本。
Node.js 和 TypeScript 编译器必须本地安装
VSCode 本身不自带 Node.js 或 tsc，所有运行和编译依赖你本地环境。如果终端里输 node -v 或 tsc -v 报“命令未找到”，说明没装或没进 PATH。
常见错误现象：tsc: command not found、node is not recognized（Windows）、终端里能运行但 VSCode 内置终端不行。
- Windows 安装 Node.js 时务必勾选「Add to PATH」，否则需手动把
C:\Program Files\nodejs\加到系统环境变量 - 全局安装 TypeScript：
npm install -g typescript；验证用tsc -v，不是npm tsc -v - macOS/Linux 用户若用
brew install node，通常自动配置 PATH；但用 nvm 管理版本时，需确保当前 shell 已加载 nvm，且执行过nvm use --delete-prefix v18类似命令
tsconfig.json 是编译行为的唯一控制开关
没有 tsconfig.json，tsc 只能单文件编译（tsc index.ts），无法识别项目结构、路径别名、输出目录等。它不是可选项，是项目级编译的前提。
生成方式很简单：tsc --init，但默认配置不适合直接开发——比如 "outDir": "./dist" 和 "rootDir": "./src" 必须成对设置，否则报错 error TS6059: File 'src/index.ts' is not under 'rootDir' '。
- 推荐最小可用配置：启用
"outDir"、"rootDir"、"module"（设为"commonjs"）、"target"（设为"ES2020"） -
"include"建议写成["src/**/*"]，避免"exclude"写错导致 .d.ts 或测试文件被误编译 - 不要在
tsconfig.json里写"files"数组——它会完全忽略include/exclude，极易漏文件
用 ts-node 直接运行 .ts 文件，绕过手动编译
每次改完代码都要 tsc → node dist/index.js 太繁琐。ts-node 提供即时解释执行能力，适合开发调试，但仅限 Node.js 环境（不能跑浏览器）。
关键点：它不替代 tsc，而是读取同一份 tsconfig.json，并按其中规则解析类型和路径。如果你的 tsconfig.json 里 "module" 设为 "ESNext"，而 Node.js 版本低于 14，则 ts-node 会报错 Cannot use import statement outside a module。
- 项目级安装（推荐）：
npm install --save-dev ts-node @types/node - 运行命令：
npx ts-node src/index.ts（无需先编译） - 配合
package.json脚本更省事："scripts": {"dev": "ts-node --esm src/index.ts"}，注意--esm仅当tsconfig.json中"module"为"ESNext"且 Node 支持时才加
VSCode 调试配置要匹配 ts-node 或 tsc 输出
直接按 F5 启动调试失败，90% 是因为 launch.json 的 runtimeExecutable 或 args 没对齐实际执行链。VSCode 不懂 TypeScript，它只调用 Node.js 或 ts-node 进程。
典型错误：Cannot find module './dist/index.js' —— 实际你用的是 ts-node，却在 launch.json 里配了 "program": "${workspaceFolder}/dist/index.js"。
- 用
tsc编译后运行：设"program": "${workspaceFolder}/dist/index.js"，并确保已执行过tsc - 用
ts-node调试：设"runtimeExecutable": "npx"，"args": ["ts-node", "${file}"]，且"skipFiles": ["<node_internals>/**"]</node_internals>避免跳进源码 - 无论哪种方式，都建议开启
"sourceMap": true并在tsconfig.json中保持一致，否则断点打在 .ts 上会失效
最易被忽略的是：VSCode 内置终端的 shell 类型（PowerShell / CMD / Git Bash）会影响 npx 解析路径，尤其 Windows 下 PowerShell 默认策略禁止脚本执行，得先运行 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser —— 这个权限设置不作用于 VSCode GUI 启动的进程，只对终端生效。
