paths未生效需检查baseUrl是否设为相对路径（如"./"）、include是否覆盖源码路径、paths键值是否含通配符*，并重启TS服务。
tsconfig.json 里 paths 没生效？检查 baseUrl 和 include
VS Code 不会自动识别 paths 别名，除非它明确知道从哪开始解析、以及哪些文件要参与类型检查。常见现象是写了 @/utils 却提示 “Cannot find module”，或跳转定义失败。
-
baseUrl必须显式设置，且值为相对路径字符串（如"./"），不能省略或写成"src"—— 后者会导致别名解析起点错位 -
include字段必须覆盖使用别名的源码，例如"include": ["src/**/*"]；若只写["src/index.ts"]，其他文件就“不在类型系统视野内” - 别名路径末尾带
/*是强制要求："@/*": ["src/*"]✅，"@/": ["src/"]❌（后者在部分 TS 版本中会静默失效）
TypeScript 报错但代码能跑通？先确认是否用了 workspace 版本
VS Code 状态栏右下角显示的 TypeScript 版本决定你看到的报错是否真实。如果显示 “Bundled” 或 “TS 5.0.4”，哪怕 tsconfig.json 里写了 "strict": true，你也大概率看不到 Object is possibly 'undefined' 这类严格检查提示。
- 按
Ctrl+Shift+P（macOS 是Cmd+Shift+P），运行TypeScript: Select TypeScript Version，选Use Workspace Version - 确认项目已安装
typescript：执行npm install --save-dev typescript，否则 workspace 版本根本不存在 - 重启 TS 服务：运行
TypeScript: Restart TS Server，尤其在改完tsconfig.json后，缓存不刷新会导致配置“看似生效实则被忽略”
报错 “Cannot find name 'require'” 或 “NodeJS namespace not found”？缺 @types/node
这和 paths 无关，是模块类型声明缺失的典型表现。TypeScript 默认不预设 Node.js 全局对象和 API 类型，必须靠 @types/node 补全。
Galileo TypeScript sdk
下载
完整的Galileo AI平台 TypeScript/JS SDK 参考，用于评估、观察和保护 GenAI 应用。适用于构建 Node.js 或 TypeScript 项目。
- 执行
npm install --save-dev @types/node，注意不是@types/nodejs或其他变体 - 确保
tsconfig.json中lib包含"DOM"（浏览器环境）或"ES2020"（Node 环境），同时types字段未被意外覆盖（默认会自动包含@types/node） - 如果项目混合前后端，避免在
compilerOptions.types中硬编码值，否则可能把@types/node排除在外
路径映射后 import 提示类型错误？检查模块解析策略和扩展名
即使 paths 配置正确，VS Code 仍可能报 “Module X has no exported member Y”，原因常出在模块解析逻辑上。
-
"moduleResolution": "node"必须显式设置在compilerOptions中，否则 TS 默认用旧式classic解析，无法识别package.json的exports或types字段 - 导入语句末尾不写
.ts扩展名是常规做法，但若目标文件是.d.ts声明文件，且未通过types或typeRoots正确暴露，就会报类型缺失 - 别名路径映射不支持动态拼接，
import * as utils from `@/utils/${env}`这种写法永远无法被静态分析，必然报错
路径别名和类型检查的耦合点很细——baseUrl 错一位、include 漏一个 glob、moduleResolution 没设对，都会让整个映射链断裂。最稳妥的做法是：每次改完 tsconfig.json，立刻重启 TS Server 并打开一个新 .ts 文件验证跳转和报错是否同步更新。
