根本原因是tsc仅处理编译期路径解析，Node.js运行时无法识别tsconfig.json中的paths别名；需配合tsconfig-paths/register或正确配置baseUrl与outDir协同，否则生成的JS仍含别名而Node报错。
为什么 tsc 编译后路径不对，import 报错找不到模块？
根本原因不是 TypeScript 写错了，而是 tsconfig.json 中的路径解析配置和实际项目结构不匹配。常见现象是：编译成功、.js 文件生成了，但运行时报 Error: Cannot find module 'xxx'，尤其在使用 import 从 src/utils 或 @/hooks 这类别名路径导入时。
关键点在于：tsc 只负责类型检查和生成 JS，它不处理运行时模块解析；Node.js 运行时按 CommonJS 规则找文件，而 TS 的 paths 和 baseUrl 仅影响编译期类型检查和路径跳转，对 Node 无效。
-
baseUrl必须设为"./"或"src"，且要和outDir配合——如果outDir是./dist，baseUrl设成"./src"，那import '@/api'在编译期能跳转，但生成的dist/index.js里仍是require('@/api')，Node 根本不认识@ -
paths映射只在 TS 编译阶段生效，不会被写入 JS 输出；想让 Node 认得别名，必须靠ts-node或node --loader（ESM）或第三方工具如tsconfig-paths - 若用
ts-node直接运行.ts文件，需额外加-r tsconfig-paths/register，否则paths别名照样失效
tsconfig.json 的 moduleResolution 该选 node 还是 bundler？
选 node。VSCode 调试 TypeScript 项目时，绝大多数场景走的是 Node.js 运行时（哪怕用 ts-node），moduleResolution: "node" 才会启用 Node 的模块查找逻辑（比如按 package.json 的 main/exports 字段、自动补 .js 后缀、识别 node_modules 等）。
bundler 是给 Webpack/Vite/Rollup 这类打包器用的，它忽略 Node 的一些约定（比如不查 package.json 的 exports），且 VSCode 的内置 TS 语言服务默认不支持该模式——开了反而导致跳转失败、类型提示消失。
- 确认项：
"moduleResolution": "node"必须显式写在compilerOptions里，不能依赖默认值（TS 5.0+ 默认已是node，但老项目可能没更新） - 如果用了 ESM（
"module": "ESNext"），还要确保"type": "module"在package.json中，否则 Node 会拒绝加载import语句 -
"allowSyntheticDefaultImports": true和"esModuleInterop": true建议同时开启，避免 CJS/ESM 混用时的import X from 'Y'报错
调试时断点进不去，sourceMap 生效但路径映射错乱
典型表现：断点打在 src/index.ts 第 10 行，调试时却停在 dist/index.js 的第 15 行，或者直接跳到 node_modules 里——这不是代码问题，是 sourceMap 生成路径和 VSCode 查找路径没对齐。
完整的Galileo AI平台 TypeScript/JS SDK 参考，用于评估、观察和保护 GenAI 应用。适用于构建 Node.js 或 TypeScript 项目。
核心原则：outFiles 和 sourceMaps 必须指向编译产物的真实位置，且 sourceRoot 要反映原始源码相对于 outDir 的路径关系。
-
"sourceMap": true和"inlineSources": false（推荐关掉 inline，单独生成.map文件更稳定） -
"outDir": "./dist"时，launch.json中的outFiles必须写成"${workspaceFolder}/dist/**/*.js"，不能漏掉**或写成dist/* - 如果
src下有子目录（如src/lib/foo.ts），编译后变成dist/lib/foo.js，那sourceMap里的sources字段应为["../src/lib/foo.ts"]，此时sourceRoot应设为"../src"（相对dist目录向上一级再进src） - VSCode 不读
tsconfig.json的sourceRoot，它只认launch.json的outFiles和生成的.map文件内容，二者必须一致
ts-node 调试绕过编译，但路径别名仍不生效？
因为 ts-node 默认不读 tsconfig.json 的 paths，它只做语法转换，不模拟模块解析。即使你配了 "paths": { "@/*": ["src/*"] }，ts-node -r tsconfig-paths/register src/index.ts 才真正启用别名。
VSCode 调试时若用 ts-node 作为 program，必须在 args 或环境变量中注入注册逻辑，否则所有 @/ 导入都会失败。
- 推荐
launch.json配置："program": "${workspaceFolder}/node_modules/.bin/ts-node"（Linux/macOS）或"program": "${workspaceFolder}/node_modules/.bin/ts-node.cmd"（Windows） -
"args"加上：["-r", "tsconfig-paths/register", "${relativeFile}"] - 确保项目已安装
tsconfig-paths：npm install --save-dev tsconfig-paths，否则-r会报Cannot find module - 注意：如果
tsconfig.json不在项目根目录（比如放在src/tsconfig.json），tsconfig-paths默认不识别，需加参数--project src/tsconfig.json
最易被忽略的是 tsconfig-paths 的安装位置和 ts-node 的调用路径——它必须从项目 node_modules 里取，不能用全局安装的版本，否则 -r 会找不到注册器。
