news 2026/9/25 5:20:22

OctoPrint 插件弃用清单与迁移指南：2.1.0/2.2.0/3.0.0 行为变更全解析

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
OctoPrint 插件弃用清单与迁移指南：2.1.0/2.2.0/3.0.0 行为变更全解析
  • 物联网
  • 后端

【免费下载链接】OctoPrint

OctoPrint is the snappy web interface for your 3D printer!

项目地址：https://gitcode.com/gh_mirrors/oc/OctoPrint
点击查看免费下载

本篇技术指南以 OctoPrint 官方维护的 docs/plugins/deprecations.md 为骨架，系统梳理当前仍处于活跃状态的弃用项（deprecations）与可能造成破坏的行为变更（behaviour changes），并按目标移除版本（2.1.0、2.2.0、3.0.0 及未定版本）分类。读完本文，你将掌握模板前缀、自动转义、API 保护、设置读写方法、钩子重命名、JS 客户端方法迁移等每一项改动的具体表现、迁移步骤与可运行的代码示例，避免你的插件或第三方客户端在 OctoPrint 未来版本中悄然失效。

这份清单是 OctoPrint 面向插件作者（plugin authors）和第三方客户端（third party clients）的"官方红线"：所有在此列出的内容都要求你现在就采取行动，而不是等到对应版本发布后再处理。

为什么需要关注这份弃用清单

OctoPrint 对插件生态采取"先警告、后移除"的兼容策略：某个接口或行为一旦被弃用，会先进入兼容层并记录弃用警告，历经多个版本周期后才真正删除。本文档汇总的每一项弃用都标注了引入弃用的版本（如1.8.0、1.11.0、2.0.0）与计划移除的版本，插件作者可据此安排迁移节奏。

仓库源码中的实现可以印证这一策略。例如 src/octoprint/util/init.py 中，新函数thaw_frozendict是正式实现，而旧名称thaw_immutabledict则是通过deprecated(...)装饰器包装出的兼容别名；又如 src/octoprint/plugin/core.py 中blacklisted属性被标记为deprecated("blacklisted is deprecated in favor of blocklisted", since="2.0.0")后仍返回self.blocklisted。这类"包装层 + 警告日志"的模式在下面各节中反复出现，识别出这些模式有助于你在自己的代码中尽早排查。

OctoPrint 2.1.0 的弃用项与行为变更

插件模板必须使用plugin_<插件标识符>前缀

自 OctoPrint 1.8.0 起，在插件模板中引入其他模板而不带plugin_<插件标识符>前缀的做法已被弃用，允许其继续工作的兼容层将在 OctoPrint 2.1.0 中移除。如果插件仍在使用不带前缀的模板引入，现在就必须修复。

需要检查两处代码：

1. 插件模板中对其他插件模板的引入。例如：

{% include "snippets/my_snippet.jinja2" %}

这种写法目前仍会被解析为相对当前插件，未来必须改为显式前缀、指向目标插件：

{% include "plugin_some_other_plugin/snippets/my_snippet.jinja2" %}

2. 插件自己渲染的模板。例如通过BlueprintPluginmixin 创建的自定义路由中的flask.render_template调用：

@octoprint.plugin.BlueprintPlugin.route("/foo", methods=["GET"]) def foo_endpoint(self): return flask.make_response( flask.render_template( "some_template.jinja2" ) )

对于标识符为my_plugin的插件，需要改为：

@octoprint.plugin.BlueprintPlugin.route("/foo", methods=["GET"]) def foo_endpoint(self): return flask.make_response( flask.render_template( "plugin_my_plugin/some_template.jinja2" ) )

从 src/octoprint/plugin/types.py 的get_template_folder实现可以看到，插件模板默认位于插件基目录的templates子目录中，OctoPrint 正是基于该目录与插件标识符建立模板命名空间，因此前缀化是模板解析规则的核心。

弃用自：1.8.0

TemplatePlugin模板自动转义从 opt-in 转为 opt-out

自 OctoPrint 1.11.0 起，OctoPrint 支持对全部插件模板强制开启自动转义（auto-escaping）。在 2.1.0 之前这是 opt-in 模式——插件必须主动告知 OctoPrint 才开启；到 2.1.0，OctoPrint 将默认对第三方插件也启用自动转义。

如果插件实现了TemplatePlugin，应先主动 opt-in 并完整测试插件：

class MyPlugin(octoprint.plugin.TemplatePlugin): # ... def is_template_autoescaped(self): return True

仓库中 src/octoprint/plugin/types.py 的is_template_autoescaped默认实现已经返回True（其 docstring 明确注明："Since OctoPrint 2.1.0 this defaults toTrue"），这正是文档所述默认行为切换的源码落点。

迁移与测试建议：

  • 如果出现问题，理想情况下应在不关闭自动转义的前提下修复；
  • 仅在个别位置需要从变量输出 HTML 时，使用手动转义过滤器|e或按需标记安全的|safe；
  • 务必只在完全受你控制的代码中使用|safe，不要标记任何可能受用户输入影响的变量或输出，否则会带来 XSS 风险；
  • 可参考 OctoPrint 官方社区 FAQ 中关于自动转义的条目（见原文档的链接）。

弃用自：1.11.0

SimpleApiPlugin端点保护从 opt-in 转为 opt-out

自 OctoPrint 1.11.2 起，OctoPrint 支持对全部SimpleApiPlugin端点强制基础认证。在 2.1.0 之前这是 opt-in 模式；到 2.1.0，OctoPrint 将默认保护所有端点。

插件作者应先主动 opt-in 并完整测试：

class MyPlugin(octoprint.plugin.SimpleApiPlugin): # ... def is_api_protected(self): return True

src/octoprint/plugin/types.py 中的is_api_protected默认实现同样已返回True，并在 docstring 中提醒：即使开启了保护，OctoPrint 也只检查"是否有有效用户登录"，插件仍应在 API 端点内自行加入针对本插件的权限检查。

迁移要点：

  • 如遇问题，优先修复问题而不是关闭保护；
  • 若因实现原因或预期工作流确实无法开启，可显式返回False选择 opt-out，并手动为不应完全开放的端点实现认证。

弃用自：1.11.2

移除SettingsViewModel.users

SettingsViewModel.users已不再被 OctoPrint 核心使用，将在 2.1.0 移除。如果插件依赖它而不是在自身 view model 中声明对accessViewModel的依赖（从而访问accessViewModel.users），请按如下步骤迁移：

  1. 在插件的 view model 中添加对accessViewModel的依赖；
  2. 将所有self.settingsViewModel.users（或你保存注入的SettingsViewModel实例的参数名）替换为self.accessViewModel.users。

弃用自：2.0.0

events.yaml中系统命令事件订阅的shell参数默认值变更

在events.yaml中配置的系统命令事件订阅，若未显式定义shell参数，目前生成的命令调用默认shell=True。由于这存在安全隐患，OctoPrint 2.1.0 将把默认值改为shell=False。

如果事件订阅依赖 shell 行为（如 shell 展开、管道、重定向），现在就必须显式加上shell: true，以免在 2.1.0 中失效：

# events.yaml 示例（显式声明 shell 行为） events: - event: PrintDone command: /path/to/script.sh arg1 arg2 shell: true

弃用自：2.0.0

OctoPrint 2.2.0 的弃用项

移除SettingsViewModel中的 webcam 兼容层

下列仍存在于SettingsViewModel中的 observable 自 OctoPrint 1.9.0 起已弃用（访问时会打印弃用警告），将在 2.2.0 中彻底移除，替代项如下：

已弃用的 observable替代项
webcam_streamUrlsettings.webcam.streamUrl
webcam_streamRatiosettings.webcam.streamRatio
webcam_streamTimeoutsettings.webcam.streamTimeout
webcam_streamWebrtcIceServerssettings.webcam.webrtcIceServers
webcam_snapshotUrlsettings.webcam.snapshotUrl
webcam_flipHsettings.webcam.flipH
webcam_flipVsettings.webcam.flipV
webcam_rotate90settings.webcam.rotate90
webcam_cacheBustersettings.webcam.cacheBuster

弃用自：1.9.0

移除重命名后的SlicingViewModel.gcodeFilename

SlicingViewModel.gcodeFilename自 2.0.0 起已重命名为SlicingViewModel.destinationFilename，旧名称支持将在 OctoPrint 2.2.0 移除。若插件使用该 observable，请相应调整。

弃用自：2.0.0

OctoPrint 3.0.0 的弃用项

移除重命名后的PluginSettings.(get|set)(Int|Float|Boolean)

注入到插件实现中、以self._settings访问的PluginSettings实例上的getInt、getFloat、getBoolean、setInt、setFloat、setBoolean六个方法已被弃用并记录弃用警告长达十年，但仍被大量第三方插件重度使用。文档给出的是最终警告：插件作者必须切换到长期存在的替代方法get_(int|float|boolean)与set_(int|float|boolean)。

实践中就是以下简单的替换：

  • self._settings.getInt→self._settings.get_int
  • self._settings.getFloat→self._settings.get_float
  • self._settings.getBoolean→self._settings.get_boolean
  • self._settings.setInt→self._settings.set_int
  • self._settings.setFloat→self._settings.set_float
  • self._settings.setBoolean→self._settings.set_boolean

从源码看，旧方法并未直接消失。例如 src/octoprint/settings/init.py 中的getInt仍实现着完整的取整与min/max边界收敛逻辑（int(value)转换失败时记录警告并返回None），src/octoprint/settings/init.py 的setInt则负责写入前的类型转换与边界约束。这些语义在get_int/set_int等新方法中保持一致，因此迁移是纯机械的改名操作。

OctoPrint 3.0.0 将彻底移除旧版本。

弃用自：1.2.0

移除重命名后的octoprint.users.factory钩子

插件钩子octoprint.users.factory自 OctoPrint 2.0.0 起弃用，将在 3.0.0 移除，其长期替代者是octoprint.access.users.factory。仍实现旧钩子的插件，请把注册改为这个可直接替换的新名称。

仓库中 src/octoprint/server/init.py 展示了这一兼容逻辑：服务器会同时收集octoprint.users.factory与octoprint.access.users.factory两个钩子，并对注册了旧钩子的插件打印警告信息，提示切换到新名称。另外 src/octoprint/cli/user.py 的 CLI 说明文档也明确将用户管理器来源指向octoprint.access.users.factory钩子。

弃用自：2.0.0

移除OctoPrintClient.access.users.update的admin参数

自 2.0.0 起，在第三个位置以admin参数调用OctoPrintClient.access.users.update已弃用，3.0.0 将不再支持。请改用permissions或groups参数来添加或移除用户账号的管理员权限。完整调用签名可参考 docs/jsclientlib/access.rst 中OctoPrintClient.access.users.update的文档。

弃用自：2.0.0

移除OctoPrintClient.printer上重命名的打印机存储方法

OctoPrintClient.printer上的以下方法已重命名：

  • issueSdCommand→issueStorageCommand
  • getSdState→getStorageState
  • initSd→initStorage
  • releaseSd→releaseStorage
  • refreshSd→ 未重命名但被替代，改用OctoPrintClient.files.listForLocation

旧名称仍可用，但会在浏览器控制台打印弃用警告。若插件或其他客户端使用这些方法，请切换到新名称。

弃用自：2.0.0

移除AccessViewModel.isCurrentUser，改用AccessViewModel.isUserMyself

AccessViewModel.isCurrentUser已重命名为AccessViewModel.isUserMyself，目的是消除旧名称的歧义。请相应替换代码中的用法。

弃用自：2.0.0

移除FilesViewModel上重命名的打印机存储方法

FilesViewModel上的以下方法已重命名：

  • initSdCard→initPrinterStorage
  • releaseSdCard→releasePrinterStorage
  • refreshSdFiles→refreshPrinterStorage

旧名称仍可用，但会在浏览器控制台打印弃用警告。请切换到新名称。

弃用自：2.0.0

从事件TransferStarted、TransferDone、TransferFailed移除local参数

TransferStarted、TransferDone、TransferFailed事件的 payload 目前仍包含local属性，自 2.0.0 起它已与path相同，并将在 3.0.0 移除。相关事件定义可参考 docs/events/index.rst 中文件处理（file handling）部分的可用事件列表。

弃用自：2.0.0

移除重命名后的OctoPrintClient.plugins.appkeys.revokeKey

OctoPrintClient.plugins.appkeys.revokeKey已重命名为OctoPrintClient.plugins.appkeys.revokeKeyForApp。旧名称仍可用，但会在浏览器控制台打印弃用警告。请切换到新名称。

弃用自：1.10.0

移除POST /api/system兼容包装

遗留的POST /api/systemAPI 端点自 1.3.0 起已被POST /api/system/commands/custom/<action>替代。旧端点目前仍作为兼容包装保留，内部重定向到新端点并记录弃用警告，将在 3.0.0 移除。若插件或其他客户端仍请求POST /api/system，请立即切换到POST /api/system/commands/custom/<action>。

弃用自：1.3.0

尚未确定移除版本的弃用项

以下弃用项尚无明确移除版本，但同样要求插件作者尽快迁移。

octoprint.printer.standard.Printer（即self._printer）上的弃用方法

已弃用方法替代方案
get_connection_options使用ConnectedPrinter.all()，并结合返回的ConnectedPrinter实例上的connection_options
select_fileset_job
unselect_fileset_job（传入None）
fake_ackrepair_communication
get_transport仅当当前连接器恰好是内置 serial connector 时才可用；如有使用请通过功能请求反馈用途
get_current_connectionconnection_state；兼容层仅在当前连接器为内置 serial connector 时可用
is_sd_readyis_storage_mounted
init_sd_cardmount_storage
release_sd_cardunmount_storage
get_sd_files通过文件管理器使用printer存储
add_sd_file通过文件管理器使用printer存储
delete_sd_file通过文件管理器使用printer存储
refresh_sd_files通过文件管理器使用printer存储
can_modify_file直接对比作业参数与current_job，并检查当前打印状态
is_current_file直接对比作业参数与current_job

弃用自：2.0.0

迁移示例：select_file

from octoprint.filemanager import FileDestinations from octoprint.util.version import is_octoprint_compatible if is_octoprint_compatible(">=2"): job = self._file_manager.create_job(storage, path) self._printer.set_job(job, print_after_select=False) else: is_sd = storage == FileDestinations.SDCARD file_to_select = path if is_sd else self._file_manager.path_on_disk(storage, path) self._printer.select_file(file_to_select, sd=is_sd, printAfterSelect=False)

迁移示例：unselect_file

from octoprint.util.version import is_octoprint_compatible if is_octoprint_compatible(">=2"): self._printer.set_job(None) else: self._printer.unselect_file()

迁移示例：refresh_sd_files与get_sd_files

from octoprint.filemanager import FileDestinations from octoprint.util.version import is_octoprint_compatible if is_octoprint_compatible(">=2"): self._file_manager.list_storage_entries([FileDestinations.PRINTER], force_refresh=blocking) else: self._printer.get_sd_files(blocking=blocking)

迁移示例：can_modify_file

from octoprint.filemanager import FileDestinations from octoprint.util.version import is_octoprint_compatible if is_octoprint_compatible(">=2"): current_job = self._printer.current_job is_current_job = current_job is not None and current_job.path == path and current_job.storage == storage return not (is_current_job and (self._printer.is_printing() or self._printer.is_paused())) else: is_sd = storage == FileDestinations.SDCARD storage_path = path if is_sd else self._file_manager.path_on_disk(storage, path) return self._printer.can_modify_file(storage_path, is_sd)

迁移示例：is_current_file

from octoprint.filemanager import FileDestinations from octoprint.util.version import is_octoprint_compatible if is_octoprint_compatible(">=2"): current_job = self._printer.current_job return current_job is not None and current_job.path == path and current_job.storage == storage else: is_sd = storage == FileDestinations.SDCARD storage_path = path if is_sd else self._file_manager.path_on_disk(storage, path) return self._printer.is_current_file(storage_path, is_sd)

这些示例中使用到的is_octoprint_compatible是 OctoPrint 提供的版本兼容性判断工具，实现在 src/octoprint/util/version.py，可让插件在迁移期间同时兼容新旧两代 API——这正是官方推荐的渐进式迁移方式。

移除对octoprint.util.comm的直接访问

octoprint.util.comm模块已迁移到内置插件serial_connector中，现在以octoprint.plugins.serial_connector.serial_comm形式存在。直接访问octoprint.util.comm已弃用，目前仅保留为从新位置再导出的兼容层。

如果插件从octoprint.util.comm导入任何内容，请将导入切换到octoprint.plugins.serial_connector.serial_comm。仓库中 src/octoprint/plugins/serial_connector/connector.py 即从.serial_comm导入MachineCom、baudrateList、serialList等核心符号，印证了新的模块位置。

弃用自：2.0.0

octoprint.filemanager.FileManager（即self._filemanager）上的弃用方法

  • list_files→list_storage_entries
  • get_file→get_storage_entry
  • add_link→ 无替代
  • remove_link→ 无替代

弃用自：2.0.0

octoprint.filemanager.storage.StorageInterface（及所有存储实现）上的弃用方法

  • last_modified→get_lastmodified
  • get_file→get_storage_entry
  • list_files→list_storage_entries
  • add_link→ 无替代
  • remove_link→ 无替代

弃用自：2.0.0

移除octoprint.server.util.flask.get_remote_address

由flask.request.remote_addr替代。

弃用自：1.10.0

octoprint.plugin.PluginInfo.blacklisted重命名为blocklisted

octoprint.plugin.PluginInfo.blacklisted已重命名为octoprint.plugin.PluginInfo.blocklisted，请相应调整调用代码。源码中 src/octoprint/plugin/core.py 将状态保存在self.blocklisted属性上，而 src/octoprint/plugin/core.py 的旧属性名则通过@deprecated(...)包装转发到新属性，插件管理器前端也在 pluginmanager.js 等位置统一使用blocklisted字段。

弃用自：2.0.0

octoprint.util.thaw_immutabledict重命名为thaw_frozendict

octoprint.util.thaw_immutabledict已重命名为octoprint.util.thaw_frozendict，请相应调整调用代码。源码实现见 src/octoprint/util/init.py：thaw_frozendict递归地将（冻结的）字典解冻为普通字典并深拷贝值，旧名称thaw_immutabledict作为兼容别名继续存在。

弃用自：1.8.0

移除serial.*设置兼容覆盖层

随着串口通信栈迁移到内置serial_connector插件，原先位于serial.*下的所有设置均已迁移。目前一个只读兼容覆盖层会把新设置暴露在旧的serial.*路径下：读取会返回当前值并记录弃用警告，写入则被静默丢弃。该覆盖层将在未来版本移除。

如果插件读写serial.*下的设置，请切换到新位置：

  • 连接参数：
    • serial.port→printerConnection.preferred.parameters.port
    • serial.baudrate→printerConnection.preferred.parameters.baudrate
    • serial.autoconnect→printerConnection.autoconnect
    • serial.autorefresh→printerConnection.autorefresh
    • serial.autorefreshInterval→printerConnection.autorefreshInterval
  • 被抑制的命令通知：
    • serial.notifySuppressedCommands→feature.notifySuppressedCommands
  • 校验和与错误处理：
    • serial.alwaysSendChecksum/serial.neverSendChecksum→plugins.serial_connector.sendChecksum（现在是枚举，取值always、never、printing）
    • serial.disconnectOnErrors/serial.ignoreErrorsFromFirmware→plugins.serial_connector.errorHandling（现在是枚举，取值disconnect、ignore、cancel）
  • 端口与波特率黑名单：
    • serial.blacklistedPorts→plugins.serial_connector.blocklistedPorts
    • serial.blacklistedBaudrates→plugins.serial_connector.blocklistedBaudrates
  • 其他所有原serial.*设置 →plugins.serial_connector.*（键名相同）

弃用自：2.0.0

移除Blacklist设置兼容覆盖层

包含Blacklist的设置键已重命名为Blocklist。目前一个只读兼容覆盖层会把新设置暴露在旧名称下：读取会返回当前值并记录弃用警告，写入则被静默丢弃。该覆盖层将在未来版本移除。

如果插件读写以下任一设置，请切换到新名称：

  • feature.autoUppercaseBlacklist→feature.autoUppercaseBlocklist
  • server.pluginBlacklist→server.pluginBlocklist

弃用自：2.0.0

移除webcam.*设置兼容覆盖层

顶层webcam.*设置已被 OctoPrint 1.9.0 引入的新 webcam 系统取代，配置现在由实现WebcamProviderPluginmixin 的插件提供。目前一个只读兼容覆盖层会把当前配置的默认 webcam 配置暴露在旧的webcam.*路径下：读取会返回当前值并记录弃用警告，写入则被静默丢弃。该覆盖层将在未来版本移除。

如果插件通过全局设置路径webcam.*读写 webcam 配置，请切换到WebcamProviderPluginmixin 提供的方法。

弃用自：1.9.0

迁移路线图：按版本分步自查

将以上内容整理成可执行的行动清单：

  1. 面向 2.1.0：模板引入与渲染全部加plugin_<标识符>前缀；TemplatePlugin先 opt-in 自动转义并修复问题；SimpleApiPlugin先 opt-in 端点保护并补充权限检查；view model 改用accessViewModel.users；events.yaml中依赖 shell 行为的事件订阅显式声明shell: true。
  2. 面向 2.2.0：替换SettingsViewModel中的 9 个 webcam observable；将SlicingViewModel.gcodeFilename改为destinationFilename。
  3. 面向 3.0.0：完成PluginSettings六个方法的机械改名；切换octoprint.users.factory钩子注册；移除admin参数、打印机存储方法、isCurrentUser、revokeKey、POST /api/system等 JS 客户端与服务端 API 的旧用法。
  4. 无确定版本但应尽快处理：self._printer与self._filemanager的旧方法、octoprint.util.comm导入、serial.*/Blacklist/webcam.*兼容覆盖层读写、blacklisted/thaw_immutabledict等重命名项。

迁移时建议优先使用is_octoprint_compatible（见 src/octoprint/util/version.py）编写兼容新旧版本的代码路径，并密切关注浏览器控制台与服务器日志中打印的弃用警告——它们会精准指出你的插件命中了哪些弃用项。完整插件开发与迁移背景可进一步参考 docs/plugins/hooks.rst、docs/plugins/mixins.rst 以及官方提供的 2.0.0 迁移指南 docs/plugins/migration_2_0_0.md。

  • 物联网
  • 后端

【免费下载链接】OctoPrint

OctoPrint is the snappy web interface for your 3D printer!

项目地址：https://gitcode.com/gh_mirrors/oc/OctoPrint
点击查看免费下载

相关推荐

上一篇：compromise-dates 插件全解析：用自然语言解析日期、时间与时长
下一篇：探索N32G031单片机：一站式学习与开发资源包

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！
网站建设 2026/9/25 5:13:47

小米非澎湃OS机型BL锁解除原理与实操指南

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

作者头像 李华
网站建设 2026/9/25 5:13:36

新能源汽车运力管理系统开发实践与优化

1. 项目背景与核心需求在新能源汽车行业快速发展的当下&#xff0c;传统的人工运力管理方式已经暴露出诸多痛点。我曾参与过某物流公司的新能源车队管理项目&#xff0c;亲眼目睹调度员每天要手动核对几十张Excel表格&#xff0c;不仅耗时费力&#xff0c;还经常出现车辆调度冲…

作者头像 李华