本地安装的Python Wheel包抛出ModuleNotFoundError错误

嘿兄弟，刚上手Python打包踩这种坑太正常了！我当初第一次搞的时候也卡了好久，先给你捋几个最容易出问题的点，大概率能解决你的ModuleNotFoundError：

1. 打包配置没写对（新手第一坑！） #

你是不是在setup.py或者pyproject.toml里漏了声明要包含的模块？举个例子，要是你的card项目结构是：

cards/
├── cards/
│   ├── __init__.py
│   └── card.py  # 你的核心代码文件
└── setup.py

那setup.py里必须明确告诉setuptools要包含这个cards包，比如这么写：

from setuptools import setup, find_packages

setup(
    name="cards",  # 这个是你pip install后要导入的包名
    version="0.1.0",
    packages=find_packages(),  # 自动扫描所有带__init__.py的子包，省得手动写
    # 要是不想用自动查找，也可以手动写packages=["cards"]
)

如果用pyproject.toml作为配置文件，要确保[tool.setuptools.packages]部分配置正确，比如加find = {}让它自动找包，或者手动列names = ["cards"]。

2. 导入路径和包名不匹配 #

比如你打包的包名是cards，结果写代码的时候写成from card import Card了？或者反过来，包名跟目录名对不上？必须严格对应setup里的name参数和实际的目录结构，差一个字母都可能报错。

3. 打包/安装的姿势不对 #

你是先打包成wheel再安装的对吧？打包的时候有没有跑python -m build --wheel？要是打包过程出了警告或错误，生成的wheel本身就有问题，安装肯定会报错。还有，安装时要选dist目录下最新生成的wheel文件，别装成旧版本的了。

另外，要是你之前用pip install -e .装了开发版，最好先跑pip uninstall cards把旧包清干净，再装正式的wheel，避免环境冲突。

4. 搞混了Python环境 #

这个真的超常见！比如你把包装到了全局Python里，但测试的时候用的是虚拟环境里的Python？可以跑pip show cards看看包的安装路径，再跑which python（Linux/macOS）或者where python（Windows）看看当前用的Python路径，对比一下是不是同一个环境。要是不一样，要么把包装到当前环境，要么切换到装了包的环境去测试。

5. 漏了__init__.py（针对Python3.3以下版本） #

要是你用的Python版本比较老（3.3之前），包目录里必须有__init__.py才能被识别成Python包，哪怕是空文件也行。3.3+虽然支持无__init__.py的命名空间包，但新手还是加上更稳妥，省得踩不必要的坑。

要是检查完这些还解决不了问题，你可以把你的项目完整目录结构、打包命令、安装命令，还有报错的完整信息贴出来，我再帮你细抠！

备注：内容来源于stack exchange，提问作者Staros