问题概述与原因分析
当尝试在 python 3.12 环境下使用 pip 或 poetry 安装 numpy 的早期版本（例如 numpy==1.25.1）时，用户可能会遇到 modulenotfounderror: no module named 'distutils' 的错误。这个错误通常在构建阶段发生，尤其是在 poetry 等工具尝试使用 pep 517 构建后端时。
根本原因在于：
- distutils 模块的移除： Python 3.12 版本正式移除了标准库中的 distutils 模块。distutils 曾是 Python 包构建和安装的基础工具。
- NumPy 版本兼容性： numpy 1.25.x 及更早的版本其构建流程（通常通过 setuptools 间接调用）依赖于 distutils。因此，这些版本的 NumPy 仅支持 Python 3.9 到 3.11。当在 Python 3.12 环境中尝试安装时，由于找不到 distutils，构建过程便会失败。
解决方案一：升级 NumPy 版本
最直接且推荐的解决方案是升级 numpy 到兼容 Python 3.12 的版本。numpy 从 1.26.0 版本开始正式支持 Python 3.12，并且其构建过程已不再依赖于 distutils。
如果您没有特定需求必须使用旧版 NumPy，请直接升级。
使用 pip 升级：
立即学习“Python免费学习笔记（深入）”；
pip install "numpy>=1.26.0"
使用 poetry 升级：
在 pyproject.toml 文件中将 numpy 的版本限制更新为 ^1.26.0 或更高，然后运行：
poetry add numpy@^1.26.0 # 或者如果已存在，直接更新 poetry update numpy
解决方案二：降级 Python 版本
如果您的项目或特定库严格依赖于某个旧版 numpy（例如，由于API兼容性问题），并且无法升级 numpy，那么另一种解决方案是降级您的 Python 环境至 numpy 1.25.x 所支持的版本，即 Python 3.9、3.10 或 3.11。
为了灵活管理多个 Python 版本，推荐使用 pyenv。
1. 安装 pyenv
pyenv 允许您在同一系统上轻松安装和切换不同的 Python 版本。
在 macOS 上使用 Homebrew 安装 pyenv：
brew install pyenv
2. 配置 Shell 环境
安装 pyenv 后，需要将其配置到您的 shell 环境中，以便 pyenv 能够拦截 python 命令并管理版本。具体配置方法可能因您使用的 shell (bash, zsh, fish) 而异，请参考 pyenv 的官方文档获取最准确的指令。
常见配置（以 Zsh 为例，添加到 ~/.zshrc 或 ~/.bashrc）：
# 添加到 .zshrc 或 .bashrc 文件末尾 export PYENV_ROOT="$HOME/.pyenv" command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH" eval "$(pyenv init -)" eval "$(pyenv virtualenv-init -)" # 如果使用 pyenv-virtualenv 插件
配置完成后，务必重启您的终端或运行 source ~/.zshrc (或 source ~/.bashrc) 使更改生效。
3. 安装兼容的 Python 版本
选择一个 numpy 1.25.x 兼容的 Python 版本，例如 Python 3.10.0。
pyenv install 3.10.0
4. 切换 Python 版本
您可以为全局环境或特定项目切换 Python 版本。
-
全局切换 (Global): 影响所有 shell 会话和项目。
pyenv global 3.10.0
-
局部切换 (Local): 仅影响当前目录及其子目录下的项目。推荐用于项目开发，以避免影响其他项目。
pyenv local 3.10.0
切换后，可以通过 python --version 或 pyenv version 确认当前激活的 Python 版本。
5. 配置 Poetry 项目环境
如果您正在使用 Poetry，在切换了系统或局部 Python 版本后，还需要确保 Poetry 项目也使用新的 Python 环境。
进入您的项目根目录，并告知 Poetry 使用特定的 Python 版本：
poetry env use 3.10.0
此命令会为您的 Poetry 项目创建一个或激活一个使用 Python 3.10.0 的虚拟环境。之后，您可以正常运行 poetry install 来安装依赖，此时 numpy==1.25.1 将能成功安装。
注意事项
- 虚拟环境： 无论是升级 NumPy 还是降级 Python，始终推荐在独立的虚拟环境（如 Poetry 创建的或 venv）中进行操作，以避免依赖冲突和污染系统环境。
- 依赖链： 在降级 Python 版本时，请确保项目中所有其他依赖项也兼容所选的 Python 版本。
-
Poetry 与 pyenv 配合： 使用 pyenv 切换 Python 版本后，对于 Poetry 项目，务必使用 poetry env use
来同步 Poetry 的虚拟环境设置。
总结
在 Python 3.12 环境下安装旧版 numpy 遇到的 distutils 错误，核心原因在于 Python 3.12 移除了 distutils 模块，而 numpy 1.26.0 之前的版本对其有依赖。解决此问题主要有两种策略：
- 首选方案： 升级 numpy 到 1.26.0 或更高版本，这些版本已兼容 Python 3.12。
- 备选方案： 如果必须使用旧版 numpy，则通过 pyenv 等工具将 Python 环境降级到 3.11 或更早版本。
根据您的项目需求和依赖关系，选择最合适的解决方案，并始终注意维护良好的虚拟环境实践。
