记得👇关注我，加星标★

🌟 你好呀，我是羽师，见字欢喜，感恩有你。

上周有个读者在后台问我：

「羽师，我项目明明能跑，但 Cursor 里 Ctrl+点击就是跳不到定义，是不是 IDE 坏了？」

我回他：大概率不是 IDE 坏了，是 Python 的「路径玄学」在搞你。

今天这篇，我把这类问题的来龙去脉、排查思路、标准解法，一次性说清楚。如果你也在用 Cursor / VS Code + Python，并且项目里是 from src.xxx import yyy 这种写法——建议收藏，下次能省你半小时。

一、先别慌：能运行 ≠ IDE 能看懂

很多 Python 项目长这样：

my-project/├── src/│   ├── api/│   ├── services/│   └── config/├── tests/├── scripts/└── pyproject.toml

代码里这么写：

from src.config.settings import settingsfrom src.services.search_service import SearchService

终端里你可能习惯这样启动：

PYTHONPATH=. uvicorn src.api.main:app --reload# 或PYTHONPATH=. pytest tests/ -v

关键点来了：

•运行时：你把「项目根目录」塞进了 PYTHONPATH，Python 能找到 src 包 •IDE 里：语言服务（Pylance / Pyright）默认不知道你做了这件事 

所以就会出现这种「分裂现场」：

这不是你代码写错了，是 IDE 和运行环境的「认知不一致」。

二、30 秒自检：你是不是「src 布局 + 绝对导入」？

满足下面 任意两条，基本就可以断定是路径配置问题：

1.项目根目录下有 src/ 文件夹2.导入写法是 from src.xxx import yyy（不是相对导入）3.启动命令里常写 PYTHONPATH=.4.换一台电脑 / 新开 IDE 窗口后，跳转突然失效5.Pyright 报 Import "src.xxx" could not be resolved

Windows 同学如果终端里不好设环境变量，PowerShell 可以这样：

$env:PYTHONPATH = "."python -m uvicorn src.api.main:app --reload

能跑，不代表 IDE 会自动继承这个设定。

三、标准解法：加一个 pyrightconfig.json

我现在的首选方案是：在项目根目录放 pyrightconfig.json。

Cursor 和 VS Code 的 Python 语言服务（Pylance）会读它，相当于告诉 IDE：「请把项目根目录当作模块搜索路径。」

通用模板（可直接复制）

{  "include": [    "src",    "tests",    "scripts"  ],  "exclude": [    "**/__pycache__",    "**/.pytest_cache",    "frontend",    "frontend/dist",    "**/node_modules"  ],  "extraPaths": ["."],  "executionEnvironments": [    {      "root": ".",      "extraPaths": ["."],      "pythonVersion": "3.11"    }  ],  "pythonVersion": "3.11",  "typeCheckingMode": "basic",  "useLibraryCodeForTypes": true,  "reportMissingImports": true,  "reportMissingTypeStubs": false}

每个字段在干什么（用人话版）

extraPaths: ["."]核心中的核心。让 from src.xxx 从项目根目录解析，而不是瞎找。

四、配完后必做 3 步（很多人卡在第 2 步）

1）重载窗口

Ctrl + Shift + P → 输入 Reload Window → 回车。

配置文件改了不 reload，等于白改。别问我怎么知道的。

2）选对 Python 解释器

【如果没安装优先安装】

Ctrl + Shift + P → Python: Select Interpreter

选你真正安装了项目依赖的那个环境（venv / conda / 系统 Python 都行，关键是包装对了）。

解释器选错，表现通常是：

•第三方库跳转不了•类型提示全乱•个别模块「时而能跳、时而不能跳」

3）确认语言服务是 Pylance

设置里搜 python.languageServer，建议是 Default 或 Pylance。

五、怎么验证「真的修好了」？

不用靠感觉，直接验收：

1.打开任意 from src.xxx import yyy 的文件2.对符号 Ctrl + 左键（Mac：Cmd + 点击）3.看能否跳到定义4.看 import 波浪线是否消失5.自动补全是否恢复正常

想更硬核一点，可以命令行跑 Pyright 做二次确认：

npx pyright src/your_module.py

如果输出 0 errors，说明路径解析已经通了。

六、进阶：不同项目结构怎么改？

情况 A：不是 src 包，而是平铺结构

app/  main.py  services/

通常 不需要extraPaths，除非你有自定义根目录。

情况 B：monorepo（多个 Python 子项目）

"executionEnvironments": [  { "root": "services/api", "extraPaths": ["services/api"] },  { "root": "services/worker", "extraPaths": ["services/worker"] }]

每个子项目单独一套 root，避免互相污染。

情况 C：还有一层 libs/ 公共模块

"extraPaths": [".", "./libs"]

七、我常用的「IDE 体验三板斧」

除了 pyrightconfig.json，羽师平时还会配套这几项：

① 统一运行方式团队文档里写清楚：开发、测试都带 PYTHONPATH=.，减少「我这能跑你那不能跑」。

② .gitignore 干净别把 __pycache__、.pytest_cache、构建产物提交进仓库，IDE 索引会快很多。

③ 类型检查别一上来就 strict先 basic 跑顺，再逐步收紧。开发体验和内容质量，要平衡，不要内卷。

八、常见翻车 FAQ

Q1：我加了配置还是跳不动？按顺序查：① 配置文件是否在项目根② 是否 Reload Window③ 解释器是否选对④ 当前打开的是不是 workspace 根目录（别只开了子文件夹）

Q2：只有第三方库跳不动？那是解释器环境里没装包，不是 extraPaths 问题。pip install -e . 或 pip install -r requirements.txt 先安排上。

Q3：Pyright 和 Pylance 啥关系？可以简单理解：Pylance = VS Code/Cursor 里的 Pyright 增强版。所以 pyrightconfig.json 通常两边通吃。

Q4：mypy 也要配吗？要。运行时和 IDE 是两条线：

•IDE：pyrightconfig.json•CI / 类型检查：mypy.ini 或 pyproject.toml [tool.mypy]后面我可以单独写一篇「mypy 怎么和 IDE 配置对齐」。

九、最后说两句

写 Python 久了你会发现一个规律：

很多问题不是语言难，是「环境上下文」没对齐。

终端能跑、IDE 不能跳，本质就是：运行时的 sys.path 和静态分析的 search path 不是同一套。

pyrightconfig.json 看起来就几行 JSON，但它解决的是每天都要碰几十次的开发效率问题——跳转、补全、重构、读代码，全都依赖它。

如果你也被 Ctrl+点击折磨过，把这篇转给同事，或者先收藏，下次配环境直接翻出来抄作业。

（本文基于真实踩坑经验整理，已去除具体业务与内部信息，适用于 Python src 布局 + Cursor/VS Code 开发场景。）

微信5000好友位将满👇

PS：因公众号平台更改了推送规则，如果不想错过内容，记得读完点一下“❤️推荐❤️”，加个“星标”，这样每次新文章推送才会第一时间出现在你的订阅列表里。
点“❤️推荐❤️”支持羽师,码字原创不易