coverage gutters 插件仅读取 coverage.xml，需 pytest-cov 显式生成该文件，且路径、源码范围、工作区路径三者必须完全对齐，否则行号无法染色；务必安装 pytest、pytest-cov 和 coverage gutters 插件，配置 pytestargs 为数组格式，确保 --cov=src 中 src 与实际目录一致，并启用 relative_files 或修正路径前缀以匹配 coverage.xml 中的 路径。
Coverage Gutters 插件不会自动生成覆盖率数据，它只读取 coverage.xml；你必须让 pytest-cov 显式输出这个文件，且路径、源码范围、工作区路径三者完全对齐，否则行号旁永远不染色。
装对插件和库，别漏掉 pytest-cov
VS Code 自带的 Python 扩展只负责发现和运行测试，不带覆盖率能力。你得手动补全工具链：
- 在终端执行
pip install pytest pytest-cov（缺一不可，pytest负责跑测试，pytest-cov负责统计） - 安装 VS Code 插件：
Coverage Gutters（仅读报告）、Python（Microsoft 官方扩展，启用测试侧边栏） - 别装
Python Test Explorer或vscode-jest这类前端/JS 专用插件——它们对 Python 无效
pytestArgs 必须是数组，不能写成字符串
很多人在 settings.json 里把参数写成一行字符串，导致 pytest 直接报错 unrecognized arguments：
- 错误写法：
"python.testing.pytestArgs": "--cov=src --cov-report=xml:coverage.xml" - 正确写法：
"python.testing.pytestArgs": ["--cov=src", "--cov-report=xml:coverage.xml", "--cov-report=term-missing"] -
--cov=src中的src要和你实际源码目录名一致（不是.，否则会混入tests/和__pycache__/） -
--cov-report=term-missing很关键：它让你在终端里立刻看到哪几行没覆盖，比等插件染色快得多
coverage.xml 路径和内容必须严格匹配打开的文件
Coverage Gutters 不会“猜”路径，它逐字比对 coverage.xml 里的 <source></source> 和你当前编辑器中文件的完整路径：
- 运行测试后，先检查项目根目录下是否有非空的
coverage.xml：head -n 5 coverage.xml应该以<?xml开头 - 打开
coverage.xml，搜索你正在编辑的文件名，找到类似<source>/home/user/project/src/utils.py</source>的行 - 你在 VS Code 里打开的路径必须完全一致：比如
./src/utils.py和/home/user/project/src/utils.py就不匹配（前者是相对路径，后者是绝对路径） - 解决办法：在
pyproject.toml中加[tool.coverage.run] relative_files = true，或用sed -i 's|/mnt/c/|C:/|g' coverage.xml修正 WSL 路径
别指望右键菜单自动刷新覆盖率
点击测试侧边栏里的 ▶️ 运行测试，Coverage Gutters 不会自动更新——它不监听测试完成事件：
- 每次改完代码，手动运行一次完整命令：
pytest --cov=src --cov-report=xml:coverage.xml --cov-report=term-missing - 或者在
.vscode/tasks.json里定义一个 task，绑定快捷键（如 Ctrl+Shift+T），避免反复敲命令 - 如果用了
pyproject.toml，确认[tool.coverage.run]下有source = ["src"]，否则即使参数对了，统计范围仍是空的
最常被忽略的是 coverage.xml 中的路径前缀和 VS Code 当前工作区路径的大小写、斜杠方向（/ vs \）、开头是否带 ./ ——差一个字符，整行就不染色。建议先用 pytest --cov=src --cov-report=html 生成 htmlcov/index.html 浏览验证数据是否正确，再回头调 coverage.xml 路径。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
