python 3.12 中 distutils 已被彻底移除，必须将 from distutils.core import setup 替换为 from setuptools import setup，并升级 setuptools ≥65.5.0，禁用废弃参数，继承类改为 setuptools 路径，ci 改用 pip wheel。
distutils 在 Python 3.12 中已被彻底移除，不是“找不到”，而是根本不存在——标准库源码里删干净了。你无法通过 pip install distutils 恢复它，PyPI 上那个同名包是空壳，装了也没用。
setup.py 还在用 from distutils.core import setup？立刻改掉
这种写法在 Python 3.12 下直接报 ModuleNotFoundError: No module named 'distutils'。
setuptools.setup 是唯一兼容且受支持的替代入口：
- 把所有
from distutils.core import setup替换为from setuptools import setup - 如果用了
find_packages()、find_namespace_packages()，它们现在只属于setuptools，不来自distutils - 不要保留
use_2to3=True或convert_2to3_doctests等已废弃参数，setuptools >= 65.5.0 会忽略并警告
旧：
from distutils.core import setup<br>setup(name='foo', ...)新：
from setuptools import setup<br>setup(name='foo', ...)
自定义构建命令（如 build_ext）继承链必须指向 setuptools
如果你写了类似 cmdclass={'build_ext': MyBuildExt}，而 MyBuildExt 继承自 distutils.command.build_ext.build_ext，运行时会失败——类路径已失效。
- 改为继承
setuptools.command.build_ext.build_ext - 若项目还依赖
numpy.distutils（比如旧版 NumPy 扩展），注意：该模块早在 NumPy 1.24 就被标记为 deprecated，Python 3.12 下必然崩溃；必须升级 NumPy 并迁移到setuptools+pybind11或meson -
build_py、sdist、install等命令同理，全部从setuptools.command下导入
CI/CD 流水线里还在跑 python setup.py bdist_wheel？换成 pip wheel
python setup.py bdist_wheel 会隐式触发 distutils 路径，即使你改了 setup.py，某些底层调用仍可能 fallback 到已删除模块。
- 改用
pip wheel --no-deps --wheel-dir ./dist .，这是 PEP 517 兼容的标准方式 - 确保 CI 环境中安装的是
setuptools >= 65.5.0（低于此版本对 Python 3.12 的build_ext支持不完整） - 虚拟环境创建后，第一时间运行
pip install --upgrade setuptools，别依赖 venv 默认附带的旧版
PyCharm 报红 distutils 找不到？不是解释器问题，是缓存没刷
IDE 显示红色波浪线、提示 unresolved reference，并不代表代码真会运行失败。
- 这是 PyCharm 基于当前解释器环境做的静态分析，但它可能还缓存着旧 Python 版本的 stubs
- 解决方法只有两个：
File → Reload project from Disk，或手动删掉.idea/caches目录后重启 - 不要试图在项目里加
try/except ImportError去“兼容”distutils——它不在了，伪装没意义
最常被忽略的一点：有些项目把 setup.py 当脚本直接执行（比如 python setup.py build），这在 Python 3.12 下已不可行。所有构建动作都应通过 pip 或 build 工具驱动，而不是直调 setup.py。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
