vscode路径别名依赖tsconfig.json或jsconfig.json的baseurl和paths配置，否则无法跳转或提示错误；多根工作区需各子项目独立配置；markdown路径与代码路径解析机制不同，不可混用。
VSCode 本身不解析路径别名，靠配置文件驱动识别
VSCode 的路径跳转、IntelliSense 和错误检查不会自动理解 @/utils 这类别名——它只认物理路径。真正起作用的是 tsconfig.json（TypeScript）或 jsconfig.json（JavaScript）里的 baseUrl 和 paths 配置。没有这个，插件再强也“看不见”别名指向哪。
常见错误现象：你写了 import api from '@/services/api'，VSCode 报“Cannot find module”，但项目能正常运行。这说明运行时（如 Vite/Webpack）已配置别名，而 VSCode 缺少对应映射。
- 必须在项目根目录下存在
tsconfig.json或jsconfig.json -
baseUrl建议设为"."，否则paths的解析基准会偏移 -
paths中的通配符需严格匹配，例如"@/*": ["src/*"]不能写成"@/*": ["src/"] - 修改后需重启 VSCode 或执行
Developer: Reload Window才生效
Import Magic 插件依赖配置，不是万能重写器
Import Magic 这类插件的作用是“根据已有配置做路径修正”，不是凭空猜测。它读取 tsconfig.json 的 paths，然后在保存时把 ../../utils/helper 自动转成 @/utils/helper。但它不会帮你补全未声明的别名，也不会跨工作区复用配置。
使用场景有限：适合已有规范路径结构、且 paths 映射明确的项目。若你刚加了 "#lib/*": ["libs/core/*"] 却没重启编辑器，插件仍按旧规则处理。
- 安装后默认开启 “on save” 自动修正，可在设置中关闭：
importMagic.autoFixOnSave - 对非标准别名（如不含
*的静态映射"@env": ["src/env.ts"]）支持不稳定 - 批量重构前建议先用
Ctrl+Click确认单个导入是否能跳转——跳转失败，插件大概率也修不对
多根工作区下路径映射必须各自独立配置
VSCode 的多根工作区（multi-root workspace）不会合并多个项目的 tsconfig.json。每个文件夹根目录下的配置只对该子树生效。如果你在 frontend/ 和 backend/ 两个文件夹里都用了 @/ 别名，但只在 frontend/tsconfig.json 里配了 paths，那么打开 backend/src/index.ts 时，@/ 就是无效的。
容易踩的坑：误以为工作区级 .vscode/settings.json 能统一控制路径解析——它不能。路径映射是语言服务（TypeScript Server）层面的行为，由每个子文件夹自己的配置驱动。
- 每个子文件夹都应有自己完整的
tsconfig.json或jsconfig.json - 避免在工作区设置里写
"typescript.preferences.importModuleSpecifier": "relative"这类选项干扰别名行为 - 如果子项目用不同构建工具（如一个用 Vite、一个用 Webpack），确保它们的别名配置与
tsconfig完全一致，否则跳转准、运行报错
Markdown 图片路径和代码路径是两套系统，别混用
你在 docs/guide.md 里写 ，和你在 src/App.tsx 里写 import logo from '@/assets/logo.png'，背后是完全不同的路径解析逻辑。前者由 Markdown 预览插件（如 Markdown All in One）基于当前文件位置计算相对路径；后者由 TypeScript 语言服务根据 tsconfig.json 解析。
这意味着：即使你给代码配好了 @/，Markdown 里照样不能直接写 ![]( "@/assets/logo.png" ) —— 没有插件支持这种语法，也不符合 CommonMark 规范。
- Markdown 路径管理要靠插件（如 Path Intellisense）+ 统一资源目录（如
/assets/images）+ 固定引用模式 - 不要试图用
jsconfig.json的paths让 Markdown 预览识别别名，它根本不读那个文件 - 若文档和源码共存于同一仓库，建议用脚本批量校验图片路径有效性，而不是依赖编辑器自动补全
路径映射不是开关一开就全局生效的事。它依赖配置文件存在、内容准确、作用域清晰，且不同文件类型（.ts/.js/.md）各自走各自的解析链。最常被忽略的，是忘记确认语言服务是否真正加载了你的配置——哪怕只差一个逗号，整个别名系统就静默失效。
