entry_points 是 setuptools 提供的声明式插件注册机制，核心价值在于解耦：主程序不硬编码插件路径，插件也不需主动注册；它在安装时写入 entry_points.txt，运行时由 importlib.metadata（3.8+）或 pkg_resources 读取，仅适用于已安装的包。
entry_points 是什么，为什么不用 importlib？
它不是 Python 的语法特性，而是 setuptools 提供的声明式插件注册机制，核心价值在于「解耦」：主程序不硬编码插件路径，插件也不需要主动向主程序注册。相比 importlib.util.spec_from_file_location 手动加载，entry_points 让插件发现完全交给包管理器——只要插件已安装（pip install myplugin），主程序就能自动识别。
常见错误是把 entry_points 当成运行时动态导入工具，其实它只在安装阶段写入 dist-info/entry_points.txt，后续靠 importlib.metadata.entry_points（Python 3.8+）或 pkg_resources（旧版）读取。别试图用它绕过 sys.path 或加载未安装的本地模块。
如何定义和安装一个 entry_points 插件？
插件作者只需在自己项目的 setup.py 或 pyproject.toml 中声明入口点组（group）和名称（name）。例如，主程序约定使用 myapp.plugins 组：
#[pyproject.toml] [project.entry-points."myapp.plugins"] json_formatter = "myplugin.formatter:JsonFormatter" csv_exporter = "myplugin.export:CsvExporter"
安装后，该插件就对所有能访问此 Python 环境的程序可见。关键点：
立即学习“Python免费学习笔记（深入）”；
- 组名（
"myapp.plugins"）必须与主程序调用时指定的完全一致，大小写敏感 - 值格式为
"module:object"，冒号前是可导入的模块路径，冒号后是模块内可调用对象（类、函数等） - 不要在插件包里写任何“向主程序注册”的代码——这是反模式
- 本地开发调试时，用
pip install -e .安装，否则entry_points不生效
主程序如何安全获取并使用插件？
主程序用 importlib.metadata.entry_points 获取匹配的插件，但注意 Python 版本差异和异常边界：
from importlib import metadata
try:
plugins = metadata.entry_points(group="myapp.plugins")
except (TypeError, ValueError) as e:
# Python <3.10 传 group 参数会报 TypeError；3.10+ group 是必需参数
plugins = metadata.entry_points().select(group="myapp.plugins") # 3.10+
<p>for ep in plugins:
try:
plugin_cls = ep.load() # 可能抛 ImportError 或 AttributeError
instance = plugin_cls()</p><h1>使用 instance...</h1><pre class='brush:python;toolbar:false;'>except (ImportError, AttributeError) as e:
print(f"跳过损坏插件 {ep.name}: {e}")</pre>务必包裹 ep.load()，因为插件模块可能依赖未安装的包，或导出的对象名拼写错误。别假设所有插件都可用——生产环境里插件版本不兼容很常见。
常见陷阱：命名冲突、缓存、跨环境失效
entry_points 查找依赖当前 Python 解释器的 site-packages 和已安装分发包（distributions）。这意味着：
- 同一插件名被多个包注册时，
entry_points返回全部，顺序不确定——主程序需自行去重或按优先级筛选 - 修改
pyproject.toml后没重新pip install -e .，改动不会反映到entry_points - 在虚拟环境外运行脚本，却期望加载虚拟环境里安装的插件？不可能，
entry_points只看当前解释器的包列表 - CI/CD 构建镜像时，如果插件是通过
git+https安装的，某些旧版 pip 可能不写入entry_points.txt，建议固定 pip ≥21.3
最易被忽略的是：插件本身不能依赖主程序的私有模块路径，否则 ep.load() 会因导入失败静默跳过——得靠日志或调试器确认是否真加载成功。
