企业官网建设流程全解析

说实话，我开始认真读pytest源码，并不是因为好奇，而是被两个实际问题逼的。

第一个问题：同事在项目里同时装了pytest-ordering和pytest-randomly，结果排序完全失效，测试用例顺序跟随机数生成器似的，怎么都调不回来。第二个问题：我写了一个插件想在pytest_terminal_summary里追加一份自检报告，但输出内容总被另一个第三方插件提前截断，少了一截。

这俩问题表面上叫"插件冲突"、"插件不生效"，但追到根上，全落在pytest插件系统同一段机制里：插件是被谁发现的、以什么名字注册的、钩子实现按什么顺序执行。换句话说，只要把源码走一遍，这类问题基本都能自己定位，不用再去翻issue和stackoverflow碰运气。

这篇文章不是教你怎么写一个插件demo，而是顺着pytest的启动链路，把插件系统从"发现插件"到"执行钩子"的关键源码拆开讲清楚。读完你至少能回答三个问题：第三方插件为什么装完就能生效？@pytest.hookimpl到底在函数上做了什么？为什么你写的pytest_collection_modifyitems有时候排在别人后面？

1. 插件系统的三条主线：发现、注册、调用

1.1 两个让我抓狂的真实场景，以及它们指向的源码位置

先回来说那两个问题。

pytest-ordering和pytest-randomly同时存在时，pytest-randomly默认会对测试顺序做随机化，而pytest-ordering想通过pytest.mark.run这类标记来固化顺序。问题在于，两个插件都在监听同一个钩子pytest_collection_modifyitems，一个要打乱，一个要排固定序，最后谁生效完全由钩子实现列表里的先后顺序决定。如果不看源码，你根本不知道这个顺序是怎么来的，只能靠试。

第二个问题更典型。我想在pytest_terminal_summary里追加内容，但这个钩子不是一个"先来后到覆盖"的机制，而是所有注册过的实现都会被依次调用，返回值通常没人接。第三方插件如果先执行并且自己做了终端输出，我的追加内容就排到后面，视觉上感觉被截断了。这不是bug，这是插件系统的工作方式。

这两个场景指向的源码位置非常集中：

• 插件发现逻辑在_pytest/config/__init__.py的PytestPluginManager里，配合pluggy的load_setuptools_entrypoints。
• 插件注册的核心在pluggy/manager.py的PluginManager.register。
• 钩子执行顺序在pluggy/hookcaller.py和pluggy/_callers.py里，由_multicall负责逐一调用。

1.2 三层结构：pytest、pluggy、打包系统各管一段

先说一个重要认知：pytest的插件系统并不是pytest自己从零写的，核心是一个叫pluggy的库，pytest官方团队自己维护的hook插件框架。pytest在这个框架之上定义了业务钩子，比如pytest_configure、pytest_runtest_makereport。

所以要理清楚一个插件从安装到生效的完整过程，其实涉及三层：

这三层缺一不可。很多人写插件时只在Python包里定义了一个pytest_configure函数，但没写entry_points，结果手动-p能加载、安装后不生效，就是没搞懂第一层。

理清这条主线之后，剩下的问题就变成三个具体环节：插件从哪来、插件注册时发生了什么、钩子调用时按什么顺序跑。

2. 插件发现链路：Entry Points、命令行参数和conftest的先后次序

2.1 pytest11分组：插件与Python打包体系的连接点

如果你写过第三方pytest插件，肯定在pyproject.toml里见过这么一段：

[project.entry-points."pytest11"] myplugin = "myplugin.plugin"

这个pytest11就是pytest留给插件世界的暗号。Python生态里有一套标准的"入口点"机制，简单说就是：一个包安装后，可以在它的打包元数据里声明"我提供哪些可被外部发现的功能入口"。pytest约定，凡是声明在pytest11分组里的入口，都视为pytest插件。

pluggy源码里对应的下载逻辑在PluginManager.load_setuptools_entrypoints。它做的事情很直接：

def load_setuptools_entrypoints(self, group, name=None): for entry_point in importlib_metadata.entry_points().select(group=group): if name is not None and entry_point.name not in name: continue if self.get_plugin(entry_point.name) is not None: continue self._load_plugin_plugin(entry_point)

_load_plugin_plugin里会调用entry_point.load()，也就是真正import这个插件模块，然后以entry point的name作为插件名去注册。注意，这里说的"name"不是模块名，不是包名，而是myplugin = "myplugin.plugin"里=左边的那个标识符。

这就是为什么你有时候在pytest --trace-config里看到插件名是html而不是pytest_html，因为pytest-html这个包在entry point里注册的name就叫html。

再强调一个细节：load_setuptools_entrypoints在被调用之前，会先检查get_plugin(entry_point.name)是不是已经注册过。如果命令行里已经用-p手动加载了一个同名插件，这里会直接跳过，避免重复注册。

2.2 -p参数、PYTEST_PLUGINS与pytest_plugins的加载时点

除了entry point这种全自动发现方式，pytest还提供了几个手动入口，源头上都集中在PytestPluginManager的consider_*系列方法。

-p参数走的是consider_pluginarg。这个方法的实现不复杂，关键是处理两种前缀：

• -p myplugin：直接调用import_plugin(myplugin)，加载并注册。
• -p no:myplugin：调用set_blocked("myplugin")，把这个名字设为封禁状态，后续任何来源想注册同名插件都会被忽略。

PYTEST_PLUGINS环境变量走的是consider_env，变量里用逗号分隔多个插件名，按顺序逐个import_plugin。这个机制在CI环境里特别有用，你不想改配置文件，但想临时挂一个私有插件，设个环境变量就行。

还有一个容易被忽略的入口：conftest.py里的pytest_plugins变量。它定义在根conftest里时可以指定要加载的外部插件模块，比如：

pytest_plugins = ["myplugin", "pytest_mock"]

需要明确的是，非根目录conftest里直接写pytest_plugins会抛错，这是pytest故意做的限制，目的是避免不同目录下的conftest各自为政，让加载链路变得不可预测。

2.3 加载顺序的源码依据和trace确认

整理一下不同来源的加载顺序，我用一个表格把它固化下来：

这里有个很反直觉的点：conftest里的钩子通常比entry point插件晚注册。因为conftest必须等到rootdir确定之后才能找到并加载，而第三方插件在命令行解析阶段就被注册了。反应到执行顺序上，默认情况下第三方插件的pytest_collection_modifyitems往往排在conftest里同名钩子的前面。

怎么验证？用pytest --trace-config跑一次。这个内置参数会打印所有插件加载的日志，包括每个entry point何时import、每个conftest何时加载。我强烈建议你在怀疑插件顺序时先跑这个命令，很多疑惑会当场解决。

3. PluginManager注册流程：插件身份、名字冲突与旧式约定

3.1 PytestPluginManager在基类之上加了什么

pytest自己的插件管理器长这样（位置在_pytest/config/__init__.py）：

class PytestPluginManager(PluginManager["HookspecMarker"]): def __init__(self) -> None: super().__init__("pytest") self._conftest_plugins = set() ...

它继承了pluggy.PluginManager，构造函数里把项目的标识名设成了"pytest"。这个标识名直接决定了后面hook标记的匹配规则：只有被HookspecMarker("pytest")和HookimplMarker("pytest")标记过的函数，才会被这个管理器识别。

PytestPluginManager在基类之上主要加了conftest相关的缓存、-p参数处理、环境变量处理、entry point批量加载等pytest特意扩展的能力。所以你在阅读源码时，核心的注册、钩子收集逻辑其实都在pluggy里，pytest只是在外面包了一层业务逻辑。

3.2 register方法到底在做什么

很多新手以为"注册插件"就是把模块对象往一个列表里塞。实际上register这个方法做的事比想象中多得多。

pluggy.PluginManager.register(plugin, name=None)的核心逻辑可以拆成四步：

1. 决定插件名。如果没传name，会尝试从模块的__name__推导；如果推导不出来，用变量名。
2. 检查是否被blocked。如果这个插件名已经在封禁名单里，直接返回None，这里对应-p no:的禁用逻辑。
3. 遍历插件模块的dir(plugin)，找出所有被识别为hookimpl的函数。
4. 对每个hookimpl，找到它对应的HookCaller，然后add_impl把实现加进去。

第3步是关键。它用dir()去扫插件模块里所有属性，然后调用parse_hookimpl_opts判断某个函数算不算hookimpl。如果是，就包装成一个HookImpl对象，挂到对应的钩子上。

这带来一个结果：只要一个函数满足识别规则，不管它叫什么名字，都可能被当成hook实现收集。这也解释了为什么插件里随意定义一个普通函数会有风险。

3.3 parse_hookimpl_opts的pytest前缀兼容逻辑

这里有一个很值得说的细节。你在conftest里经常这样写：

def pytest_configure(config): pass

这个函数没有加任何@pytest.hookimpl装饰器，但它确实被当成hook实现收集了。为什么？

因为PytestPluginManager重写了parse_hookimpl_opts。它的逻辑大致是：如果函数名以pytest_开头，并且后面不是大写字母（避免误伤pytest_模块内部的私有方法），就默认当成hookimpl收集；如果名称不满足这个前缀条件，才回退到基类逻辑，去检查函数上有没有被pytest_impl标记。

这意味着pytest向后兼容了老式命名约定：只要你的函数名带pytest_前缀，即使不装饰也能生效。但这是把双刃剑。

我见过有人在一个插件模块里写了个pytest_helper()普通工具函数，结果被当成hookimpl收集，导致每次运行都触发一个参数不匹配的warning。为了避免这种坑，我的建议是：新代码一律显式加@pytest.hookimpl装饰器，不要再依赖前缀约定。

3.4 blocked机制：为什么重复注册会被拦截

前面提到set_blocked，这里展开说一下。

PytestPluginManager在consider_pluginarg里处理-p no:xxx时，会调用pluginmanager.set_blocked("xxx")。之后任何来源尝试注册名为xxx的插件，都直接跳过。

这个机制对调试非常有用。比如你想完全禁用pytest内置的缓存插件，可以这样：

pytest -p no:cacheprovider

有时第三方插件之间互相依赖，A插件依赖B插件，但B插件的入口点名字和另一个包冲突了，用-p no:xxx可以精确地把那个冲突的插件禁掉。注意这里的名字是entry point的name，不是模块名。

4. hookspec与hookimpl：约定之上还有一层显式契约

4.1 HookspecMarker：把规范函数写在明处

pytest在_pytest/hookspec.py里定义了几乎所有的内置钩子规范。这个文件的开头通常是这样：

from pluggy import HookspecMarker hookspec = HookspecMarker("pytest") @hookspec def pytest_addoption(parser, pluginmanager): ...

HookspecMarker("pytest")这个装饰器做的事情，本质上是给被装饰的函数打上一个私有属性，标记它是"属于pytest项目的hook规范"。之后PluginManager.add_hookspecs会读取这些规范函数，逐个生成对应的HookCaller对象。

所以hookspec回答的问题是：pytest世界里存在哪些钩子，每个钩子应该传什么参数。hookimpl实现的函数必须和这些规范兼容，pluggy在注册时会做参数检查，参数对不上会直接抛错。

4.2 HookimplMarker：标记一个可被收集的实现

对应的，HookimplMarker是给插件实现方用的：

from pluggy import HookimplMarker hookimpl = HookimplMarker("pytest") @hookimpl def pytest_configure(config): ...

@hookimpl装饰器实际上也没有魔法，它就是往函数对象上加一个_pytest_impl属性，里面存着tryfirst、trylast、hookwrapper、optionalhook这些选项。

真正收集发生在register时。pluggy通过parse_hookimpl_opts读到函数上的这个属性，如果属性存在，就把这个函数包装成HookImpl并关联到对应名称的HookCaller上。

这里必须提醒一个重要的点：hookimpl对应的函数名必须和hookspec里的规范函数名完全一致。装饰器只会标记"这是个hook实现"，不会帮你自动改名。你写了个@hookimpl def my_own_config(config)，它不会去代替pytest_configure，而是尝试寻找名为my_own_config的hook规范，找不到就新建一个没人调的孤立HookCaller。

4.3 一次HookCaller调用背后发生了什么

当pytest内部执行某个钩子时，比如执行pytest_runtest_makereport，它本质上是在调用一个HookCaller对象。

这个对象持有一个实现列表，调用时的核心逻辑在_multicall函数里。大致流程是：

1. 把普通实现和wrapper实现分开。
2. 按排序后的顺序依次调用普通实现。
3. wrapper实现包裹在外层，通过yield控制前后时机。
4. 如果有firstresult=True的规范，第一个返回非None结果的实现会提前终止后续调用。

值得一提的是，普通hook实现的返回值默认没人接收。pytest_configure返回什么，pytest通常不关心；pytest_runtest_makereport的返回结果会被收集是因为这个钩子本身被定义为firstresult=True并有特殊处理。这个约定很反直觉，很多人以为可以在pytest_configure里return一个值传到下一个钩子，实际上不行。想要跨钩子传状态，正确做法是挂到config对象或者自定义的类实例上。

4.4 optionalhook：声明"没有配置也不会炸"

插件开发里还有一个容易被忽视的参数：@pytest.hookimpl(optionalhook=True)。

它的含义是：这个hook实现是可选性的，即使对应的hookspec在pytest当前版本里不存在，也不要报错。

为什么需要它？因为pytest版本迭代会增删钩子。你的插件可能想在旧版pytest上也跑，但你用了新版才有的钩子名。如果不加optionalhook=True，pluggy在注册时会因为找不到对应hookspec，直接抛ValueError。

加了它之后，注册阶段就不会因为找不到规范而崩溃。这个参数我在做跨版本兼容的插件时几乎必用。

5. 钩子执行顺序：tryfirst、trylast、wrapper与覆盖内置钩子

5.1 排序器如何处理注册顺序和特殊标记

前面说过，多插件监听同一个钩子时，执行顺序非常重要。那pluggy到底怎么排序？源码里有个专门的函数处理这件事，它遵循几条主规则：

• 带tryfirst=True的实现排在普通实现前面。
• 带trylast=True的实现排在普通实现后面。
• 同一档内，按注册顺序排列。
• wrapper实现整体排在普通实现之后，因为wrapper要包裹整段调用链。

所以默认情况下，注册越早，钩子执行越靠前。这个"注册顺序"就是第三节里说的加载顺序决定的：内置插件最早，-p和PYTEST_PLUGINS次之，pytest11entry point再往后，conftest最后。

这意味着：如果你在conftest里写了个pytest_collection_modifyitems，有个第三方插件也写了同名实现，那么默认第三方插件先生效，你的后执行。如果你想强制自己的实现排在第三方前面，可以在装饰器里加tryfirst=True；如果只是想尽量最后一个收尾处理，用trylast=True。

5.2 覆盖内置钩子不生效是最常见误区

回到文章开头那个场景。很多人想"覆盖"pytest内置钩子，于是在自己的插件里写了同名实现，并且期待它取代内置实现。但hook系统不是覆盖关系，它是追加关系。内置插件注册得更早，你的实现注册得更晚，所以内置实现总会先执行。

比如你想完全接管pytest_runtest_call，自己决定用例怎么跑。如果你只是写一个同名实现，内置实现会先执行，你的再执行，等于跑了两遍。此时正确思路是：

1. 用-p no:xxx禁掉某个内置插件，或
2. 把内置插件的实现逻辑在你的实现里主动绕开，或
3. 用hookwrapper包一层，在yield之前拦截，在yield之后收尾。

大多数情况下，hookwrapper是更优雅的方案。

5.3 wrapper：在钩子前后同时插入动作

hookwrapper=True是一个特殊模式。普通hook实现只在这个钩子被调用时执行一次，而wrapper可以同时拿到"调用前"和"调用后"两个时机：

@hookimpl(hookwrapper=True) def pytest_runtest_makereport(item, call): outcome = yield # 这里能拿到完整的调用结果 report = outcome.get_result() ...

yield之前的代码在所有普通实现之前执行；yield之后的代码在所有普通实现完成之后执行。outcome对象可以拿到内部实现的结果，也可以对结果做修改。

这个机制非常像是给整段调用链套了一层"洋葱皮"。有个很实用的场景：你想在所有用例执行完后统计信息，不是等pytest_terminal_summary，而是在pytest_runtest_protocol外面包一层wrapper，统计每个用例的进出时间。我用过不止一次。

5.4 firstresult：谁先返回非None谁说了算

还有一类特殊钩子，定义时带有firstresult=True，含义是：一旦某个实现返回了非None结果，就停止调用后续实现，把这个结果作为整个钩子的返回值。

典型例子是pytest_assertrepr_compare，用于自定义断言失败的详细输出。多个插件都注册了这个实现，但谁先返回一个非None的字符串，谁就决定了失败信息长什么样。这类钩子的执行顺序同样重要，一旦遇到多个插件都想抢这个输出，就得靠tryfirst/trylast和注册顺序来调节。

写插件时需要主动区分：你要处理的钩子到底是"广播型"还是"firstresult型"。广播型只需要关心执行时机，firstresult型还需要关心优先级。

6. 动手写一个插件，并全程跟踪它的加载链路

6.1 最简插件骨架与entry_points配置

把前面的源码知识合起来，落地写一个最小的插件。目录假设是这样：

myplugin/ ├── pyproject.toml └── src/ └── myplugin/ └── plugin.py

pyproject.toml里声明pytest11入口：

[build-system] requires = ["setuptools>=61"] build-backend = "setuptools.build_meta" [project] name = "myplugin" version = "0.1.0" [project.entry-points."pytest11"] myplugin = "myplugin.plugin"

插件本体：

from pluggy import HookimplMarker hookimpl = HookimplMarker("pytest") @hookimpl(tryfirst=True) def pytest_configure(config): print("myplugin configure with tryfirst")

这里不用pytest_前缀的自动识别，而是显式声明@hookimpl(tryfirst=True)，保证这个函数即使改名也能被准确收集。

6.2 用pytest --trace-config观察加载过程

装上插件后，执行：

pytest --trace-config

输出里你能看到类似这样的内容：

PLUGIN registered: <module 'myplugin.plugin' from '...'>

这个输出说明entry point已经被找到、导入并注册成功。如果没看到，说明你的entry_points分组写错了，或者插件没安装到当前Python环境。

继续在插件里加一点临时日志，也可以用print观察注册顺序。我经常在写插件时先加一个pytest_configure，里面打印当前已经注册了哪些插件：

@hookimpl def pytest_configure(config): print(config.pluginmanager.list_name_plugin())

list_name_plugin()会返回一份插件名到插件对象的映射。通过它，你可以直观看到自己的插件排在什么位置，其他插件是什么名字，从而推断钩子执行顺序。

6.3 三个常见问题与排查思路

第一个问题是-p能加载但entry point不生效。排查顺序是：先用pip list确认包已安装；然后看pyproject.toml里入口分组是不是pytest11；再用importlib.metadata.entry_points().select(group="pytest11")在Python交互环境里确认入口存在。这基本能覆盖90%的"装了但不生效"。

第二个问题是插件里定义了pytest_开头的普通函数，导致注册警告。定位方法就是在--trace-config日志里搜hookimpl相关的warning。防止再犯，统一给所有hook实现加@hookimpl，普通工具函数改名不要带pytest_前缀。

第三个问题是多个插件同名导致后注册的被跳过。这种情况往往发生在两个包都声明了相同的entry point name。处理方式是用-p no:后注册的那个禁用其中一个，或者把entry point name改成不冲突的标识。查这个问题的关键命令还是list_name_plugin()，一眼就能看出哪个插件名被占用了。

最后再分享一点个人体会

代码读到这里，我最大的感受是：pytest插件系统并不神秘，它就是一个"事件总线"加"注册表"。事件总线是pluggy的hook机制，注册表是PluginManager的插件名到插件对象的映射。搞懂了入口点加载、注册扫描、排序调用这三个环节，大多数插件相关的怪问题都能自己推断出原因。

我后来处理那两个老问题的方式也简单了：pytest-ordering和pytest-randomly同时存在时，不再试图改代码，而是直接确认加载顺序，并在自己的conftest里给排序钩子加tryfirst来兜底；第二个输出被截断的问题，改成在pytest_terminal_summary里用hookwrapper包一层，确保收尾内容一定最后输出。两个问题都没改第三方插件，只改了我自己的加载方式和装饰器参数。

如果你刚开始读这部分源码，我建议从pluggy/manager.py的register方法和pluggy/hookcaller.py的_multicall看起，这两个函数看明白了，其他都是细节。把pytest当黑盒用十年，不如花一个下午把它插件系统的核心路径读一遍，值。