如果包内的 Python 文件在直接运行时引发 ImportError: attempted relative import with no known parent package，请将其作为模块从包的上级目录启动。在 macOS 上，在终端中切换到项目根目录，然后运行 python3 -m package.module。这将为 Python 提供直接文件路径所无法提供的包上下文。

为什么直接运行文件时相对导入会失败？

类似 from .helpers import format_result 的相对导入取决于模块的包名称。Python 使用前置的点来标识当前包及其父包。当你使用 python3 path/to/file.py 运行文件时，Python 会将该文件作为顶层的 __main__ 模块运行；它不会为其提供解析点号所需的包元数据。因此，即使 helpers.py 就位于该文件旁边，导入也可能会失败。Python 的导入参考文档描述了相对导入以及针对 __main__ 的特殊处理。

例如，假设你的项目结构如下：

project/
└── myapp/
    ├── __init__.py
    ├── cli.py
    └── helpers.py

如果 cli.py 包含 from .helpers import format_result，那么从 project 运行 python3 myapp/cli.py 是错误的调用方式。问题在于 Python 被要求运行该文件的方式，而并不一定是相对导入或文件位置有误。

在 macOS 上从项目根目录运行模块

打开终端并切换到包含 myapp 的目录。将示例路径替换为你项目的实际位置。用引号括起路径，以便 shell 能够正确处理空格；macOS 终端的默认 shell 是 zsh。Apple 的终端使用手册记录了该默认设置。

cd "/Users/yourname/Projects/project"
python3 -m myapp.cli

-m 选项要求 Python 通过其带点号的包名称来查找并运行该模块。在命令中保留包名，并去掉 .py 和文件系统斜杠。通过 -m 调用时，Python 的模块搜索路径从当前目录开始，这就是为什么从项目根目录运行很关键的原因。Python 的 sys.path 文档解释了此起始路径。

如果该命令使用了错误的 Python 安装，请先激活项目现有的虚拟环境，然后使用相同的 python -m 模式。对于项目根目录下的典型 .venv：

cd "/Users/yourname/Projects/project"
source .venv/bin/activate
python -m myapp.cli

激活后使用 python 会选择该环境的解释器。如果你的环境名称或位置不同，请调整激活路径；不要假定 .venv 一定存在。你可以使用 python -c 'import sys; print(sys.executable)' 检查所选的解释器。

如果你想运行包本身

对于旨在启动包的命令，请在包内添加 __main__.py，并保持入口点简短：

myapp/
├── __init__.py
├── __main__.py
├── cli.py
└── helpers.py

在 myapp/__main__.py 中，导入并调用包的入口函数。然后从项目根目录运行 python3 -m myapp。对于这种形式的 -m 调用，Python 会执行包的 __main__.py，并且该文件可以使用相对于包的导入。Python __main__ 文档解释了这种包入口点模式。

如果错误仍然存在，请检查以下细节

  • 确认你的工作目录。 在终端中运行 pwd，确保它输出项目根目录，即包含 myapp 的目录。例如，如果包嵌套在 src 下，请使用可导入的包名，并确保项目配置的环境使其可用；仅仅切换到错误的父文件夹并不能解决模块发现问题。
  • 使用真实的包名。 在 python3 -m myapp.cli 中，myapp 必须是包目录名（或其导入名称），而 cli 是不带 .py 的模块文件名。
  • 检查回溯行。 如果相对导入解析成功，但后面的导入失败，那可能是由于缺少其他模块或依赖项。修复启动上下文只能解决与包上下文相关的失败。
  • 避免将 PYTHONPATH 作为首选修复方案。 它会改变 Python 的导入搜索路径，但本身并不能将直接执行的文件变成正确命名的包模块。Python 还提醒，PYTHONPATH 可能会影响多个 Python 版本和环境。Python 的路径初始化参考描述了其作用范围。
  • 如果必须直接执行文件，请考虑修改代码以使用适当的绝对导入，并确保在该环境中已安装该包或以其他方式使其可导入。这属于不同的架构选择；不要既使用相对于包的导入，又期望该文件表现得像一个独立脚本。

实用的规则是将命令与导入风格相匹配：对于相对于包的导入，使用 python -m 从包的父目录运行模块。对于包命令，请提供 __main__.py 并使用 -m 运行该包。

来源