★ FEATURED ARTICLE 物联网后端【免费下载链接】OctoPrintOctoPrint is the snappy web interface for your 3D printer!项目地址https://gitcode.com/gh_mirrors/oc/OctoPrint点击查看免费下载OctoPrint 是面向 3D 打印机的 Web 控制界面本文以其 docs/development 开发文档为主线系统讲解参与 OctoPrint 开发必须掌握的六大主题分支模型、版本号生成策略、Conventional Commits 提交规范、开发环境搭建、内置虚拟打印机的使用与调试、以及请求级性能分析。读完本文你将具备从克隆源码、搭建开发环境到使用虚拟打印机模拟固件通信、定位性能瓶颈的完整实战能力。一、分支模型main / dev / bugfix / next 的分工与流转OctoPrint 采用清晰的主干分支 维护分支模型详见 branches.rst。整个仓库围绕两条主分支运转main始终包含当前稳定版本代码以及稳定版之后对文档的修改OctoPrint 的实际代码只在新版本发布时才会改动。其版本号遵循x.y.z格式例如1.11.2。dev下一个非 bugfix 版本的持续开发分支几乎不断更新可视为下一版本的预览。官方建议该分支应始终保持稳定如果你发现任何问题并反馈将极大帮助下一个稳定版的质量。其版本号通常为x.y1.0.dev自 y 递增以来的提交数例如稳定版为1.11.2时dev 分支可能是1.12.0.dev114若下一个版本是不向后兼容的版本则为x1.0.0.dev提交数例如2.0.0.dev38。此外还有若干与 bugfix 和 RC 相关的分支bugfix所有潜在 bugfix 版本的准备工作在此进行版本号为x.y.z1.dev提交数例如稳定版1.11.2对应1.11.3.dev4。next从dev分支毕业、准备作为 Prerelease 预发布通道推送测试的未来版本。版本号通常为x.y1.0rcn例如1.12.0rc1不兼容版本则为x1.0.0rcn例如2.0.0rc1。仓库中还可能周期性出现带前缀的临时分支它们表明了开发意图与合入目标分支前缀用途合入目标bug/...正在开发的修复bugfix→mainregression/...当前 RC 中发现的回归修复nextfixnext/...、wipnext/...将进入下一版本的在研改动nextfix/...、wip/...将进入开发分支的在研改动dev这些分支与分支模式之所以需要严格遵循是因为它们都绑定了一个自定义版本工具来自动生成正确的版本号。值得注意的是该分支模型在 2025 年 9 月进行过一次调整master更名为mainmaintenance更名为devstaging/bugfix更名为bugfixstaging/rc与rc/maintenance的角色合并为新的next而devel、staging/devel、rc/devel则被移除。如果你在旧资料中看到这些旧分支名请按上述映射对应到新模型。二、版本号策略PEP 440 语义化版本 自动生成OctoPrint 的版本号遵循 PEP 440并采用MAJOR.MINOR.PATCH三段式语义化版本约定详见 versioning.rstPATCH位只在 hotfix 版本中递增。仅变更 patch 号的版本表示只包含 bug 修复且通常是 hotfix例如1.5.0→1.5.1。需要留意的是在 1.4.2 之前patch 段因维护版本最常递增从 1.5.0 起完全遵循语义化版本中patch 只含 bug 修复的约定维护版本改由MINOR段承载。MINOR位在新增功能且保持已文档化 API内部与外部向后兼容时递增例如1.4.x→1.5.0。MAJOR位在涉及已文档化接口REST API、插件接口等的破坏性变更时递增例如1.x.y→2.0.0。版本号由自定义版本工具依据当前 git 分支、最近的 git 标签与提交数自动生成。除非直接使用 git 标签确定版本否则版本号会在本地版本标识中包含 git 哈希以便精确定位当前代码例如1.2.9.dev68g46c7a9c若工作区存在未提交的改动本地版本标识中还会出现.dirty后缀。版本映射1.12.0 到 2.0.0原计划作为 OctoPrint 1.12.0 发布的版本最终变成了 2.0.0因此你看到的任何关于 1.12.0、1.13.0 等后续版本变更的弃用警告与信息目前按如下映射理解1.12.0→2.0.01.13.0→2.1.0依此类推源码中的版本判定工具与版本策略配套仓库在 src/octoprint/util/version.py 中提供了完整的版本工具函数底层大量使用packaging库get_octoprint_version_string()/get_octoprint_version(cut...)获取当前 OctoPrint 版本字符串或可比较的Version实例cut参数可以裁掉若干版本段例如cut1把1.2.3变成1.2cut0或baseTrue则去掉 dev/rc 信息只留基础版本。is_stable()/is_release()/is_prerelease()判断版本是否为稳定版、发布版或预发布版例如1.3.6rc3不是稳定版但属于发布版1.3.6.post1.dev0g1234则两者都不是。is_octoprint_compatible(2, ...)按兼容性字符串如2、2、1.2.3检测当前版本是否兼容插件常借此声明自己对 OctoPrint 版本的兼容范围未以比较运算符开头的字符串会自动补上前缀。normalize_version()处理非 PEP 440 兼容输入例如去掉末尾的Debian 系统 Python 版本如2.7.15的问题和开头的v。三、提交信息规范向 Conventional Commits 靠拢为了让提交日志在发布准备期间更统一、更易快速浏览OctoPrint 仓库的提交信息大体遵循 Conventional Commits。官方明确这是指南而非铁律——如果它是硬性规则仓库里早就该有 pre-commit 驱动的 linter 了。合并merge与回滚revert提交保持 git 默认格式2024 年 6 月之前的提交使用另一套 emoji 风格个别提交也可能因一时混淆而误用类型或 scope。通用提交格式type[(scope)][!]: description body references footertype与可选的scope列表见下文type或type(scope)后紧跟的!表示破坏性变更breaking change。可选的body与标题行之间必须空一行用于进一步描述提交内容。可选的references与前一部分之间必须空一行这里放 GitHub 关联关键词如Closes #1234、Fixes #5678。可选的footer与 body若无 body 则为标题之间必须空一行。类型type速查type含义chore日常杂务版本号提升、依赖升级、发布准备等ci持续集成相关工作流调整等docs文档相关含完整文档与捆绑的 Markdown 文件dx开发者体验如 Taskfile 新增任务、工具链改进feat新功能新捆绑插件、新 UI 功能等fixbug 或安全修复meta元文件更新.github/*.yml等不含 workflows——那归cirefactor重构无有意的公开 API 变更style代码风格相关如 pre-commit 配置更新及其代码调整test测试相关单元测试、e2e 测试wip进行中的工作后续很可能被 squash常用 scope 示例scope 用于标注改动所属的子系统例如access访问管理、api公开 REST API、auth认证与会话、cli命令行、coreui核心 UI、gcvgcode 查看器插件、jsclientJavaScript 客户端库、plugins插件相关、printer打印机接口、serial串口连接插件、settings设置、storage内部存储 API、swu软件更新插件、tornadoTornado 实现、ux用户体验、virtualprinter虚拟打印机插件等。实例feat: add achievements plugin fix(ci): update raspberrypi keyfile to fix canary build ux: improve readability of progress bars Bringing back the optics that got lost after merging #4105, now that browsers have more options to make this stuff work. Also introduced a new ko-binding progressbar for easier implementation of dynamic progress bars. Closes #5267merge 与 revert 提交保持 git 默认格式Merge branch bugfix into dev Revert fix(ci): update raspberrypi keyfile to fix canary build四、搭建开发环境从克隆源码到跑通测试environment.md 给出了平台无关的通用搭建步骤。当前仓库要求 Python3.10, 3.15见 pyproject.toml具体支持范围以 README 或pyproject.toml为准。前置条件稳定版 Python 3请先对照 pyproject.toml 中的requires-python确认当前支持的版本Git安装步骤# 1. 克隆源码 git clone https://github.com/OctoPrint/OctoPrint.git cd OctoPrint # 2. 在源码目录内创建虚拟环境避免依赖与系统安装实例产生版本冲突 python -m venv venv # 若 python 不在 PATH 上请使用完整路径例如 /path/to/python -m venv venv # 3. 激活虚拟环境Linux/macOS source venv/bin/activate # 或 Windows Git Bash # source venv/Scripts/activate # 4. 升级虚拟环境内的 pip pip install --upgrade pip # 5. 以可编辑模式安装 OctoPrint包含常规 开发 插件开发依赖 pip install -e .[develop,plugins,docs] # 6. 安装 pre-commit 钩子确保改动符合代码风格 pre-commit install # 7. 让 git blame 忽略仅做格式化改动的历史修订 git config blame.ignoreRevsFile .git-blame-ignore-revs激活环境后的常用命令在虚拟环境激活后可以启动 OctoPrint 服务octoprint serve若当前工作目录是 OctoPrint 源码目录还可以以下任务定义均可在 Taskfile.yml 中找到命令作用go-task test-unit运行单元测试即pytestgo-task test-e2e从源码目录运行基于 Playwright 的端到端测试go-task pre-commit对所有文件运行 pre-commit 检查octoprint dev css:build --help查看从.less重新构建.css的用法go-task docs-build构建文档产物位于docs/_build目录go-task docs-serve带自动重载地本地预览文档浏览器访问http://localhost:8000go-task check-deps检查是否有依赖新版本可用go-task babel-refresh/babel-compile/babel-bundle更新、编译并打包 OctoPrint 翻译文件go-task --list查看全部可用任务此外日常开发中执行git commit会自动触发 pre-commit 检查确保格式与 lint 通过git blame会忽略.git-blame-ignore-revs中列出的纯格式化修订。e2e 测试基于 Playwright用例位于 tests/playwright/specs安装框架用go-task test-e2e-install交互式运行用go-task test-e2e-uiQUnit 前端测试则通过go-task test-qunit运行。IDE 配置VS Code 与 PyCharmVisual Studio Code在项目根创建.vscode目录分别配置settings.json设置虚拟环境解释器为venv/bin/python、开启保存时用 ruff 格式化与导入排序、启用 pytest 测试发现、tasks.json清理构建产物、安装依赖等任务与launch.json以octoprint模块 serve --debug参数启动调试。安装扩展ms-python.python与charliermarsh.ruff后按F5即可进入调试模式。这些.vscode文件刻意不纳入 OctoPrint 源码以保持 IDE 无关性。PyCharm在 Settings 中把 OctoPrint 的venv注册为 Project Interpreter将src标记为源码目录为服务、pytest 测试与 Sphinx 文档构建各添加一个 Run/Debug Configuration模块名分别为octoprint、pytest 的 Custom Target、sphinx.cmd.build。官方文档特别警告PyCharm 章节已约五年未更新作者本人也已停止使用该 IDE因此相关步骤很可能已过时仅作参考。切换虚拟环境只需更换 Project Default Interpreter 并重启 OctoPrint。五、虚拟打印机无需真实硬件调试串口通信OctoPrint 默认捆绑了虚拟打印机插件详见 bundledplugins/virtual_printer.rst 与 src/octoprint/plugins/virtual_printer/virtual.py可以在不连接真实打印机的情况下调试 OctoPrint 的串口通信还能构造真实打印机上难以复现的边界条件。它通过virtual_printer_factory钩子拦截端口名为VIRTUAL的连接见 src/octoprint/plugins/virtual_printer/init.py核心类VirtualPrinter用队列模拟了 Rx 缓冲区、命令缓冲区、虚拟 SD 卡与虚拟 EEPROM。启用方式虚拟打印机通过其设置面板启用plugins.virtual_printer.enabled置为true启用后会出现在可用串口连接列表中。核心配置项config.yaml以下为 virtual_printer.rst 给出的完整配置示例涵盖了通信协议行为、温度、SD 与固件响应的方方面面plugins: virtual_printer: # 是否启用虚拟打印机并纳入可用串口列表。默认 false。 enabled: true # 重发请求后是否额外发送一次 okRepetier 风格。默认 false。 okAfterResend: false # 是否强制校验和与行号Repetier 风格为 true 时只接受带行号和校验和的命令。默认 false。 forceChecksum: false # 发送 ok 时是否附带被确认的行号。默认 false。 okWithLinenumber: false # 模拟的挤出机数量。默认 1。 numExtruders: 1 # 将某些喷头固定在指定温度。默认 null。 pinnedExtruders: null # M105 输出中是否包含当前工具温度独立 T 段 # True: M105 # ok T:23.5/0.0 T0:34.3/0.0 T1:23.5/0.0 B:43.2/0.0 # False: ok T0:34.3/0.0 T1:23.5/0.0 B:43.2/0.0 includeCurrentToolInTemps: true # M23 打开文件响应中是否包含文件名 # True: File opened: filename.gcode Size: 27 # False: File opened includeFilenameInOpened: true # 是否模拟加热床。默认 true。 hasBed: true # 是否模拟加热腔。默认 false。 hasChamber: false # 以独立消息报告目标温度Repetier 风格。默认 false。 repetierStyleTargetTemperature: false # Repetier 风格的重发同一行发送多次重发请求。默认 false。 repetierStyleResends: false # 命令输出前先发送 okM105 输出则内联。默认 false。 okBeforeCommandOutput: false # M105 中第一个挤出机报为 T 而非 T0Smoothie 风格。默认 false。 smoothieTemperatureReporting: false # SD 文件列表输出相关 sdFiles: size: true # M20 响应是否包含文件大小 timestamp: false # 是否包含时间戳仅当 sizetrue longname: false # 是否包含长文件名仅当 sizetrue # 从输出缓冲区取回时的强制暂停。默认 0.01。 throttle: 0.01 # 串口 Rx 缓冲区为空时是否周期发送 wait。默认 false。 sendWait: false # 发送 wait 的间隔秒。默认 1。 waitInterval: 1 # 模拟 Rx 缓冲区大小字节满时 OctoPrint 侧发送会阻塞。默认 64。 rxBuffer: 64 # 模拟命令缓冲区大小条满时缓冲命令阻塞。默认 4。 commandBuffer: 4 # 是否支持 M112 模拟急停。默认 true。 supportM112: true # 是否把 M117 收到的消息回显为 echo:。默认 true。 echoOnM117: true # 是否模拟损坏的 M29响应后缺 ok。默认 true。 brokenM29: true # 是否支持 F 作为独立命令。默认 false。 supportF: false # 上报的固件名称可用于测试固件识别。默认 Virtual Marlin 1.0。 firmwareName: Virtual Marlin 1.0 # 模拟共享喷嘴。默认 false。 sharedNozzle: false # 忙碌时发送 busy 消息。默认 false。 sendBusy: false # 连接时模拟复位。默认 true。 simulateReset: true # 模拟复位时发送的行。 resetLines: - start - Marlin: Virtual Marlin! - SD card ok # 预先准备好的 ok 响应可模拟错发的 ok也可在运行时用调试命令 prepare_ok 填充。默认 []。 preparedOks: [] # ok 响应格式串。占位符lastN最后确认行号buffer命令缓冲区空槽数。 # 例ok N{lastN} P{buffer}。 okFormatString: ok # M115 输出格式串。占位符firmware_name。 m115FormatString: FIRMWARE_NAME: {firmware_name} PROTOCOL_VERSION:1.0 # M115 输出是否包含能力报告。默认 true。 m115ReportCapabilities: true # 能力报告列表Marlin 的 AUTOREPORT_*、EMERGENCY_PARSER 等。 capabilities: AUTOREPORT_TEMP: true AUTOREPORT_SD_STATUS: true AUTOREPORT_POS: false EMERGENCY_PARSER: true EXTENDED_M20: false LFN_WRITE: false # M115 输出是否包含区域报告Marlin 的 M115_GEOMETRY_REPORT。默认 false。 m115ReportArea: false # 模拟环境温度°C。默认 21.3。 ambientTemperature: 21.3 # 有目标温度时 M105 的响应格式。占位符heater、actual、target。 m105TargetFormatString: {heater}:{actual:.2f}/ {target:.2f} # 无目标温度时 M105 的响应格式。占位符heater、actual。 m105NoTargetFormatString: {heater}:{actual:.2f} # M123 风扇 RPM 响应格式。占位符fan、rpm。 m123RPMFormatString: {fan}:{rpm} RPM # 虚拟风扇最大转速RPM。默认 4560。 fanMaxSpeed: 4560 # 启用虚拟 EEPROM会在插件数据目录创建 eeprom.json 以跨连接持久化设置 # 并启用 M500/1/2/4 等命令响应模型参照 Marlin 2.0。默认 true。 enable_eeprom: true # 支持 M503。默认 true。 support_m503: true # 模拟线路噪声的重发比例。默认 0。 resend_ratio: 0 # 在指定行号模拟通信错误 simulated_errors: - 100:resend # 第 100 行请求一次简单重发 - 105:resend_with_timeout # 第 105 行请求重发并模拟不响应 - 110:missing_lineno # 第 110 行模拟缺失行号 - 115:checksum_mismatch # 第 115 行模拟校验和不匹配以上默认值可在 src/octoprint/plugins/virtual_printer/init.py 的get_settings_defaults中找到对应实现例如ambientTemperature: 21.3、fanMaxSpeed: 4560、enable_eeprom: True、support_M503: True、resend_ratio: 0等。在 virtual.py 中可以看到这些配置如何落地rxBuffer决定CharCountingQueue的 Rx 缓冲区大小、commandBuffer决定命令缓冲队列maxsize、simulateReset为 true 时连接即发送resetLines中的行、preparedOks会被注入预置 ok 队列等。串口日志虚拟打印机启用后所有串口通信会记录到日志目录下的plugin_virtual_printer_serial.log文件由CleaningTimedRotatingFileHandler按天轮转保留 3 份备份见 src/octoprint/plugins/virtual_printer/init.py。调试命令Terminal 标签页在 OctoPrint 界面的终端标签页中发送!!DEBUG:命令即可模拟特定条件。例如!!DEBUG:action_disconnect会断开打印机连接单独发送!!DEBUG会显示全部可用命令的帮助。完整的调试命令体系如下# Action 触发器 action_pause # 向主机发送 // action:pause action_resume # 向主机发送 // action:resume action_disconnect # 向主机发送 // action:disconnect action_custom action[ parameters] # 发送自定义 // action:action parameters # 通信错误 dont_answer # 不确认下一条命令 go_awol # 完全停止回复 trigger_resend_lineno # 触发行号不匹配的重发错误 trigger_resend_checksum # 触发校验和不匹配的重发错误 trigger_missing_checksum # 触发缺失校验和的重发错误 trigger_missing_lineno # 触发有校验和无行号错误不带重发请求 drop_connection # 断开串口连接 prepare_ok broken ok # 预置 broken ok后续将用它替代真正的 ok # 回复时机 / 睡眠 sleep int:seconds # 睡眠 seconds 秒 sleep_after str:command int:seconds # 每次执行 command 后睡眠 seconds 秒 sleep_after_next str:command int:seconds # 执行下一条 command 后睡眠 seconds 秒 # SD 打印 start_sd str:file # 从 SD 选择并开始打印 file select_sd str:file # 仅选择 SD 文件不开始打印 cancel_sd # 取消正在进行的 SD 打印 # 其他 send str:message # 向 OctoPrint 回发 message reset # 模拟复位内部状态将丢失这些命令的正则解析与实现位于 virtual.py例如prepare_ok、send、start_sd、select_sd、resend_ratio均有对应的re.compile规则sleep_after类命令依赖_sleepAfter/_sleepAfterNext字典在每轮命令循环中生效。六、请求级性能分析?perfprofile 参数开发环境搭建完成后用以下方式启动 OctoPrint 即可对 HTTP 请求做性能剖析详见 request-profiling.rstoctoprint serve --debug随后照常发起任意请求只需在 URL 上追加?perfprofile或对已有查询参数的请求追加perfprofile请求仍会正常渲染但你会收到一份包含剖析结果的 HTML 文档而非正常响应内容。在源码层面该机制由 src/octoprint/server/init.py 实现当self._debug为真且请求参数中包含perfprofile时请求前置钩子会创建Profiler()并start()请求结束的后置钩子中stop()剖析器并把output_html()作为响应输出。底层剖析器基于pyinstrument。常见错误与处理若收到500: Internal Server Error且控制台出现ModuleNotFoundError: No module named pyinstrument说明你没有安装开发依赖。此时执行pip install -e .[develop]安装后重新启动octoprint serve --debug即可。七、参与贡献的入口如果你有兴趣为 OctoPrint 贡献代码请务必先阅读仓库根目录的 CONTRIBUTING.md贡献指南。开发相关的其余细节如仓库分支约定、版本号规则、提交规范与虚拟打印机均可通过 docs/development/index.rst 的目录树导航到对应章节。结合上述分支模型、自动版本号机制与 pre-commit 流程从dev分支出发、按规范格式提交改动、在提交前跑通单元测试与 lint就是一条符合 OctoPrint 官方预期的开发路径。赞分享物联网后端【免费下载链接】OctoPrintOctoPrint is the snappy web interface for your 3D printer!项目地址https://gitcode.com/gh_mirrors/oc/OctoPrint点击查看免费下载相关推荐GSYGithubApp Flutter 本地开发环境搭建指南版本契约、OAuth 配置与分层验证策略GSYGithubApp Flutter 本地开发环境搭建指南版本契约、OAuth 配置与分层验证策略 本篇指南基于 GSYGithubApp Flutter移动开发开发者工具7步快速搭建本地AI模型开发环境Docker环境配置终极指南7步快速搭建本地AI模型开发环境Docker环境配置终极指南 GitHub 加速计划gallery44/gallery是一个展示设备端机器学习/生成式AI人工智能大模型本地部署AI 应用移动开发AI AgentAI 技能MCP ClientsESP8266_RTOS_SDK开发环境搭建指南Linux版ESP8266_RTOS_SDK开发环境搭建指南Linux版 前言 本文将详细介绍如何在Linux系统上搭建ESP8266_RTOS_SDK的开发环境。ES嵌入式物联网固件嵌入式OS通信上一篇Evergreen Skills for Software Developers完全指南从新手到专家的完整成长路径下一篇RxDB 事务、冲突与修订Transactions, Conflicts and Revisions完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
