Python发布后烟雾测试清单

Python包发布后必须立即执行一套精简却关键的烟雾测试：在干净虚拟环境中验证模块能否成功导入（尤其关注入口模块和文档示例）、CLI命令是否能直接调用且版本号在pkg_resources与importlib.metadata间保持一致、核心功能在最低支持Python版本下真正可运行，同时排除开发环境变量和架构兼容性（如Apple Silicon）等隐蔽陷阱——这些看似琐碎的检查，恰恰是避免用户“首用即崩”、维护项目口碑的第一道防线。

发布后立刻检查 import 是否失败

模块能装上不等于能导入，尤其当包结构改过、__init__.py 漏删或新增了循环引用时，import 会在运行时才炸。别等用户报错才反应过来。

实操建议：

• 在干净虚拟环境中 pip install 发布的 wheel 或 sdist，然后逐个 import 公共模块（如 from mypkg import core、import mypkg.utils）
• 重点测入口模块和文档里第一个示例用到的模块名，它们最常被用户直接敲
• 如果用了 pyproject.toml 的 [project.optional-dependencies]，记得也装上对应 extra 再试，比如 pip install "mypkg[dev]"
• Windows 用户可能遇到 ModuleNotFoundError: No module named '_ctypes' —— 这不是你代码的问题，是他们没装完整 Python，但你要在 CI 里用 Windows 环境跑一遍 import，早发现早加文档说明

pkg_resources.get_distribution() 和 importlib.metadata.version() 返回值是否一致

很多 CLI 工具靠这个打版本号，用户截图问“为什么 mypkg --version 显示 0.1.0，但 pip show mypkg 是 0.2.0？”——八成是打包时元数据没刷进去。

实操建议：

• 发布前，在安装后的环境中分别运行：python -c "import pkg_resources; print(pkg_resources.get_distribution('mypkg').version)" 和 python -c "from importlib import metadata; print(metadata.version('mypkg'))"
• 确保 setup.py 或 pyproject.toml 中的版本字段和源码里硬编码的 __version__ 同步；如果用了动态版本（如 setuptools-scm），CI 打包时必须有 .git 目录或正确配置 fallback_version
• 如果用 build --wheel 但没清 dist/，旧 wheel 可能被 pip 优先选中——每次发布前手动删掉 dist/ 和 build/

CLI 命令能否在 PATH 中直接执行（不进 Python 解释器）

用户不会输 python -m mypkg.cli，他们就敲 mypkg-do-this。entry_points 配错了，命令就根本找不到。

实操建议：

• 安装后立刻运行 which mypkg-do-this（macOS/Linux）或 where mypkg-do-this（Windows），确认路径指向 site-packages 下的 wrapper 脚本
• 检查 pyproject.toml 中 [project.entry-points."console_scripts"] 的键名是否含非法字符（只允许字母、数字、下划线、连字符），值是否为 module:attr 格式，比如 "mypkg-cmd = mypkg.cli:main"
• 如果 CLI 函数带参数解析（如 argparse），在 smoke 测试里至少跑一次 mypkg-cmd --help，避免因导入失败导致 help 都打不出来
• Windows 上脚本扩展名是 .exe，但内容仍是纯文本；如果用 pyinstaller 打包过，会覆盖标准 entry point 行为——确认你发布的不是那个

关键函数在最低支持 Python 版本下是否真能跑通

写 requires-python = ">=3.8" 不代表 3.8 就稳。类型提示里的 Literal、Self、TypedDict 的关键字参数，3.8 默认不认；pathlib.Path.walk() 是 3.12 才加的——这些地方一跑就 AttributeError 或 SyntaxError。

实操建议：

• CI 必须跑最低版本（如 3.8）+ 最高版本（如 3.12）两套测试环境，不能只靠本地 3.11
• 烟雾测试里挑 2–3 个核心路径：比如初始化客户端、读一个配置文件、吐出一行 JSON——用最简输入触发主干逻辑，不追求覆盖率，只验“不崩”
• 如果用了 typing_extensions，确认 install_requires 里写了对应版本约束，例如 typing-extensions>=4.0.0; python_version
• Mac M1/M2 用户可能用 Rosetta 或原生 Python，arm64 架构下某些 C 扩展（如 cryptography）二进制不兼容——在 Apple Silicon 机器上装一遍，比只信 CI 更可靠

最容易被跳过的其实是环境变量和当前工作目录的影响：烟雾测试得在空目录下跑，且不带 PYTHONPATH、MY_PKG_DEBUG=1 这类开发期变量，否则你以为稳了，用户一开终端就挂。

今天关于《Python发布后烟雾测试清单》的内容就介绍到这里了，是不是学起来一目了然！想要了解更多关于的内容请关注golang学习网公众号！