pytest.ini必须放在项目根目录下，pytest仅从当前工作目录向上逐级查找该文件，不从测试文件路径或PYTHONPATH搜索；文件名须严格为pytest.ini，语法需用[tool:pytest]节头，且避免与pyproject.toml等高优先级配置冲突。
pytest.ini 文件必须放在项目根目录下
pytest 只会在当前工作目录（即你运行 pytest 命令时所在的目录）向上逐级查找 pytest.ini，直到找到第一个匹配文件为止。它**不会**从测试文件所在目录、__file__ 所在路径或 PYTHONPATH 中搜索。
常见错误是把 pytest.ini 放在 tests/ 或 src/ 子目录里，结果 pytest 完全无视它。
- 确认你执行
pytest时的当前路径：运行pwd（Linux/macOS）或cd（Windows），确保该路径下存在pytest.ini - 可以用
pytest --debug查看加载日志，其中会明确打印 “Using ini file: …” 或 “No ini file found” - 如果项目结构复杂（比如多层嵌套包），建议在 git 根目录（即
.git同级）放pytest.ini，并始终从该目录运行测试
文件名拼写和格式必须严格正确
pytest 只认 pytest.ini 这个精确文件名——不能是 py.test.ini、pytest.conf、setup.cfg（除非你明确想用它替代），更不能是 pytest.ini.bak 或隐藏文件如 .pytest.ini。
同时，INI 文件语法有硬性要求：
- 必须以
[tool:pytest]作为 section header（不是[pytest]，也不是[tool:py.test]） - 所有配置项必须是 key = value 形式，等号前后可有空格，但不能有 tab 混入（尤其从 Word 或某些编辑器复制时易出问题）
- 注释只能用
#开头，;不被支持（这是常见坑）
示例正确写法：
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
[tool:pytest] testpaths = tests python_files = test_*.py addopts = -v --tb=short
pytest 优先级规则导致配置被覆盖
pytest 加载配置的顺序是：pytest.ini → pyproject.toml（含 [tool.pytest.ini_options]）→ setup.cfg → 命令行参数。只要后面有同名配置项，前面的就会被覆盖。
如果你项目里同时存在 pyproject.toml 和 pytest.ini，哪怕 pyproject.toml 里没写任何 pytest 配置，只要它包含 [tool.pytest.ini_options] 这个 section（哪怕为空），pytest 就会跳过 pytest.ini。
- 检查是否存在
pyproject.toml，运行pytest --help看 “configfile” 行显示的是哪个文件 - 临时重命名
pyproject.toml为pyproject.toml.bak，再运行pytest --debug确认是否开始读取pytest.ini - 如果必须共存，把所有配置统一迁移到
pyproject.toml中，避免歧义
使用 pytest-xdist 或其他插件时的路径陷阱
某些插件（尤其是 pytest-xdist）在分布式执行时，worker 进程可能在临时目录启动，导致无法访问原项目的 pytest.ini。此时即使你在根目录放了配置，worker 也读不到。
这不是配置写错，而是执行环境变了：
- 运行
pytest -n 2时，实际是启动多个子进程，它们的工作目录可能不是你预期的项目根目录 - 解决办法：显式用
--confcutdir=.锁定配置搜索起点，或改用pyproject.toml（它被识别得更稳定） - 验证方式：在测试中加
print(os.getcwd())，确认每个 worker 的当前路径
配置失效往往不是语法错，而是位置、命名、优先级或执行上下文这四个点中的某一个没对齐。最省事的排查路径是：先 cd 到项目根目录，删掉所有其他配置文件，只留 pytest.ini，用 pytest --debug 看它到底加载了什么。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
