小问题大隐患:如何正确设置 Python 项目的入口文件?

off999 2025-07-07 22:14 88 浏览 0 评论

有一位同学提到了 Python 找不到模块的问题：

问题涉及到的代码结构和代码截图如下：

这个问题的解决方法非常简单，就是把start.py文件从bin文件夹移出来就好了。

但如果对这个问题进一步分析，可以看到更多问题。

在之前，我讲到了工作区（Workdir）对代码的影响。PyCharm、VSCode 识别的工作区，可能并不等于你直接在终端窗口运行.py文件时候的工作区。

今天这个问题本质上也是工作区导致的问题。这个同学的项目根目录是MY_API，所以他使用的编辑器VSCode 就会默认把MY_API当做工作区。所以，当他在start.py文件中写上from lib.interface import server时，VScode 并不会给他标记红色波浪线。因为从 VSCode 的视角看，lib文件夹确实就是在工作区下面的。

但是，当他在 VSCode 里面运行这个start.py文件时，Python 是从bin文件夹下面运行的。此时，Python 会把bin文件夹当做工作区。在工作区里面就只有这一个start.py文件，所以当然找不到lib文件夹。

如果仅仅从技术上来说，你非要导入 bin 文件夹的父文件夹下面的其他模块，也并不困难。

但问题在于，你不应该这样做。你不应该把项目的入口文件，放到项目内部很深的文件夹中。

所谓入口文件，就是要首先经过它，才能到达其他的文件。当你拿到一个 Python 项目，你只需要首先从入口文件开始阅读代码，根据入口文件调用的模块，一路看下去，你就能读到它的所有实现逻辑。

但如果大家经常逛 Github，就会发现，有些人可能是被其他垃圾语言污染了思想，他的 Python 项目，根目录有五六个文件夹和七八个.py文件。你拿到这个项目的时候，你甚至不知道，当你想运行这个代码的时候，python3 xxx.py应该运行哪个文件。你多方打听，或者看了半天文档，才知道，哦，原来入口文件在com/xx/yy/zz/script/run.py。

当你打开这个run.py文件，你发现它的顶部，文件导入的代码写的是from ../../../../aaa import bbb。

简直是神经病写法。我知道有些垃圾语言流行这样写。但现在你用的是 Python，学聪明一点，别那样写。

对于一个 Python 项目来说，入口文件应该始终在最外层。例如：

当你要启动这个项目的时候，直接在最外层python3 main.py，就能把它启动起来。在main.py里面，你可以导入其他模块，然后调用其他模块里面的类或者函数。

这样做的好处是什么？这样做，你是在项目的根目录启动的这个项目，所以你的工作区就是项目的根目录。那么你在任何一个.py文件里面都可以很容易地基于工作区导入任意其他文件。例如，你现在在models/mongo-util/mongob_helper.py文件中，你想导入utils/abc.py中的time_format()函数，那么，你只需要这样写就可以了。

from utils.abc import time_format

你根本不可能出现需要导入父文件夹中的某个模块的情况。

只有工具脚本，才需要单独使用一个文件夹来存放，然后调用父文件夹中的其他文件。例如，我现在有一个工具脚本，它每天晚上0点会读写 MongoDB，清理无效数据，那么此时，我可以在根目录单独创建一个script或tools或者bin文件夹，然后把工具脚本放进去，例如：

在这个工具脚本里面，你可能会调用models/mongo-util/mongob_helper.py文件中的某个函数。这种情况下，你调用父文件夹中的内容是可以接受的。但这毕竟只是工具脚本。

可能还有同学要问，那如果我的项目是一个 Python 的包，它本身没有入口文件怎么办呢？这个时候，你可以把这个包的__init__.py当做它的入口文件。大家可以参考我在 GitHub - kingname/GeneralNewsExtractor: 新闻网页正文通用抽取器 Beta 版.[1]的代码组织结构。在项目根目录留下一个example.py文件，用来演示如何调用这个包。而这个包本身的代码，是在一个叫做gne的文件夹中的。这个gne文件夹是一个包，它的入口文件在__init__.py中。

各位，当你写代码的时候，你先想一想，如果别人拿到了你的代码，想要梳理一下这个项目的逻辑，在不询问你的情况下，怎么让他知道应该从哪个文件开始读？应该按什么顺序读？他能不能轻易地看到数据在你的代码中是怎么运转的？