basedpyright 如何解析 tests 目录中的测试工具导入？

2026-11-06数据阿明

结论

不必把测试辅助模块移到 src。对于 from tests.utility.helpers import some_helper，basedpyright 的导入搜索路径需要包含顶层包 tests 的父目录，也就是项目根目录。当前配置中的 extraPaths: ["tests"] 指向 tests 目录本身。按这种导入写法，解析器会在该目录下继续查找 tests，路径层级可能因此对不上。

调整配置

如果 pyrightconfig.json 位于 project-root，可以把 tests 执行环境中的 extraPaths 改为项目根目录：

{
  "pythonVersion": "3.10",
  "reportAny": "none",
  "executionEnvironments": [
    {
      "root": "src"
    },
    {
      "root": "tests",
      "reportUninitializedInstanceVariable": "none",
      "reportMissingModuleSource": "none",
      "extraPaths": ["."]
    }
  ]
}

root 用来为匹配的文件选择执行环境，extraPaths 用来补充模块搜索路径。这里的 "." 是相对于配置文件所在目录的项目根目录，解析器因此能从根目录找到 tests/utility/helpers.py。如果配置文件不在项目根目录，extraPaths 应指向实际包含 tests 目录的位置。

为什么 unittest 能运行

unittest 能运行，说明测试运行时的 Python 导入路径可以找到该模块。测试的启动方式、当前工作目录或其他运行配置都可能影响运行时的搜索路径。静态分析器则根据自己的项目配置解析导入，不会因为测试运行成功就自动使用相同的路径。

是否需要把辅助模块移到 src

不需要，测试专用的辅助代码可以留在 tests 中。对于 tests.utility.helpers 这种完整包名，静态分析器的搜索路径需要包含 tests 的父目录。调整后如果仍无法解析，请确认 tests 和 tests/utility 中的 __init__.py 与给出的结构一致，并检查 pyrightconfig.json 是否位于假定的项目根目录。