物联网后端【免费下载链接】OctoPrintOctoPrint is the snappy web interface for your 3D printer!项目地址https://gitcode.com/gh_mirrors/oc/OctoPrint点击查看免费下载本篇技术指南以 OctoPrint 官方插件分发文档为主体系统讲解插件的两种分发途径——手动文件分发与可 pip 安装的正式包——并延伸到官方插件仓库注册、版本发布管理以及基于 release channel 的预发布渠道配置。读完本文你将掌握各平台插件文件夹的准确位置、pyproject.toml中octoprint.plugin入口点的标准写法、插件被 OctoPrint 自动发现的底层机制以及如何借助 Software Update 插件为 beta 用户提供稳定的多发布渠道。分发途径总览两条路线怎么选OctoPrint 的插件分发共有两种方式二者在发现机制、依赖管理能力和适用场景上有明显差异分发方式用户安装动作插件形态依赖管理推荐度手动文件分发复制文件到插件文件夹单个.py模块或包目录无仅限最简单的插件pip 正式包pip installPython 包 entry point完整支持官方强烈推荐从源码角度可以更清楚地看到两条路径的区别。OctoPrint 初始化插件管理器时会同时扫描两类来源插件管理器初始化代码 中定义了plugin_folders内置插件目录 用户插件文件夹与plugin_entry_points [octoprint.plugin]随后在 插件系统核心实现 中分别调用_find_plugins_from_folders与_find_plugins_from_entry_points完成加载。也就是说两条分发路线最终都汇入同一个插件管理器只是发现插件的来源不同。方式一手动文件分发手动分发是最直接的方案让用户把插件文件复制到 OctoPrint 的插件文件夹中。该文件夹在三大平台上的默认位置为Linux~/.octoprint/pluginsWindows%APPDATA%\OctoPrint\pluginsMac~/Library/Application Support/OctoPrint在此方式下插件以两种形态被直接分发单个 Python 模块一个.py文件文件名与插件标识一致包含插件全部代码包package一个与插件同名的文件夹内部包含__init__.py。从实现层面看_find_plugins_from_folders对插件文件夹中的每个条目进行判定目录必须含__init__.py才会被当作插件包文件则仅接受扩展名为.py、且不以__开头的条目__init__.py本身会被忽略。扫描成功后单文件插件获得FolderOrigin包插件获得ModuleOrigin来源标记。值得注意的是插件是否可管理即可被插件管理器卸载取决于文件夹是否可写——只读目录或内置插件目录会被标记为不可管理。手动分发的局限性在于插件无法声明依赖用户必须自行安装所需的第三方库且版本升级完全依赖人工复制覆盖。因此官方建议只对最基础的插件使用这种方式。方式二可 pip 安装的正式包推荐对于大多数插件官方推荐打包为可通过pip安装的标准 Python 包并在pyproject.toml中注册octoprint.plugin入口点entry point。这样 OctoPrint 在初始化插件子系统时就能自动发现插件[project.entry-points.octoprint.plugin] your_plugins_identifier your_plugins_package_name其中键your_plugins_identifier是插件标识符值your_plugins_package_name是要导入的包名。参考实例仓库自带的 Hello World 插件当前仓库在 docs/plugins/examples/helloworld 目录下完整保存了一个可参考的标准插件包结构可作为打包目录范本octoprint_helloworld/ static/ css/helloworld.css js/helloworld.js less/helloworld.less templates/ helloworld_navbar.jinja2 helloworld_settings.jinja2 __init__.py MANIFEST.in Taskfile.yml babel.cfg pyproject.toml setup.py其 pyproject.toml 给出了一个完整可用的打包配置[build-system] requires [setuptools68, wheel] build-backend setuptools.build_meta [project] name OctoPrint-Helloworld version 1.0.0 description A quick \Hello World\ example plugin for OctoPrint requires-python 3.7,4 dependencies [] [tool.setuptools] include-package-data true [tool.setuptools.packages.find] include [ octoprint_helloworld, octoprint_helloworld.*, ] [project.entry-points.octoprint.plugin] helloworld octoprint_helloworld [project.urls] Homepage https://github.com/yourGithubName/OctoPrint-Helloworld配套的 setup.py 仅保留向后兼容的许可证声明针对 setuptools 77MANIFEST.in用于保证非 Python 资源文件模板、静态资源被包含进发行包。插件本体 octoprint_helloworld/init.py 则通过__plugin_name__、__plugin_pythoncompat__、__plugin_implementation__等控制属性向 OctoPrint 声明自身。自动发现的底层原理入口点机制在 PluginManager._find_plugins_from_entry_points 中实现插件管理器遍历importlib.metadata.distributions()返回的所有已安装发行版筛选出group octoprint.plugin的入口点进而读取发行版的Name、Version、Summary、Author、License-Expression、Home-page/Project-URL等核心元数据用于构建PluginInfo最后导入入口点指向的模块并实例化插件实现。这也解释了为什么打包后无需任何额外注册步骤只要插件被安装进了 OctoPrint 所在的 Python 环境中其元数据就会在启动时被自动读取。OctoPrint 本身也会从pyproject.toml读取插件名称、版本与描述因此插件代码中的__plugin_name__、__plugin_version__、__plugin_description__可以省略仅保留__plugin_implementation__与__plugin_pythoncompat__即可如需更友好的显示名称可再用__plugin_name__覆盖详见 插件教程 中growing up一节。正式包带来的能力选择 pip 打包分发意味着插件可以获得 Python setuptools 生态提供的全部能力依赖管理在pyproject.toml的dependencies中声明第三方库pip自动解析安装元数据管理版本号、作者、许可证、项目主页统一由包元数据维护OctoPrint 直接读取资源打包模板与静态资源通过include-package-data/MANIFEST.in随包分发版本比较Software Update 插件可利用packaging对包版本进行语义化比较实现可靠的增量升级。OctoPrint 的许多内置但由外部维护的插件如 FileCheck都采用这一路径分发。关键注意事项Python 环境必须一致自动注册只在同一个 Python 安装包括虚拟环境内生效。也就是说用户安装插件所使用的 Python 解释器必须与安装、运行 OctoPrint 时使用的完全一致否则插件虽然被pip装上OctoPrint 却无法通过入口点发现它。在 OctoPi 这类环境中这一点尤为重要OctoPrint 运行在~/oprint虚拟环境中用户应使用~/oprint/bin/pip安装插件而不是系统级pip~/oprint/bin/pip install OctoPrint-SomePlugin从源码也可以印证这一约束PluginManager.init会在初始化时调用_detect_python_environment()检测sys.prefix与base_prefix判断是否处于虚拟环境而插件可管理性判定core.py 第 1190-1204 行同样要求插件安装在当前虚拟环境内部否则插件管理器不会将其标记为可卸载。因此在文档与安装说明中明确告知用户请使用与 OctoPrint 相同的 Python 环境安装插件是避免大量装了却找不到工单的关键一步。注册官方插件仓库当插件开发完成、准备面向公众分发时可以将其注册到官方 OctoPrint 插件仓库plugins.octoprint.org。注册的具体流程以插件仓库的帮助页面为准如果插件是用 OctoPrint 插件 Cookiecutter 模板创建的在插件项目的extras文件夹中会预置好一份可直接填写的注册条目.md文件只需补充必要信息提交即可。注册的意义在于插件会进入 OctoPrint 内置的插件管理器与 Software Update 的已知插件列表用户可以直接在界面中搜索、安装并持续接收更新而不必手动复制文件或敲pip命令。官方仓库发布后的版本管理插件进入官方仓库后每次迭代都涉及发布 → 验证 → 生效三个环节更新版本号完成新版本开发后务必先在包的版本元数据pyproject.toml的[project] version或旧式setup.py中更新版本号发布 GitHub Release为新的版本创建对应的 GitHub Release本地验证发布后可在自己安装的 OctoPrint 中打开设置里的 Software Update 菜单使用**高级选项中的强制检查更新force check**立即触发一次版本检查确认新版本能被正确识别等待生效普通用户侧的新版本提示通常会在24 小时内出现具体取决于各用户更新缓存cache_ttl的刷新时机。当前仓库中 OctoPrint 自身的更新检查默认cache_ttl为一天见 softwareupdate 默认配置。进阶用发布渠道管理预发布版本对于希望让 beta 用户抢先体验预发布版本、又不影响稳定版用户的场景官方提供了**发布渠道release channel**机制。相比手动分发预发布文件这显然更优雅用户可以在 Software Update 中自行决定是否订阅预发布渠道。渠道机制的核心是在插件提供的更新信息中声明两个配置项stable_branch稳定渠道定义prerelease_branches预发布渠道定义列表。更新信息的提供方式check_config 钩子需要说明的是文档原文以 get_update_information函数 描述这一入口在当前版本中插件是通过名为octoprint.plugin.softwareupdate.check_config的钩子来提供更新信息的自 OctoPrint 1.2.0 引入见 hooks 文档。Software Update 插件在 源码第 246 行 通过self._plugin_manager.get_hooks(octoprint.plugin.softwareupdate.check_config)收集所有插件的钩子钩子返回以插件标识为键、以检查配置为值的字典。渠道字段的具体结构定义在 Software Update 插件文档 中stable_branch可选稳定渠道定义包含branch渠道关联的分支同时作为渠道 IDname渠道的人类可读名称commitish用于与 GitHub Release 数据中target_commitish字段匹配的取值列表未设置时默认匹配branch本身。prerelease_branches可选预发布渠道定义列表结构与stable_branch相同每个条目同样含branch、name、commitishprereleaseTrue或False默认False为True时才把标记为预发布的 Release 纳入检查范围prerelease_channel用户当前选定的预发布渠道仅在prerelease为True时生效用于把更新范围限制到该渠道关联的commitish。配置示例三条发布渠道以下 YAML 示例来自 Software Update 插件文档展示了为某个github_release类型的插件声明Stable / Maintenance RCs / Devel RCs三个渠道、当前激活稳定渠道的完整配置plugins: softwareupdate: checks: some_plugin: type: github_release user: someUser repo: OctoPrint-SomePlugin stable_branch: name: Stable branch: master commitish: - master prerelease_branches: - name: Maintenance RCs branch: rc/maintenance commitish: - rc/maintenance - master - name: Devel RCs branch: rc/devel commitish: - rc/devel - rc/maintenance - master pip: https://github.com/someUser/OctoPrint-SomePlugin/archive/{target}.zip当用户或 beta 用户切换到 Maintenance RCs 渠道时配置变为注意新增的prerelease与prerelease_channelplugins: softwareupdate: checks: some_plugin: type: github_release user: someUser repo: OctoPrint-SomePlugin stable_branch: name: Stable branch: master commitish: - master prerelease_branches: - name: Maintenance RCs branch: rc/maintenance commitish: - rc/maintenance - master - name: Devel RCs branch: rc/devel commitish: - rc/devel - rc/maintenance - master prerelease: True prerelease_channel: rc/maintenance pip: https://github.com/someUser/OctoPrint-SomePlugin/archive/{target}.zip底层如何匹配渠道渠道匹配逻辑在 github_release 版本检查器 中实现检查器读取prerelease与prerelease_channel从prerelease_branches中构建{branch: [commitish...]}映射据此筛选出target_commitish匹配的 Release——这就是为什么发布预发布版本时需要在对应渠道分支如rc/maintenance上打标签并发布 Release。OctoPrint 自身的更新配置源码第 664-686 行即采用这一模式将stable_branch指向stable分支、prerelease_branches指向prerelease分支作为 Release Candidate 渠道。结语与进一步阅读综上OctoPrint 插件分发的完整链路是本地开发Cookiecutter 模板起步→ 打包为 pip 包并注册 entry point → 用户安装注意 Python 环境一致性→ 注册官方插件仓库 → 发布 GitHub Release → 通过 Software Update 渠道机制管理稳定版与预发布版。对于绝大多数插件直接选择 pip 正式包路线即可一步到位手动分发仅适合无需依赖、不求自动更新的极简插件。如需继续深入可在当前仓库中查阅以下资料插件入门教程从零编写一个可打包发布的插件的完整过程Hello World 示例插件的完整打包文件可直接套用的打包模板插件系统核心实现入口点与文件夹两种发现机制的源码细节Software Update 插件文档全部版本检查类型与渠道参数说明插件钩子文档octoprint.plugin.softwareupdate.check_config钩子的注册方式。赞分享物联网后端【免费下载链接】OctoPrintOctoPrint is the snappy web interface for your 3D printer!项目地址https://gitcode.com/gh_mirrors/oc/OctoPrint点击查看免费下载相关推荐WordPress插件自动化部署终极指南如何用GitHub Actions轻松发布到官方仓库WordPress插件自动化部署终极指南如何用GitHub Actions轻松发布到官方仓库 WordPress插件开发者在发布新版本时往往需要手动将代码提t3code AUR 打包指南从 AppImage 到 Arch 官方仓库的自动化发布链路t3code AUR 打包指南从 AppImage 到 Arch 官方仓库的自动化发布链路 t3code 的 Linux 桌面端以官方 x86_64 AppIAI Agent代码智能体后端前端移动开发桌面应用VSCode Rainbow Fart插件打包与发布完整部署流程指南VSCode Rainbow Fart插件打包与发布完整部署流程指南 VSCode Rainbow Fart是一款在你编程时疯狂称赞你的创意扩展插件通过识别开发工具IDE上一篇L1B3RT45提示注入测试库完整指南3步把大模型安全评测跑起来下一篇如何利用Engine-Sim命令行工具实现发动机模拟自动化完整批处理脚本指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考