要测试项目实际构建的 wheel，请创建一个全新的 macOS 虚拟环境，从 dist/ 安装该 wheel 文件，并检查其元数据和导入行为是否正确。在终端中从项目目录运行以下命令。这将测试针对你所使用的 Python 版本和 Mac 架构的安装情况；它并不能确立与所有受支持的 Python 版本或 Mac 的兼容性。

1. 从你的项目构建 wheel

使用你想要测试的 Python 解释器。在 macOS 上，python3 是 Python 3 的常用命令；如果你使用版本管理器，请先选择目标解释器。在包含 pyproject.toml 的目录中，使用 Python Packaging Authority 的 build 工具构建 wheel：Packaging Python Projects 介绍了此构建步骤以及生成的 dist/ 目录。

python3 -m pip install --upgrade build
python3 -m build --wheel

build 命令会在 dist/ 中生成一个 .whl 文件。从项目根目录进行构建可使该工件可用于下方的安装测试。Wheel 是你要测试的已构建分发包；安装项目目录或使用可编辑模式测试的则是不同的安装路径。有关源码树、构建工件和安装之间的区别，请参阅 The Packaging Flow。

2. 创建一个全新的虚拟环境

在项目目录中创建该环境，但要将构建输出与环境分开。如果 .venv-wheel-test 已经存在并且你想进行全新运行，请先将其删除；该命令会永久删除该特定目录及其内容，因此在运行之前请确认路径。

rm -rf .venv-wheel-test
python3 -m venv .venv-wheel-test
source .venv-wheel-test/bin/activate
python -m pip --version

报告的 pip 路径应包含 .venv-wheel-test。Python 的 venv 会基于用于创建它的解释器创建一个隔离的环境，并拥有自己安装的包；macOS 终端的默认 zsh 支持此处显示的 source 激活命令。Python 的 venv 文档 解释了隔离和激活机制。为了避免依赖环境激活或 shell 路径中的 python，可以在其余命令中使用 .venv-wheel-test/bin/python 代替 python。

3. 安装 wheel 文件，而不是源码目录

列出 wheel 文件，以便确定要测试的确切工件：

ls dist/*.whl

从输出中复制所需的文件名并填入以下命令中。保留引号，并将示例文件名替换为实际文件名。所示带连字符的文件名仅用于说明；wheel 名称包含分发包名称、版本和兼容性标签，因此你的文件名会有所不同。

python -m pip install "dist/my_package-1.2.3-py3-none-any.whl"

这会安装本地 wheel，并在需要时从配置的包索引中解析其声明的依赖项。它不会安装你的源码目录。pip 支持直接安装本地分发包归档文件，如 Install packages in a virtual environment using pip and venv 中所述。如果测试必须在没有网络访问的情况下进行，请确保 wheel 的依赖项在本地也可用；否则依赖解析可能会失败。如果使用 --no-deps，pip 会跳过依赖项安装，因此即使 wheel 本身安装正确，需要这些包的导入操作也可能会失败。

4. 检查安装和导入行为

检查已安装分发包的元数据及其声明的依赖项是否一致：

python -m pip show my-package
python -m pip check

在 pip show 中使用 wheel 文件名或项目元数据中显示的分发包名称；它可能与 Python 导入名称不同。然后使用你软件包文档中记录的模块名称测试导入。例如，如果模块是 my_package，请运行：

python -c 'import my_package; print(my_package.__file__)'

如果导入成功且其文件路径指向 .venv-wheel-test 内部，则证明已安装的包是从测试环境中导入的。单凭导入操作并不能测试每个函数或入口点：如果你需要行为覆盖率，请针对此环境运行项目的相关测试。

当 wheel 安装失败时

关于不兼容 wheel 的错误通常意味着其兼容性标签与当前使用的 Python、macOS 或 CPU 架构不匹配。包含编译扩展的 wheel 可能是平台专用的；纯 Python wheel 的适用范围可能更广。平台兼容性标签规范 解释了安装程序如何使用这些标签。为你打算支持的解释器和 Mac 架构构建或获取兼容的 wheel，然后在全新创建的环境中重复测试。

如果安装成功但导入失败，请检查导入名称是否正确，以及项目是否声明了必需的运行时依赖项。如果 wheel 安装成功但缺少某个模块或数据文件，请检查 wheel 内容并在重新构建之前修正项目的打包配置。干净的环境有助于暴露未声明的依赖项和遗漏的打包文件，这些问题在开发人员环境中可能会被已有包或源码文件所掩盖。

成功的安装、依赖项检查和针对性导入可以确认 wheel 在此 Mac 和 Python 版本上的部分有效行为。它们并不能验证其他平台或 Python 版本；请使用匹配的解释器和兼容的 wheel 构建分别测试这些平台或版本。

来源