pytest插件必须在pyproject.toml中正确定义[project.entry-points."pytest11"]，键名只能是"pytest11"，格式为插件名="包路径:对象"，否则无法被自动发现和加载。
插件没被 pytest 自动发现？检查 pyproject.toml 的 [project.entry-points."pytest11"]
pytest 插件必须通过 entry-points 声明，否则 pytest --help 看不见你的插件，pytest 运行时也加载不了。常见错误是写成 "pytest" 或 "pytest.plugins" —— 正确键名只能是 "pytest11"（这是 pytest 硬编码的字符串）。
实操建议：
- 确保
pyproject.toml中有且仅有一处[project.entry-points."pytest11"]段落 - 值必须是
插件名 = "包路径:对象"格式，例如：myplugin = "myplugin.plugin:pytest_configure" - 插件模块（如
myplugin/plugin.py）里导出的函数名不重要，但必须是可调用对象（函数或类），且不能报错导入 - 本地验证：安装后运行
pytest --trace-config，在输出里搜你的插件名，确认它出现在 “active plugins” 列表中
打包后 pip install 报 ModuleNotFoundError？核对 packages 和 package-dir
默认情况下，build 工具（如 build 或 setuptools）不会自动发现子目录里的 Python 包，尤其当你的插件代码不在顶层目录时（比如放在 src/myplugin/ 下）。这时 pip install . 会装空包，导致运行时报 ModuleNotFoundError: No module named 'myplugin'。
实操建议：
- 如果用
src目录结构，必须在pyproject.toml中加[project.options.packages.find]并设where = ["src"] - 或者显式声明
packages = ["myplugin"]，并确保该目录下有__init__.py - 运行
python -m build后，解压生成的.tar.gz文件，检查里面是否真包含你的 Python 模块文件 - 避免混用
setup.py和pyproject.toml—— 现代打包只认后者，setup.py会被忽略
上传到 PyPI 失败：403 Client Error？检查 API token 权限和仓库地址
twine upload 报 403，大概率不是密码错，而是 token 权限不足或发到了错误仓库。PyPI 不再接受用户名密码上传，必须用 API token，且该 token 必须有对应项目（或 org）的上传权限。
librosa 是一个用于音频和音乐分析的 Python 库。它提供了特征提取、频谱分析、节拍跟踪、起始检测和音频可视化的工具，基于 NumPy 和 SciPy 构建，用于科学音频计算。
实操建议：
- 去 https://www.php.cn/link/0e1ceaca3e404ed57c3d9d6eaa2928a3 创建 token，Scope 选 “Entire account” 或精确到你的项目名
- 上传命令必须指定
--repository-url https://upload.pypi.org/legacy/（别用 test.pypi.org 除非你真想传测试库） - token 要以
pypi-开头，使用时前面不加api_token:等前缀，直接当密码用：twine upload --username __token__ --password $TWINE_PASSWORD dist/* - 上传前先
twine check dist/*，能提前发现long_description格式错误等导致 400 的问题
用户装了插件却没生效？提醒他们别漏掉 pytest_plugins 或 conftest.py
插件发布后，用户仍可能遇到“功能没触发”的情况——这不是你打包错了，而是他们没按 pytest 规则启用。pytest 插件分两类：自动发现型（靠 entry-point）和手动导入型（靠 pytest_plugins 变量）。前者只要安装即生效；后者需要用户主动声明。
实操建议：
- 如果你的插件依赖
conftest.py里的逻辑（比如 fixture 注册），务必在文档里强调：“需在项目根目录或测试目录下放置conftest.py，内容为pytest_plugins = ["myplugin"]” - 避免在插件内部做条件导入（如
if os.getenv("CI")就跳过注册），这会让行为不可预测 - 提供一个最小可复现示例：新建空目录 →
pip install myplugin→ 放一个带@pytest.mark.myfeature的测试 →pytest -v应看到标记被识别
最常被忽略的一点：插件的 __version__ 必须和 pyproject.toml 里的 version 严格一致，否则用户升级后可能因缓存或 import 顺序问题，加载到旧版本的模块。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
