一台正常工作的 Marlin 打印机，本身已经保存着一套关于自己的描述。每单位步数、引脚分配、限位开关极性、热敏电阻类型、探针偏移、加热器限制、电机电流、加速度和切片器启动代码合在一起，对机器的描述已经足以让塑料持续落在正确的位置。

迁移至 Klipper 时，这套模型会换一个位置、换一种写法。大部分设置移入主机端的 printer.cfg；运动规划在 Linux 主机上运行；打印机的微控制器负责执行排定时序的底层命令。这样的分工让配置修改和实验变得格外方便，Klipper 早期的独立报道也把这一点视为其吸引力的一部分。[2][3][10] 因此，迁移应按控制系统切换来处理，提速留给后续阶段。

安全的次序刻意朴素：保存旧状态，建立通信，验证传感器与关停功能，逐一验证电机和限位开关，复现日常打印，随后才调校 pressure advance（压力提前）或 input shaping（输入整形）。如果打印机先变快、后变得乏味可预期，测试次序便已经倒置。

图片说明：封面照片中的 Voron 打印机正在铺设一个零件，皮带、拖链、工具头和线缆都清晰可见。固件驱动的从来都是一套具体的物理组件，每根轴的几何关系和极限都必须完整延续到新系统中；这正是图片放在这里的原因。[11]

刷写固件前，先封存正常工作的机器状态

应从 Marlin 仍能启动时着手。如果启用了 M503，运行该命令并保存完整的控制台输出。Marlin 文档说明，该命令报告当前生效的运行参数；它们与 EEPROM 中保存的值未必相同。因此，这份输出能证明打印机此刻实际采用什么参数，源配置和固件镜像也必须一并保留。若编译时移除了该命令，完整的 Marlin 源代码与配置，或供应商的固件记录，就成为首要基准。[1]

根据这份输出，整理一份简洁的迁移档案：

• 控制板的准确修订版、微控制器、bootloader，以及当前固件文件或可复现的 Marlin 源代码树；
• M92 每单位步数、归零方向、行程限制、最高速度和加速度、探针偏移、热床尺寸及挤出模式；
• 热敏电阻类型、加热器与风扇引脚、安全温度限制、PID 数值、限位开关逻辑、步进驱动器型号与模式，以及电机电流设置；
• 正常工作的切片器配置，尤其是起始与结束 G-code、回抽、流量、加速度控制，以及固件专用命令；
• 控制板接头和跳线的照片，以及控制板引脚图与打印机接线文档的链接；
• 一份已知良好的 G-code 文件及其打印件，用测量结果或照片把它记录为实体基准。

供应商配置文件要在迁移前保存，事后重建并无保障。即使两台打印机以相同产品名称销售，控制板、探针或接线修订版也会不同。社区提供的 printer.cfg 只有在文件头与实际硬件完全匹配时，才适合作为配置线索。Klipper 安装指南也明确划分了两项工作：配置文件记录目标打印机的技术信息，编译并刷写微控制器则是另一个独立步骤。[2]

切换前还要把回滚落实到具体材料。旧固件文件、刷回固件所需的方法与介质、旧切片器配置和已保存的参数应放在一起。若旧状态的唯一副本仍留在即将被覆盖的微控制器里，回滚便只剩考古。

认识新的可用性边界

在 Marlin 常见的部署方式中，打印机控制器解析 G-code，并在本地掌管运动。Klipper 把这项工作拆开：一条移动指令先进入主机，依次经过 G-code 处理、前瞻规划、运动学计算和时间调度，再以指定时钟时刻执行的命令抵达微控制器。[3] 因而，大部分配置都能在主机上修改，打印机固件无须重新编译。[2][10]

这种安排扩大了操作空间，同时带来新的依赖。Linux 主机、存储设备、电源、服务状态和主机至 MCU 的链路，如今都位于实时打印链路之中。Klipper FAQ 警告，在共享主机上执行高负载任务或大量使用交换空间会引发打印错误；对于随机出现的 MCU 断连，文档要求从 USB 线缆、电源质量和打印机接线等方面排查。[4] 一张备用 microSD 卡解决不了失效的电源，控制面板能够打开也证明不了串行链路干净稳定。

安全设计与可用性需要分开看。Klipper 说明，加热器启用后，主机必须每隔三秒续发一次启用确认；确认一旦缺失，微控制器便进入关停状态，关闭加热器和步进电机。配置中的温度上下限还会触发另一项 MCU 端关停条件。[4] 主机确认中断后，MCU 会按设计安全关停；无关的接线、开关器件、电源或控制器故障仍需另行防护，打印任务也会丢失。小型实验室应把主机视为机器基础设施：保证供电稳定，避免无关负载，备份配置，并保留一条经过测试的替换路线。

应把 /dev/serial/by-id/ 下的稳定设备名写入 [mcu]，避免采用 /dev/ttyUSB0 这类依发现次序分配的名称。Klipper FAQ 推荐持久标识符；当多个设备缺少唯一 ID 时，文档还给出了 /dev/serial/by-path/。[4] 这项小选择可以防止重启或新增 USB 设备后，主机悄然改向另一块控制器。

以硬件事实为准，重新解释熟悉的数字

第一版 printer.cfg 应保守描述现有机器，暂时排除提速目标。引脚名称、极性标记、运动学类型、行程、热敏电阻、限位开关、探针、驱动器接线和加热器限制都要符合物理实况，后续校准打印才有意义。

最常见的转换陷阱，是把 Marlin 的每毫米步数直接抄入一个含义已经不同的参数。Klipper 用 rotation_distance 表示轴的几何关系，即电机完整旋转一圈所产生的直线距离。文档给出的换算公式是：

rotation_distance = full_steps_per_rotation × microsteps ÷ steps_per_mm

对于 X、Y 和 Z 轴，Klipper 建议根据皮带节距与皮带轮齿数，或丝杆几何关系推导数值；测试件微调法不适合“校准”这些轴。挤出轴另当别论：先确定一个合理初值，再依照文档缓慢送出 50 mm 耗材，测量实际行程，并按结果调整 rotation_distance。[5] 两类参数的依据有所不同。皮带与丝杆几何属于机器事实；挤出还包含耗材咬合和传动比，需要实际测量。

Marlin 的 PID 数值属于旧控制回路，迁移时不能直接沿用。对于输出硬件和配置适合 PWM/PID 控制的加热器，Klipper 的配置检查流程指出，其他固件或示例文件中的数值往往表现欠佳，并要求在实际机器上运行 PID_CALIBRATE。同一指南还提醒，由机械继电器控制的热床会需要另一种控制方式。[6] 探针偏移与归零行为也要根据测量和接线转换，两段配置看起来相像并不能作为依据。

第一版配置宜保持精简。复制来的宏包、自适应网床流程、CAN 工具头、摄像头服务和复杂的切片器编排，都会为每次故障增加解释分支。初次验收的目标是一台朴素的打印机：能够正确加热、归零、移动、挤出和停止。

一次只验收一个危险环节

Klipper 自己给出的配置检查顺序很适合作为调试规程，因为它先取得低能量证据，再开放高能量动作。[6]

首先给电子系统上电，加热器保持冷态，电机保持静止。确认喷嘴和热床温度读数合理且稳定。若闲置状态下的读数明显异常或持续上升，应切断电源并停止加热测试。随后发送 M112，确认 Klipper 进入关停状态，再用 FIRMWARE_RESTART 恢复，并按要求重新连接前端，最后确认温度读数依然合理。[6]

接下来逐个测试加热器，同时观察对应的温度通道。归零前先验证限位开关：使用 QUERY_ENDSTOPS，逐个用手触发开关，确认报告状态按预期方向变化。把每个运动轴置于行程中段附近，再分别对 X、Y 和 Z 使用 STEPPER_BUZZ。挤出机的该项测试只安排在未装耗材时；已经装料时，应先加热热端，再按照独立的挤出方向检查流程操作。命令安排的一毫米往返运动，能暴露使能、步数、方向和旋转距离设置错误，同时避免贸然执行完整归零。[6]

完成上述检查后，才让 G28 执行机器归零。手应放在实体电源开关旁，浏览器中的停止按钮只作辅助。在机器允许的情况下逐轴归零，随后再归零全部轴。通过包络范围内的低速移动确认软限位。PID 校准只适用于采用合适 PWM/PID 开关硬件与配置的加热器；如果装有探针和热床调平流程，也要完成验证；向热端送入耗材前，还要再次检查挤出方向。[6]

此时可以用保守的速度和加速度打印一组朴素的基准件：一张首层图案、一个简单的尺寸测试件，以及旧配置中一件具有代表性的已知良好模型。观察冷机启动后的重复性，单次外观漂亮的成功不足以验收。记录内容应包括首层表现、指令尺寸与实测尺寸、挤出一致性、加热器稳定性、限位开关重复性、主机日志，以及同一套 G-code 流程在重启后能否正常完成。

如果测试失败，应停留在产生证据的子系统内继续排查。网床补偿不能掩盖机械松动，流量调整不能掩盖挤出机几何错误，输入整形也不能掩盖丢步。

基准打印稳定复现后，再调压力与共振

Klipper 的性能功能属于校准层，承担不了故障救援。打印机完成配置并能正常运行后，才可根据特定打印机、喷嘴与耗材调校 pressure advance。测试会在其他条件保持固定时，有意改变 advance 数值，以便检查转角表现。[8] 如果此后改变挤出校准、耗材通路或热端流量，原测试结果的前提也会随之改变。

input shaping 的次序还要靠后。Klipper 的手动共振测试会在测试塔上逐步提高加速度，测量振纹频率，并提醒操作者在机器剧烈晃动或出现丢步时停止。文档还指出，有些缺陷并不符合预期的振纹模式，其来源在机械或挤出系统，应先修复再启用整形器。[7] 输入整形器能以一定平滑效应换取更少的振纹，却无法收紧皮带、校正机架、提高电机扭矩或冷却打印件。

每次只调一个轴或一种挤出效应，并保留调整前后的打印件与记录。加速度上限应取自质量和可靠性仍可接受的位置，单次跑完的最高区段不作依据。随后再次打印那件代表性模型。速度更高的校准塔算不上迁移成果；真正的成果是日常零件质量相当，并且留有稳定的运行余量。

让主机配置便于维护

机器通过验收后，应把 printer.cfg、被引用的宏文件、切片器配置和简短调试记录作为一个带版本的整体管理，同时记下与之配套测试的 Klipper 修订版。手工编写的配置要与 SAVE_CONFIG 追加的数值分开；每次改动都经过审阅，避免只凭记忆在浏览器中编辑。

更新时也应保持初次迁移时的克制。Klipper 维护着一份按日期记录的配置变更日志，涵盖选项改名、弃用和行为变化；仅 2026 年的条目就包括探针状态与手动步进器改动。[9] 升级前先阅读日志，在一台机器上分阶段部署，再运行一轮简短的安全与运动冒烟测试，同时保留上一版主机镜像或软件包版本。“服务已重启”只说明进程恢复，仍不能证明宏、探针和切片器生成的命令保有相同含义。

对于一台个人爱好打印机，一名负责人用一个配置仓库、一件已知良好的打印件和一套可刷写的回滚包就能维持这套做法。共享实验室或打印农场还要补充明确的负责人、固定版本、每个硬件修订版的基准配置、备用主机和线缆、集中日志、分阶段推广，以及一份能由他人执行的验收清单。若 Linux 可用性、固件更新和校准证据都缺少负责人，即使 Klipper 在技术上兼容，受支持的供应商固件也会提供更合适的运维约定。

出现以下任一情况时，应停止推广并恢复 Marlin：传感器身份无法确定；关停行为尚未得到验证；原因不明的 MCU 断连持续出现；日常零件无法稳定复现；旧生产流程依赖尚未转换和测试的命令。这些迹象与解锁速度无关，它们表明新的控制链路还未取得掌管机器的充分依据。

Marlin 至 Klipper 的迁移完成于最平淡的时刻：冷机启动后，新系统能把旧零件连续打印两次，同时每项限位与停止流程都符合预期。速度排在这之后。Klipper 首先应带来的改进，是一份可以检查的说明：打印机为何正确运动；加速度稍后再谈。

来源

1. Marlin Firmware 文档源文件“M503 — Report Settings”——用于在迁移前捕获当前运行参数，并说明该命令的适用范围和限制。
2. Klipper 文档“Installation”——Linux 主机与 MCU 的职责、printer.cfg、示例配置匹配、编译及刷写流程。
3. Klipper 文档“Code overview”——一条 G-code 移动指令从主机前瞻规划与调度，到微控制器定时步进命令的处理过程。
4. Klipper 文档“Frequently Asked Questions”——持久串行标识符、主机调度要求、MCU 通信故障、三秒加热器确认与关停行为。
5. Klipper 文档“Rotation distance”——从 steps_per_mm 换算、轴几何、传动比，以及依据测量校准挤出机的流程。
6. Klipper 文档“Configuration checks”——依次验证传感器、M112、加热器、限位开关、步进电机、归零、挤出和 PID 控制。
7. Klipper 文档“Resonance Compensation”——振纹测试、输入整形器选择、加速度限制、平滑取舍与机械故障的适用范围。
8. Klipper 文档“Pressure advance”——受控调校流程、打印机就绪要求，以及对喷嘴与耗材的依赖。
9. Klipper 文档“Configuration Changes”——配置弃用与行为变化的日期记录，更新期间必须逐项审阅。
10. Al Williams，《Fast 3D Printing With Raspberry Pi — But Not How You Think》，Hackaday，2017 年 12 月 26 日——Klipper 主机与 MCU 分工、重新配置方式及物理速度限制的早期独立报道。
11. disinterpreter，“Printer in working”（2022 年 10 月 5 日），图片来自 Wikimedia Commons——封面所用 Voron 打印机照片的出处与许可记录。