如何获取调用Python插件的项目根目录

避坑提醒 #

别在插件代码里直接用Path(__file__).parent取路径，这个拿到的是你插件自身的安装/存放路径，和调用方的项目没有任何关系；也不要用os.getcwd()，这个返回的是程序启动时的shell工作目录，用户可能在任意路径下执行命令，结果完全不可靠。

方案1：基于入口脚本探测（通用场景首选） #

绝大多数Python项目都是通过入口脚本启动的，不管是直接python run.py还是用包管理工具的run命令，sys.argv[0]都会保存最顶层入口脚本的路径，从这个路径出发，向上遍历目录，匹配项目根目录的常见标记文件即可，性能好、准确率高。
示例代码：

import sys
from pathlib import Path
from typing import Optional, Tuple

def get_project_root(
    root_markers: Tuple[str, ...] = ("pyproject.toml", ".git", "requirements.txt", "setup.py", "Pipfile")
) -> Path:
    # 取入口脚本的绝对路径
    entry_file = Path(sys.argv[0]).resolve()
    # 从入口文件所在目录向上逐层查找
    for check_dir in (entry_file.parent, *entry_file.parents):
        if any((check_dir / marker).exists() for marker in root_markers):
            return check_dir
    # 未匹配到标记时兜底返回入口文件所在目录
    return entry_file.parent

你可以根据插件面向的用户群体调整默认的根标记列表，也可以开放参数让调用方传入自己项目的标记文件。

方案2：调用栈回溯（兼容非脚本启动场景） #

如果你的插件需要兼容交互式运行、嵌入式Python环境这类没有固定入口脚本的场景，可以通过inspect模块遍历调用栈，过滤掉插件自身的代码帧，找到第一个来自调用方项目的代码帧，再从该文件路径出发向上查找根目录。
示例代码：

import inspect
import sys
from pathlib import Path
from typing import Optional, Tuple

# 插件初始化时先记录自身的根路径，用于过滤栈帧
import your_plugin_name
PLUGIN_SELF_PATH = Path(your_plugin_name.__file__).parent.resolve()

def get_project_root_by_stack(
    root_markers: Tuple[str, ...] = ("pyproject.toml", ".git", "requirements.txt", "setup.py")
) -> Optional[Path]:
    # 遍历调用栈，跳过插件自身的帧
    for frame in inspect.stack():
        frame_file = Path(frame.filename).resolve()
        # 属于插件自身的代码直接跳过
        if PLUGIN_SELF_PATH in frame_file.parents:
            continue
        # 找到第一个外部调用帧，从该文件目录向上查找根
        check_base = frame_file.parent
        for check_dir in (check_base, *check_base.parents):
            if any((check_dir / marker).exists() for marker in root_markers):
                return check_dir
        break
    return None

注意：inspect.stack()有一定性能开销，不要在高频调用的逻辑里重复执行，建议插件初始化时调用一次，把结果缓存到全局变量里复用。

兼容性优化建议 #

• 如果插件面向特定框架（Django、Flask、FastAPI等）开发，可以优先读取框架本身暴露的根目录配置（比如Django的django.conf.settings.BASE_DIR），准确率更高。
• 开放手动配置入口：在插件初始化参数里增加project_root选项，调用方如果有自定义目录结构可以手动传入，自动探测逻辑仅作为兜底方案，能覆盖绝大多数使用场景。

内容的提问来源于stack exchange，提问作者D. Bazel