OctoPrint 插件控制属性（Control Properties）完全指南：从元数据声明到加载生命周期

• 物联网
• 后端

本篇技术指南聚焦 OctoPrint 插件系统的核心契约——控制属性（Control Properties），即定义在插件包顶层模块中的一组__plugin_*__特殊属性。它们决定了插件如何向 OctoPrint 的插件子系统宣告自身的名称、版本、Python 兼容性、钩子（hooks）、实现（implementation）以及加载/卸载/启用/禁用等生命周期行为。阅读完本文，你将掌握全部控制属性的语义、默认值与回退规则，理解插件子系统的 AST 元数据解析与PluginInfo装配机制，并能够依据仓库中的真实示例编写出规范、可发布的 OctoPrint 插件。

控制属性是什么：插件与子系统之间的元数据契约

如 docs/plugins/gettingstarted.rst 所述，插件本质上是携带特定元数据的 Python 包。这些元数据以模块级属性的形式定义在插件包最顶层的包文件（通常是__init__.py）中，OctoPrint 的插件子系统在发现、校验、加载、启用与禁用插件的各个阶段都会读取它们。

一个最简插件骨架如下：

import octoprint.plugin # ... __plugin_name__ = "My Plugin" __plugin_pythoncompat__ = ">=2.7,<4" def __plugin_load__(): # whatever you need to do to load your plugin, if anything at all pass

这些__plugin_*__属性就是控制属性。它们不要求定义顺序，也几乎全部可选——插件子系统为每一个属性都提供了默认值或回退逻辑（详见后文源码分析）。

元数据类属性：声明插件的身份信息

以下几组属性用于描述插件本身，全部可选，且在setup.py中已有对应值时可以被覆盖：

以名称为例，PluginInfo.name的解析顺序是：模块属性__plugin_name__→ 构造时传入的name（来自setup.py）→ 插件标识符key。对应的实现见 src/octoprint/plugin/core.py：

return self._get_instance_attribute( ControlProperties.attr_name, defaults=(self._name, self.key), incl_metadata=True, )

其中ControlProperties类（src/octoprint/plugin/core.py#L179-L252）集中定义了所有受识别属性名的常量，例如attr_name = "__plugin_name__"、attr_version = "__plugin_version__"等，all()类方法会收集所有attr_*常量供子系统遍历。

__plugin_pythoncompat__：Python 兼容性声明与加载门槛

__plugin_pythoncompat__声明插件的 Python 版本兼容范围，默认值为>=2.7,<3（即只兼容 Python 2、不兼容 Python 3）。这是针对存量 Python 2 插件的一项预防性设计：OctoPrint 根本不会尝试加载 Python 兼容性信息与当前运行环境不匹配的插件，从而避免导入阶段就崩溃。

源码中的默认值有两处体现：ControlProperties.default_pythoncompat = ">=2.7,<3"（src/octoprint/plugin/core.py#L248），以及pythoncompat属性读取时的默认参数default=">=2.7,<3"（src/octoprint/plugin/core.py#L660-L671）。

对于只兼容受支持 Python 3 版本的新插件，应显式声明：

__plugin_pythoncompat__ = ">=3.10,<4"

两点补充事实：

• 内置（bundled）插件会被自动视为兼容，无需声明该属性（见 src/octoprint/plugin/core.py 的 docstring）。
• 仓库中的示例插件普遍使用">=2.7,<4"以同时覆盖 Python 2 与 Python 3 环境，例如 docs/plugins/examples/add_tornado_route.py。

生命周期类属性：__plugin_check__/__plugin_load__/__plugin_unload__

这三个属性是可调用对象（函数或方法），对应插件被子系统处理的不同阶段：

__plugin_check__— 插件被发现时调用，返回True表示可以稍后实例化，False表示存在阻碍（例如依赖缺失）。典型用法：

def __plugin_check__(): # Make sure we only run our plugin if some_dependency is available try: import some_dependency except ImportError: return False return True

从源码看，PluginInfo.check属性在未设置时回退为一个恒返回True的 lambda：default=lambda: True（src/octoprint/plugin/core.py#L720-L732）。

__plugin_load__— 插件加载时调用，常用来实例化插件实现并挂接钩子。文档给出的标准模式是先global声明再赋值，因为加载阶段模块级变量通常还是空的：

def __plugin_load__(): global __plugin_implementation__ __plugin_implementation__ = MyPlugin() global __plugin_hooks__ __plugin_hooks__ = { "octoprint.plugin.softwareupdate.check_config": __plugin_implementation__.get_update_information }

__plugin_unload__— 插件卸载时调用，用于执行清理工作。未设置时同样回退为空操作 lambda（src/octoprint/plugin/core.py#L747-L758）。

启用与禁用：__plugin_enable__/__plugin_disable__

__plugin_enable__在插件被启用时调用，__plugin_disable__在插件被禁用时调用。它们与基类Plugin上的on_plugin_enabled()/on_plugin_disabled()钩子一一对应（见 src/octoprint/plugin/core.py#L2443-L2453），可用来响应启用/禁用事件（例如启动或停止后台线程）。

功能类属性：__plugin_implementation__与__plugin_hooks__

这是插件"真正干活"的两个入口：

__plugin_implementation__— 一个实现了插件 Mixin（如SettingsPlugin、BlueprintPlugin、SimpleApiPlugin等）的实例对象：

__plugin_implementation__ = MyPlugin()

__plugin_hooks__— 一个字典，键为插件钩子名称，值为对应处理函数。例如监听发往打印机的 G 代码：

def handle_gcode_sent(comm_instance, phase, cmd, cmd_type, gcode, *args, **kwargs): if gcode in ("M106", "M107"): import logging logging.getLogger(__name__).info("We just sent a fan command to the printer!") __plugin_hooks__ = { "octoprint.comm.protocol.gcode.sent": handle_gcode_sent }

PluginInfo.hooks属性在未设置时回退为空字典default={}，implementation回退为None（src/octoprint/plugin/core.py#L685-L707）。

仓库示例中可以找到大量对应组合，例如 docs/plugins/examples/comm_error_handler_test.py 只声明了__plugin_hooks__一个钩子；docs/plugins/examples/custom_atcommand.py 挂接octoprint.comm.protocol.atcommand.queuing；而 docs/plugins/examples/add_tornado_route.py 则在__plugin_load__中同时装配实现与钩子。

__plugin_settings_overlay__：覆盖应用的默认设置

__plugin_settings_overlay__是一个可选的dict，为 OctoPrint及其插件的默认设置提供叠加层（overlay），仅在config.yaml中不存在对应配置时生效——config.yaml拥有最终决定权，通过 overlay 无法覆盖其中已有的内容。文档建议作者谨慎使用，它适用于创建核心应用定制化场景，例如修改标准命名、UI 排序或 API 端点：

__plugin_settings_overlay__ = dict(api=dict(enabled=False), server=dict(host="127.0.0.1", port=5001))

其底层处理逻辑位于 src/octoprint/init.py#L841-L904，关键行为包括：

• 插件加载时（handle_plugin_loaded），若模块存在__plugin_settings_overlay__，插件会被标记为needs_restart = True，overlay 通过settings.load_overlay()加载；
• overlay 定义支持(dict, order)元组/列表形式以指定应用顺序；
• 支持特殊的"plugins": {"_disabled": [...]}键，用于声明应被禁用的其他插件；
• 在插件启用时（handle_plugin_enabled）通过settings.add_overlay()真正注入。

源码深处的机制：AST 解析、回退链与"看起来像插件"

理解控制属性的读取机制，能帮你规避许多隐蔽的坑。核心事实如下：

1. 元数据通过 AST 静态解析，而非导入模块。src/octoprint/plugin/core.py#L75-L176 的parse_plugin_metadata()使用 Python 标准库ast解析插件源文件的语法树，仅提取__plugin_name__、__plugin_version__、__plugin_author__、__plugin_description__、__plugin_url__、__plugin_license__、__plugin_pythoncompat__、__plugin_hidden__等字面量值。这意味着：这些元数据必须是可静态求值的常量（或gettext(...)调用），且解析过程不会执行插件代码，因此即使插件本身有语法问题，子系统仍能先读出其元数据。

2. 回退链由PluginInfo._get_instance_attribute统一实现。见 src/octoprint/plugin/core.py#L786-L802：优先级为 模块实例属性 → AST 解析出的元数据（incl_metadata=True时）→ 构造时传入的默认值 → 兜底默认值。

3. "看起来像插件"是硬门槛。parse_plugin_metadata()会扫描模块中是否出现任何控制属性名（赋值或函数定义），并设置has_control_properties标志；PluginInfo.looks_like_plugin属性直接返回该标志（src/octoprint/plugin/core.py#L813-L818），并被validate(phase="before_import")作为插件是否进入加载流程的判定条件之一。

源码中还承认的附加控制属性

除文档主表外，ControlProperties类还定义了三个附加属性（src/octoprint/plugin/core.py#L186-L231），可作为补充：

• __plugin_hidden__：布尔值，仅对内置（bundled）插件生效，用于将其从插件管理器中隐藏；
• __plugin_helpers__：插件向其他插件暴露的辅助函数字典（PluginInfo.helpers默认回退{}）；
• __plugin_disabling_discouraged__：仅对内置插件生效，提供不建议禁用该插件的理由字符串。

完整实战骨架：把控制属性串起来

综合以上全部属性，一个规范的现代插件包文件（参照 docs/plugins/examples/helloworld/octoprint_helloworld/init.py 的布局）应当看起来像这样：

import octoprint.plugin __plugin_name__ = "My Plugin" __plugin_version__ = "1.0.0" __plugin_description__ = "A short description of what this plugin does" __plugin_author__ = "Your Name" __plugin_url__ = "https://example.com/my-plugin" __plugin_license__ = "AGPLv3" __plugin_pythoncompat__ = ">=3.10,<4" def __plugin_check__(): # optional: verify dependencies before loading return True def __plugin_load__(): global __plugin_implementation__ global __plugin_hooks__ __plugin_implementation__ = MyPlugin() __plugin_hooks__ = { "octoprint.comm.protocol.gcode.sent": __plugin_implementation__.on_gcode_sent, } def __plugin_unload__(): # optional: cleanup pass

总结

OctoPrint 的控制属性是一套轻量而严谨的模块级契约：元数据类属性负责身份宣告并遵循"模块属性 > setup.py > 标识符"的回退链，兼容性属性充当加载前的安全闸门，生命周期函数贯穿检查、加载、卸载、启用、禁用五个阶段，__plugin_implementation__与__plugin_hooks__承载实际功能，而__plugin_settings_overlay__提供默认配置的定制通道。理解它们的读取机制（AST 静态解析、ControlProperties常量表、PluginInfo统一装配）后，你便能写出元数据规范、兼容性声明正确、可被插件管理器正确识别与管理的插件。更多系统化说明可继续参阅 docs/plugins/gettingstarted.rst、docs/plugins/mixins.rst 与 docs/plugins/hooks.rst。

• 物联网
• 后端