调试断点“跳行”或失效通常因__pycache__缓存未同步：修改.py文件后旧.pyc仍被加载，导致源码行号与字节码指令映射错位；手动删除__pycache__并重启调试即可验证和解决。
调试时断点“跳行”或失效，常因__pycache__缓存未同步
Python调试器（如VS Code、PyCharm、pdb）依赖源码行号与字节码指令的映射关系。当修改了.py文件但__pycache__里仍保留旧.pyc，调试器实际执行的是旧字节码，而你在新源码上设的断点就可能绑定到错位的指令行——表现为断点不触发、跳到空行、或停在完全无关的代码位置。
这不是调试器bug，而是缓存和源码“脱节”的典型症状。尤其在快速迭代、热重载、或多人协作共享同一工作区时高频出现。
-
__pycache__/utils.cpython-312.pyc若比utils.py时间戳旧，就会被加载；即使你刚改完逻辑，调试器也看不到变更 - 装饰器（
@lru_cache、@property）、生成器（含yield）、async/await会进一步放大映射偏差 - IDE自动重启语言服务器不一定清掉所有.pyc，尤其跨Python版本（如从3.11切到3.12）后残留旧缓存
如何确认是__pycache__导致调试异常？
最直接的方法是观察调试器行为是否与源码一致：比如在某行加断点，运行后停在上一行/下一行/空白处；或者修改函数体后，debug时打印的变量值仍是旧逻辑的结果。
验证步骤很简单：
立即学习“Python免费学习笔记（深入）”；
python-script-generator
下载
快速生成专业的 Python 脚本和应用代码。一键创建完整项目结构，支持CLI、API、爬虫、Bot、Django等多种项目类型，包含完整的项目结构、配置文件、依赖管理、测试、README和文档。
- 手动删除当前模块所在目录下的
__pycache__文件夹（例如rm -rf utils/__pycache__） - 重启调试会话（不是仅重启终端，要彻底关闭调试器进程）
- 重新运行，看断点是否回归正常位置
- 若恢复正常，基本可锁定是缓存问题；若仍异常，则需排查装饰器、动态导入或IDE配置
禁用__pycache__不是万能解，但适合特定调试场景
临时禁用字节码缓存，能彻底规避“源码-字节码”不同步问题，适合深度调试、CI环境复现、或怀疑缓存损坏时使用。
注意：禁用后每次import都会重新编译，启动变慢，仅建议短期使用。
- 命令行运行时加
-B参数：python -B main.py，该参数强制不写.pyc - 设置环境变量：
PYTHONDONTWRITEBYTECODE=1（Linux/macOS）或set PYTHONDONTWRITEBYTECODE=1（Windows） - 在脚本开头插入：
import sys; sys.dont_write_bytecode = True（仅对当前进程生效） - VS Code中可勾选 “Python: Clear All Caches and Restart Language Server”，但该操作不删除.pyc，只清内存缓存
Git提交和CI部署中忽略__pycache__，但别指望它“自愈”
__pycache__ 不该进版本库，这是共识；但很多人误以为只要加了 __pycache__/ 到 .gitignore 就万事大吉——其实CI构建或同事拉取代码后，本地仍会自动生成，且可能沿用旧缓存。
真正影响调试一致性的，是团队成员Python版本是否统一、以及CI是否做了缓存清理。
- Docker构建中务必显式清理：
find . -type d -name "__pycache__" -delete和find . -type f -name "*.py[co]" -delete - pyenv多版本切换时，
__pycache__会按cpython-312、cpython-311分开存储，但旧版本残留的.pyc可能被误读（尤其PATH混乱时） - 某些IDE（如PyCharm）的“Clean Python compiled files”功能只清当前项目，不递归子包，容易漏掉嵌套模块的缓存
__pycache__，比反复检查语法和逻辑更高效。 
