树莓派4B运行Klipper：从固件编译到printer.cfg的完整指南

玩 3D 打印的人最近几年应该没少听 Klipper 这个名字。简单说Klipper 把 3D 打印机的运动控制从主板上的芯片挪到了树莓派 4B 上计算交给 ARM 处理器主板只负责按指令执行。换来的好处是更高的打印速度、更平滑的轨迹规划以及网页端直接调参和监控的体验。这篇攻略就带你把树莓派 4B 刷好系统给打印机主板编译并烧录 Klipper 固件再安装主机端服务最后写出一份能稳定运行的 printer.cfg。适合刚接触 Klipper、准备在树莓派 4B 上从零开始折腾的小伙伴也适合用惯了 Marlin 想换固件的老玩家。我会按完整流程走一遍每个步骤都解释为什么这么做顺带把我实测踩过的坑也放进来。这篇文章不会讲太多玄学都是能在自己机器上复现的操作。1. 为什么要用 Klipper给 3D 打印机换大脑的核心收益1.1 从 Marlin 到 Klipper控制方式到底改了什么传统固件比如 Marlin运动规划、加减速、震动抑制全都在打印机主板上完成。主板上一个 8 位或者 32 位 MCU既要读传感器又要算插补还得控制步进电机脉冲。算力有限导致速度一高就丢步或者加速度一大就出现明显振纹。Klipper 的思路完全反过来它把运动规划交给了连在打印机旁的树莓派 4B。树莓派 CPU 算好每一步要走的位置、速度、加速度再通过 USB 或者串口把指令喂给主板。主板上的 MCU 只做一个非常简单的任务把收到的运动指令转换成真实的步进脉冲。也就是说主板从“算运动的大脑”变成了“执行运动的肌肉”。这样做最直接的好处是加速度可以拉得更高。Marlin 里加速度可能只能放到 1500-3000 mm/s²Klipper 通过输入整形 input shaper 之后很多机器能跑到 5000 甚至 10000 mm/s²打印速度也有明显提升。同时因为运动算法跑在 Linux 上调试也更方便改个参数重启下服务就行不用反复重新编译固件。1.2 树莓派 4B 为什么是首选控制主机Klipper 主机端本身不挑设备旧笔记本电脑、虚拟机、甚至电视盒子都能跑。但实际用下来树莓派 4B 是性价比和稳定性最均衡的选择。4B 的 CPU 性能足够同时跑 Klipper 主机服务、Moonraker API、Fluidd/Mainsail 网页界面以及 KlipperScreen 触屏界面负载也不会太高。内存建议 2GB 起步如果你还要开摄像头做延时摄影、加 OctoPrint 之类那 4GB 版本更安心。USB 3.0 接口也很重要Klipper 与主板走 USB 虚拟串口USB 3.0 的供电和延迟都比老一代树莓派更稳。另外树莓派 4B 的 GPIO 还能接 SPI 屏幕、加速度传感器 ADXL345做 resonance measurement 共振测量。这个功能对输入整形非常有用能自动测出机器共振频率然后自动生成补偿参数。整条链路在 4B 上跑得非常顺这也是我后来把所有机器都换成 4B 的原因。1.3 安装前需要准备哪些硬件在动手装系统之前先把东西备齐避免做到一半缺什么。树莓派 4B 主板建议 2GB 以上内存最好带原装 5V 3A 电源。至少 16GB 的 TF 卡读速快一点会更舒服比如 A1 或 A2 等级。打印机主板一块常见的有 BIGTREETECH SKR Mini E3、SKR 3、Octopus、MKS Robin或者老一点的 8 位板子。一条用于连接树莓派和打印机主板的数据线。如果是 USB 直连尽量选带磁环的短线太长容易引入干扰。读卡器或者树莓派官方 Imager 工具用来把系统写入 TF 卡。如果你要用 KlipperScreen还需要一个 HDMI 触摸屏或者 GPIO 屏幕。这里提醒一句很多玩家把树莓派和打印机主板接在同一个电源上结果树莓派一开机或者打印头加热时电压波动系统直接重启。最稳妥的方案是给树莓派配独立的稳压电源模块主板单独供电GND 再连在一起。这样既能避免 USB 供电不足又能减少互相干扰。2. 系统准备树莓派 4B 刷入操作系统与基础配置2.1 系统镜像选择Raspberry Pi OS Lite 还是 Desktop这一步决定了后面很多东西。很多人第一次用树莓派习惯性装了桌面版 Raspberry Pi OS Desktop结果一开机内存就占了不少风扇也吵。实际上 Klipper 的交互界面是网页端的树莓派本身不需要接显示器、键盘鼠标更不需要桌面环境。我推荐使用 Raspberry Pi OS Lite 64 位版本。Lite 没有预装桌面环境系统占用小内存管理和稳定性都更好。64 位系统对 Klipper 的 Python 依赖也更友好因为 32 位系统在装某些包时可能出现兼容问题。虽然 Klipper 官方文档里还比较保守说 32 位系统也能跑但实测下来新版本 Moonraker 在 64 位环境下要省心很多。如果你手里有一台性能普通的树莓派 3B那可以退而求其次选 32 位配置脚本会自动适配。但给 4B 用闭眼选 64 位 Lite 就行。2.2 用 Raspberry Pi Imager 烧录系统并开启 SSH首先去树莓派官网下载 Raspberry Pi Imager插入 TF 卡打开工具。在“Choose Device”里选择树莓派 4B然后“Choose OS”选 Raspberry Pi OS (Other) 下的 Raspberry Pi OS Lite (64-bit)。烧录前点设置按钮可以预配置几个关键项开启 SSH建议设置用户名和密码。如果你有无线网络需求可以预填 Wi-Fi SSID 和密码。我个人更推荐插网线稳定性高很多。设置主机名比如 klipperpi方便局域网访问。烧录完之后把 TF 卡插入树莓派 4B接网线、电源等一两分钟就能从局域网 SSH 登录了。Windows 用户可以用 PowerShell 直接执行ssh klipperpi主机名.local前提是树莓派和电脑在同一个局域网。如果无法解析就到路由器后台找分配给树莓派的 IP 地址用ssh 用户名IP连。2.3 基础系统设置更新、时区与权限登录进系统后先跑一遍更新sudo apt update sudo apt upgrade -y这一步建议执行因为 Klipper 的 Python 依赖对系统库版本有要求。接下来设置时区否则打印日志时间对不上排查问题时很困惑sudo dpkg-reconfigure tzdata然后建议把当前用户加入 tty 和 dialout 组否则后面访问 USB 串口可能出现权限问题sudo usermod -aG tty 用户名 sudo usermod -aG dialout 用户名这里注意Klipper 主机服务默认用 Python venv 运行创建用户之后最好就用这个普通用户操作不要在用 root 跑 Klipper。权限问题会少很多也方便后续用 KIAUH 管理服务。3. Klipper 固件编译给打印机主板烧录新固件3.1 理清 Klipper 的两个部分主机端与固件端Klipper 不是一个单独安装到主板上的“固件”就完事了。它包含两部分树莓派上跑的主机服务叫 Klipper负责解析 G-code、规划运动、调用 Moonraker API。打印机主板上跑的 MCU 固件由 Klipper 源码编译出来负责执行实时控制。这两者必须版本匹配。树莓派上 clone 下来的 Klipper 源码编译出来的固件版本和主机端一致才能正常通信。所以顺序很重要先编译固件烧到主板再配置树莓派上的主机服务或者反过来都行但一定保证两边源码是同一套。我建议先从源码编译固件做起。因为如果主板没有正确跑起 Klipper 固件后面主机端装得再好也是白搭。3.2 编译前确认主板控制芯片型号Klipper 官方文档有一个 Config Reference 和很多主板的示例配置。编译固件之前你需要确认打印机主板上 MCU 的完整型号。主板上一般会印有主芯片型号比如 SKR Mini E3 V3 用的是 STM32G0B1SKR Mini E3 V2 用的是 STM32F103Octopus 系列通常用 STM32F446。不要光看板子名字就猜有时候同系列不同版本芯片差别很大。建议去主板厂商仓库里找对应主板的示例配置里面有明确的[board]类型和 bootloader 地址。比如 BIGTREETECH 的 GitHub 库里就有很多printer-cfg文件每个文件顶部都会标注 MCU 和编译选项。然后 SSH 到树莓派进入 Klipper 源码目录cd ~/klipper make menuconfig在 menuconfig 界面里需要根据主板型号做几个关键选择Micro-controller Architecture: 通常选 STMicroelectronics STM32。Processor model: 一定要选对比如 STM32F103、STM32F446、STM32G0B1。Bootloader offset: 这个非常关键主板芯片出厂自带的 bootloader 决定了固件要写在哪个地址。如果选错固件可能刷进去但无法启动。Communication interface: 选 USB 或 UART。USB 就是通过 USB 虚拟串口通信UART 就是接到树莓派 GPIO 的串口上需要额外配线。建议第一次玩的时候优先走 USB调试最方便。3.3 编译并烧录固件以 SKR Mini E3 系列为例我拿 BIGTREETECH SKR Mini E3 V3 举例。在 menuconfig 里选择Micro-controller Architecture: STM32Processor model: STM32G0B1Bootloader offset: 8KiB bootloaderCommunication interface: USB (on PA11/PA12)USB IDs 不用改默认即可保存退出后执行make clean make编译完成后会生成文件out/klipper.bin。这个 bin 文件就是我们要烧录到主板上的固件。SKR Mini E3 V3 支持把固件放到 TF 卡烧录把out/klipper.bin复制到一张 FAT32 格式的 TF 卡根目录改名为firmware.bin。断电状态把 TF 卡插到主板卡槽再上电指示灯开始闪烁说明正在写入完成后固件就进到主板 Flash 里了。不同主板的烧录方式可能不同。有的主板支持 DFU 模式用 USB 直接刷有的需要通过 bootloader 跳线。最稳妥的方式是去对应厂商文档里找“download firmware”说明。万用表都没用这种硬件细节必须按厂商步骤来。3.4 固件刷错导致的典型问题最常见的刷错情况有两种一是 Processor model 选错二是 Bootloader offset 选错。刷错之后主板常常表现为上电无反应USB 电脑不识别或者刷完到这里前面一直正常但连主机端时一直报错找不到串口。这时候不要慌先确认能进入 bootloader 模式。很多主板上电开机时按着板上的 BOOT 按钮可以进入 DFU/刷机模式。然后用工具检查 USB 设备列表lsusb如果能看到对应厂商的设备说明 bootloader 还是好的可以重新编译后刷入。如果完全识别不到可能需要用 stm32flash 或者官方软件强行重刷但那就比较折腾了。所以我给的建议是编译前花三分钟去主板仓库下对应配置不要凭感觉选参数。4. 安装主机端服务Klipper、Moonraker 与 Fluidd/Mainsail4.1 用 KIAUH 脚本一键安装全家桶固件烧好之后树莓派上还需要装三个关键服务Klipper 本体核心服务。MoonrakerKlipper 的 API 接口层网页界面的后端也能管理文件、更新软件。Fluidd 或 Mainsail网页前端用浏览器控制打印机。手工安装这些东西不是不行但新手很容易在 Python 虚拟环境或者 systemd 服务配置上出错。我推荐直接用 KIAUH 脚本全称 Klipper Installation And Update Helper。它能自动完成创建虚拟环境、安装依赖、注册 systemd 服务、配置示例文件的步骤非常省心。登录 SSH 后执行cd ~ git clone https://github.com/dw-0/kiauh.git cd kiauh ./kiauh.sh脚本是菜单式操作选安装 Klipper它会问你 Klipper 源码装在那个目录、用什么 Python 环境一路回车默认即可。装完 Klipper 之后再运行脚本选择 Moonraker同样默认即可。最后安装 Mainsail 或者 Fluidd。Mainsail 和 Fluidd 都是现代、高颜值的网页前端功能差别不大选一个就行。4.2 手工安装流程拆解理解服务之间的关系如果你不想用脚本或者脚本在你的系统上出问题手工安装的核心步骤也很清晰。以普通用户身份执行cd ~ git clone https://github.com/Klipper3d/klipper.git python3 -m venv ~/klipper/venv ~/klipper/venv/bin/pip install -r ~/klipper/requirements.txt然后创建 systemd 服务文件告诉系统开机自动启动 Klipper。服务文件路径一般是/etc/systemd/system/klipper.service里面内容大概是[Unit] DescriptionKlipper Afternetwork-online.target [Service] Userpi ExecStart/home/pi/klipper/venv/bin/python /home/pi/klipper/klippy/klippy.py /home/pi/printer_data/config/printer.cfg -l /home/pi/printer_data/logs/klippy.log Restartalways RestartSec5 [Install] WantedBymulti-user.target这里有一个目录结构问题Klipper 默认会使用~/printer_data作为配置、日志、gcode 文件的根目录。KIAUH 装完后会自动创建好这个目录手工安装则需要自己建。目录里至少要有config、logs、gcodes三个子目录。用脚本还是手工本质区别就在这些细节。4.3 配置文件链接与 Web 界面访问安装完成之后网页前端默认端口是 80打开浏览器输入树莓派 IP 就能看到界面。前提是系统里装了 NGINX 或类似的 Web 服务器KIAUH 会自动配置好。在第一次打开网页前我们需要确保printer.cfg里指定的 MCU 串口是存在的。这个在下一节详细说但你可以先确认串口路径ls /dev/serial/by-id/*如果主板固件烧录正确并且 USB 线接好了这里会显示类似usb-Klipper_stm32g0b1xxxx的路径。把这个路径填到printer.cfg的[mcu]section 里即可。4.4 如果还想加触摸屏KlipperScreen树莓派 4B 加一块 HDMI 触摸屏就能让打印机脱离电脑独立操作。KlipperScreen 是一个全屏触摸界面可以在屏幕上完成打印文件选择、温度调节、Z 轴微调这些操作。安装最简单的方式还是 KIAUH 里的 Install KlipperScreen 选项。装完以后在系统服务的配置里把它启动起来。如果屏幕没有自动适配需要在系统/boot/config.txt里设置分辨率、触摸屏驱动。我自己的经验是KlipperScreen 很方便但别指望它能取代网页端调参。真正复杂的功能还是要开浏览器到 Fluidd 或者 Mainsail 里设置。5. 打印机配置从零写出一份能用的 printer.cfg5.1 配置文件基本骨架与参数逻辑Klipper 的所有打印参数都在printer.cfg里。这个文件是纯文本改完以后需要在网页端执行 FIRMWARE_RESTART 才能生效。很多新手第一反应是到处抄别人配置但不同主板、不同电机的接线和引脚都不一样直接抄容易出问题。最可靠的方式是先找到你主板型号对应的示例 printer.cfg。一般官方 Klipper 的 GitHub 仓库里有config目录里面有海量主板的示例配置。下载对应主板的那个文件放到~/printer_data/config/下改名为printer.cfg再根据自己的打印机型号调整部分参数。一个标准 printer.cfg 至少包含这些 section[mcu]主板串口地址。[printer]打印尺寸、运动速度和加速度。[stepper_x]、[stepper_y]、[stepper_z]各轴电机引脚和运动参数。[extruder]挤出机电机、加热器、热敏电阻。[heater_bed]热床控制。[fan]模型冷却风扇。5.2 步进电机、热端、热床、风扇配置详解以[stepper_x]为例核心参数包括[stepper_x] step_pin: PB13 dir_pin: PB12 enable_pin: !PB14 microsteps: 16 rotation_distance: 40 endstop_pin: ^PC0 position_endstop: 0 position_min: 0 position_max: 200 homing_speed: 50step_pin、dir_pin、enable_pin是电机驱动器的引脚这些引脚必须在主板原理图里找。驱动器的方向脚前有!表示电平反转如果电机方向跑反了要调整这里而不是改线。rotation_distance表示电机轴转一圈带动皮带前进多少毫米这个参数直接影响步进距离算错的话打印尺寸会差很多。microsteps是驱动器的细分数Klipper 在软件层面主要通过这个配置来计算每一步对应的距离。[extruder]部分除了引脚还有 PID 参数和热敏电阻类型[extruder] step_pin: PB1 dir_pin: PB0 enable_pin: !PB2 microsteps: 16 rotation_distance: 22.6789511 nozzle_diameter: 0.400 filament_diameter: 1.750 heater_pin: PC8 sensor_type: EPCOS 100K B57560G104F sensor_pin: PC7 control: pid pid_kp: 22.2 pid_ki: 1.08 pid_kd: 114sensor_type一定要和实际传感器匹配。很多国产热敏电阻不是标准的 NTC 104 型号老老实实查主板配置里的默认值别乱改。heater_pin控制加热棒一般是通过 MOSFET 开关Klipper 会做 PWM 控制所以引脚写对就行。风扇部分[fan] pin: PC6如果你有多个风扇可以用[heater_fan extruder_fan]来控制热端散热风扇用[controller_fan]控制主板风扇避免打印机待机时风扇一直狂转。5.3 限位开关、调平与挤出机参数要点限位开关配置里有一个容易忽略的地方开关类型。机械限位通常是一个微动开关有常开和常闭两种接法。Klipper 配置中用^表示启用内部上拉!表示反转触发逻辑。很多新手照着示例配置抄结果限位一直触发或者不触发问题往往就出在这里。正确做法是先用排除法拔掉限位开关插头看状态是否变化。调平方面如果你的打印机有 BLTouch 或 CR Touch需要单独配置[bltouch]section并把[stepper_z]的endstop_pin改成探针的引脚。如果只是普通机械限位也可以用 Klipper 自带的[bed_mesh]进行网格多点补偿[bed_mesh] speed: 50 horizontal_move_z: 5 mesh_min: 10, 10 mesh_max: 190, 190 probe_count: 5, 5 algorithm: bicubicprobe_count控制取多少个点。5×5 通常够用如果平台形变很大可以加到 7×7。需要 BLTouch 的话还要标定探针偏移。挤出机参数里rotation_distance对挤出端来说尤其重要它决定了挤出多少毫米长的耗材。测量方法是用一条标记加热到 200℃手动挤出 50mm看实际挤出量然后按比例修正配置值。这个校准步骤虽然有点麻烦但直接影响打印表面质量。5.4 首次启动G-code 命令、PID 校准和全轴测试配置文件整理好之后在网页端执行FIRMWARE_RESTART。如果配置有语法或逻辑错误Klipper 日志或者网页界面都会报错。我通常先看左下角的状态栏再点开 Log 查看具体行号。首次启动强烈建议一步一步测试而不是直接点击打印。先在控制台发布以下命令QUERY_ENDSTOPS这个命令会报告每个限位开关的状态手动按压开关看是否正常切换。然后测试各轴运动G28 X G28 Y G28 Z归零正常后再小步移动G1 X10 F300 G1 X100 F1200如果运动方向反了就在配置里反转 dir_pin这时不要只改一个轴三轴一起检查。接下来做 PID 校准。PID 参数如果不准温度波动会很大导致热端保护触发或者打印层间不稳定。执行PID_CALIBRATE HEATERextruder TARGET200 PID_CALIBRATE HEATERheater_bed TARGET60校准结束后Klipper 会在控制台返回新的一组 PID 值你需要把这组值更新到printer.cfg里。实测下来热床 60℃ 校准可能需要十几分钟耐心等它跑完。6. 常见问题与排查技巧实录6.1 固件烧录后 USB 无法识别这是新手上路最常见的坑。主板刷完 Klipper 固件后插上树莓派执行ls /dev/serial/by-id/发现什么都没有或者执行lsusb看到设备但没生成串口节点。排查顺序我一般是这样先用一根确定能传数据的 USB 线把主板连到电脑上看电脑能不能识别到带 Klipper 字样的串口。如果电脑也识别不到基本可以断定是固件没刷进去或者 bootloader 地址选错。去主板厂商文档里重新确认一次编译参数。如果电脑能识别到但树莓派上不行多半是权限问题。检查当前用户是否在 dialout 组我刚才在前面提到过。还有可能是 USB 口供电不足换个口或者换根线再试。6.2 打印过程中树莓派与主板断开打印到一半网页界面突然显示“Lost communication with MCU”或者“Timer too close”这类问题在 Klipper 用户里非常常见。Timer too close一般是运动计算跟不上实时控制常见原因包括加速度设置太高、SD 卡读写性能差、树莓派负载过高。先降低打印速度试试如果你同时开着了 KlipperScreen 和摄像头实时监控偶尔也会卡顿。更可靠的方案是给树莓派换一张速度快一点的 TF 卡并避免在打印过程中执行大型文件操作。还有一种情况是电磁干扰导致的 USB 数据线丢包。遇到这种问题不要怀疑 Klipper 不稳定先换一条带磁环、屏蔽更好的短线。问题往往就解决了。6.3 温度异常热敏电阻类型或接线错误温度读数明显不对比如室温显示 -15℃ 或者 200℃通常有两个原因一是sensor_type配置与热敏电阻实际型号不符二是接线接触不良。Klipper 支持很多热敏电阻模型常见的有NTC 100K beta 3950、EPCOS 100K B57560G104F、Generic 3950等。如果你是国产热敏电阻优先试Generic 3950。换完配置后重启服务再读温度如果读数从异常值跳到合理范围就说明类型对了。接线方面热敏电阻两端没有极性但一定要保证接触牢靠。特别是热端热敏电阻很多线头是压接的时间久了容易松动造成读数跳变。这种问题最危险因为可能导致温控保护误动作。6.4 调平失败的排查调平时探针不回弹、一直下压或者每次测量高度都不一样都是常见难缠问题。首先检查探针供电是否稳定。BLTouch 和 CR Touch 最好单独用稳定的 5V 供电不要和树莓派共享同一个 5V 引脚。然后看[bltouch]配置里的控制引脚是否和主板实际接线一致。很多主板上有专用的探针接口不要把信号线接到普通 GPIO 上。如果测出的 z 坐标普遍偏低或偏高可以通过Z_PROBE_OFFSET_CALIBRATE命令校正偏差。这个命令会提示你先手动让喷嘴刚好贴纸接触热床再自动测探针位置计算出的偏移值要写入配置文件。整个过程在网页控制台里即可完成。6.5 新手指南建议的安全设置Klipper 本身只是一个工具没有内置“在危险时刻强制停止打印”的能力。所以安全设置必须自己注意。我建议第一件事给加热器加max_power限制。在[extruder]和[heater_bed]里设置最大功率例如[heater_bed] max_power: 0.7这样能避免 MOSFET 故障时全功率加热。其次设置min_temp和max_tempKlipper 每 100ms 会检查一次温度超范围就断开加热器。这是保护热端不烧坏的最后一道防线。另外强烈建议在打印机旁放一个带自动断电功能的智能插座并设置好断电后自动重启打印的任务。虽然这是后话了但万一机器半夜出问题远程能断电会让你安心很多。6.6 一些我在实际使用中总结的小技巧配置改得频繁之后最怕的是改着改着忘了上次哪里动过。我的习惯是给printer.cfg做详细注释每改一个参数都写一句为什么改。Klipper 支持#注释不影响运行但排除问题时真的救急。还有一个经常被忽略的地方升级 Klipper 源码之前先备份printer.cfg和moonraker.conf。KIAUH 更新一般不会动这些配置但万一遇到大版本变更某些关键参数可能不兼容。备份永远不嫌多。最后再说一下Klipper 的日志文件~/printer_data/logs/klippy.log其实是排查问题的第一手资料。报错信息里经常直接告诉你是哪一行配置出了问题或者哪个组件没有响应。很多人看到日志先懵其实只要从报错行的关键字去搜基本都能找到答案。Klipper 这套系统比起 Marlin 多了一层“主机端固件端”的架构刚开始会觉得复杂可一旦跑顺了你会发现后期调参的体验完全是另一种级别。树莓派 4B、Klipper 固件、网页界面三者配合已经是我现在每台打印机的标准配置。如果你也是一路摸着石头过河希望这份攻略能帮你少走一点弯路。