自动导入生成长路径（如../../../src/utils）的根本原因是语言服务器缺乏明确的模块根路径配置，导致其退化为暴力向上遍历；解决方式是通过tsconfig.json配置baseurl+paths或pyrightconfig.json设置extrapaths，并重启服务。
为什么自动导入总生成 ../../../src/utils 的长路径
VSCode 的自动导入（尤其是 TypeScript/JavaScript）默认按“最短相对路径”解析模块位置，但当项目存在多层嵌套目录、软链接或未配置 tsconfig.json 时，它会退化为暴力向上遍历，直到找到匹配的导出声明——结果就是生成一串 ../../../。这不是 bug，而是路径解析逻辑在缺乏明确上下文时的保守 fallback。
- 典型场景：你在
src/features/dashboard/components/Chart.tsx中输入useApi，它却自动导入成import { useApi } from "../../../../hooks/useApi" - 根本原因：语言服务器没被告知“哪些目录是可直接引用的根”，只能靠物理路径距离算“最近”
- 关键判断点：打开命令面板（
Ctrl+Shift+P），执行TypeScript: Open TS Server Log，搜索getExternalModuleFile或resolveModuleNames，若日志里反复出现大量../回溯，说明解析已失控
用 baseUrl + paths 让导入路径扁平化
这是最稳定、团队协作最友好的解法。它不依赖文件系统结构，而是通过 tsconfig.json 显式声明“别名映射”，让 import { x } from "@hooks/useApi" 成为可能。
- 在
tsconfig.json的compilerOptions中添加：
{
"baseUrl": "./src",
"paths": {
"@hooks/*": ["hooks/*"],
"@utils/*": ["utils/*"],
"@components/*": ["components/*"]
}
}
- 重启 TS 服务：保存后执行
Ctrl+Shift+P → TypeScript: Restart TS server（必须做，否则缓存不更新） - 验证是否生效：在任意文件中输入
import {，补全列表里应出现带@hooks/前缀的选项；手动输入@hooks/useApi也应能正确解析并跳转 - 注意坑：
baseUrl必须是相对路径（不能写./src/后多一个斜杠），且paths的 key 必须以*结尾，value 也必须对应带*—— 缺一不可，否则 TS Server 直接忽略该条映射
Python 项目怎么避免 sys.path 插入过深的相对路径
Python 的自动导入（如 Pylance）同样受 sys.path 影响。如果项目结构是 project/backend/src/main.py，而你想从 main.py 导入 project/backend/src/utils/helper.py，Pylance 默认不会把 src 自动加进路径，导致它拼命往上爬，生成 from ....utils import helper 这种危险写法。
- 优先改
pyrightconfig.json（比settings.json更精准）：
{
"include": ["src/**/*"],
"extraPaths": ["src"]
}
- 或者在 VSCode 的
.vscode/settings.json中设：
"python.defaultInterpreterPath": "./venv/bin/python", "python.analysis.extraPaths": ["src"]
- 绝对不要在代码里写
sys.path.insert(0, "../../..")—— 这会让 Pylance 的静态分析彻底失效，补全和跳转会断掉 - 验证方式：把光标停在报错的 import 上，按
F12，能正常跳转到定义即成功；如果提示 “No definition found”，说明extraPaths没生效或路径写错了
软链接项目里自动导入失效的隐藏陷阱
当你用 pnpm/lerna 管理 monorepo，并在 packages/app 下开发时，VSCode 可能通过软链接把 node_modules 解析进工作区深层路径（比如 packages/app/node_modules/.pnpm/xxx/node_modules/yyy）。此时 TS Server 在解析类型时，会误判模块位置，导致自动导入要么找不到，要么生成错误路径（如指向 ../../node_modules/.pnpm/...）。
- 先确认是否中招：终端进项目根目录，运行
find packages/app/node_modules -type l -path "*/node_modules/*" | head -5，若有输出，基本就是它 - 临时缓解：在
tsconfig.json加"skipLibCheck": true（仅跳过 node_modules 类型检查，不影响业务代码导入） - 长期解法：在
packages/app/tsconfig.json里显式排除软链干扰：
"compilerOptions": {
"types": ["node"],
"moduleResolution": "node"
},
"exclude": ["node_modules/**", "**/node_modules/**"]
- 最关键一步：确保你打开的是
packages/app单独文件夹，而不是整个 monorepo 根目录 —— VSCode 对多级软链的路径解析在单根工作区下更可控
tsconfig.json 或 pyrightconfig.json 缺失、路径配置有语法错误、或工作区加载顺序混乱，所有自动导入都会回归原始暴力模式。检查这些配置文件是否存在、是否被正确读取（看右下角语言模式状态栏有没有报 TS/Pyright 错误），比调各种插件参数更有效。
